codebay 0.9.0 → 0.10.0

package/src/lib/instances.server.ts

@@ -41,17 +41,32 @@ import {
 	devcontainerCliAvailable,
 	devcontainerUp,
 	INJECTIONS_DONE_FILE,
+	launchCommandFor,
 	readDeclaredContainerPorts,
+	TERMINAL_LAUNCHED_MARKER,
 	writeOverrideConfig
 } from './devcontainer.server.ts';
 import { writeContainerFile } from './container-files.server.ts';
+import { execInContainer } from './exec.server.ts';
 import { clearAttention, getAttention } from './bridge.server.ts';
 import { proxyPathFor } from './proxy.server.ts';
-import { resolveInjections } from './injections.server.ts';
+import { resolveInjectionStages } from './injections.server.ts';
 import { cloneRepo, readGitBranch } from './git.server.ts';
 import { isRepoUrl, parseRepoUrl } from './repo-url.ts';
-import { currentHealthSnapshots, stopHealthMonitor, syncHealthMonitors } from './health.server.ts';
-import { pickFreePort } from './ports.server.ts';
+import { getClaudePermissionMode } from '../container-injections/claude-permission-mode.ts';
+import {
+	customEnvVarsConfig,
+	customEnvVarValues
+} from '../container-injections/custom-env-vars.ts';
+import {
+	currentHealthSnapshots,
+	stopHealthMonitor,
+	surfaceAccessible,
+	syncHealthMonitors
+} from './health.server.ts';
+import { runCapturePass, stopLogCapture, syncLogCapture } from './log-capture.server.ts';
+import { isHostPortBindable, pickBindablePort } from './ports.server.ts';
+import { pickAvatar, pickUniqueAvatar } from '../avatars/pick.server.ts';
 import type { ServerWebSocket } from 'bun';
 import {
 	isInstanceFilter,
@@ -61,13 +76,17 @@ import {
 	type InstanceHealth
 } from '../types.ts';
 
+/** The sprite a row shows: its persisted choice, or the id hash for rows created before avatars were stored. */
+const effectiveAvatarName = (row: InstanceRow): string => row.avatar ?? pickAvatar(row.id).name;
+
 /**
- * `bridge_token` authenticates the no-Basic-Auth `/api/bridge/` endpoint, so it
- * must never reach the browser — every row handed to a route goes through here.
+ * `bridge_token` authenticates the no-Basic-Auth `/api/bridge/` endpoint, so it must never reach the
+ * browser — every row handed to a route goes through here. Also resolves the avatar name so the
+ * client renders by name (`findAvatar`) and never needs a hash function of its own.
  */
 export function sanitizeInstance(row: InstanceRow): Omit<InstanceRow, 'bridge_token'> {
 	const { bridge_token: _token, ...rest } = row;
-	return rest;
+	return { ...rest, avatar: effectiveAvatarName(row) };
 }
 
 interface LiveState {
@@ -87,7 +106,36 @@ function live(id: string): LiveState {
 	return state;
 }
 
+/**
+ * Cached so the redaction on every log chunk doesn't re-read the DB. Rebuilt lazily after the
+ * settings action invalidates it; values shorter than 4 chars are skipped so a trivially short
+ * secret can't blank out unrelated log text, and longest-first avoids a short value masking a
+ * substring of a longer one.
+ */
+let secretValuesCache: string[] | null = null;
+
+function getSecretValues(): string[] {
+	if (secretValuesCache === null) {
+		secretValuesCache = customEnvVarValues()
+			.filter((v) => v.length >= 4)
+			.sort((a, b) => b.length - a.length);
+	}
+	return secretValuesCache;
+}
+
+/** Call after the custom-env-vars setting changes so newly-added values redact from the next boot. */
+export function invalidateSecretValues(): void {
+	secretValuesCache = null;
+}
+
+/** Exported for tests; the boot flow reaches it only through `appendLog`. */
+export function redactSecrets(text: string): string {
+	for (const value of getSecretValues()) text = text.split(value).join('••••');
+	return text;
+}
+
 function appendLog(id: string, chunk: string): void {
+	chunk = redactSecrets(chunk);
 	const state = live(id);
 	state.logs.push(chunk);
 	if (state.logs.length > 2000) state.logs.splice(0, state.logs.length - 2000);
@@ -255,7 +303,10 @@ async function allocatePort(): Promise<number> {
 	for (const [port, reservedAt] of reservedPorts) {
 		if (dbPorts.has(port) || now - reservedAt > RESERVATION_TTL_MS) reservedPorts.delete(port);
 	}
-	const port = pickFreePort([dbPorts, dockerPorts, new Set(reservedPorts.keys())]);
+	const port = await pickBindablePort(
+		[dbPorts, dockerPorts, new Set(reservedPorts.keys())],
+		isHostPortBindable
+	);
 	reservedPorts.set(port, now);
 	return port;
 }
@@ -270,6 +321,10 @@ async function assertDir(path: string): Promise<void> {
 	if (!info.isDirectory()) throw new Error(`Not a folder: ${path}`);
 }
 
+function elapsed(startMs: number): string {
+	return `${((Date.now() - startMs) / 1000).toFixed(1)}s`;
+}
+
 function failInstance(id: string, err: unknown): void {
 	const message = (err as Error).message;
 	updateInstance(id, { status: 'error', error: message });
@@ -279,15 +334,18 @@ function failInstance(id: string, err: unknown): void {
 
 async function boot(row: InstanceRow, opts: { branch?: string } = {}): Promise<void> {
 	try {
+		const sourceStart = Date.now();
 		if (isRepoUrl(row.source_path)) {
 			appendLog(row.id, `Cloning ${row.source_path} → ${row.workspace_path}\n`);
 			await cloneRepo(row.source_path, row.workspace_path, (chunk) => appendLog(row.id, chunk), {
 				branch: opts.branch
 			});
+			appendLog(row.id, `⏱ clone: ${elapsed(sourceStart)}\n`);
 		} 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);
+			appendLog(row.id, `⏱ copy: ${elapsed(sourceStart)}\n`);
 		}
 		await seedDeclaredPorts(row);
 	} catch (err) {
@@ -314,22 +372,52 @@ async function seedDeclaredPorts(row: InstanceRow): Promise<void> {
 	}
 }
 
+const surfaceLabel = (mode: InstanceMode) =>
+	mode === 'terminal' ? 'ttyd terminal' : 'code-server';
+
+/**
+ * Moves an instance off a host port that something outside Docker has taken over, which otherwise
+ * strands it forever — the container publishes fine but nothing reaches it from the host. Requires
+ * the port to be *both* unbindable and dead, because a rebuild doesn't stop the old container
+ * first: a healthy instance's port is always unbindable here, and its surface still answers.
+ */
+async function rescueHijackedPort(row: InstanceRow): Promise<void> {
+	if (await isHostPortBindable(row.host_port)) return;
+	if (await surfaceAccessible(row.host_port)) return;
+	const stale = row.host_port;
+	const port = await allocatePort();
+	updateInstance(row.id, { host_port: port });
+	row.host_port = port;
+	appendLog(
+		row.id,
+		`⚠ Host port ${stale} is held by another process and isn't reachable — moving to ${port}\n`
+	);
+}
+
 /** Never re-copies the workspace, so in-container edits survive a rebuild. */
 async function provision(row: InstanceRow, opts: { noCache?: boolean } = {}): Promise<void> {
 	try {
+		// On a rebuild `devcontainer up --remove-existing-container` discards the old container's
+		// ~/.claude, so drain it first; a first boot has no container_id and skips straight past.
+		if (row.container_id) {
+			stopLogCapture(row.id);
+			await runCapturePass(row).catch(() => undefined);
+		}
+		await rescueHijackedPort(row);
 		const forwards = listForwards(row.id).map((f) => ({
 			container_port: f.container_port,
 			host_port: f.host_port
 		}));
-		const surface = row.mode === 'terminal' ? 'ttyd terminal' : 'code-server';
-		appendLog(row.id, `Injecting ${surface} (host port ${row.host_port})\n`);
+		appendLog(row.id, `Injecting ${surfaceLabel(row.mode)} (host port ${row.host_port})\n`);
 		const defaultImage = getOption('default_image') ?? DEFAULT_IMAGE;
 		const { imageSource } = await writeOverrideConfig(
 			row.workspace_path,
 			row.host_port,
 			forwards,
 			defaultImage,
-			row.mode
+			row.mode,
+			getClaudePermissionMode(),
+			customEnvVarsConfig()?.vars ?? []
 		);
 		updateInstance(row.id, { image_source: imageSource });
 
@@ -337,9 +425,11 @@ async function provision(row: InstanceRow, opts: { noCache?: boolean } = {}): Pr
 		if (noCache) appendLog(row.id, `Building without cache (--build-no-cache)\n`);
 
 		appendLog(row.id, `Starting devcontainer…\n`);
+		const upStart = Date.now();
 		const result = await devcontainerUp(row.workspace_path, (chunk) => appendLog(row.id, chunk), {
 			noCache
 		});
+		appendLog(row.id, `⏱ devcontainer up: ${elapsed(upStart)}\n`);
 
 		if (result.outcome !== 'success' || !result.containerId) {
 			throw new Error(
@@ -362,25 +452,41 @@ async function provision(row: InstanceRow, opts: { noCache?: boolean } = {}): Pr
 		row.remote_user = result.remoteUser ?? null;
 		row.status = 'running';
 
+		// Start the health monitor now so the IDE mounts as soon as code-server answers,
+		// instead of after every injection plus a full reconcile/health poll cycle.
+		triggerReconcile();
+
 		const target = {
 			containerId: result.containerId,
 			remoteUser: result.remoteUser,
 			instance: row
 		};
-		// Swallow per-injection failures so one bad injection can't abort the rest of provisioning.
-		for (const injection of resolveInjections(row.mode)) {
-			try {
-				await injection.apply(target, (msg) => appendLog(row.id, msg));
-			} catch (err) {
-				appendLog(row.id, `⚠ ${injection.label} injection failed: ${(err as Error).message}\n`);
-			}
+		// Stages parallelize independent injections; per-injection failures are still swallowed
+		// so one bad injection can't abort the rest of provisioning.
+		const injectionsStart = Date.now();
+		for (const stage of resolveInjectionStages(row.mode)) {
+			await Promise.all(
+				stage.map(async (injection) => {
+					try {
+						await injection.apply(target, (msg) => appendLog(row.id, msg));
+					} catch (err) {
+						appendLog(row.id, `⚠ ${injection.label} injection failed: ${(err as Error).message}\n`);
+					}
+				})
+			);
 		}
+		appendLog(row.id, `⏱ injections: ${elapsed(injectionsStart)}\n`);
 
 		// Unblocks the terminal launcher's wait; written even after ⚠s — its timeout is the fallback.
 		await writeContainerFile(target, { dir: '$HOME', name: INJECTIONS_DONE_FILE }, 'done\n').catch(
 			() => undefined
 		);
 
+		// postStartCommand ran before the injections above, and its launcher bails when the binary
+		// is missing — so a container whose build-time ttyd install failed got it too late to be
+		// started. No-ops (one accessibility probe) whenever postStart already brought the port up.
+		await relaunchSurface(row);
+
 		appendLog(row.id, `\n✓ Instance running — open it via the proxy at ${proxyPathFor(row.id)}\n`);
 		triggerReconcile();
 	} catch (err) {
@@ -437,6 +543,8 @@ export async function createInstance(
 		bridge_token: crypto.randomUUID().replace(/-/g, ''),
 		remote_user: null,
 		image_source: null,
+		// Kept synchronous through insertInstance so two concurrent creations can't claim the same free sprite.
+		avatar: pickUniqueAvatar(id, allInstances().map(effectiveAvatarName)).name,
 		mode: opts.mode ?? getDefaultMode(),
 		terminal_split: 0
 	};
@@ -468,6 +576,7 @@ export async function listInstances(): Promise<Instance[]> {
 	);
 	// Reconcile is the only place that knows the current running set.
 	syncHealthMonitors(rows);
+	syncLogCapture(rows);
 	// Distinguishes a forward that's live from one still pending a rebuild.
 	const openPorts = new Map<string, Set<number>>();
 	for (const { id, health } of currentHealthSnapshots()) {
@@ -488,6 +597,9 @@ export async function listInstances(): Promise<Instance[]> {
 	}
 	return rows.map((row) => ({
 		...sanitizeInstance(row),
+		// Resolve legacy null rows to their hashed sprite here so the client only sees an
+		// unresolvable name when a persisted sprite was actually removed from the catalog.
+		avatar: effectiveAvatarName(row),
 		git_branch: branches.get(row.id) ?? null,
 		attention: getAttention(row.id),
 		forwarded_ports: forwards.get(row.id) ?? []
@@ -524,6 +636,10 @@ export async function addForwardedPort(id: string, containerPort: number): Promi
 	if (!Number.isInteger(containerPort) || containerPort < 1 || containerPort > 65535) {
 		throw new Error('Port must be an integer between 1 and 65535');
 	}
+	// Forwards publish on PUBLISH_HOST (0.0.0.0 under HOST=0.0.0.0), so forwarding the port the
+	// instance is actually served on would republish code-server/ttyd — neither of which has auth
+	// of its own — outside the Basic-Auth-gated proxy. Scoped to the live surface on purpose: in
+	// terminal mode nothing listens on 8080, and it's far too common an app port to reserve.
 	const reserved = row.mode === 'terminal' ? TTYD_PORT : CODE_SERVER_PORT;
 	if (containerPort === reserved) {
 		throw new Error(
@@ -575,11 +691,51 @@ export function rebuildRunningInstancesNoCache(): number {
 	return running.length;
 }
 
+/** Single-quote a path for the shell, so a workspace folder with spaces survives the `cd`. */
+function quote(value: string): string {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * `postStartCommand` is a devcontainer-CLI lifecycle hook, not a container entrypoint, so a plain
+ * `docker start` never re-runs it and the ttyd daemon it backgrounded is gone. IDE mode only
+ * survives because the code-server feature ships an entrypoint of its own; ttyd has no equivalent.
+ * Both launchers are guarded (ttyd by process name, code-server by its port), so re-running one
+ * against a healthy container is a no-op.
+ */
+export async function relaunchSurface(row: InstanceRow): Promise<void> {
+	if (!row.container_id) return;
+
+	const steps: string[] = [];
+	// 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}"`);
+	// code-server comes back on its own (its feature ships a container entrypoint), so only launch
+	// a surface that is actually down rather than racing the entrypoint for the port.
+	if (!(await surfaceAccessible(row.host_port))) steps.push(launchCommandFor(row.mode));
+	if (!steps.length) return;
+
+	// Both launchers resolve paths off `$PWD`, which under postStartCommand is the workspace
+	// folder; an exec only inherits the image's WorkingDir, so re-establish it explicitly.
+	const cd = row.remote_workspace_folder
+		? `cd ${quote(row.remote_workspace_folder)} || exit 1; `
+		: '';
+	const res = await execInContainer(
+		{ containerId: row.container_id, remoteUser: row.remote_user },
+		{ script: cd + steps.join('; ') }
+	);
+	if (!res.ok) {
+		appendLog(row.id, `⚠ Could not relaunch ${surfaceLabel(row.mode)}: ${res.error}\n`);
+	}
+}
+
 export async function startInstance(id: string): Promise<InstanceRow> {
 	const row = getInstance(id);
 	if (!row) throw new Error('Instance not found');
 	if (!row.container_id) throw new Error('Instance has no container yet');
 	const ok = await startContainer(row.container_id);
+	// Awaited so the first health tick after the reconcile below already sees a listening port.
+	if (ok) await relaunchSurface(row);
 	updateInstance(id, {
 		status: ok ? 'running' : 'error',
 		error: ok ? null : 'Failed to start container'
@@ -591,6 +747,9 @@ export async function startInstance(id: string): Promise<InstanceRow> {
 export async function stopInstance(id: string): Promise<InstanceRow> {
 	const row = getInstance(id);
 	if (!row) throw new Error('Instance not found');
+	// 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);
 	const ok = row.container_id ? await stopContainer(row.container_id) : true;
 	updateInstance(id, {
 		status: ok ? 'stopped' : 'error',
@@ -604,12 +763,19 @@ export async function stopInstance(id: string): Promise<InstanceRow> {
 export async function deleteInstance(id: string): Promise<void> {
 	const row = getInstance(id);
 	if (!row) return;
-	if (row.container_id) await removeContainer(row.container_id);
+	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.
+	stopLogCapture(id);
+	if (row.container_id) {
+		await runCapturePass(row).catch(() => undefined);
+		await removeContainer(row.container_id);
+	}
 	await rm(join(INSTANCES_DIR, id), { recursive: true, force: true });
 	deleteForwards(id);
 	deleteInstanceRow(id);
 	registry.delete(id);
-	stopHealthMonitor(id);
 	clearAttention(id);
 	triggerReconcile();
 }

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

@@ -0,0 +1,262 @@
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	writeFileSync
+} from 'node:fs';
+import { join } from 'node:path';
+import { 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';
+
+/** Delta pulls are cheap, so a lazier cadence than the 5s health probe is plenty. */
+const CAPTURE_MS = 10_000;
+
+const MANIFEST_MARKER = '__CODEBAY_MANIFEST__';
+const FETCH_MARKER = '__CODEBAY_FETCH__';
+const FILE_MARKER = '__CODEBAY_FILE__';
+const END_MARKER = '__CODEBAY_END__';
+
+export interface ManifestEntry {
+	path: string;
+	size: number;
+}
+
+interface FetchJob {
+	path: 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.
+ */
+function manifestScript(): string {
+	return (
+		`h=$(eval echo ~$(id -un)); cfg="\${CLAUDE_CONFIG_DIR:-$h/.claude}"; ` +
+		`printf '%s\\n' '${MANIFEST_MARKER}'; ` +
+		`{ 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`
+	);
+}
+
+/** 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`
+	);
+}
+
+export function parseManifest(stdout: string): ManifestEntry[] {
+	const at = stdout.indexOf(MANIFEST_MARKER);
+	if (at === -1) return [];
+	const out: ManifestEntry[] = [];
+	for (const line of stdout.slice(at + MANIFEST_MARKER.length).split('\n')) {
+		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 });
+	}
+	return out;
+}
+
+/** A `/projects/` path is a session transcript; the only other file we list is `history.jsonl`. */
+export function hostFileNameFor(instanceId: string, containerPath: string): string {
+	const base = containerPath.split('/').pop() ?? containerPath;
+	if (containerPath.includes('/projects/')) {
+		return `transcript-${instanceId}-${base.replace(/\.jsonl$/, '')}.jsonl`;
+	}
+	return `history-${instanceId}.jsonl`;
+}
+
+/** Diffs container sizes against the host mirrors: append new bytes, or re-pull a file that shrank. */
+export function planFetch(
+	instanceId: string,
+	manifest: ManifestEntry[],
+	hostSize: (hostFileName: string) => number
+): FetchJob[] {
+	const jobs: FetchJob[] = [];
+	for (const { path, size } of manifest) {
+		const hostFileName = hostFileNameFor(instanceId, path);
+		const existing = hostSize(hostFileName);
+		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' });
+	}
+	return jobs;
+}
+
+export function parseFetchBlocks(stdout: string): { path: string; base64: string }[] {
+	const at = stdout.indexOf(FETCH_MARKER);
+	if (at === -1) return [];
+	const blocks: { path: string; base64: string }[] = [];
+	for (const part of stdout
+		.slice(at + FETCH_MARKER.length)
+		.split(FILE_MARKER)
+		.slice(1)) {
+		const end = part.indexOf(END_MARKER);
+		const seg = end === -1 ? part : part.slice(0, end);
+		const nl = seg.indexOf('\n');
+		if (nl === -1) continue;
+		const path = seg.slice(0, nl).replace(/^\t/, '');
+		// base64 wrapping (GNU wraps at 76 cols) is stripped so multi-line blocks decode cleanly.
+		blocks.push({ path, base64: seg.slice(nl + 1).replace(/\s+/g, '') });
+	}
+	return blocks;
+}
+
+function sizeOnDisk(path: string): number {
+	try {
+		return statSync(path).size;
+	} catch {
+		return 0;
+	}
+}
+
+/**
+ * A rebuild recreates the container (`--remove-existing-container`), so its `~/.claude` starts empty
+ * and the next manifest reports a file smaller than our mirror. Archiving the mirror aside — rather
+ * than overwriting it with the new container's few hundred bytes — is what makes retention real.
+ */
+function rollOver(dest: string): void {
+	if (!existsSync(dest)) return;
+	const dot = dest.lastIndexOf('.');
+	const stem = dot === -1 ? dest : dest.slice(0, dot);
+	const ext = dot === -1 ? '' : dest.slice(dot);
+	for (let n = 1; ; n++) {
+		const archive = `${stem}.${n}${ext}`;
+		if (existsSync(archive)) continue;
+		renameSync(dest, archive);
+		return;
+	}
+}
+
+/** Keeps `index.json` mapping the opaque UUID filenames back to a human-readable instance. */
+function updateIndex(logsDir: string, row: InstanceRow): void {
+	const indexPath = join(logsDir, 'index.json');
+	let index: Record<string, unknown> = {};
+	try {
+		const parsed = JSON.parse(readFileSync(indexPath, 'utf8'));
+		if (parsed && typeof parsed === 'object') index = parsed as Record<string, unknown>;
+	} catch {
+		// Absent or corrupt — start fresh rather than lose this pass.
+	}
+	index[row.id] = {
+		name: row.name,
+		source_path: row.source_path,
+		created_at: row.created_at,
+		last_captured: Date.now()
+	};
+	writeFileSync(indexPath, JSON.stringify(index, null, 2));
+}
+
+interface CaptureDeps {
+	exec?: typeof execInContainer;
+	logsDir?: string;
+}
+
+/**
+ * One extraction pass: manifest → plan deltas → fetch → append/roll over host mirrors → index.
+ * Resolves false when the container could not be read, which is how `tick` detects a dead chain.
+ */
+export async function runCapturePass(row: InstanceRow, deps: CaptureDeps = {}): Promise<boolean> {
+	if (!row.container_id) return false;
+	const exec = deps.exec ?? execInContainer;
+	const logsDir = deps.logsDir ?? LOGS_DIR;
+	const target = { containerId: row.container_id, remoteUser: row.remote_user };
+
+	const manifestRes = await exec(target, { script: manifestScript(), capture: true });
+	if (!manifestRes.ok) return false;
+	const manifest = parseManifest(manifestRes.stdout);
+
+	mkdirSync(logsDir, { recursive: true });
+	const jobs = planFetch(row.id, manifest, (name) => sizeOnDisk(join(logsDir, name)));
+
+	if (jobs.length) {
+		const args = ['fetch'];
+		for (const j of jobs) args.push(j.path, String(j.startByte));
+		const fetchRes = await exec(target, { script: fetchScript(), args, capture: true });
+		if (fetchRes.ok) {
+			const byPath = new Map(jobs.map((j) => [j.path, j]));
+			for (const block of parseFetchBlocks(fetchRes.stdout)) {
+				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);
+			}
+		}
+	}
+	updateIndex(logsDir, row);
+	return true;
+}
+
+interface Capture {
+	timer: ReturnType<typeof setTimeout>;
+}
+
+// Pinned to globalThis so dev-mode hot reload doesn't orphan the interval timers.
+const globalForCapture = globalThis as unknown as { __codebayLogCapture?: Map<string, Capture> };
+const captures: Map<string, Capture> = (globalForCapture.__codebayLogCapture ??= new Map());
+
+async function tick(id: string, cap: Capture): Promise<void> {
+	// Re-read every tick: a rename has to reach index.json, and a stale container_id would exec
+	// against a container that no longer exists.
+	const row = getInstance(id);
+	// Best-effort: a failed pass (container just stopped, transient exec error) must not kill the loop.
+	const ok = row ? await runCapturePass(row).catch(() => false) : false;
+	// syncLogCapture would normally stop us, but it only runs from the reconcile loop, which is idle
+	// whenever no client is connected — so a container that died on its own has to end the chain here.
+	const alive =
+		ok || (!!row?.container_id && (await isRunning(row.container_id).catch(() => false)));
+	// Stopped or replaced while the pass was in flight — rescheduling would leak a second chain.
+	if (captures.get(id) !== cap) return;
+	if (!alive) {
+		stopLogCapture(id);
+		return;
+	}
+	cap.timer = setTimeout(() => void tick(id, cap), CAPTURE_MS);
+}
+
+function startLogCapture(id: string): void {
+	if (captures.has(id)) return;
+	const cap: Capture = { timer: setTimeout(() => undefined, 0) };
+	captures.set(id, cap);
+	// Seed a pass now so a short-lived session is captured without waiting a full interval.
+	void tick(id, cap);
+}
+
+/** Stops the timer only — the mirrored logs are retained on disk past instance deletion. */
+export function stopLogCapture(id: string): void {
+	const cap = captures.get(id);
+	if (!cap) return;
+	clearTimeout(cap.timer);
+	captures.delete(id);
+}
+
+/** Driven from the reconcile loop, so capture tracks the container lifecycle automatically. */
+export function syncLogCapture(rows: InstanceRow[]): void {
+	const running = new Set(
+		rows.filter((r) => r.status === 'running' && r.container_id).map((r) => r.id)
+	);
+	for (const row of rows) {
+		if (running.has(row.id) && !captures.has(row.id)) startLogCapture(row.id);
+	}
+	for (const id of [...captures.keys()]) {
+		if (!running.has(id)) stopLogCapture(id);
+	}
+}

package/src/lib/ports.server.ts

@@ -7,3 +7,34 @@ export function pickFreePort(usedSets: ReadonlySet<number>[]): number {
 	}
 	throw new Error('No free host ports available.');
 }
+
+/**
+ * A listener outside Docker's view is invisible to the DB/Docker union — and on a VM-backed daemon
+ * the collision never surfaces as an error, because the `-p` bind happens inside the VM where the
+ * port is free while the host-side forward fails (colima logs that as a warning). Claiming the port
+ * ourselves first is the only way the collision reaches us.
+ */
+export async function isHostPortBindable(port: number): Promise<boolean> {
+	try {
+		// Loopback specifically: it's where code-server is always published, and a wildcard squatter
+		// blocks this bind too, so the one probe covers both.
+		const server = Bun.listen({ hostname: '127.0.0.1', port, socket: { data() {} } });
+		server.stop(true);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Takes the probe as a parameter so the scan is testable without binding real sockets. */
+export async function pickBindablePort(
+	usedSets: ReadonlySet<number>[],
+	isBindable: (port: number) => Promise<boolean>
+): Promise<number> {
+	const rejected = new Set<number>();
+	for (;;) {
+		const port = pickFreePort([...usedSets, rejected]);
+		if (await isBindable(port)) return port;
+		rejected.add(port);
+	}
+}