codebay 0.14.0 → 0.15.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/instances.server.ts

@@ -18,6 +18,9 @@ import {
 	deleteInstanceRow,
 	getInstance,
 	getOption,
+	getRun,
+	openRunFor,
+	openRuns,
 	insertForward,
 	insertInstance,
 	listForwards,
@@ -38,6 +41,7 @@ import {
 	stopContainer
 } from './docker.server.ts';
 import {
+	AGENT_RUN_MARKER,
 	copyWorkspace,
 	devcontainerCliAvailable,
 	devcontainerUp,
@@ -67,12 +71,14 @@ 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 type { ServerWebSocket } from 'bun';
 import {
 	isInstanceFilter,
 	normalizeMode,
+	type AgentRunSummary,
 	type Instance,
 	type InstanceFilter,
 	type InstanceHealth,
@@ -186,6 +192,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 } }
@@ -240,6 +249,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 } });
@@ -301,6 +315,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 } });
@@ -381,7 +396,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);
@@ -680,6 +706,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 +728,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 +800,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 +839,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 +879,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,6 +905,7 @@ 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 —

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

@@ -17,7 +17,7 @@ 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__';
 
@@ -48,14 +48,26 @@ function manifestScript(): string {
 	);
 }
 
+/**
+ * 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`
 	);
 }
 
@@ -118,7 +130,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 {

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/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
 	};
 }

package/src/lib/sandbox-ops.server.ts

@@ -0,0 +1,263 @@
+import {
+	EXEC_STDIN_MAX_BYTES_BASE64,
+	afterMarker,
+	execInContainer,
+	execTargetFor,
+	markerLine
+} from './exec.server.ts';
+import { SOURCE_INJECTED_ENV } from './devcontainer.server.ts';
+import { getOption, type InstanceRow } from './db.server.ts';
+import { HOME_PRELUDE, shellSingleQuote as quote } from './container-files.server.ts';
+
+/** Enough for a big diff or a test run's output, small enough not to blow a caller's context. */
+export const OUTPUT_CAP = 200_000;
+
+/** What `write_file` can carry in one call: the content rides base64'd through the exec env carrier. */
+export const WRITE_FILE_MAX_BYTES = EXEC_STDIN_MAX_BYTES_BASE64;
+
+const CODE_MARKER = '__CODEBAY_CMD__';
+const OUT_MARKER = '__CODEBAY_CMD_OUT__';
+const ERR_MARKER = '__CODEBAY_CMD_ERR__';
+const END_MARKER = '__CODEBAY_CMD_END__';
+
+/** `timeout`'s own exit code for a command it had to kill. */
+const TIMEOUT_EXIT = 124;
+
+export interface CommandResult {
+	exitCode: number;
+	stdout: string;
+	stderr: string;
+	timedOut: boolean;
+	truncated: boolean;
+}
+
+/** Everything here runs from the workspace, since an exec only inherits the image's WorkingDir. */
+function workspacePrelude(row: InstanceRow): string {
+	const cd = row.remote_workspace_folder
+		? `cd ${quote(row.remote_workspace_folder)} || exit 1; `
+		: '';
+	return `${HOME_PRELUDE}[ -n "$HOME" ] || export HOME="$h"; ${cd}`;
+}
+
+function decodeBlock(stdout: string, marker: string): string {
+	const rest = afterMarker(stdout, marker);
+	if (rest === null) return '';
+	const end = rest.indexOf(END_MARKER);
+	// GNU base64 wraps at 76 columns, and a trimmed capture can drop the final newline.
+	const b64 = (end === -1 ? rest : rest.slice(0, end)).replace(/\s+/g, '');
+	return b64 ? Buffer.from(b64, 'base64').toString('utf8') : '';
+}
+
+function cap(text: string): { text: string; truncated: boolean } {
+	return text.length > OUTPUT_CAP
+		? { text: text.slice(0, OUTPUT_CAP) + '\n… output truncated', truncated: true }
+		: { text, truncated: false };
+}
+
+/**
+ * The command rides in through the stdin carrier rather than the script body, so nothing has to be
+ * escaped and it never reaches the container's process list; output is base64'd because the
+ * capture path trims and the demuxed stream is text.
+ */
+export async function execCommand(
+	row: InstanceRow,
+	command: string,
+	opts: { timeoutSeconds?: number; cwd?: string } = {}
+): Promise<CommandResult> {
+	const seconds = Math.max(1, Math.min(opts.timeoutSeconds ?? 120, 3600));
+	const script =
+		workspacePrelude(row) +
+		SOURCE_INJECTED_ENV +
+		`o=$(mktemp); e=$(mktemp); ` +
+		// The in-container `timeout` is what actually kills the process; execInContainer's own
+		// timeoutMs below is only a backstop for a wedged docker stream.
+		`if command -v timeout >/dev/null 2>&1; then timeout -k 5 ${seconds} bash -c "$CODEBAY_STDIN" >"$o" 2>"$e"; ` +
+		`else bash -c "$CODEBAY_STDIN" >"$o" 2>"$e"; fi; c=$?; ` +
+		`printf '${CODE_MARKER}%s\\n' "$c"; ` +
+		`printf '${OUT_MARKER}\\n'; base64 < "$o"; printf '\\n${END_MARKER}\\n'; ` +
+		`printf '${ERR_MARKER}\\n'; base64 < "$e"; printf '\\n${END_MARKER}\\n'; ` +
+		`rm -f "$o" "$e"; true`;
+
+	const res = await execInContainer(execTargetFor(row), {
+		script,
+		stdin: opts.cwd ? `cd ${quote(opts.cwd)} || exit 1\n${command}` : command,
+		capture: true,
+		timeoutMs: (seconds + 15) * 1000
+	});
+	if (!res.ok) {
+		return {
+			exitCode: -1,
+			stdout: '',
+			stderr: res.error ?? 'the command could not be run',
+			timedOut: false,
+			truncated: false
+		};
+	}
+
+	const exitCode = Number.parseInt(markerLine(res.stdout, CODE_MARKER) ?? '', 10);
+	const out = cap(decodeBlock(res.stdout, OUT_MARKER));
+	const err = cap(decodeBlock(res.stdout, ERR_MARKER));
+	return {
+		exitCode: Number.isFinite(exitCode) ? exitCode : -1,
+		stdout: out.text,
+		stderr: err.text,
+		timedOut: exitCode === TIMEOUT_EXIT,
+		truncated: out.truncated || err.truncated
+	};
+}
+
+/** Throws the command's own stderr, so a tool caller sees why git or gh refused. */
+async function must(row: InstanceRow, command: string, timeoutSeconds = 120): Promise<string> {
+	const res = await execCommand(row, command, { timeoutSeconds });
+	if (res.exitCode !== 0) {
+		throw new Error((res.stderr || res.stdout || `command failed (exit ${res.exitCode})`).trim());
+	}
+	return res.stdout;
+}
+
+/**
+ * The path arrives as an argv entry rather than spliced into the script, so no amount of quoting
+ * in a caller-supplied filename can escape into the shell.
+ */
+export async function readWorkspaceFile(row: InstanceRow, path: string): Promise<string> {
+	const script =
+		workspacePrelude(row) +
+		`if [ ! -f "$1" ]; then printf '${CODE_MARKER}1\\n'; exit 0; fi; ` +
+		`printf '${CODE_MARKER}0\\n'; printf '${OUT_MARKER}\\n'; base64 < "$1"; printf '\\n${END_MARKER}\\n'`;
+	const res = await execInContainer(execTargetFor(row), {
+		script,
+		args: ['read-file', path],
+		capture: true,
+		timeoutMs: 30_000
+	});
+	if (!res.ok) throw new Error(res.error ?? 'could not read the file');
+	if (res.stdout.includes(`${CODE_MARKER}1`)) throw new Error(`no such file: ${path}`);
+	return cap(decodeBlock(res.stdout, OUT_MARKER)).text;
+}
+
+export async function writeWorkspaceFile(
+	row: InstanceRow,
+	path: string,
+	content: string
+): Promise<void> {
+	const bytes = Buffer.byteLength(content, 'utf8');
+	if (bytes > WRITE_FILE_MAX_BYTES) {
+		throw new Error(
+			`content is ${bytes} bytes; write_file carries at most ${WRITE_FILE_MAX_BYTES} — split it, or ` +
+				'build the file inside the sandbox with exec_command'
+		);
+	}
+	const script =
+		workspacePrelude(row) +
+		`set -e; mkdir -p "$(dirname "$1")"; printf '%s' "$CODEBAY_STDIN" | base64 -d > "$1"`;
+	const res = await execInContainer(execTargetFor(row), {
+		script,
+		args: ['write-file', path],
+		stdin: Buffer.from(content, 'utf8').toString('base64'),
+		timeoutMs: 30_000
+	});
+	if (!res.ok) throw new Error(res.error ?? 'could not write the file');
+}
+
+export interface DiffResult {
+	diff: string;
+	status: string;
+	branch: string;
+	truncated: boolean;
+}
+
+/** `--stat`-free full patch plus a porcelain summary, which is what an agent usually wants next. */
+export async function gitDiff(
+	row: InstanceRow,
+	opts: { base?: string; staged?: boolean } = {}
+): Promise<DiffResult> {
+	const range = opts.base ? ` ${quote(opts.base)}...HEAD` : opts.staged ? ' --staged' : '';
+	const [diff, status, branch] = await Promise.all([
+		execCommand(row, `git --no-pager diff${range}`),
+		execCommand(row, 'git status --short'),
+		execCommand(row, 'git rev-parse --abbrev-ref HEAD')
+	]);
+	if (diff.exitCode !== 0) throw new Error((diff.stderr || 'git diff failed').trim());
+	return {
+		diff: diff.stdout,
+		status: status.stdout,
+		branch: branch.stdout.trim(),
+		truncated: diff.truncated
+	};
+}
+
+export interface PushResult {
+	branch: string;
+	committed: boolean;
+	output: string;
+}
+
+/**
+ * The `github-credentials` injection has already authed git and `gh` inside the container, so this
+ * is a plain push — nothing here handles credentials.
+ */
+export async function gitPush(
+	row: InstanceRow,
+	opts: { branch?: string; commitMessage?: string; force?: boolean } = {}
+): Promise<PushResult> {
+	const current = (await must(row, 'git rev-parse --abbrev-ref HEAD')).trim();
+	const branch = opts.branch?.trim() || current;
+	if (!branch || branch === 'HEAD') {
+		throw new Error('the sandbox is on a detached HEAD — pass an explicit branch');
+	}
+
+	let committed = false;
+	if (opts.commitMessage) {
+		const dirty = await execCommand(row, 'git status --porcelain');
+		if (dirty.stdout.trim()) {
+			await must(row, `git add -A && git commit -m ${quote(opts.commitMessage)}`);
+			committed = true;
+		}
+	}
+
+	if (current !== branch) await must(row, `git checkout -B ${quote(branch)}`);
+
+	// --force-with-lease rather than --force: it still refuses to discard commits we never saw.
+	const force = opts.force ? ' --force-with-lease' : '';
+	const output = await must(
+		row,
+		`git push${force} -u origin HEAD:refs/heads/${quote(branch)} 2>&1`,
+		300
+	);
+	return { branch, committed, output: output.trim() };
+}
+
+export const PR_ATTRIBUTION_KEY = 'mcp_pr_attribution';
+
+/** The footer appended to an MCP-opened PR body when the setting is on. */
+export const PR_ATTRIBUTION =
+	'🤖 Written by Claude Code in a [Codebay](https://github.com/khromov/codebay) sandbox, driven over MCP.';
+
+/** Off unless explicitly enabled — an attribution line on someone's PR is theirs to opt into. */
+export function prAttributionEnabled(): boolean {
+	return getOption(PR_ATTRIBUTION_KEY) === '1';
+}
+
+/** Appends the footer, unless the body already carries it (a caller may have written its own). */
+export function withAttribution(body: string): string {
+	if (!prAttributionEnabled() || body.includes(PR_ATTRIBUTION)) return body;
+	return `${body.trimEnd()}\n\n---\n${PR_ATTRIBUTION}\n`;
+}
+
+export async function createPr(
+	row: InstanceRow,
+	opts: { title: string; body?: string; base?: string; draft?: boolean }
+): Promise<{ url: string }> {
+	const parts = [
+		'gh pr create',
+		`--title ${quote(opts.title)}`,
+		`--body ${quote(withAttribution(opts.body ?? ''))}`
+	];
+	if (opts.base) parts.push(`--base ${quote(opts.base)}`);
+	if (opts.draft) parts.push('--draft');
+	const out = await must(row, `${parts.join(' ')} 2>&1`, 300);
+	// gh prints the PR URL as its last line; anything else is progress chatter.
+	const url = out.trim().split('\n').filter(Boolean).at(-1) ?? '';
+	if (!url.startsWith('http')) throw new Error(out.trim() || 'gh did not return a PR url');
+	return { url };
+}