@miraland-labs/conduit-bridge 0.4.1 → 0.7.0

package/README.md

@@ -38,6 +38,8 @@ Persist (macOS/Linux):
 npx @miraland-labs/conduit-bridge install-service --agent <claude-code|codex|cursor|opencode|kiro|antigravity> --workspace /path/to/repo
 ```
 
+For a Start-created GitHub repo that is not checked out yet, point `--workspace` at the intended path and add `--ensure-checkout <https://github.com/…>` so Bridge clones with the machine’s Git credentials before the first heartbeat (never the control-plane PAT).
+
 ## Grant enforcement
 
 Every driver enforces the assignment's granted actions with its CLI's native mechanism — never just the prompt:
@@ -47,7 +49,7 @@ Every driver enforces the assignment's granted actions with its CLI's native mec
 | `claude-code` | pump or local | `--allowedTools` / `--disallowedTools` per grant; bounded verification commands |
 | `codex` | pump or local | sandbox `read-only` / `workspace-write`; network enabled only with `pr_create`; resumes by thread id |
 | `opencode` | pump or local | `plan`/`build` agents; per-run `opencode.json` bash deny list (shared `deniedCommands`); `--session` resume; `--format json` |
-| `cursor` | local only | per-run `.cursor/cli.json` allowlist (`approvalMode: allowlist`, shared deny list, no `--force`); read-only runs in `--mode plan` |
+| `cursor` | local only | per-run `.cursor/cli.json` `permissions` allow/deny (no `--force`); read-only runs in `--mode plan` |
 | `kiro` | local only | `--trust-tools=fs_read,fs_write,execute_bash` allowlist; `--no-interactive`; `--resume-id`. Tool-level only — no per-command scoping, so a bash grant trusts `execute_bash` wholesale (Antigravity-tier) |
 | `antigravity` | local only | `-p --mode plan` (read-only) / `--mode accept-edits --sandbox` (write). Mode-level, coarser than per-tool; plain-text output; resume not surfaced |
 

package/dist/attempt-worktree.js

@@ -0,0 +1,104 @@
+/**
+ * F-07 slice 1: one Git worktree per attempt. The install-service source checkout is never the
+ * agent cwd; retries must not inherit dirty files from a failed run.
+ */
+import { access, appendFile, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export function attemptWorktreePath(sourceWorkspace, attemptId) {
+    return join(sourceWorkspace, ".conduit", "attempts", attemptId);
+}
+export async function ensureConduitExclude(sourceWorkspace) {
+    const excludePath = join(sourceWorkspace, ".git", "info", "exclude");
+    await mkdir(join(sourceWorkspace, ".git", "info"), { recursive: true });
+    let existing = "";
+    try {
+        existing = await readFile(excludePath, "utf8");
+    }
+    catch {
+        existing = "";
+    }
+    if (existing.split("\n").some((line) => line.trim() === ".conduit/" || line.trim() === ".conduit"))
+        return;
+    const prefix = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+    await appendFile(excludePath, `${prefix}# Conduit Bridge attempt worktrees (F-07)\n.conduit/\n`, "utf8");
+}
+export async function assertSourceWorkspaceClean(sourceWorkspace) {
+    const { stdout } = await execFileAsync("git", ["-C", sourceWorkspace, "status", "--porcelain"], {
+        timeout: 30_000,
+        maxBuffer: 2_000_000,
+    });
+    if (stdout.trim().length > 0) {
+        throw new Error("source_workspace_dirty");
+    }
+}
+export async function createAttemptWorktree(input) {
+    await ensureConduitExclude(input.sourceWorkspace);
+    await assertSourceWorkspaceClean(input.sourceWorkspace);
+    const path = attemptWorktreePath(input.sourceWorkspace, input.attemptId);
+    await mkdir(join(input.sourceWorkspace, ".conduit", "attempts"), { recursive: true });
+    await execFileAsync("git", ["-C", input.sourceWorkspace, "worktree", "add", "--detach", path, input.startCommit], { timeout: 60_000, maxBuffer: 2_000_000 });
+    return path;
+}
+export async function removeAttemptWorktree(sourceWorkspace, worktreePath) {
+    try {
+        await execFileAsync("git", ["-C", sourceWorkspace, "worktree", "remove", "--force", worktreePath], { timeout: 60_000, maxBuffer: 2_000_000 });
+    }
+    catch {
+        await rm(worktreePath, { recursive: true, force: true }).catch(() => undefined);
+        await execFileAsync("git", ["-C", sourceWorkspace, "worktree", "prune"], {
+            timeout: 30_000,
+            maxBuffer: 1_000_000,
+        }).catch(() => undefined);
+    }
+}
+/**
+ * F-07 safe resume: prove the interrupted attempt still owns this worktree path.
+ * Does not check session identity — caller requires config.sessions[taskId] separately.
+ */
+export async function proveResumeWorktree(sourceWorkspace, attemptId, worktreePath) {
+    if (!worktreePath?.trim())
+        return false;
+    const expected = attemptWorktreePath(sourceWorkspace, attemptId);
+    if (resolve(worktreePath) !== resolve(expected))
+        return false;
+    try {
+        await access(worktreePath, constants.F_OK);
+        const { stdout } = await execFileAsync("git", ["-C", worktreePath, "rev-parse", "HEAD"], {
+            timeout: 15_000,
+            maxBuffer: 1_000_000,
+        });
+        return /^[0-9a-f]{40,64}$/i.test(stdout.trim());
+    }
+    catch {
+        return false;
+    }
+}
+/** Hold a crashed attempt tree for local diagnosis; never reused as agent cwd. */
+export async function quarantineAttemptWorktree(sourceWorkspace, worktreePath, attemptId) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const dest = join(sourceWorkspace, ".conduit", "quarantine", `${attemptId}-${stamp}`);
+    await mkdir(join(sourceWorkspace, ".conduit", "quarantine"), { recursive: true });
+    try {
+        await execFileAsync("git", ["-C", sourceWorkspace, "worktree", "remove", "--force", worktreePath], { timeout: 60_000, maxBuffer: 2_000_000 });
+        return null;
+    }
+    catch {
+        try {
+            await rename(worktreePath, dest);
+            await execFileAsync("git", ["-C", sourceWorkspace, "worktree", "prune"], {
+                timeout: 30_000,
+                maxBuffer: 1_000_000,
+            }).catch(() => undefined);
+            await writeFile(join(dest, ".conduit-quarantine.json"), `${JSON.stringify({ attemptId, at: stamp })}\n`, "utf8");
+            return dest;
+        }
+        catch {
+            await removeAttemptWorktree(sourceWorkspace, worktreePath);
+            return null;
+        }
+    }
+}

package/dist/brief.js

@@ -1,5 +1,8 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
 const MANIFESTS = ["package.json", "wrangler.jsonc", "wrangler.toml", "tsconfig.json", "Cargo.toml", "pyproject.toml", "go.mod", "Makefile"];
 const VERIFICATION_SCRIPTS = ["verify", "typecheck", "lint", "test", "build"];
 const EXCLUDED_DIRECTORIES = new Set(["node_modules", "dist", "build", "target", "coverage"]);
@@ -25,6 +28,21 @@ export function normalizeRepositoryUrl(url) {
         value = `https://${ssh[1]}/${ssh[2]}`;
     return value.replace(/^https?:\/\//, "").replace(/^ssh:\/\/(git@)?/, "");
 }
+export async function isBaseCommitAncestor(workspace, baseCommit, headCommit) {
+    try {
+        await execFileAsync("git", ["-C", workspace, "merge-base", "--is-ancestor", baseCommit, headCommit], {
+            timeout: 10_000,
+            windowsHide: true,
+        });
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 1 || code === "1")
+            return false;
+        throw error;
+    }
+}
 async function gitRemoteUrl(workspace) {
     try {
         const { common } = await gitDirectories(workspace);
@@ -39,20 +57,28 @@ async function gitRemoteUrl(workspace) {
 async function gitHeadCommit(workspace) {
     try {
         const { worktree, common } = await gitDirectories(workspace);
-        const head = (await readFile(join(worktree, "HEAD"), "utf8")).trim();
-        if (/^[0-9a-f]{40,64}$/i.test(head))
-            return head;
-        const ref = head.match(/^ref:\s*(\S+)$/)?.[1];
-        if (!ref)
-            return null;
-        try {
-            return (await readFile(join(common, ref), "utf8")).trim();
-        }
-        catch {
-            const packed = await readFile(join(common, "packed-refs"), "utf8");
-            const line = packed.split("\n").find((entry) => entry.endsWith(` ${ref}`));
-            return line?.split(" ")[0] ?? null;
+        let head = String(await readFile(join(worktree, "HEAD"), "utf8")).trim();
+        // Follow one level of symbolic refs (HEAD → refs/heads/main, or a nested ref file).
+        for (let hop = 0; hop < 3; hop++) {
+            if (/^[0-9a-f]{40,64}$/i.test(head))
+                return head.toLowerCase();
+            const ref = head.match(/^ref:\s*(\S+)$/)?.[1];
+            if (!ref)
+                return null;
+            try {
+                head = String(await readFile(join(common, ref), "utf8")).trim();
+            }
+            catch {
+                const packed = String(await readFile(join(common, "packed-refs"), "utf8"));
+                const line = packed.split("\n").find((entry) => {
+                    const trimmed = entry.trim();
+                    return trimmed.length > 0 && !trimmed.startsWith("#") && !trimmed.startsWith("^") && trimmed.endsWith(` ${ref}`);
+                });
+                const sha = line?.split(/\s+/)[0]?.trim() ?? null;
+                return sha && /^[0-9a-f]{40,64}$/i.test(sha) ? sha.toLowerCase() : null;
+            }
         }
+        return null;
     }
     catch {
         return null;
@@ -73,13 +99,22 @@ async function gitDirectories(workspace) {
     }
 }
 async function verificationCommands(workspace, files) {
-    if (!files.has("package.json"))
-        return [];
-    try {
-        const manifest = JSON.parse(await readFile(join(workspace, "package.json"), "utf8"));
-        return VERIFICATION_SCRIPTS.filter((name) => manifest.scripts?.[name]).map((name) => `npm run ${name}`);
+    const commands = [];
+    if (files.has("package.json")) {
+        try {
+            const manifest = JSON.parse(await readFile(join(workspace, "package.json"), "utf8"));
+            commands.push(...VERIFICATION_SCRIPTS.filter((name) => manifest.scripts?.[name]).map((name) => `npm run ${name}`));
+        }
+        catch { /* malformed manifests do not broaden execution */ }
     }
-    catch {
-        return [];
+    if (files.has("Makefile")) {
+        try {
+            const makefile = await readFile(join(workspace, "Makefile"), "utf8");
+            for (const target of ["check", "test"])
+                if (new RegExp(`^${target}\\s*:`, "m").test(makefile))
+                    commands.push(`make ${target}`);
+        }
+        catch { /* unreadable Makefiles do not broaden execution */ }
     }
+    return commands;
 }

package/dist/checkout.js

@@ -0,0 +1,95 @@
+/**
+ * Explicit Bridge checkout provisioning (F-07 ensure-checkout).
+ *
+ * Clones a remote into --workspace when the path is absent, using the operator machine's
+ * existing Git credentials (SSH agent / credential helper). Never uses the control-plane
+ * GitHub PAT. Does not overwrite an existing checkout.
+ */
+import { access, mkdir, readdir } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { normalizeRepositoryUrl } from "./brief.js";
+const execFileAsync = promisify(execFile);
+async function pathExists(path, accessFn) {
+    try {
+        await accessFn(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function gitOriginUrl(workspace, exec) {
+    try {
+        const { stdout } = await exec("git", ["-C", workspace, "config", "--get", "remote.origin.url"], {
+            timeout: 15_000,
+            maxBuffer: 1_000_000,
+        });
+        const value = stdout.trim();
+        return value.length > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ensure `workspace` is a checkout of `repositoryUrl`.
+ *
+ * - Missing path → `git clone` into that path (parent dirs created).
+ * - Existing matching origin → no-op.
+ * - Existing mismatched or non-git path → throw (never overwrite).
+ */
+export async function ensureCheckout(workspace, repositoryUrl, deps = {}) {
+    const exec = deps.execFile ?? execFileAsync;
+    const accessFn = deps.access ?? access;
+    const mkdirFn = deps.mkdir ?? mkdir;
+    const readdirFn = deps.readdir ?? readdir;
+    const wanted = normalizeRepositoryUrl(repositoryUrl);
+    if (!wanted)
+        throw new Error("ensure_checkout_invalid_url");
+    const exists = await pathExists(workspace, accessFn);
+    if (!exists) {
+        await mkdirFn(dirname(workspace), { recursive: true });
+        try {
+            await exec("git", ["clone", "--", repositoryUrl, workspace], {
+                timeout: 300_000,
+                maxBuffer: 2_000_000,
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : "clone_failed";
+            throw new Error(`ensure_checkout_clone_failed:${detail}`);
+        }
+        const origin = await gitOriginUrl(workspace, exec);
+        if (!origin || normalizeRepositoryUrl(origin) !== wanted) {
+            throw new Error("ensure_checkout_clone_mismatch");
+        }
+        return "cloned";
+    }
+    const entries = await readdirFn(workspace).catch(() => null);
+    if (entries === null)
+        throw new Error("ensure_checkout_path_unreadable");
+    if (entries.length === 0) {
+        try {
+            await exec("git", ["clone", "--", repositoryUrl, workspace], {
+                timeout: 300_000,
+                maxBuffer: 2_000_000,
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : "clone_failed";
+            throw new Error(`ensure_checkout_clone_failed:${detail}`);
+        }
+        return "cloned";
+    }
+    const origin = await gitOriginUrl(workspace, exec);
+    if (!origin) {
+        throw new Error("ensure_checkout_path_occupied");
+    }
+    if (normalizeRepositoryUrl(origin) !== wanted) {
+        throw new Error(`ensure_checkout_origin_mismatch:${normalizeRepositoryUrl(origin)}`);
+    }
+    return "already_present";
+}

package/dist/cli.js

@@ -1,17 +1,30 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
-import { resolve } from "node:path";
+import { resolve, dirname, join as pathJoin } from "node:path";
 import { hostname, userInfo } from "node:os";
 import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { ConduitClient } from "./client.js";
-import { clearPendingConnection, loadConfig, loadConfigIfPresent, loadOrCreateInstallationId, loadPendingConnection, redactSecrets, saveConfig, savePendingConnection, suggestMachineName, } from "./config.js";
+import { BRIDGE_LEASE_CAPACITY, BRIDGE_MAX_LEASE_CAPACITY, clampLeaseCapacity, clearPendingConnection, loadConfig, loadConfigIfPresent, loadOrCreateInstallationId, loadPendingConnection, redactSecrets, saveConfig, savePendingConnection, suggestMachineName, } from "./config.js";
 import { runMcp } from "./mcp.js";
-import { detectInstalledClients } from "./detect.js";
+import { detectInstalledClients, localFuelOnlyClients, suggestFuelSource } from "./detect.js";
 import { DRIVERS } from "./driver.js";
 import { buildWorkspaceBrief } from "./brief.js";
-import { executeNextAssignment, renewLeases } from "./execution.js";
+import { ensureCheckout } from "./checkout.js";
+import { pumpExecutionSlots, renewLeases } from "./execution.js";
 import { installRunnerService, uninstallRunnerService } from "./service.js";
 const [command] = process.argv.slice(2);
+/** Read our own package version so every runner start logs exactly which build is live. */
+function bridgeVersion() {
+    try {
+        const packagePath = pathJoin(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        return JSON.parse(readFileSync(packagePath, "utf8")).version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 /** Install-free form shown in help/output so clean laptops never need `conduit` on PATH. */
 const BRIDGE_NPX = "npx @miraland-labs/conduit-bridge";
 function bridgeUsage(...args) {
@@ -78,15 +91,20 @@ async function join() {
         const operatorName = values.operator?.trim() || userInfo().username;
         const machineName = values.machine?.trim() || suggestMachineName(hostname(), installationId);
         const capabilities = values.capability?.map((item) => item.trim()).filter(Boolean) ?? ["implement"];
-        const leaseCapacity = values.capacity ? Number(values.capacity) : 1;
+        const requestedCapacity = values.capacity ? Number(values.capacity) : BRIDGE_LEASE_CAPACITY;
+        if (!Number.isInteger(requestedCapacity) || requestedCapacity < 1 || requestedCapacity > BRIDGE_MAX_LEASE_CAPACITY) {
+            throw new Error(`--capacity must be an integer from 1 to ${BRIDGE_MAX_LEASE_CAPACITY} (concurrent attempt slots)`);
+        }
+        const leaseCapacity = clampLeaseCapacity(requestedCapacity);
         console.log("\nRequesting a Conduit connection:");
         console.log(`Operator: ${operatorName}`);
         console.log(`Computer: ${machineName}`);
+        const plannedFuel = fuelSource ?? suggestFuelSource(detected);
         console.log(`Detected local clients: ${detected.join(", ") || "none"}`);
         console.log(`Proposed roles: ${capabilities.join(", ")}`);
         console.log(`Assignments at once: ${leaseCapacity}`);
-        if (fuelSource)
-            console.log(`Fuel source: ${fuelSource === "local" ? "local subscription" : "Conduit pump"}`);
+        console.log(`Fuel source: ${plannedFuel === "local" ? "local subscription" : "Conduit pump"}`
+            + (!fuelSource && plannedFuel === "local" ? " (auto: only Cursor/Kiro/Antigravity detected)" : ""));
         console.log(`Execution drivers: ${Object.keys(DRIVERS).join(", ")} (cursor/kiro/antigravity require local fuel).`);
         console.log("Use --machine <name> to override the computer label.\n");
         const response = await fetch(`${baseUrl}/runner/v1/connect/requests`, {
@@ -121,6 +139,7 @@ async function join() {
     console.log("Waiting for a project owner to approve. You may close this terminal and run `conduit join --resume` later.\n");
     if (!values["no-open"])
         openUrl(pending.verificationUrl);
+    // Explicit --fuel wins; otherwise finishConnection re-detects and may default to local.
     await waitForConnection(pending, fuelSource);
 }
 function normalizeBaseUrl(value) {
@@ -165,6 +184,9 @@ async function finishConnection(baseUrl, data, fuelSource) {
         if (row.project_id && row.gateway_secret)
             fuel[row.project_id] = { gatewayKey: row.gateway_secret };
     }
+    const detected = await detectInstalledClients();
+    const resolvedFuel = fuelSource ?? suggestFuelSource(detected);
+    const fuelAutoLocal = fuelSource === undefined && resolvedFuel === "local";
     const config = {
         baseUrl,
         organizationId: String(data.organization_id),
@@ -172,9 +194,9 @@ async function finishConnection(baseUrl, data, fuelSource) {
         runnerKey: String(data.runner_secret),
         capabilities: data.capabilities,
         grants: data.grants,
-        leaseCapacity: Number(data.lease_capacity),
+        leaseCapacity: clampLeaseCapacity(data.lease_capacity),
         activeAttempts: {},
-        fuelSource: fuelSource ?? "conduit",
+        fuelSource: resolvedFuel,
         ...(Object.keys(fuel).length ? { fuel } : {}),
     };
     await saveConfig(config);
@@ -186,13 +208,17 @@ async function finishConnection(baseUrl, data, fuelSource) {
     catch {
         heartbeatOk = false;
     }
-    const detected = await detectInstalledClients();
     console.log(`Connected machine: ${config.machineId}`);
     console.log(heartbeatOk ? "Runner credential and heartbeat: OK" : "Runner credential saved; heartbeat will retry when the runner starts");
     console.log(`Detected local clients: ${detected.join(", ") || "none"}`);
     console.log(`Confirmed capabilities (matching): ${config.capabilities.join(", ") || "none"}`);
     console.log(`Allowed actions: ${config.grants.join(", ") || "none"}`);
-    console.log(`Fuel source: ${config.fuelSource === "local" ? "local subscription" : "Conduit pump"}`);
+    console.log(`Fuel source: ${config.fuelSource === "local" ? "local subscription" : "Conduit pump"}`
+        + (fuelAutoLocal ? " (auto: only Cursor/Kiro/Antigravity detected)" : ""));
+    const localOnly = localFuelOnlyClients(detected);
+    if (config.fuelSource === "conduit" && localOnly.length) {
+        console.log(`Note: ${localOnly.join(", ")} cannot use Conduit pump. Before --agent cursor|kiro|antigravity run: ${bridgeUsage("fuel", "local")}`);
+    }
     console.log("Heartbeats report capabilities for diagnostics only; matching uses the Connect confirmation. Detected clients never receive grants automatically.");
     console.log(`MCP setup: {"mcpServers":{"conduit":{"command":"npx","args":["-y","@miraland-labs/conduit-bridge","mcp"]}}}`);
     console.log(`Execute work: ${bridgeUsage("runner", "--agent", AGENT_PLACEHOLDER, "--workspace", "<repo>")}`);
@@ -223,18 +249,27 @@ async function installService() {
     await loadConfig();
     const { values } = parseArgs({ args: process.argv.slice(3), options: {
             agent: { type: "string" }, workspace: { type: "string" }, interval: { type: "string" }, "agent-timeout-minutes": { type: "string" },
+            "ensure-checkout": { type: "string" },
         } });
     if (!values.agent || !values.workspace) {
-        throw new Error(`Usage: ${bridgeUsage("install-service", "--agent", AGENT_PLACEHOLDER, "--workspace", "<repository-path>")} (agent + workspace required; heartbeat-only services are not supported)`);
+        throw new Error(`Usage: ${bridgeUsage("install-service", "--agent", AGENT_PLACEHOLDER, "--workspace", "<repository-path>", "[--ensure-checkout <repository-url>]")} (agent + workspace required; heartbeat-only services are not supported)`);
     }
     if (!DRIVERS[values.agent]) {
         throw new Error(`Unknown agent driver: ${values.agent}. Available: ${Object.keys(DRIVERS).join(", ")}`);
     }
+    const workspace = resolve(values.workspace);
+    if (values["ensure-checkout"]) {
+        const result = await ensureCheckout(workspace, values["ensure-checkout"]);
+        console.log(result === "cloned"
+            ? `Cloned ${values["ensure-checkout"]} into ${workspace}`
+            : `Workspace already matches ${values["ensure-checkout"]}`);
+    }
     const result = await installRunnerService({
         agent: values.agent,
-        workspace: resolve(values.workspace),
+        workspace,
         interval: values.interval,
         agentTimeoutMinutes: values["agent-timeout-minutes"],
+        ensureCheckout: values["ensure-checkout"],
     });
     console.log(`Installed Conduit runner service (${result.platform}): ${result.path}`);
     console.log("The runner keeps executing after this terminal closes. Laptop sleep still pauses work.");
@@ -258,7 +293,7 @@ async function fuelCommand() {
 async function runner() {
     const { values } = parseArgs({ args: process.argv.slice(3), options: {
             agent: { type: "string" }, workspace: { type: "string" }, interval: { type: "string" }, once: { type: "boolean" },
-            "agent-timeout-minutes": { type: "string" }, fuel: { type: "string" },
+            "agent-timeout-minutes": { type: "string" }, fuel: { type: "string" }, "ensure-checkout": { type: "string" },
         } });
     const config = await loadConfig();
     const fuelOverride = parseFuelSource(values.fuel);
@@ -275,7 +310,16 @@ async function runner() {
         if (!values.workspace)
             throw new Error("--workspace <repository-path> is required with --agent");
     }
+    if (values["ensure-checkout"] && !values.workspace) {
+        throw new Error("--ensure-checkout requires --workspace <repository-path>");
+    }
     const workspace = values.workspace ? resolve(values.workspace) : null;
+    if (workspace && values["ensure-checkout"]) {
+        const result = await ensureCheckout(workspace, values["ensure-checkout"]);
+        console.log(result === "cloned"
+            ? `Cloned ${values["ensure-checkout"]} into ${workspace}`
+            : `Workspace already matches ${values["ensure-checkout"]}`);
+    }
     const brief = workspace ? await buildWorkspaceBrief(workspace) : null;
     const intervalMs = values.interval ? Math.max(5_000, Number(values.interval)) : 15_000;
     const timeoutMs = values["agent-timeout-minutes"] ? Number(values["agent-timeout-minutes"]) * 60_000 : undefined;
@@ -283,21 +327,28 @@ async function runner() {
     if (!driver || !workspace) {
         console.warn(`WARNING: heartbeat only — no work will execute. Use: ${bridgeUsage("runner", "--agent", AGENT_PLACEHOLDER, "--workspace", "<repo>")}`);
     }
-    console.log(`Conduit runner connected to ${config.baseUrl}${driver ? ` — executing via ${driver.name} in ${workspace}` : " — heartbeat only (no --agent)"} (fuel: ${fuelLabel})`);
+    console.log(`Conduit runner (bridge v${bridgeVersion()}) connected to ${config.baseUrl}${driver ? ` — executing via ${driver.name} in ${workspace}` : " — heartbeat only (no --agent)"} (fuel: ${fuelLabel}; slots: ${config.leaseCapacity})`);
+    const running = new Map();
     for (;;) {
-        let executed = false;
+        let progressed = false;
         try {
             await heartbeat(client, config, workspace ? await buildWorkspaceBrief(workspace).catch(() => brief) : null);
             await renewLeases(client, config);
             if (driver && workspace) {
-                executed = await executeNextAssignment(client, config, driver, workspace, brief, timeoutMs);
+                progressed = await pumpExecutionSlots(client, config, driver, workspace, brief, timeoutMs, {
+                    heartbeat: async () => heartbeat(client, config, await buildWorkspaceBrief(workspace).catch(() => brief)),
+                    heartbeatIntervalMs: intervalMs,
+                }, running);
             }
         }
         catch (error) {
             console.error(`Runner cycle failed; retrying: ${redactSecrets(error instanceof Error ? error.message : "unknown error")}`);
         }
-        if (values.once && executed)
+        if (values.once && progressed) {
+            if (running.size)
+                await Promise.allSettled([...running.values()]);
             return;
+        }
         await new Promise((resolveSleep) => setTimeout(resolveSleep, intervalMs));
     }
 }

package/dist/client.js

@@ -44,7 +44,13 @@ export class ConduitClient {
     }
     async updateAttempt(taskId, patch) {
         const active = this.attempt(taskId);
-        Object.assign(active, patch);
+        for (const key of Object.keys(patch)) {
+            const value = patch[key];
+            if (value === undefined)
+                delete active[key];
+            else
+                Object.assign(active, { [key]: value });
+        }
         await this.persist(this.config);
         return active;
     }

package/dist/config.js

@@ -1,8 +1,20 @@
 import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { randomBytes } from "node:crypto";
 import { homedir } from "node:os";
-import { join } from "node:path";
-const directory = join(homedir(), ".config", "conduit");
+import { join, resolve } from "node:path";
+/** Default when join omits --capacity. */
+export const BRIDGE_LEASE_CAPACITY = 1;
+/** Hard ceiling for truthful concurrent Bridge slots (one agent + worktree each). */
+export const BRIDGE_MAX_LEASE_CAPACITY = 4;
+export function clampLeaseCapacity(value) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isInteger(n) || n < 1)
+        return BRIDGE_LEASE_CAPACITY;
+    return Math.min(n, BRIDGE_MAX_LEASE_CAPACITY);
+}
+const directory = process.env.CONDUIT_BRIDGE_CONFIG_DIR?.trim()
+    ? resolve(process.env.CONDUIT_BRIDGE_CONFIG_DIR)
+    : join(homedir(), ".config", "conduit");
 const path = join(directory, "config.json");
 const pendingPath = join(directory, "pending-connect.json");
 const installationPath = join(directory, "installation.json");
@@ -36,6 +48,8 @@ export async function loadConfigIfPresent() {
         active.phase ??= "agent_running";
     if (config.fuelSource !== "local" && config.fuelSource !== "conduit")
         config.fuelSource = "conduit";
+    // Clamp to what concurrent slot workers can run (1..BRIDGE_MAX_LEASE_CAPACITY).
+    config.leaseCapacity = clampLeaseCapacity(config.leaseCapacity ?? BRIDGE_LEASE_CAPACITY);
     return config;
 }
 export async function saveConfig(config) {

package/dist/detect.js

@@ -11,6 +11,24 @@ const CLIENTS = [
     { command: "agy", label: "Antigravity" },
     { command: "code", label: "Visual Studio Code" },
 ];
+/** Agents Conduit /v1 pump fuel can drive today. */
+const PUMP_CAPABLE_LABELS = new Set(["Claude Code", "Codex CLI", "OpenCode"]);
+/** Agents that only accept vendor login — Bridge refuses Conduit pump for these drivers. */
+const LOCAL_FUEL_ONLY_LABELS = new Set(["Cursor Agent", "Cursor", "Kiro CLI", "Antigravity"]);
+export function localFuelOnlyClients(detected) {
+    return detected.filter((label) => LOCAL_FUEL_ONLY_LABELS.has(label));
+}
+/**
+ * Default join fuel when `--fuel` is omitted.
+ * Pump when any pump-capable client is present; local when only Cursor/Kiro/Antigravity are.
+ */
+export function suggestFuelSource(detected) {
+    const hasPumpCapable = detected.some((label) => PUMP_CAPABLE_LABELS.has(label));
+    const hasLocalOnly = localFuelOnlyClients(detected).length > 0;
+    if (!hasPumpCapable && hasLocalOnly)
+        return "local";
+    return "conduit";
+}
 export async function detectInstalledClients(pathValue = process.env.PATH ?? "", platform = process.platform) {
     const directories = pathValue.split(delimiter).filter(Boolean);
     const extensions = platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];