@pasko70/pibo 1.9.9 → 1.9.11

package/dist/compute/docker.js

@@ -0,0 +1,835 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { readFile, readdir, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { COMPUTE_RESOURCE_POLICY_LABELS, buildComputeResourcePolicyLabels, buildDockerResourcePolicyArgs, resolveComputeResourcePolicy, } from "./resource-policy.js";
+const execFileAsync = promisify(execFile);
+export const IMAGE_NAME = "pibo:latest";
+export const LABEL_ROLE = "pibo.compute.role";
+export const LABEL_CREATED_AT = "pibo.compute.createdAt";
+export const LABEL_HOLDER = "pibo.compute.holder";
+export const LABEL_WORKTREE = "pibo.compute.worktree";
+export const LABEL_WORKTREE_PATH = "pibo.compute.worktreePath";
+export const LABEL_PORT_BLOCK = "pibo.compute.portBlock";
+export const LABEL_TTL_SECONDS = "pibo.compute.ttlSeconds";
+export const LABEL_IDLE_SECONDS = "pibo.compute.idleSeconds";
+export const LABEL_LAST_USED_AT = "pibo.compute.lastUsedAt";
+export const LABEL_CLEANUP_STATE = "pibo.compute.cleanupState";
+export const LABEL_DIRTY_REASON = "pibo.compute.dirtyReason";
+export const LABEL_RALPH_JOB_ID = "pibo.ralph.jobId";
+export const LABEL_RALPH_RUN_ID = "pibo.ralph.runId";
+export async function dockerBuild(workspaceDir) {
+    const { stderr } = await execFileAsync("docker", ["build", "-t", IMAGE_NAME, "."], {
+        cwd: workspaceDir,
+        maxBuffer: 50 * 1024 * 1024,
+    });
+    if (stderr)
+        console.error(stderr);
+}
+export async function imageExists(name) {
+    try {
+        await execFileAsync("docker", ["inspect", "--type=image", name]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function getDependencyHash(workspaceDir) {
+    const hash = createHash("sha256");
+    const files = ["package.json", "package-lock.json", "Dockerfile"];
+    for (const file of files) {
+        try {
+            const content = await readFile(path.join(workspaceDir, file));
+            hash.update(content);
+        }
+        catch {
+            // file missing, skip
+        }
+    }
+    return hash.digest("hex");
+}
+export async function getSourceHash(workspaceDir) {
+    const hash = createHash("sha256");
+    const files = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" ||
+                    entry.name === ".git" ||
+                    entry.name === "dist" ||
+                    entry.name === ".pibo" ||
+                    entry.name === "plans" ||
+                    entry.name === "Reports") {
+                    continue;
+                }
+                await walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                if (entry.name.endsWith(".ts") ||
+                    entry.name.endsWith(".tsx") ||
+                    entry.name === "package.json" ||
+                    entry.name === "package-lock.json" ||
+                    entry.name === "Dockerfile") {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    await walk(workspaceDir);
+    files.sort();
+    for (const file of files) {
+        const content = await readFile(file);
+        hash.update(content);
+    }
+    return hash.digest("hex");
+}
+export async function shouldRebuild(workspaceDir, hashFile) {
+    const currentHash = await getSourceHash(workspaceDir);
+    try {
+        const savedHash = await readFile(hashFile, "utf-8");
+        return savedHash.trim() !== currentHash;
+    }
+    catch {
+        return true;
+    }
+}
+export async function shouldRebuildDeps(workspaceDir, hashFile) {
+    const currentHash = await getDependencyHash(workspaceDir);
+    try {
+        const savedHash = await readFile(hashFile, "utf-8");
+        return savedHash.trim() !== currentHash;
+    }
+    catch {
+        return true;
+    }
+}
+export async function saveHash(workspaceDir, hashFile) {
+    const hash = await getSourceHash(workspaceDir);
+    await mkdir(path.dirname(hashFile), { recursive: true });
+    await writeFile(hashFile, hash, "utf-8");
+}
+export async function saveDepHash(workspaceDir, hashFile) {
+    const hash = await getDependencyHash(workspaceDir);
+    await mkdir(path.dirname(hashFile), { recursive: true });
+    await writeFile(hashFile, hash, "utf-8");
+}
+const DEV_PORT_BASE = 4800;
+const DEV_PORT_BLOCK_SIZE = 10;
+async function findNextPortBlock() {
+    const { stdout } = await execFileAsync("docker", [
+        "ps",
+        "--filter",
+        `label=${LABEL_ROLE}=dev`,
+        "--format",
+        "{{.Labels}}",
+    ]);
+    const usedBlocks = new Set();
+    for (const line of stdout.trim().split("\n")) {
+        const match = line.match(/pibo\.compute\.portBlock=(\d+)/);
+        if (match)
+            usedBlocks.add(Number(match[1]));
+    }
+    let block = 0;
+    while (usedBlocks.has(block))
+        block++;
+    return block;
+}
+export const DEFAULT_COMPUTE_WORKER_TTL_SECONDS = 60 * 60;
+export const DEFAULT_COMPUTE_WORKER_IDLE_SECONDS = 30 * 60;
+export function resolveComputeWorkerLifecycle(options = {}, env = process.env) {
+    return {
+        ttlSeconds: positiveIntegerOption(options.ttlSeconds, env.PIBO_COMPUTE_TTL_SECONDS, DEFAULT_COMPUTE_WORKER_TTL_SECONDS),
+        idleSeconds: positiveIntegerOption(options.idleSeconds, env.PIBO_COMPUTE_IDLE_SECONDS, DEFAULT_COMPUTE_WORKER_IDLE_SECONDS),
+    };
+}
+const SAFE_RALPH_LABEL_VALUE = /^[A-Za-z0-9._:-]{1,128}$/;
+function safeRalphLabel(label, value) {
+    if (!value || !SAFE_RALPH_LABEL_VALUE.test(value))
+        return [];
+    return [`${label}=${value}`];
+}
+function buildComputeWorkerMetadataLabels(options) {
+    return [
+        `${LABEL_ROLE}=${options.role}`,
+        `${LABEL_CREATED_AT}=${options.createdAt}`,
+        `${LABEL_PORT_BLOCK}=${options.portBlock}`,
+        `${LABEL_TTL_SECONDS}=${options.ttlSeconds}`,
+        `${LABEL_IDLE_SECONDS}=${options.idleSeconds}`,
+        ...(options.holder ? [`${LABEL_HOLDER}=${options.holder}`] : []),
+        ...(options.worktree ? [`${LABEL_WORKTREE}=${options.worktree}`] : []),
+        ...(options.worktreePath ? [`${LABEL_WORKTREE_PATH}=${options.worktreePath}`] : []),
+        ...Object.entries(options.ports).map(([name, value]) => `pibo.compute.port.${name}=${value}`),
+        ...safeRalphLabel(LABEL_RALPH_JOB_ID, options.ralphJobId),
+        ...safeRalphLabel(LABEL_RALPH_RUN_ID, options.ralphRunId),
+    ];
+}
+function positiveIntegerOption(optionValue, envValue, fallback) {
+    if (typeof optionValue === "number" && Number.isInteger(optionValue) && optionValue > 0)
+        return optionValue;
+    if (envValue === undefined || envValue.trim() === "")
+        return fallback;
+    const parsed = Number(envValue);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+export async function createWorktree(repoDir, name) {
+    const worktreePath = path.join(repoDir, ".worktrees", name);
+    try {
+        await execFileAsync("git", ["worktree", "add", worktreePath, "-b", name], { cwd: repoDir });
+    }
+    catch (err) {
+        if (err.stderr?.includes("already exists")) {
+            // branch or worktree exists; try without -b
+            await execFileAsync("git", ["worktree", "add", worktreePath, name], { cwd: repoDir });
+        }
+        else {
+            throw err;
+        }
+    }
+    return worktreePath;
+}
+export function buildDevWorkerDockerRunArgs(options) {
+    const policy = options.policy ?? resolveComputeResourcePolicy();
+    const lifecycle = resolveComputeWorkerLifecycle(options);
+    return [
+        "run",
+        "-d",
+        "--name",
+        options.id,
+        ...buildDockerResourcePolicyArgs(policy),
+        "-e",
+        "PIBO_COMPUTE_WORKER=1",
+        "-e",
+        "PIBO_COMPUTE_WORKER_ROLE=dev",
+        "-p",
+        `127.0.0.1:${options.gatewayPort}:4789`,
+        "-p",
+        `127.0.0.1:${options.cdpPort}:56663`,
+        "-p",
+        `127.0.0.1:${options.webPort}:4788`,
+        "-p",
+        `127.0.0.1:${options.webUIPortChat}:4790`,
+        "-p",
+        `127.0.0.1:${options.webUIPortContext}:4791`,
+        "-v",
+        `${options.worktreePath}:/workspace`,
+        ...(options.hostNodeModules ? ["-v", `${options.hostNodeModules}:/workspace/node_modules`] : []),
+        "-w",
+        "/workspace",
+        ...buildComputeWorkerMetadataLabels({
+            role: "dev",
+            createdAt: options.createdAt,
+            holder: options.holder,
+            worktree: options.worktreeName,
+            worktreePath: options.worktreePath,
+            portBlock: String(options.block),
+            ports: {
+                gateway: String(options.gatewayPort),
+                cdp: String(options.cdpPort),
+                web: String(options.webPort),
+                chatUi: String(options.webUIPortChat),
+                contextUi: String(options.webUIPortContext),
+            },
+            ttlSeconds: lifecycle.ttlSeconds,
+            idleSeconds: lifecycle.idleSeconds,
+            ralphJobId: options.ralphJobId,
+            ralphRunId: options.ralphRunId,
+        }).flatMap((label) => ["--label", label]),
+        ...buildComputeResourcePolicyLabels(policy).flatMap((label) => ["--label", label]),
+        "--entrypoint",
+        "/bin/sh",
+        IMAGE_NAME,
+        "-c",
+        "tail -f /dev/null",
+    ];
+}
+export async function spawnDevWorker(options) {
+    const worktreePath = path.join(options.repoDir, ".worktrees", options.worktreeName);
+    await createWorktree(options.repoDir, options.worktreeName);
+    const block = await findNextPortBlock();
+    const base = DEV_PORT_BASE + block * DEV_PORT_BLOCK_SIZE;
+    const gatewayPort = base;
+    const cdpPort = base + 1;
+    const webPort = base + 2;
+    const webUIPortChat = base + 3;
+    const webUIPortContext = base + 4;
+    const id = `pibo-dev-${options.worktreeName}`;
+    const createdAt = new Date().toISOString();
+    // Mount host node_modules into the container so dependencies are immediately available
+    const hostNodeModules = path.join(options.repoDir, "node_modules");
+    let nodeModulesMount;
+    try {
+        const { stdout } = await execFileAsync("ls", ["-d", hostNodeModules]);
+        if (stdout.trim())
+            nodeModulesMount = hostNodeModules;
+    }
+    catch {
+        // host node_modules does not exist; skip mount
+    }
+    const args = buildDevWorkerDockerRunArgs({
+        id,
+        worktreePath,
+        worktreeName: options.worktreeName,
+        block,
+        gatewayPort,
+        cdpPort,
+        webPort,
+        webUIPortChat,
+        webUIPortContext,
+        createdAt,
+        holder: options.holder,
+        ttlSeconds: options.ttlSeconds,
+        idleSeconds: options.idleSeconds,
+        ralphJobId: options.ralphJobId,
+        ralphRunId: options.ralphRunId,
+        hostNodeModules: nodeModulesMount,
+    });
+    await execFileAsync("docker", args, { cwd: options.repoDir });
+    const host = await detectHost();
+    return {
+        id,
+        image: IMAGE_NAME,
+        gatewayHost: host,
+        gatewayPort,
+        cdpPort,
+        webPort,
+        webUIPortChat,
+        webUIPortContext,
+        connect: `docker exec -it ${id} bash`,
+        worktree: worktreePath,
+    };
+}
+export function buildWorkerDockerRunArgs(options) {
+    const policy = options.policy ?? resolveComputeResourcePolicy();
+    const lifecycle = resolveComputeWorkerLifecycle(options);
+    return [
+        "run",
+        "-d",
+        "--name",
+        options.id,
+        ...buildDockerResourcePolicyArgs(policy),
+        "-e",
+        "PIBO_COMPUTE_WORKER=1",
+        "-e",
+        "PIBO_COMPUTE_WORKER_ROLE=worker",
+        "-p",
+        "127.0.0.1::4789",
+        "-p",
+        "127.0.0.1::56663",
+        "-p",
+        "127.0.0.1::4788",
+        ...buildComputeWorkerMetadataLabels({
+            role: "worker",
+            createdAt: options.createdAt,
+            holder: options.holder,
+            worktree: options.worktreePath ? path.basename(options.worktreePath) : undefined,
+            worktreePath: options.worktreePath,
+            portBlock: "dynamic",
+            ports: { gateway: "4789", cdp: "56663", web: "4788" },
+            ttlSeconds: lifecycle.ttlSeconds,
+            idleSeconds: lifecycle.idleSeconds,
+            ralphJobId: options.ralphJobId,
+            ralphRunId: options.ralphRunId,
+        }).flatMap((label) => ["--label", label]),
+        ...buildComputeResourcePolicyLabels(policy).flatMap((label) => ["--label", label]),
+        IMAGE_NAME,
+        "gateway:web",
+    ];
+}
+export async function spawnWorker(options) {
+    const id = options.name || `pibo-worker-${Math.random().toString(36).slice(2, 10)}`;
+    const createdAt = new Date().toISOString();
+    const args = buildWorkerDockerRunArgs({
+        id,
+        createdAt,
+        holder: options.holder,
+        worktreePath: options.workspaceDir,
+        ttlSeconds: options.ttlSeconds,
+        idleSeconds: options.idleSeconds,
+        ralphJobId: options.ralphJobId,
+        ralphRunId: options.ralphRunId,
+    });
+    await execFileAsync("docker", args, { cwd: options.workspaceDir });
+    // Get assigned ports
+    const { stdout: port4789 } = await execFileAsync("docker", ["port", id, "4789"]);
+    const { stdout: port56663 } = await execFileAsync("docker", ["port", id, "56663"]);
+    const { stdout: port4788 } = await execFileAsync("docker", ["port", id, "4788"]);
+    const gatewayPort = parseHostPort(port4789);
+    const cdpPort = parseHostPort(port56663);
+    const webPort = parseHostPort(port4788);
+    // Detect host IP
+    const host = await detectHost();
+    return {
+        id,
+        image: IMAGE_NAME,
+        gatewayHost: host,
+        gatewayPort,
+        cdpPort,
+        webPort,
+        connect: `docker exec -it ${id} bash`,
+    };
+}
+function parseHostPort(dockerPortOutput) {
+    const lines = dockerPortOutput.trim().split("\n");
+    for (const line of lines) {
+        const parts = line.trim().split(":");
+        if (parts.length >= 2) {
+            const port = parseInt(parts[parts.length - 1], 10);
+            if (!Number.isNaN(port) && port > 0) {
+                return port;
+            }
+        }
+    }
+    return 0;
+}
+async function detectHost() {
+    try {
+        const { stdout } = await execFileAsync("hostname", ["-I"]);
+        const ips = stdout.trim().split(/\s+/);
+        const nonLocal = ips.find((ip) => !ip.startsWith("127."));
+        if (nonLocal)
+            return nonLocal;
+        return ips[0] || "127.0.0.1";
+    }
+    catch {
+        return "127.0.0.1";
+    }
+}
+export function parseDockerLabels(labelsStr) {
+    const labels = {};
+    for (const part of (labelsStr ?? "").split(",")) {
+        const index = part.indexOf("=");
+        if (index <= 0)
+            continue;
+        labels[part.slice(0, index)] = part.slice(index + 1);
+    }
+    return labels;
+}
+function numberLabel(value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function resourcePolicyFromLabels(labels) {
+    const policy = {};
+    if (labels[COMPUTE_RESOURCE_POLICY_LABELS.memory])
+        policy.memory = labels[COMPUTE_RESOURCE_POLICY_LABELS.memory];
+    if (labels[COMPUTE_RESOURCE_POLICY_LABELS.memorySwap])
+        policy.memorySwap = labels[COMPUTE_RESOURCE_POLICY_LABELS.memorySwap];
+    const pidsLimit = numberLabel(labels[COMPUTE_RESOURCE_POLICY_LABELS.pidsLimit]);
+    if (pidsLimit !== undefined)
+        policy.pidsLimit = pidsLimit;
+    if (labels[COMPUTE_RESOURCE_POLICY_LABELS.shmSize])
+        policy.shmSize = labels[COMPUTE_RESOURCE_POLICY_LABELS.shmSize];
+    if (labels[COMPUTE_RESOURCE_POLICY_LABELS.init])
+        policy.init = labels[COMPUTE_RESOURCE_POLICY_LABELS.init] === "true";
+    if (labels[COMPUTE_RESOURCE_POLICY_LABELS.restart] === "no")
+        policy.restart = "no";
+    if (labels[COMPUTE_RESOURCE_POLICY_LABELS.logDriver] === "json-file")
+        policy.logDriver = "json-file";
+    if (labels[COMPUTE_RESOURCE_POLICY_LABELS.logMaxSize])
+        policy.logMaxSize = labels[COMPUTE_RESOURCE_POLICY_LABELS.logMaxSize];
+    const logMaxFile = numberLabel(labels[COMPUTE_RESOURCE_POLICY_LABELS.logMaxFile]);
+    if (logMaxFile !== undefined)
+        policy.logMaxFile = logMaxFile;
+    return Object.keys(policy).length > 0 ? policy : undefined;
+}
+function portMapFromLabels(labels) {
+    const portMap = {};
+    for (const [key, value] of Object.entries(labels)) {
+        if (!key.startsWith("pibo.compute.port."))
+            continue;
+        portMap[key.slice("pibo.compute.port.".length)] = value;
+    }
+    return portMap;
+}
+function portMapFromInspectPorts(ports) {
+    const portMap = {};
+    if (!ports)
+        return portMap;
+    for (const [containerPort, bindings] of Object.entries(ports)) {
+        if (!bindings?.length)
+            continue;
+        portMap[containerPort] = bindings.map((binding) => `${binding.HostIp ?? ""}:${binding.HostPort ?? ""}`).join(",");
+    }
+    return portMap;
+}
+function cleanupEligibilityForWorker(worker) {
+    const reasons = [];
+    const normalizedState = worker.state.toLowerCase();
+    const stopped = ["exited", "dead", "created"].includes(normalizedState) || /^exited\b/i.test(worker.status);
+    if (worker.oomKilled)
+        reasons.push("oom-killed");
+    if (worker.cleanupState === "dirty" || worker.dirtyReason)
+        reasons.push("dirty");
+    if (stopped)
+        reasons.push("stopped");
+    if (normalizedState === "restarting")
+        reasons.push("restarting");
+    if (worker.role === "dev" && reasons.length > 0) {
+        return {
+            eligible: false,
+            reasons: ["dev-worker-preserved", ...reasons],
+            nextCommands: ["pibo compute reap --include-dev --max-age-minutes <n>"],
+        };
+    }
+    if (reasons.length === 0) {
+        return { eligible: false, reasons: ["running-or-retained"], nextCommands: ["pibo compute list --all --json"] };
+    }
+    return {
+        eligible: true,
+        reasons,
+        nextCommands: ["pibo compute reap --max-age-minutes <n>"],
+    };
+}
+function workerFromLabels(base) {
+    const role = base.labels[LABEL_ROLE] ?? base.fallbackRole ?? "unknown";
+    const portMap = portMapFromLabels(base.labels);
+    const worker = {
+        id: base.id,
+        name: base.name,
+        role,
+        state: base.state || stateFromStatus(base.status),
+        status: base.status ?? "",
+        ports: base.ports ?? "",
+        portMap,
+        hostPid: base.hostPid,
+        createdAt: base.labels[LABEL_CREATED_AT] ?? "unknown",
+        lastUsedAt: base.labels[LABEL_LAST_USED_AT],
+        holder: base.labels[LABEL_HOLDER],
+        worktree: base.labels[LABEL_WORKTREE],
+        worktreePath: base.labels[LABEL_WORKTREE_PATH],
+        ralphJobId: base.labels[LABEL_RALPH_JOB_ID],
+        ralphRunId: base.labels[LABEL_RALPH_RUN_ID],
+        cleanupState: base.labels[LABEL_CLEANUP_STATE],
+        dirtyReason: base.labels[LABEL_DIRTY_REASON],
+        oomKilled: base.oomKilled,
+        exitCode: base.exitCode,
+        resourcePolicy: resourcePolicyFromLabels(base.labels),
+        cleanupEligibility: { eligible: false, reasons: [], nextCommands: [] },
+    };
+    worker.cleanupEligibility = cleanupEligibilityForWorker(worker);
+    return worker;
+}
+function stateFromStatus(status) {
+    const lower = status.toLowerCase();
+    if (lower.startsWith("up"))
+        return "running";
+    if (lower.startsWith("exited"))
+        return "exited";
+    if (lower.includes("restarting"))
+        return "restarting";
+    if (lower.startsWith("created"))
+        return "created";
+    if (lower.startsWith("dead"))
+        return "dead";
+    return "unknown";
+}
+export function parseDockerWorkerListLine(line, fallbackRole) {
+    const [containerId, name, stateOrStatus, statusOrPorts, portsOrLabels, labelsMaybe] = line.split("\t");
+    if (!containerId || !name)
+        return undefined;
+    const hasStateColumn = labelsMaybe !== undefined;
+    const state = hasStateColumn ? stateOrStatus : stateFromStatus(stateOrStatus ?? "");
+    const status = hasStateColumn ? statusOrPorts : stateOrStatus;
+    const ports = hasStateColumn ? portsOrLabels : statusOrPorts;
+    const labels = parseDockerLabels(hasStateColumn ? labelsMaybe : portsOrLabels);
+    return workerFromLabels({ id: containerId, name, state: state ?? "unknown", status: status ?? "", ports: ports ?? "", labels, fallbackRole });
+}
+export function parseDockerWorkerInspect(value, fallback) {
+    const labels = value.Config?.Labels ?? {};
+    const role = labels[LABEL_ROLE] ?? fallback?.role;
+    if (!role)
+        return fallback;
+    const state = value.State?.Status ?? fallback?.state ?? "unknown";
+    const status = statusFromInspectState(value.State, fallback?.status ?? state);
+    const portMap = { ...portMapFromInspectPorts(value.NetworkSettings?.Ports), ...portMapFromLabels(labels) };
+    const worker = workerFromLabels({
+        id: value.Id ?? fallback?.id ?? "unknown",
+        name: (value.Name ?? fallback?.name ?? "unknown").replace(/^\//, ""),
+        state,
+        status,
+        ports: fallback?.ports ?? portsTextFromPortMap(portMap),
+        labels,
+        fallbackRole: role,
+        oomKilled: value.State?.OOMKilled,
+        exitCode: value.State?.ExitCode,
+        hostPid: value.State?.Pid,
+    });
+    worker.portMap = portMap;
+    if (value.Created && worker.createdAt === "unknown")
+        worker.createdAt = value.Created;
+    return worker;
+}
+function statusFromInspectState(state, fallback) {
+    if (!state)
+        return fallback;
+    if (state.Status === "running" && state.StartedAt)
+        return `running since ${state.StartedAt}`;
+    if (state.Status === "exited")
+        return `exited (${state.ExitCode ?? "unknown"})`;
+    if (state.Status)
+        return state.Status;
+    return fallback;
+}
+function portsTextFromPortMap(portMap) {
+    const entries = Object.entries(portMap);
+    return entries.length ? entries.map(([key, value]) => `${key}=${value}`).join(",") : "-";
+}
+async function enrichWorkersWithInspect(workers) {
+    if (workers.length === 0)
+        return workers;
+    try {
+        const { stdout } = await execFileAsync("docker", ["inspect", ...workers.map((worker) => worker.id)]);
+        const inspected = JSON.parse(stdout);
+        const fallbackById = new Map(workers.map((worker) => [worker.id, worker]));
+        const fallbackByName = new Map(workers.map((worker) => [worker.name, worker]));
+        return inspected.map((container) => parseDockerWorkerInspect(container, fallbackById.get(container.Id ?? "") ?? fallbackByName.get((container.Name ?? "").replace(/^\//, "")))).filter((worker) => Boolean(worker));
+    }
+    catch {
+        return workers;
+    }
+}
+export async function listWorkers(options = {}) {
+    const roles = options.includeDev === false ? ["worker"] : ["worker", "dev"];
+    const workers = [];
+    for (const role of roles) {
+        const { stdout } = await execFileAsync("docker", [
+            "ps",
+            ...(options.all ? ["--all"] : []),
+            "--filter",
+            `label=${LABEL_ROLE}=${role}`,
+            "--format",
+            "{{.ID}}\t{{.Names}}\t{{.State}}\t{{.Status}}\t{{.Ports}}\t{{.Labels}}",
+        ]);
+        if (!stdout.trim())
+            continue;
+        const lines = stdout.trim().split("\n");
+        for (const line of lines) {
+            const worker = parseDockerWorkerListLine(line, role);
+            if (worker)
+                workers.push(worker);
+        }
+    }
+    return enrichWorkersWithInspect(workers);
+}
+function isStoppedWorker(worker) {
+    const normalizedState = worker.state.toLowerCase();
+    return ["exited", "dead", "created"].includes(normalizedState) || /^exited\b/i.test(worker.status) || normalizedState === "restarting";
+}
+function isDirtyWorker(worker) {
+    return worker.cleanupState === "dirty" || Boolean(worker.dirtyReason) || worker.oomKilled === true;
+}
+export function buildComputeWorkerReapPlan(workers, options = {}) {
+    const now = options.now ?? new Date();
+    const maxAgeMinutes = options.maxAgeMinutes ?? 60;
+    const resolved = {
+        includeDev: options.includeDev === true,
+        includeStopped: options.includeStopped !== false,
+        includeDirty: options.includeDirty !== false,
+        maxAgeMinutes,
+    };
+    const items = workers.map((worker) => {
+        const reasons = [];
+        const skipReasons = [];
+        const created = new Date(worker.createdAt).getTime();
+        const ageMinutes = Number.isNaN(created) ? undefined : (now.getTime() - created) / 1000 / 60;
+        if (worker.role === "dev" && !resolved.includeDev)
+            skipReasons.push("dev-worker-preserved");
+        if (worker.role !== "worker" && worker.role !== "dev")
+            skipReasons.push("unsupported-role");
+        if (resolved.includeStopped && isStoppedWorker(worker))
+            reasons.push("stopped");
+        if (resolved.includeDirty && isDirtyWorker(worker))
+            reasons.push(worker.oomKilled ? "oom-killed" : "dirty");
+        if (ageMinutes !== undefined && ageMinutes > resolved.maxAgeMinutes)
+            reasons.push("old");
+        if (reasons.length === 0)
+            skipReasons.push("not-selected");
+        const action = skipReasons.length === 0 ? "remove" : "skip";
+        return {
+            worker,
+            action,
+            reasons,
+            skipReasons,
+            ageMinutes,
+            preservesWorktree: Boolean(worker.worktreePath),
+        };
+    });
+    return {
+        createdAt: now.toISOString(),
+        options: resolved,
+        items,
+        summary: {
+            selected: items.filter((item) => item.action === "remove").length,
+            skipped: items.filter((item) => item.action === "skip").length,
+            worktreesPreserved: items.filter((item) => item.action === "remove" && item.preservesWorktree).length,
+        },
+        nextCommands: [
+            "pibo compute reap --dry-run --max-age-minutes <n>",
+            "pibo compute reap --apply --max-age-minutes <n>",
+            "pibo compute list --all --json",
+        ],
+    };
+}
+export async function releaseWorker(id) {
+    try {
+        await execFileAsync("docker", ["stop", "-t", "10", id]);
+    }
+    catch {
+        // might already be stopped
+    }
+    await execFileAsync("docker", ["rm", id]);
+}
+export async function applyComputeWorkerReapPlan(plan, options = {}) {
+    const release = options.release ?? releaseWorker;
+    const removed = [];
+    for (const item of plan.items) {
+        if (item.action !== "remove")
+            continue;
+        await release(item.worker.name);
+        removed.push(item.worker.name);
+    }
+    return removed;
+}
+export async function planReapWorkers(options = {}) {
+    const workers = await listWorkers({ all: true });
+    return buildComputeWorkerReapPlan(workers, options);
+}
+export async function reapWorkers(maxAgeMinutes, options = {}) {
+    const plan = await planReapWorkers({ ...options, maxAgeMinutes });
+    return applyComputeWorkerReapPlan(plan);
+}
+function normalizeDockerSystemDfKind(type) {
+    const normalized = (type ?? "").trim().toLowerCase();
+    if (normalized === "images")
+        return "images";
+    if (normalized === "containers")
+        return "containers";
+    if (normalized === "local volumes" || normalized === "volumes")
+        return "localVolumes";
+    if (normalized === "build cache" || normalized === "buildkit cache")
+        return "buildCache";
+    return "unknown";
+}
+function parseOptionalNumber(value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+export function parseDockerSizeBytes(value) {
+    const match = (value ?? "").trim().match(/^([0-9]+(?:\.[0-9]+)?)\s*([a-zA-Z]+)?/);
+    if (!match)
+        return undefined;
+    const amount = Number(match[1]);
+    if (!Number.isFinite(amount))
+        return undefined;
+    const unit = (match[2] ?? "B").toLowerCase();
+    const multipliers = {
+        b: 1,
+        kb: 1000,
+        mb: 1000 ** 2,
+        gb: 1000 ** 3,
+        tb: 1000 ** 4,
+        kib: 1024,
+        mib: 1024 ** 2,
+        gib: 1024 ** 3,
+        tib: 1024 ** 4,
+    };
+    const multiplier = multipliers[unit];
+    if (!multiplier)
+        return undefined;
+    return Math.round(amount * multiplier);
+}
+export function parseDockerSystemDfLines(output) {
+    const rows = [];
+    for (const line of output.trim().split("\n")) {
+        if (!line.trim())
+            continue;
+        let raw;
+        try {
+            const parsed = JSON.parse(line);
+            raw = Object.fromEntries(Object.entries(parsed).map(([key, value]) => [key, String(value ?? "")]));
+        }
+        catch {
+            continue;
+        }
+        const label = raw.Type ?? raw.type ?? "unknown";
+        const size = raw.Size ?? raw.size ?? "";
+        const reclaimable = raw.Reclaimable ?? raw.reclaimable ?? "";
+        rows.push({
+            kind: normalizeDockerSystemDfKind(label),
+            label,
+            totalCount: parseOptionalNumber(raw.TotalCount ?? raw.totalCount),
+            active: parseOptionalNumber(raw.Active ?? raw.active),
+            size,
+            sizeBytes: parseDockerSizeBytes(size),
+            reclaimable,
+            reclaimableBytes: parseDockerSizeBytes(reclaimable),
+            raw,
+        });
+    }
+    return rows;
+}
+export function buildComputeDiskDiagnostics(rows, options = {}) {
+    const usage = {
+        images: undefined,
+        containers: undefined,
+        localVolumes: undefined,
+        buildCache: undefined,
+        unknown: undefined,
+    };
+    for (const row of rows) {
+        usage[row.kind] = row;
+    }
+    const sizeBytes = rows.reduce((sum, row) => row.sizeBytes === undefined ? sum : sum + row.sizeBytes, 0);
+    const reclaimableBytes = rows.reduce((sum, row) => row.reclaimableBytes === undefined ? sum : sum + row.reclaimableBytes, 0);
+    return {
+        generatedAt: (options.now ?? new Date()).toISOString(),
+        readOnly: true,
+        dockerAvailable: options.dockerAvailable !== false,
+        dockerError: options.dockerError,
+        usage,
+        rows,
+        totals: {
+            sizeBytes: rows.some((row) => row.sizeBytes !== undefined) ? sizeBytes : undefined,
+            reclaimableBytes: rows.some((row) => row.reclaimableBytes !== undefined) ? reclaimableBytes : undefined,
+        },
+        suggestions: [
+            {
+                kind: "container-cleanup",
+                reason: "Remove stopped, dirty, or old Pibo compute containers without deleting Git worktrees.",
+                nextCommands: ["pibo compute reap --dry-run --json", "pibo compute reap --apply --max-age-minutes <n>"],
+            },
+            {
+                kind: "image-cleanup",
+                reason: "Review unused Docker images separately from Pibo compute containers.",
+                nextCommands: ["docker image ls", "docker image prune"],
+            },
+            {
+                kind: "build-cache-prune",
+                reason: "Review BuildKit cache before pruning retained build layers.",
+                nextCommands: ["docker builder du", "docker builder prune"],
+            },
+            {
+                kind: "worktree-cleanup",
+                reason: "Clean Git worktrees explicitly; compute container cleanup does not remove them.",
+                nextCommands: ["git worktree list", "git worktree prune"],
+            },
+        ],
+    };
+}
+export async function getComputeDiskDiagnostics(options = {}) {
+    try {
+        const { stdout } = await execFileAsync("docker", ["system", "df", "--format", "{{json .}}"], { maxBuffer: 10 * 1024 * 1024 });
+        return buildComputeDiskDiagnostics(parseDockerSystemDfLines(stdout), { now: options.now, dockerAvailable: true });
+    }
+    catch (error) {
+        return buildComputeDiskDiagnostics([], { now: options.now, dockerAvailable: false, dockerError: String(error?.message ?? error) });
+    }
+}