codebay 0.14.0 → 0.16.0

package/src/lib/exec.server.ts

@@ -22,6 +22,37 @@ function collector(): { stream: Writable; text: () => string } {
 const STDIN_ENV = '__CODEBAY_EXEC_STDIN';
 const STDIN_VAR = 'CODEBAY_STDIN';
 
+/**
+ * Linux rejects any single argv/env string over 128 KiB (`MAX_ARG_STRLEN`), and the stdin carrier
+ * is one env entry — so this, minus headroom for the name, is the hard ceiling on any payload.
+ */
+export const EXEC_STDIN_MAX_BYTES = 128 * 1024 - 1024;
+
+/** The largest UTF-8 payload that still fits the carrier once base64 has inflated it by 4/3. */
+export const EXEC_STDIN_MAX_BYTES_BASE64 = Math.floor((EXEC_STDIN_MAX_BYTES / 4) * 3);
+
+/** Builds the exec target from an instance row; `container_id` must already be known non-null. */
+export function execTargetFor(row: {
+	container_id: string | null;
+	remote_user: string | null;
+}): ExecTarget {
+	return { containerId: row.container_id!, remoteUser: row.remote_user };
+}
+
+/** Everything after the last `marker`, or null when absent — login-shell profile noise precedes every script's own output. */
+export function afterMarker(stdout: string, marker: string): string | null {
+	const at = stdout.lastIndexOf(marker);
+	return at === -1 ? null : stdout.slice(at + marker.length);
+}
+
+/** Just the marker's own line, untrimmed — an empty leading field is meaningful to some callers. */
+export function markerLine(stdout: string, marker: string): string | null {
+	const rest = afterMarker(stdout, marker);
+	if (rest === null) return null;
+	const nl = rest.indexOf('\n');
+	return (nl === -1 ? rest : rest.slice(0, nl)).replace(/\r$/, '');
+}
+
 /**
  * Real exec stdin is unusable on Bun — dockerode's hijack path needs an `upgrade` event
  * Bun never emits, and `openStdin` needs full-duplex client HTTP Bun also lacks.
@@ -31,16 +62,41 @@ function wrapWithStdin(script: string): string {
 	return `${STDIN_VAR}="$${STDIN_ENV}"; unset ${STDIN_ENV}\n${script}`;
 }
 
+/**
+ * Resolves false on timeout. A host-side backstop only: the container process keeps running, so a
+ * caller that needs the command itself killed must also wrap it in the container's own `timeout`.
+ */
+function streamEnded(stream: NodeJS.ReadableStream, timeoutMs?: number): Promise<boolean> {
+	return new Promise((resolve, reject) => {
+		const timer = timeoutMs ? setTimeout(() => resolve(false), timeoutMs) : null;
+		const settle = (fn: () => void) => {
+			if (timer) clearTimeout(timer);
+			fn();
+		};
+		stream.on('end', () => settle(() => resolve(true)));
+		stream.on('error', (e) => settle(() => reject(e)));
+	});
+}
+
 /**
  * The one place the `bash -lc` container-exec pattern lives; every injection goes through it.
  * `stdin` reaches the script as `$CODEBAY_STDIN`, and `args` as `$0`, `$1`, ….
  */
 export async function execInContainer(
 	target: ExecTarget,
-	opts: { script: string; stdin?: string; args?: string[]; capture?: boolean }
+	opts: { script: string; stdin?: string; args?: string[]; capture?: boolean; timeoutMs?: number }
 ): Promise<{ ok: boolean; stdout: string; error?: string }> {
 	const user = target.remoteUser?.trim() || 'root';
 	const hasStdin = opts.stdin !== undefined;
+	const stdinBytes = hasStdin ? Buffer.byteLength(opts.stdin!, 'utf8') : 0;
+	if (stdinBytes > EXEC_STDIN_MAX_BYTES) {
+		// The kernel would fail the exec with an opaque E2BIG; say what the limit actually is.
+		return {
+			ok: false,
+			stdout: '',
+			error: `payload of ${stdinBytes} bytes exceeds the ${EXEC_STDIN_MAX_BYTES}-byte limit a container exec can carry`
+		};
+	}
 	try {
 		const exec = await (await getDocker()).getContainer(target.containerId).exec({
 			Cmd: [
@@ -60,10 +116,15 @@ export async function execInContainer(
 		const out = collector();
 		const err = collector();
 		exec.modem.demuxStream(stream, out.stream, err.stream);
-		await new Promise<void>((resolve, reject) => {
-			stream.on('end', resolve);
-			stream.on('error', reject);
-		});
+		if (!(await streamEnded(stream, opts.timeoutMs))) {
+			// Otherwise the exec socket and its demux collectors live on for as long as the command does.
+			stream.destroy();
+			return {
+				ok: false,
+				stdout: opts.capture ? out.text().trim() : '',
+				error: `timed out after ${opts.timeoutMs}ms`
+			};
+		}
 
 		const code = (await exec.inspect()).ExitCode ?? 1;
 		const stdout = opts.capture ? out.text().trim() : '';

package/src/lib/injections.server.ts

@@ -8,6 +8,7 @@ import { gitIdentity } from '../container-injections/git-identity.ts';
 import { claudeCodeCredentials } from '../container-injections/claude-code-credentials.ts';
 import { claudeCodeCustom } from '../container-injections/claude-code-custom.ts';
 import { claudeCodeSkills } from '../container-injections/claude-code-skills.ts';
+import { claudeHistory } from '../container-injections/claude-history.ts';
 import { claudeCodeIdeExtension } from '../container-injections/claude-code-ide-extension.ts';
 import { codeServerDark } from '../container-injections/code-server-dark.ts';
 import { claudeCodeInstall } from '../container-injections/claude-code-install.ts';
@@ -70,7 +71,10 @@ function buildStages(claudeInjection: Injection): Injection[][] {
 			claudeInjection,
 			claudeCodeSkills,
 			claudeCodeIdeExtension,
-			claudeEffortLevel
+			claudeEffortLevel,
+			// Only writes `projects/**` + `history.jsonl`, which no other injection touches, and
+			// lands before the injections-done sentinel releases the launcher's `claude`.
+			claudeHistory
 		],
 		// 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. code-server-dark

package/src/lib/instances.server.ts

@@ -1,6 +1,8 @@
+import { mkdirSync } from 'node:fs';
 import { rm, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import {
+	claudeMirrorDir,
 	CODE_SERVER_PORT,
 	DATA_DIR,
 	DEFAULT_COPY_IGNORE,
@@ -18,6 +20,9 @@ import {
 	deleteInstanceRow,
 	getInstance,
 	getOption,
+	getRun,
+	openRunFor,
+	openRuns,
 	insertForward,
 	insertInstance,
 	listForwards,
@@ -38,6 +43,7 @@ import {
 	stopContainer
 } from './docker.server.ts';
 import {
+	AGENT_RUN_MARKER,
 	copyWorkspace,
 	devcontainerCliAvailable,
 	devcontainerUp,
@@ -67,12 +73,15 @@ import {
 	syncHealthMonitors
 } from './health.server.ts';
 import { runCapturePass, stopLogCapture, syncLogCapture } from './log-capture.server.ts';
+import { currentRunSummaries, runSummary, setRunChangeHook, stopRun } from './agent-runs.server.ts';
 import { isHostPortBindable, pickBindablePort } from './ports.server.ts';
 import { pickAvatar, pickUniqueAvatar } from '../avatars/pick.server.ts';
+import { uploadEnabled } from './uploads.server.ts';
 import type { ServerWebSocket } from 'bun';
 import {
 	isInstanceFilter,
 	normalizeMode,
+	type AgentRunSummary,
 	type Instance,
 	type InstanceFilter,
 	type InstanceHealth,
@@ -186,6 +195,9 @@ export function subscribeLogs(id: string, onChunk: (chunk: string) => void): ()
 export type StreamEvent =
 	| { type: 'instances'; data: Instance[] }
 	| { type: 'health'; data: { id: string; health: InstanceHealth } }
+	// Its own frame rather than a list reconcile: run progress ticks every few seconds, and
+	// `reconcileInstances` runs a `docker inspect` per instance.
+	| { type: 'run'; data: AgentRunSummary }
 	| { type: 'preflight'; data: { docker: boolean; cli: boolean } }
 	// `name` is the chosen sprite, or null for the default box logo. Lets the header swap live.
 	| { type: 'pet'; data: { name: string | null } }
@@ -194,7 +206,9 @@ export type StreamEvent =
 	// The global default editor surface, so the picker's toggle follows a settings change.
 	| { type: 'default-mode'; data: { mode: InstanceMode } }
 	// The colour scheme, so a change in the settings popup repaints the window behind it.
-	| { type: 'theme'; data: { value: Theme } };
+	| { type: 'theme'; data: { value: Theme } }
+	// Arms/disarms the drop zones on every open page when the setting flips.
+	| { type: 'upload-enabled'; data: { enabled: boolean } };
 
 interface StreamHub {
 	sockets: Set<ServerWebSocket<unknown>>;
@@ -240,6 +254,11 @@ export function broadcastHealth(id: string, health: InstanceHealth): void {
 	broadcast({ type: 'health', data: { id, health } });
 }
 
+setRunChangeHook((runId) => {
+	const row = getRun(runId);
+	if (row) broadcast({ type: 'run', data: runSummary(row) });
+});
+
 /** Called from the settings action so every open dashboard swaps its header logo without a reload. */
 export function broadcastPet(name: string | null): void {
 	broadcast({ type: 'pet', data: { name } });
@@ -263,6 +282,11 @@ export function broadcastTheme(value: Theme): void {
 	broadcast({ type: 'theme', data: { value } });
 }
 
+/** Settings opens in its own popup, so every open dashboard/IDE tab needs the new toggle pushed. */
+export function broadcastUploadEnabled(enabled: boolean): void {
+	broadcast({ type: 'upload-enabled', data: { enabled } });
+}
+
 async function reconcileInstances(force = false): Promise<void> {
 	const list = await listInstances();
 	const listJson = JSON.stringify(list);
@@ -301,6 +325,7 @@ export function streamOpen(ws: ServerWebSocket<unknown>): void {
 	// Seed everything up front so a fresh or reconnected client is correct without waiting a tick.
 	void listInstances().then((list) => sendTo(ws, { type: 'instances', data: list }));
 	for (const snap of currentHealthSnapshots()) sendTo(ws, { type: 'health', data: snap });
+	for (const run of currentRunSummaries()) sendTo(ws, { type: 'run', data: run });
 	void backgroundPreflight().then((pf) => sendTo(ws, { type: 'preflight', data: pf }));
 	// Keeps a reconnecting client correct even if the pet changed while it was away.
 	sendTo(ws, { type: 'pet', data: { name: getOption('pet') || null } });
@@ -312,6 +337,8 @@ export function streamOpen(ws: ServerWebSocket<unknown>): void {
 	});
 	// Same, for the default mode the picker's toggle seeds from.
 	sendTo(ws, { type: 'default-mode', data: { mode: getDefaultMode() } });
+	// Same, for the upload toggle, so a reconnecting client's drop zones match the current setting.
+	sendTo(ws, { type: 'upload-enabled', data: { enabled: uploadEnabled() } });
 }
 
 export function streamClose(ws: ServerWebSocket<unknown>): void {
@@ -381,7 +408,18 @@ async function boot(row: InstanceRow, opts: { branch?: string } = {}): Promise<v
 		} else {
 			appendLog(row.id, `Copying ${row.source_path} → ${row.workspace_path}\n`);
 			const ignore = parseCopyIgnore(getOption('copy_ignore_patterns') ?? DEFAULT_COPY_IGNORE);
-			await copyWorkspace(row.source_path, row.workspace_path, ignore);
+			const { dereferencedSymlinks } = await copyWorkspace(
+				row.source_path,
+				row.workspace_path,
+				ignore
+			);
+			if (dereferencedSymlinks > 0) {
+				appendLog(
+					row.id,
+					`⚠ ${dereferencedSymlinks} symlink(s) copied as regular files — Windows needs Developer Mode (or admin rights) to recreate symlinks, so edits to them no longer write through to their targets
+`
+				);
+			}
 			appendLog(row.id, `⏱ copy: ${elapsed(sourceStart)}\n`);
 		}
 		await seedDeclaredPorts(row);
@@ -467,6 +505,10 @@ async function provision(row: InstanceRow, opts: { noCache?: boolean } = {}): Pr
 		}));
 		appendLog(row.id, `Injecting ${surfaceLabel(row.mode)} (host port ${row.host_port})\n`);
 		const defaultImage = getOption('default_image') ?? DEFAULT_IMAGE;
+		// Mounted read-only for claude-history to restore from, so it has to exist before the boot —
+		// and it has to be mounted *after* the drain above, or a rebuild would restore a stale mirror.
+		const mirrorDir = claudeMirrorDir(row.id);
+		mkdirSync(mirrorDir, { recursive: true });
 		const { imageSource, configPath, overrideConfigPath } = await writeOverrideConfig(
 			row.workspace_path,
 			row.host_port,
@@ -474,7 +516,8 @@ async function provision(row: InstanceRow, opts: { noCache?: boolean } = {}): Pr
 			defaultImage,
 			row.mode,
 			getClaudePermissionMode(),
-			customEnvVarsConfig()?.vars ?? []
+			customEnvVarsConfig()?.vars ?? [],
+			mirrorDir
 		);
 		updateInstance(row.id, { image_source: imageSource });
 
@@ -680,6 +723,8 @@ export async function listInstances(): Promise<Instance[]> {
 	for (const { id, health } of currentHealthSnapshots()) {
 		openPorts.set(id, new Set(health.openPorts));
 	}
+	// One query for every sandbox rather than one per row, since this runs on every reconcile tick.
+	const runs = new Map(openRuns().map((run) => [run.instance_id, runSummary(run)]));
 	const forwards = new Map<
 		string,
 		{ container_port: number; host_port: number; open: boolean }[]
@@ -700,7 +745,8 @@ export async function listInstances(): Promise<Instance[]> {
 		avatar: effectiveAvatarName(row),
 		git_branch: branches.get(row.id) ?? null,
 		attention: getAttention(row.id),
-		forwarded_ports: forwards.get(row.id) ?? []
+		forwarded_ports: forwards.get(row.id) ?? [],
+		active_run: runs.get(row.id) ?? null
 	}));
 }
 
@@ -771,6 +817,9 @@ export function rebuildInstance(id: string, opts: { noCache?: boolean } = {}): I
 	const row = getInstance(id);
 	if (!row) throw new Error('Instance not found');
 	if (inFlight.has(id)) return row; // a build is already in flight
+	// The rebuild replaces the container the run's detached process lives in, so it can never
+	// report back — fail it now rather than leaving the poller to time it out.
+	void cancelActiveRun(id, 'the sandbox was rebuilt');
 	// Claimed before the broadcast below, which reconciles synchronously: an unclaimed `creating`
 	// row reads as orphaned, and reconcile would flip it straight back off `creating`.
 	inFlight.add(id);
@@ -807,7 +856,9 @@ function quote(value: string): string {
 export async function relaunchSurface(row: InstanceRow): Promise<void> {
 	if (!row.container_id) return;
 
-	const steps: string[] = [];
+	// No run survives a container restart, but its marker does when the container was stopped out
+	// from under it — left in place, every launcher would keep opening a plain shell instead of Claude.
+	const steps: string[] = [`rm -f "$HOME/${AGENT_RUN_MARKER}"`];
 	// The folderOpen task's run-once gate is meant to span one container run, but the marker file
 	// outlives it — left in place, a restarted IDE container never reopens the Claude terminal.
 	if (row.mode !== 'terminal') steps.push(`rm -f "$HOME/${TERMINAL_LAUNCHED_MARKER}"`);
@@ -845,9 +896,16 @@ export async function startInstance(id: string): Promise<InstanceRow> {
 	return getInstance(id)!;
 }
 
+/** Runs are per-container, so any transition that replaces or stops one has to settle them first. */
+async function cancelActiveRun(id: string, reason: string): Promise<void> {
+	const open = openRunFor(id);
+	if (open) await stopRun(open.id, reason).catch(() => undefined);
+}
+
 export async function stopInstance(id: string): Promise<InstanceRow> {
 	const row = getInstance(id);
 	if (!row) throw new Error('Instance not found');
+	await cancelActiveRun(id, 'the sandbox was stopped');
 	// A later delete can't exec into a stopped container, so this is the last chance to mirror.
 	stopLogCapture(id);
 	if (row.container_id) await runCapturePass(row).catch(() => undefined);
@@ -864,10 +922,11 @@ export async function stopInstance(id: string): Promise<InstanceRow> {
 export async function deleteInstance(id: string): Promise<void> {
 	const row = getInstance(id);
 	if (!row) return;
+	await cancelActiveRun(id, 'the sandbox was deleted');
 	stopHealthMonitor(id);
 	// Mirror the tail of the session before the transcripts die with the container; the periodic
-	// chain is stopped first so it can't race this last pass. Retention outlives the instance —
-	// <LOGS_DIR>/*-<id>.jsonl is deliberately left on disk.
+	// chain is stopped first so it can't race this last pass. The flat <LOGS_DIR>/*-<id>.jsonl
+	// archive is deliberately left on disk; the per-instance mirror goes with the instance below.
 	stopLogCapture(id);
 	if (row.container_id) {
 		await runCapturePass(row).catch(() => undefined);

package/src/lib/log-capture.server.ts

@@ -7,8 +7,8 @@ import {
 	statSync,
 	writeFileSync
 } from 'node:fs';
-import { join } from 'node:path';
-import { LOGS_DIR } from './config.server.ts';
+import { dirname, join } from 'node:path';
+import { claudeMirrorDir, LOGS_DIR } from './config.server.ts';
 import { getInstance, type InstanceRow } from './db.server.ts';
 import { isRunning } from './docker.server.ts';
 import { execInContainer } from './exec.server.ts';
@@ -17,58 +17,83 @@ import { execInContainer } from './exec.server.ts';
 const CAPTURE_MS = 10_000;
 
 const MANIFEST_MARKER = '__CODEBAY_MANIFEST__';
-const FETCH_MARKER = '__CODEBAY_FETCH__';
+export const FETCH_MARKER = '__CODEBAY_FETCH__';
 const FILE_MARKER = '__CODEBAY_FILE__';
 const END_MARKER = '__CODEBAY_END__';
 
 export interface ManifestEntry {
 	path: string;
+	/** Path relative to the container's Claude config dir, e.g. `projects/-workspaces-foo/x.jsonl`. */
+	relPath: string;
 	size: number;
 }
 
 interface FetchJob {
 	path: string;
+	relPath: string;
 	hostFileName: string;
 	/** 1-indexed byte to `tail -c +N` from; 1 re-pulls the whole file. */
 	startByte: number;
-	mode: 'append' | 'rollover';
 }
 
 /**
- * Lists the transcript + history files with their byte sizes. `find`/`wc -c` (not GNU `-printf`)
- * so it works on busybox containers too; the marker line lets the parser skip login-shell noise.
+ * Lists the transcript + history files with their byte sizes, led by the config dir itself so the
+ * parser can derive each file's layout-preserving relative path rather than guess at the encoding.
+ * `find`/`wc -c` (not GNU `-printf`) so it works on busybox containers too; the marker line lets
+ * the parser skip login-shell noise.
  */
-function manifestScript(): string {
+export function manifestScript(): string {
 	return (
 		`h=$(eval echo ~$(id -un)); cfg="\${CLAUDE_CONFIG_DIR:-$h/.claude}"; ` +
 		`printf '%s\\n' '${MANIFEST_MARKER}'; ` +
+		`printf '%s\\n' "$cfg"; ` +
 		`{ find "$cfg" -maxdepth 1 -type f -name 'history.jsonl' 2>/dev/null; ` +
 		`find "$cfg/projects" -type f -name '*.jsonl' 2>/dev/null; } | ` +
 		`while IFS= read -r f; do printf '%s\\t%s\\n' "$f" "$(wc -c < "$f" | tr -d ' ')"; done; true`
 	);
 }
 
+/**
+ * One framed base64 block of `pathExpr` from `offsetExpr` to EOF (or `maxBytes`) — the shape
+ * `parseFetchBlocks` reads. Both exprs are spliced into a shell script, so callers pass shell
+ * exprs, not values.
+ */
+export function tailBlockScript(pathExpr: string, offsetExpr: string, maxBytes?: number): string {
+	const cap = maxBytes ? ` | head -c ${maxBytes}` : '';
+	return (
+		`printf '${FILE_MARKER}\\t%s\\n' "${pathExpr}"; ` +
+		`tail -c "+${offsetExpr}" "${pathExpr}" 2>/dev/null${cap} | base64; ` +
+		`printf '\\n${END_MARKER}\\n'`
+	);
+}
+
 /** Emits, per requested file, a framed block of base64 bytes from `startByte` to EOF. */
 function fetchScript(): string {
 	return (
 		`printf '%s\\n' '${FETCH_MARKER}'; ` +
 		`while [ "$#" -ge 2 ]; do p="$1"; o="$2"; shift 2; ` +
-		`printf '${FILE_MARKER}\\t%s\\n' "$p"; ` +
-		`tail -c "+$o" "$p" 2>/dev/null | base64; ` +
-		`printf '\\n${END_MARKER}\\n'; done`
+		`${tailBlockScript('$p', '$o')}; done`
 	);
 }
 
 export function parseManifest(stdout: string): ManifestEntry[] {
 	const at = stdout.indexOf(MANIFEST_MARKER);
 	if (at === -1) return [];
+	const [, cfgLine, ...lines] = stdout.slice(at + MANIFEST_MARKER.length).split('\n');
+	// Trailing slashes would leave the relative path leading with one, breaking the host join.
+	const cfg = (cfgLine ?? '').trim().replace(/\/+$/, '');
+	if (!cfg) return [];
 	const out: ManifestEntry[] = [];
-	for (const line of stdout.slice(at + MANIFEST_MARKER.length).split('\n')) {
+	for (const line of lines) {
 		const tab = line.indexOf('\t');
 		if (tab === -1) continue;
 		const path = line.slice(0, tab);
 		const size = Number(line.slice(tab + 1).trim());
-		if (path && Number.isFinite(size)) out.push({ path, size });
+		if (!path || !Number.isFinite(size) || !path.startsWith(`${cfg}/`)) continue;
+		const relPath = path.slice(cfg.length + 1);
+		// `find` can't emit `..` today, but this gets joined onto a host dir, so don't rely on that.
+		if (relPath.split('/').includes('..')) continue;
+		out.push({ path, relPath, size });
 	}
 	return out;
 }
@@ -82,19 +107,22 @@ export function hostFileNameFor(instanceId: string, containerPath: string): stri
 	return `history-${instanceId}.jsonl`;
 }
 
-/** Diffs container sizes against the host mirrors: append new bytes, or re-pull a file that shrank. */
+/**
+ * Diffs container sizes against the host mirrors: append new bytes, or re-pull a file that shrank.
+ * Sized against the layout-preserving mirror, not the flat archive, because that one tracks the
+ * container 1:1 — it's what gets mounted back in, so it must stay a byte-exact copy.
+ */
 export function planFetch(
 	instanceId: string,
 	manifest: ManifestEntry[],
-	hostSize: (hostFileName: string) => number
+	hostSize: (relPath: string) => number
 ): FetchJob[] {
 	const jobs: FetchJob[] = [];
-	for (const { path, size } of manifest) {
+	for (const { path, relPath, size } of manifest) {
 		const hostFileName = hostFileNameFor(instanceId, path);
-		const existing = hostSize(hostFileName);
+		const existing = hostSize(relPath);
 		if (size === existing) continue;
-		if (size < existing) jobs.push({ path, hostFileName, startByte: 1, mode: 'rollover' });
-		else jobs.push({ path, hostFileName, startByte: existing + 1, mode: 'append' });
+		jobs.push({ path, relPath, hostFileName, startByte: size < existing ? 1 : existing + 1 });
 	}
 	return jobs;
 }
@@ -118,7 +146,7 @@ export function parseFetchBlocks(stdout: string): { path: string; base64: string
 	return blocks;
 }
 
-function sizeOnDisk(path: string): number {
+export function sizeOnDisk(path: string): number {
 	try {
 		return statSync(path).size;
 	} catch {
@@ -166,6 +194,7 @@ function updateIndex(logsDir: string, row: InstanceRow): void {
 interface CaptureDeps {
 	exec?: typeof execInContainer;
 	logsDir?: string;
+	mirrorDir?: string;
 }
 
 /**
@@ -176,6 +205,7 @@ export async function runCapturePass(row: InstanceRow, deps: CaptureDeps = {}):
 	if (!row.container_id) return false;
 	const exec = deps.exec ?? execInContainer;
 	const logsDir = deps.logsDir ?? LOGS_DIR;
+	const mirrorDir = deps.mirrorDir ?? claudeMirrorDir(row.id);
 	const target = { containerId: row.container_id, remoteUser: row.remote_user };
 
 	const manifestRes = await exec(target, { script: manifestScript(), capture: true });
@@ -183,7 +213,7 @@ export async function runCapturePass(row: InstanceRow, deps: CaptureDeps = {}):
 	const manifest = parseManifest(manifestRes.stdout);
 
 	mkdirSync(logsDir, { recursive: true });
-	const jobs = planFetch(row.id, manifest, (name) => sizeOnDisk(join(logsDir, name)));
+	const jobs = planFetch(row.id, manifest, (rel) => sizeOnDisk(join(mirrorDir, rel)));
 
 	if (jobs.length) {
 		const args = ['fetch'];
@@ -195,9 +225,19 @@ export async function runCapturePass(row: InstanceRow, deps: CaptureDeps = {}):
 				const job = byPath.get(block.path);
 				if (!job) continue;
 				const bytes = Buffer.from(block.base64, 'base64');
-				const dest = join(logsDir, job.hostFileName);
-				if (job.mode === 'rollover') rollOver(dest);
-				appendFileSync(dest, bytes);
+				const archive = join(logsDir, job.hostFileName);
+				const mirror = join(mirrorDir, job.relPath);
+				mkdirSync(dirname(mirror), { recursive: true });
+				// The archive keeps every generation; the mirror only ever holds what the container
+				// holds, since it gets mounted back in and a stale byte would resurface as history.
+				// Any whole-file pull rolls, since a pre-mirror instance's archive would otherwise double.
+				if (job.startByte === 1) {
+					rollOver(archive);
+					writeFileSync(mirror, bytes);
+				} else {
+					appendFileSync(mirror, bytes);
+				}
+				appendFileSync(archive, bytes);
 			}
 		}
 	}

package/src/lib/mcp-auth.server.ts

@@ -0,0 +1,52 @@
+import { randomBytes } from 'node:crypto';
+import { getOption, setOption } from './db.server.ts';
+import { timingSafeEqualStr } from './crypto.server.ts';
+
+/** The MCP endpoint's path; `auth.server.ts` and the CSRF filter both key off this exact value. */
+export const MCP_PATH = '/mcp';
+
+export const MCP_ENABLED_KEY = 'mcp_enabled';
+export const MCP_TOKEN_KEY = 'mcp_token';
+
+/**
+ * Off until someone opts in. The token gates the endpoint, but an install that never wanted an
+ * agent-facing control plane shouldn't expose one at all.
+ */
+export function mcpEnabled(): boolean {
+	return getOption(MCP_ENABLED_KEY) === '1';
+}
+
+export function setMcpEnabled(enabled: boolean): void {
+	setOption(MCP_ENABLED_KEY, enabled ? '1' : '0');
+	if (enabled) getMcpToken();
+}
+
+function mint(): string {
+	return `cb_${randomBytes(32).toString('base64url')}`;
+}
+
+/**
+ * Minted on first read and persisted, so the settings page and the route can't disagree. Unlike
+ * every other secret here this one is shown to the user in plaintext — copying it into an MCP
+ * client is the whole point of it existing.
+ */
+export function getMcpToken(): string {
+	const existing = getOption(MCP_TOKEN_KEY);
+	if (existing) return existing;
+	const token = mint();
+	setOption(MCP_TOKEN_KEY, token);
+	return token;
+}
+
+export function regenerateMcpToken(): string {
+	const token = mint();
+	setOption(MCP_TOKEN_KEY, token);
+	return token;
+}
+
+/** Constant-time, like the bridge token check, so a wrong guess leaks nothing by timing. */
+export function mcpAuthOk(request: Request): boolean {
+	const header = request.headers.get('authorization');
+	if (!header?.startsWith('Bearer ')) return false;
+	return timingSafeEqualStr(header.slice(7).trim(), getMcpToken());
+}

package/src/lib/osc52.ts

@@ -0,0 +1,18 @@
+/**
+ * OSC 52 is how a program inside the container asks the *outer* terminal to put text on the host
+ * clipboard — what tmux's `set-clipboard on` emits on copy. xterm.js ships no handler for it, so
+ * every such write was silently dropped and copy out of an instance was impossible.
+ */
+export function decodeOsc52(data: string): string | null {
+	const sep = data.indexOf(';');
+	if (sep === -1) return null;
+	const payload = data.slice(sep + 1).replace(/\s+/g, '');
+	// `?` is a read request; answering it would hand the host clipboard to the container.
+	if (payload === '' || payload === '?') return null;
+	try {
+		const bytes = Uint8Array.from(atob(payload), (c) => c.charCodeAt(0));
+		return new TextDecoder().decode(bytes);
+	} catch {
+		return null;
+	}
+}

package/src/lib/picker.server.ts

@@ -1,17 +1,30 @@
 import { readdir, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { getOption, setOption } from './db.server';
 import { findDevcontainerConfig } from './devcontainer.server.ts';
+import { DRIVES_ROOT } from './drives.ts';
 import type { BrowseResult, DirEntry } from '../types.ts';
 
 const LAST_VIEWED_FOLDER = 'last_viewed_folder';
 
+const isWindows = process.platform === 'win32';
+
 function hasDevcontainer(dir: string): boolean {
 	return findDevcontainerConfig(dir) !== null;
 }
 
+/** Probed rather than enumerated, so listing the drives needs no shell-out. */
+function driveRoots(): DirEntry[] {
+	const roots: DirEntry[] = [];
+	for (let i = 0; i < 26; i++) {
+		const path = `${String.fromCharCode(65 + i)}:${sep}`;
+		if (existsSync(path)) roots.push({ name: path, path, hasDevcontainer: hasDevcontainer(path) });
+	}
+	return roots;
+}
+
 /** Persists every folder it lists, so an argument-less call resumes where the user left off. */
 export async function browse(path?: string): Promise<BrowseResult> {
 	let target: string;
@@ -22,6 +35,12 @@ export async function browse(path?: string): Promise<BrowseResult> {
 		target = saved && existsSync(saved) ? saved : homedir();
 	}
 
+	// Deliberately not persisted as the last-viewed folder: it is not a real directory, so a
+	// resume would fall through to the home dir anyway.
+	if (isWindows && target === DRIVES_ROOT) {
+		return { path: DRIVES_ROOT, hasDevcontainer: false, parent: null, entries: driveRoots() };
+	}
+
 	const info = await stat(target);
 	if (!info.isDirectory()) throw new Error(`Not a folder: ${target}`);
 
@@ -40,7 +59,9 @@ export async function browse(path?: string): Promise<BrowseResult> {
 	return {
 		path: target,
 		hasDevcontainer: hasDevcontainer(target),
-		parent: parent === target ? null : parent,
+		// A Windows drive root is its own dirname, which would otherwise strand the user on
+		// whichever drive their home directory sits on.
+		parent: parent === target ? (isWindows ? DRIVES_ROOT : null) : parent,
 		entries
 	};
 }