@miraland-labs/conduit-bridge 0.16.25 → 0.16.27

package/README.md

@@ -2,7 +2,7 @@
 
 Local Bridge CLI for [Conduit](https://github.com/miralandlabs/conduit). Connects a computer to one organization, claims work, and drives a local agent.
 
-**Package version:** `0.16.21` — mutate_repo with `pr_create` opens a pull request even when `change_scope` is empty. `ops disconnect` now asks before it removes the runner service and clears credentials; pass `--yes` to skip the question. `ops.env` is enrollment/bootstrap defaults only: an explicit workspace does not inherit an old repository, and project switches do not rewrite global project state. `ops enroll` exchanges a single-use token, registers the machine, binds project affinity, provisions fuel keys, brings detected drivers online, and starts the runner in one command. On Linux, `ops install` refuses any effective systemd drop-in. A switch intent remains queued until the target runner heartbeat proves Bound. After every Bridge publish, operators must re-run `ops install` (LaunchAgent pins an absolute `cli.js`).
+**Package version:** `0.16.27` — work-package execution budgets reach every agent turn, are bounded by the machine ceiling, and expose their effective source for operations. Local-fuel provider refusals make the affected lane unavailable instead of repeatedly spending attempts; an operator who changes the lane's account or plan can invalidate that observation with `ops quota-clear <driver>`. Bridge discovers bounded repository verification commands, including Make targets `test`, `check`, `verify`, `replay`, `typecheck`, `lint`, and `build`. `ops disconnect` asks before it removes the runner service and clears credentials; pass `--yes` to skip the question. `ops.env` is enrollment/bootstrap defaults only: an explicit workspace does not inherit an old repository, and project switches do not rewrite global project state. `ops enroll` exchanges a single-use token, registers the machine, binds project affinity, provisions fuel keys, brings detected drivers online, and starts the runner in one command. On Linux, `ops install` refuses any effective systemd drop-in. A switch intent remains queued until the target runner heartbeat proves Bound. After every Bridge publish, operators must re-run `ops install` (LaunchAgent pins an absolute `cli.js`).
 
 ## Prerequisites
 
@@ -48,6 +48,7 @@ Later:
 ```bash
 npx @miraland-labs/conduit-bridge@latest ops online cursor
 npx @miraland-labs/conduit-bridge@latest ops offline cursor
+npx @miraland-labs/conduit-bridge@latest ops quota-clear cursor  # after changing its account or plan
 npx @miraland-labs/conduit-bridge@latest ops disconnect   # then join again to change organizations
 ```
 
@@ -78,8 +79,12 @@ npx @miraland-labs/conduit-bridge disconnect --yes
 Before agent spend, Bridge checks that the workspace is readable, matches the expected repository,
 and is clean; each online driver must be installed, compatible with its configured fuel, and signed
 in when local fuel is used. The same bounded report is sent on heartbeat so Conduit can place an
-environment failure on Hold without consuming an execution attempt. Fix the named issue and let a
-fresh heartbeat land before choosing **Recheck** in Activity.
+environment failure on Hold without consuming an execution attempt. A local provider refusal is
+persisted and excludes only that lane; `online`/`offline` does not erase it. `ops doctor` proves CLI
+installation and authentication, not remaining vendor allowance. After deliberately changing an
+account or plan, run `ops quota-clear <driver>` to clear the old observation; this does not probe the
+provider, and the next real claim records another refusal if the new allowance is still unavailable.
+Fix the named issue and let a fresh heartbeat land before choosing **Recheck** in Activity.
 
 Conduit labels an exact driver/CLI version **Certified** only after two consecutive real canaries:
 repository delivery with PR/evidence and a successful rework cycle. All other lanes are

package/dist/brief.js

@@ -2,6 +2,7 @@ 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";
+import { isBoundedVerificationCommand } from "./execution-class.js";
 const execFileAsync = promisify(execFile);
 const MANIFESTS = [
     "package.json", "wrangler.jsonc", "wrangler.toml", "tsconfig.json",
@@ -10,6 +11,7 @@ const MANIFESTS = [
 ];
 /** Prefer test before typecheck/lint so discovery order matches what pickVerificationCommand wants. */
 const VERIFICATION_SCRIPTS = ["test", "verify", "typecheck", "lint", "build"];
+const MAKE_VERIFICATION_TARGETS = ["test", "check", "verify", "replay", "typecheck", "lint", "build"];
 const EXCLUDED_DIRECTORIES = new Set(["node_modules", "dist", "build", "target", "coverage", ".venv", "venv"]);
 export async function buildWorkspaceBrief(workspace) {
     const entries = await readdir(workspace, { withFileTypes: true });
@@ -197,8 +199,40 @@ async function gitDirectories(workspace) {
     }
 }
 /** Exported for tests — discovers bounded verification commands from workspace manifests. */
+/**
+ * Commands a project declares for itself, in `.conduit/verification` — one per line, `#` comments
+ * ignored.
+ *
+ * Discovery below recognises the conventional names (`test`, `check`, `npm run verify`, …). A project
+ * whose gate is named anything else had no way to say so, and an acceptance criterion naming that
+ * gate was unrunnable and therefore unverifiable — which is how four agent attempts died on a target
+ * that was declared in the very Makefile Bridge had already read.
+ *
+ * The file is repository content and therefore UNTRUSTED. Every line must pass the same shape check
+ * every discovered command passes, so a declaration can name a gate but can never smuggle a command:
+ * one tool, one identifier, no shell metacharacters. That check is the boundary, not the name — a
+ * recipe body was always repository-authored.
+ */
+const MAX_DECLARED_VERIFICATION = 8;
+export function parseDeclaredVerification(text) {
+    const declared = [];
+    for (const raw of text.split("\n")) {
+        const line = raw.split("#")[0].trim();
+        if (!line || !isBoundedVerificationCommand(line))
+            continue;
+        if (!declared.includes(line))
+            declared.push(line);
+        if (declared.length >= MAX_DECLARED_VERIFICATION)
+            break;
+    }
+    return declared;
+}
 export async function discoverVerificationCommands(workspace, files) {
     const commands = [];
+    try {
+        commands.push(...parseDeclaredVerification(await readFile(join(workspace, ".conduit", "verification"), "utf8")));
+    }
+    catch { /* no declaration, or unreadable: discovery below still applies */ }
     if (files.has("package.json")) {
         try {
             const manifest = JSON.parse(await readFile(join(workspace, "package.json"), "utf8"));
@@ -209,9 +243,10 @@ export async function discoverVerificationCommands(workspace, files) {
     if (files.has("Makefile")) {
         try {
             const makefile = await readFile(join(workspace, "Makefile"), "utf8");
-            for (const target of ["test", "check"])
+            for (const target of MAKE_VERIFICATION_TARGETS) {
                 if (new RegExp(`^${target}\\s*:`, "m").test(makefile))
                     commands.push(`make ${target}`);
+            }
         }
         catch { /* unreadable Makefiles do not broaden execution */ }
     }

package/dist/cli.js

@@ -8,12 +8,13 @@ import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath } from "node:url";
 import { ConduitClient, ConduitRequestError } from "./client.js";
-import { BRIDGE_LEASE_CAPACITY, BRIDGE_MAX_LEASE_CAPACITY, clampLeaseCapacity, clearLocalConnection, clearPendingConnection, loadConfig, loadConfigIfPresent, loadOrCreateInstallationId, loadPendingConnection, redactSecrets, saveConfig, saveConfigPrefs, savePendingConnection, suggestMachineName, } from "./config.js";
+import { BRIDGE_LEASE_CAPACITY, BRIDGE_MAX_LEASE_CAPACITY, clampLeaseCapacity, clearLocalConnection, clearPendingConnection, loadConfig, loadConfigIfPresent, loadOrCreateInstallationId, loadPendingConnection, redactSecrets, saveConfig, saveConfigPrefs, saveDriverQuota, savePendingConnection, suggestMachineName, } from "./config.js";
 import { runMcp } from "./mcp.js";
 import { detectInstalledClients, localFuelOnlyClients, suggestFuelSource } from "./detect.js";
 import { DRIVERS } from "./driver.js";
-import { driversHeartbeatReport, driverLabel, heartbeatStatusForDrivers, isSupportedDriverId, listDriverLanes, onlineDriverIds, seedDriversFromDetection, seedDriverLanes, setDriverFuel, setDriversOnline, } from "./drivers.js";
+import { driversHeartbeatReport, driverLabel, heartbeatStatusForDrivers, isSupportedDriverId, listDriverLanes, onlineDriverIds, seedDriversFromDetection, seedDriverLanes, setDriverFuel, setDriversOnline, laneDispatchBlock, laneStatuses, } from "./drivers.js";
 import { buildWorkspaceBrief } from "./brief.js";
+import { parseAgentTimeoutMinutes } from "./execution-budget.js";
 import { BOOTSTRAP_RESULTS, buildSovereignExecutionFacts } from "./execution-facts.js";
 import { ensureCheckout } from "./checkout.js";
 import { buildOnShiftIntentProof, maybeApplyOnShiftIntent } from "./on-shift-apply.js";
@@ -382,7 +383,7 @@ async function initOps() {
     console.log(`Config file (separate): ${envPath}`);
     console.log("");
     console.log("Works the same on macOS, Linux, and Windows via:");
-    console.log(`  ${bridgeUsage("ops", "<connect|install|switch|online|offline|status|doctor|disconnect|uninstall>")}`);
+    console.log(`  ${bridgeUsage("ops", "<connect|install|switch|online|offline|quota-clear|status|doctor|disconnect|uninstall>")}`);
     console.log("");
     console.log("1. Set enrollment/bootstrap defaults once:");
     console.log(`   Create folder: ${configDir}`);
@@ -401,12 +402,12 @@ async function initOps() {
         console.log("3. Install runner:");
         console.log(`   ${pathJoin(target, "install.sh")}`);
     }
-    console.log("Later: status · online · offline · disconnect (same names .sh / .cmd)");
+    console.log("Later: status · online · offline · quota-clear · disconnect (same names .sh / .cmd)");
 }
 async function opsCommand() {
     const verb = process.argv[3];
     if (!verb || !OPS_VERBS.includes(verb)) {
-        throw new Error(`Usage: ${bridgeUsage("ops", "<connect|install|switch|online|offline|status|doctor|disconnect|uninstall>", "[driver…]")} (install also takes --workspace <path> [--repo <url>])`);
+        throw new Error(`Usage: ${bridgeUsage("ops", "<connect|install|switch|online|offline|quota-clear|status|doctor|disconnect|uninstall>", "[driver…]")} (install also takes --workspace <path> [--repo <url>])`);
     }
     await runOps(verb, process.argv.slice(4));
 }
@@ -433,12 +434,21 @@ async function driversCommand() {
             return;
         }
         console.log(`Computer ${config.machineId} — shared capacity ${config.leaseCapacity} (sum across online lanes, not per IDE)`);
-        for (const lane of lanes) {
-            console.log(`  ${lane.id.padEnd(14)} ${lane.state.padEnd(8)} fuel=${lane.fuel}  (${lane.label})`);
+        // Allowance is printed beside state because the two disagree exactly when it matters: a lane can
+        // be installed, logged in and online while the provider is refusing it, and reporting only the
+        // first three reads as "Ready" for a lane dispatch is skipping.
+        for (const lane of laneStatuses(config)) {
+            const when = lane.observed_at ? ` observed=${lane.observed_at}` : "";
+            const reset = lane.resets_at ? ` resets=${lane.resets_at}` : lane.allowance === "unavailable" ? " resets=unknown" : "";
+            console.log(`  ${lane.id.padEnd(14)} ${lane.state.padEnd(8)} fuel=${lane.fuel}  allowance=${lane.allowance}${when}${reset}  (${lane.label})`);
         }
+        const blocked = laneDispatchBlock(laneStatuses(config));
+        console.log(blocked
+            ? `Dispatch: BLOCKED — ${blocked}.`
+            : `Dispatch: ready — eligible ${laneStatuses(config).filter((lane) => lane.eligible).map((lane) => lane.id).join(", ")}.`);
         const online = onlineDriverIds(config);
         console.log(online.length
-            ? `Online: ${online.join(", ")}. Toggle: ${bridgeUsage("drivers", "online|offline", "<id…>")}`
+            ? `Toggle a lane: ${bridgeUsage("drivers", "online|offline", "<id…>")}`
             : `All offline — no new claims. Bring one online: ${bridgeUsage("drivers", "online", AGENT_PLACEHOLDER)}`);
         return;
     }
@@ -458,6 +468,23 @@ async function driversCommand() {
         console.log(`Now online: ${onlineDriverIds(config).join(", ") || "(none)"}`);
         return;
     }
+    if (sub === "quota") {
+        const action = process.argv[4]?.trim();
+        const id = process.argv[5]?.trim();
+        if (action !== "clear" || !id || process.argv[6]) {
+            throw new Error(`Usage: ${bridgeUsage("drivers", "quota", "clear", AGENT_PLACEHOLDER)}`);
+        }
+        if (!isSupportedDriverId(id))
+            throw new Error(`Unknown driver: ${id}. Available: ${Object.keys(DRIVERS).join(", ")}`);
+        if (!listDriverLanes(config).some((lane) => lane.id === id))
+            throw new Error(`Driver lane is not registered: ${id}`);
+        // A login or plan change happens outside Bridge, so only the operator can invalidate the last
+        // observed refusal. This intentionally does not toggle the lane or synthesize a successful probe:
+        // the next real claim is the proof, and will record another refusal if allowance is still spent.
+        await saveDriverQuota(id, undefined);
+        console.log(`Cleared recorded provider allowance refusal for ${id}. The next claim will recheck this lane.`);
+        return;
+    }
     if (sub === "fuel") {
         const id = process.argv[4]?.trim();
         const mode = process.argv[5];
@@ -470,7 +497,7 @@ async function driversCommand() {
         console.log(`${driverLabel(id)} lane fuel set to ${mode}`);
         return;
     }
-    throw new Error(`Usage: ${bridgeUsage("drivers", "[list|online|offline|fuel]", "…")}`);
+    throw new Error(`Usage: ${bridgeUsage("drivers", "[list|online|offline|fuel|quota]", "…")}`);
 }
 async function runner() {
     applyRunnerToolPath();
@@ -503,7 +530,17 @@ async function runner() {
     }
     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;
+    // Validated at startup rather than at use. Number("abc") is NaN, NaN is not nullish, and the
+    // unvalidated value flowed straight past `input.timeoutMs ?? DEFAULT` to become the timer itself.
+    let timeoutMs;
+    try {
+        timeoutMs = parseAgentTimeoutMinutes(values["agent-timeout-minutes"]);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
     const canExecute = Boolean(workspace) && onlineDriverIds(config).length > 0;
     if (!workspace) {
         console.warn(`WARNING: heartbeat only — pass --workspace <repo>. Lanes: ${bridgeUsage("drivers", "online", AGENT_PLACEHOLDER)}`);

package/dist/driver.js

@@ -1,9 +1,20 @@
 import { spawn } from "node:child_process";
+import { resolveAgentTimeout } from "./execution-budget.js";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, rm, rmdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { z } from "zod";
 import { deniedCommands, executionClassPromptRules, parsePiJsonl, projectClaude, projectCoarseMode, projectCodex, projectCursor, projectGrok, projectKiroTools, projectPi, requireStampedExecutionClass, } from "./execution-class.js";
+/**
+ * The bound for this turn.
+ *
+ * One place, so the eight call sites cannot drift apart, and so a package budget has a single seam to
+ * arrive through when the contract carries one. `input.timeoutMs` is the machine ceiling the operator
+ * configured; `input.maxDurationMs` is what the package asked for and is treated as payload.
+ */
+function agentTurnTimeoutMs(input) {
+    return resolveAgentTimeout({ machineCeilingMs: input.timeoutMs, packageBudgetMs: input.maxDurationMs }).timeoutMs;
+}
 export { branchCreateCommands, deniedCommands, isBoundedVerificationCommand, prCreateCommands, requireStampedExecutionClass, } from "./execution-class.js";
 function deliveryLanguageRule(language) {
     if (language === "zh") {
@@ -502,7 +513,7 @@ export const claudeCodeDriver = {
         args.push("--disallowedTools", projected.disallowedTools.join(","));
         if (projected.acceptEdits)
             args.push("--permission-mode", "acceptEdits");
-        const { code, stdout, stderr } = await execute(input.executable ?? "claude", args, input.workspace, input.timeoutMs ?? 20 * 60_000, fuelSource === "conduit" ? input.fuel : undefined, fuelSource);
+        const { code, stdout, stderr } = await execute(input.executable ?? "claude", args, input.workspace, agentTurnTimeoutMs(input), fuelSource === "conduit" ? input.fuel : undefined, fuelSource);
         let message = null;
         try {
             message = JSON.parse(stdout);
@@ -609,7 +620,7 @@ export const codexDriver = {
             diagnosis: input.workRole === "diagnose",
         });
         // Prompt via stdin avoids ARG_MAX limits on large assignment contracts.
-        const { code, stdout, stderr } = await execute(input.executable ?? resolveCodexExecutable(), codexExecArgs({ ...input, networkAccess: projected.networkAccess }, projected.sandbox), input.workspace, input.timeoutMs ?? 20 * 60_000, fuelSource === "conduit" ? input.fuel : undefined, fuelSource, input.prompt);
+        const { code, stdout, stderr } = await execute(input.executable ?? resolveCodexExecutable(), codexExecArgs({ ...input, networkAccess: projected.networkAccess }, projected.sandbox), input.workspace, agentTurnTimeoutMs(input), fuelSource === "conduit" ? input.fuel : undefined, fuelSource, input.prompt);
         const parsed = parseCodexJsonl(stdout);
         const resultText = parsed.resultText ?? (stdout || null);
         if (code !== 0) {
@@ -741,7 +752,7 @@ export const cursorDriver = {
             capabilities: input.capabilities ?? [],
             diagnosis: input.workRole === "diagnose",
         });
-        const configured = await withCursorPermissions(input.workspace, { allow: projected.allow, deny: projected.deny }, () => execute(executable, cursorRunArgs({ ...input, trustWorkspace, executionClass, force: projected.force }), input.workspace, input.timeoutMs ?? 20 * 60_000, undefined, "local"));
+        const configured = await withCursorPermissions(input.workspace, { allow: projected.allow, deny: projected.deny }, () => execute(executable, cursorRunArgs({ ...input, trustWorkspace, executionClass, force: projected.force }), input.workspace, agentTurnTimeoutMs(input), undefined, "local"));
         const { code, stdout, stderr } = configured;
         const parsed = parseCursorOutput(stdout);
         if (code !== 0 || parsed.isError) {
@@ -909,7 +920,7 @@ export const openCodeDriver = {
         }
         const args = openCodeRunArgs(input, agent);
         args.push(input.prompt);
-        const { code, stdout, stderr } = await withOpenCodePermissions(input.workspace, () => execute(input.executable ?? "opencode", args, input.workspace, input.timeoutMs ?? 20 * 60_000, fuelSource === "conduit" ? input.fuel : undefined, fuelSource));
+        const { code, stdout, stderr } = await withOpenCodePermissions(input.workspace, () => execute(input.executable ?? "opencode", args, input.workspace, agentTurnTimeoutMs(input), fuelSource === "conduit" ? input.fuel : undefined, fuelSource));
         const parsed = parseOpenCodeOutput(stdout);
         if (code !== 0 || parsed.isError) {
             return { status: "failed", resultText: parsed.resultText, sessionId: parsed.sessionId, error: (stderr || parsed.resultText || `opencode exited with code ${code}`).slice(0, 20_000) };
@@ -975,7 +986,7 @@ export const kiroDriver = {
         }
         const args = kiroChatArgs(input, trusted);
         args.push(input.prompt);
-        const { code, stdout, stderr } = await execute(executable, args, input.workspace, input.timeoutMs ?? 20 * 60_000, undefined, "local");
+        const { code, stdout, stderr } = await execute(executable, args, input.workspace, agentTurnTimeoutMs(input), undefined, "local");
         if (code !== 0) {
             return { status: "failed", resultText: stdout || null, sessionId: null, error: (stderr || stdout || `kiro-cli exited with code ${code}`).slice(0, 20_000) };
         }
@@ -1023,7 +1034,7 @@ export const antigravityDriver = {
             return { status: "failed", resultText: null, sessionId: null, error: "No Bridge-mapped Antigravity mode for active grants; refusing to start agent" };
         }
         // agy print mode emits plain text and does not surface a resumable id, so rework resume is not wired.
-        const { code, stdout, stderr } = await execute(input.executable ?? "agy", antigravityRunArgs({ prompt: input.prompt, grants: input.grants }, mode), input.workspace, input.timeoutMs ?? 20 * 60_000, undefined, "local");
+        const { code, stdout, stderr } = await execute(input.executable ?? "agy", antigravityRunArgs({ prompt: input.prompt, grants: input.grants }, mode), input.workspace, agentTurnTimeoutMs(input), undefined, "local");
         if (code !== 0) {
             return { status: "failed", resultText: stdout || null, sessionId: null, error: (stderr || stdout || `agy exited with code ${code}`).slice(0, 20_000) };
         }
@@ -1071,7 +1082,7 @@ export const piDriver = {
         if (version.code !== 0 || !(version.stdout || version.stderr).trim()) {
             return { status: "failed", resultText: null, sessionId: null, error: "pi preflight could not verify the installed CLI version" };
         }
-        const { code, stdout, stderr } = await execute(executable, piRunArgs({ prompt: input.prompt, tools: projected.tools, model: input.model }), input.workspace, input.timeoutMs ?? 20 * 60_000, undefined, "local");
+        const { code, stdout, stderr } = await execute(executable, piRunArgs({ prompt: input.prompt, tools: projected.tools, model: input.model }), input.workspace, agentTurnTimeoutMs(input), undefined, "local");
         const parsed = parsePiJsonl(stdout);
         if (code !== 0) {
             return {
@@ -1207,7 +1218,7 @@ export const grokDriver = {
         if (input.grants.includes("test_run") && !(input.verificationCommands?.length)) {
             return { status: "failed", resultText: null, sessionId: null, error: "grok preflight found no bounded verification command for the test_run grant" };
         }
-        const { code, stdout, stderr } = await execute(executable, grokRunArgs(input), input.workspace, input.timeoutMs ?? 20 * 60_000, undefined, "local");
+        const { code, stdout, stderr } = await execute(executable, grokRunArgs(input), input.workspace, agentTurnTimeoutMs(input), undefined, "local");
         const parsed = parseGrokOutput(stdout);
         if (code !== 0 || parsed.isError) {
             return { status: "failed", resultText: parsed.resultText, sessionId: parsed.sessionId, error: (stderr || parsed.resultText || `grok exited with code ${code}`).slice(0, 20_000) };
@@ -1247,7 +1258,12 @@ function execute(executable, args, cwd, timeoutMs, fuel, fuelSource = "conduit",
         });
         let stdout = "";
         let stderr = "";
-        const timer = setTimeout(() => { child.kill("SIGTERM"); setTimeout(() => child.kill("SIGKILL"), 10_000).unref(); }, timeoutMs);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => child.kill("SIGKILL"), 10_000).unref();
+        }, timeoutMs);
         // Bounded: a noisy or hostile local agent could otherwise grow these strings until the runner
         // dies. The report is the last fenced JSON block, so keeping the tail preserves what is parsed
         // while discarding the transcript ahead of it. Truncation is recorded, never silent.
@@ -1269,7 +1285,13 @@ function execute(executable, args, cwd, timeoutMs, fuel, fuelSource = "conduit",
             clearTimeout(timer);
             if (stdoutTruncated)
                 console.error(`Agent output exceeded ${MAX_AGENT_OUTPUT} bytes; kept the tail for report parsing.`);
-            resolve({ code, stdout, stderr: stderr.slice(0, 20_000) });
+            resolve({
+                code,
+                stdout,
+                // Never let vendor stderr appended before SIGTERM turn a local timer into a quota refusal.
+                // This stable prefix is classified by Bridge and the control plane as execution timeout.
+                stderr: timedOut ? `agent_turn_timeout: agent turn exceeded ${timeoutMs}ms` : stderr.slice(0, 20_000),
+            });
         });
         if (stdinText !== undefined && child.stdin) {
             // An agent that exits before reading its prompt closes this pipe, and the write then raises

package/dist/drivers.js

@@ -150,6 +150,34 @@ export function listDriverLanes(config) {
         };
     });
 }
+export function laneStatuses(config, now = Date.now()) {
+    return listDriverLanes(config).map((lane) => {
+        const quota = laneQuota(config, lane.id, now);
+        // A conduit-fuelled lane bills through the control plane, so a local refusal record says nothing
+        // about whether the next claim can run.
+        const local = lane.fuel === "local";
+        const allowance = !local || !quota
+            ? "unknown"
+            : quota.exhausted ? "unavailable" : "available";
+        return {
+            ...lane,
+            allowance,
+            observed_at: quota?.observed_at,
+            resets_at: quota?.resets_at ?? undefined,
+            eligible: lane.state === "online" && allowance !== "unavailable",
+        };
+    });
+}
+/** Why this machine cannot take a claim, or null when at least one lane can. */
+export function laneDispatchBlock(statuses) {
+    if (statuses.some((lane) => lane.eligible))
+        return null;
+    if (!statuses.length)
+        return "no driver lane is registered";
+    if (!statuses.some((lane) => lane.state === "online"))
+        return "every lane is offline";
+    return "every online lane has an allowance the provider refused";
+}
 export function onlineDriverIds(config) {
     const drivers = normalizeDrivers(config.drivers);
     return SUPPORTED_AGENTS.map((agent) => agent.id).filter((id) => drivers[id]?.state === "online");

package/dist/execution-budget.js

@@ -0,0 +1,77 @@
+/**
+ * How long one agent turn may run.
+ *
+ * Twenty minutes is a safety default for ordinary work, not a statement that longer work is
+ * ill-formed. A package should be split when its deliverables or authority boundaries are
+ * independent — never merely to fit a timer — so a cohesive task that genuinely needs thirty or
+ * sixty minutes must be able to say so.
+ *
+ * Two sources, and the smaller wins: the package asks for what the work needs, the machine caps what
+ * this host will tolerate. The operator's ceiling is the one that cannot be argued with by a payload.
+ */
+export const DEFAULT_AGENT_TIMEOUT_MS = 20 * 60_000;
+/**
+ * The longest turn any configuration may request.
+ *
+ * A bound this generous is not a scheduling opinion; it is the point past which a value is far more
+ * likely to be a mistake — a millisecond figure pasted where minutes were wanted — than an intention.
+ */
+export const MAX_AGENT_TIMEOUT_MS = 4 * 60 * 60_000;
+export const MIN_AGENT_TIMEOUT_MS = 60_000;
+export class InvalidAgentTimeoutError extends Error {
+}
+/**
+ * Minutes from a command line, validated.
+ *
+ * `Number("abc")` is `NaN`, and `NaN` is not nullish — so an unvalidated value flowed straight past
+ * `input.timeoutMs ?? DEFAULT` and became the timer itself. A typo must fail loudly at startup, not
+ * silently produce a turn that never times out or one that fires at once.
+ */
+export function parseAgentTimeoutMinutes(value) {
+    if (value === undefined)
+        return undefined;
+    const minutes = Number(value);
+    if (!Number.isFinite(minutes) || minutes <= 0) {
+        throw new InvalidAgentTimeoutError(`--agent-timeout-minutes must be a positive number of minutes, got ${JSON.stringify(value)}`);
+    }
+    const ms = Math.round(minutes * 60_000);
+    if (ms < MIN_AGENT_TIMEOUT_MS) {
+        throw new InvalidAgentTimeoutError(`--agent-timeout-minutes must be at least ${MIN_AGENT_TIMEOUT_MS / 60_000} minute`);
+    }
+    if (ms > MAX_AGENT_TIMEOUT_MS) {
+        throw new InvalidAgentTimeoutError(`--agent-timeout-minutes must not exceed ${MAX_AGENT_TIMEOUT_MS / 60_000} minutes`);
+    }
+    return ms;
+}
+/**
+ * The effective turn budget, and where it came from.
+ *
+ * The source is returned rather than inferred later because an operator reading a timed-out attempt
+ * needs to know which side set the bound; "it timed out" without that is not actionable.
+ *
+ * A package budget is payload, so it is bounded on both ends before use. A package asking for more
+ * than the machine allows is not an error — the machine simply wins, and the decision records that
+ * it was clamped so the difference is visible rather than mysterious.
+ */
+export function resolveAgentTimeout(inputs = {}) {
+    const ceiling = usableMs(inputs.machineCeilingMs);
+    const requested = usableMs(inputs.packageBudgetMs);
+    if (requested === undefined) {
+        return ceiling === undefined
+            ? { timeoutMs: DEFAULT_AGENT_TIMEOUT_MS, source: "default" }
+            : { timeoutMs: ceiling, source: "machine" };
+    }
+    // With no operator ceiling the default is the ceiling: a payload must not be able to lengthen a
+    // turn on a host whose operator never opted into longer runs.
+    const limit = ceiling ?? DEFAULT_AGENT_TIMEOUT_MS;
+    if (requested > limit)
+        return { timeoutMs: limit, source: "clamped_to_machine" };
+    return { timeoutMs: requested, source: "package" };
+}
+function usableMs(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return undefined;
+    if (value < MIN_AGENT_TIMEOUT_MS || value > MAX_AGENT_TIMEOUT_MS)
+        return undefined;
+    return Math.round(value);
+}

package/dist/execution-class.js

@@ -5,7 +5,12 @@
 /** Bounded verification commands a `test_run` grant may execute. */
 export function isBoundedVerificationCommand(command) {
     // Exact forms only — a trailing `.*` on pytest would admit `pytest ; curl … | sh`.
-    return /^(npm run (verify|typecheck|lint|test|build)|pnpm (verify|typecheck|lint|test|build)|yarn (verify|typecheck|lint|test|build)|cargo (test|check)|go test(?: \.\/\.\.\.)?|make (test|check)|python -m pytest|pytest(?: [\w./=-]+)?|\.\/gradlew test)$/.test(command);
+    // A target or script NAME is not a trust boundary: `make check` already runs whatever recipe the
+    // repository authored, so restricting the name to check/test grants no safety — it only stops a
+    // project from naming its own gate, which is what forced four attempts to die on a command they
+    // could not run. The boundary that matters is the SHAPE: one tool, one identifier, no shell
+    // metacharacters, so nothing can be smuggled in through the name.
+    return /^(npm run [A-Za-z0-9][A-Za-z0-9._:-]*|pnpm [A-Za-z0-9][A-Za-z0-9._:-]*|yarn [A-Za-z0-9][A-Za-z0-9._:-]*|cargo (test|check)|go test(?: \.\/\.\.\.)?|make [A-Za-z0-9][A-Za-z0-9._-]*|python -m pytest|pytest(?: [\w./=-]+)?|\.\/gradlew test)$/.test(command);
 }
 /** Shell commands each grant authorizes — mapped per driver so they cannot drift. */
 export const branchCreateCommands = [
@@ -76,7 +81,9 @@ export function executionClassPromptRules(input) {
     const artifact = executionClass === "publish_artifact";
     const rules = [];
     const grantShell = [
-        ...(grants.includes("test_run") ? verificationCommands.filter(isBoundedVerificationCommand) : []),
+        ...(grants.includes("test_run")
+            ? verificationCommands.filter((command) => isBoundedVerificationCommand(command) && !deniedCommands.includes(command))
+            : []),
         ...(grants.includes("branch_create") ? branchCreateCommands : []),
         ...(grants.includes("pr_create") ? prCreateCommands : []),
     ];

package/dist/execution-facts.js

@@ -123,5 +123,7 @@ export async function buildSovereignExecutionFacts(input) {
         verification_commands_digest: verificationCommandsDigest(input.brief?.verification ?? []),
         workspace_clean: input.workspaceClean,
         final_commit: commitOrNull(input.finalCommit),
+        ...(input.agentTimeoutMs !== undefined ? { agent_timeout_ms: input.agentTimeoutMs } : {}),
+        ...(input.agentTimeoutSource ? { agent_timeout_source: input.agentTimeoutSource } : {}),
     };
 }

package/dist/execution.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { z } from "zod";
+import { resolveAgentTimeout } from "./execution-budget.js";
 import { ConduitRequestError } from "./client.js";
 import { redactSecrets, saveDriverQuota } from "./config.js";
 import { DRIVERS, agentReportTemplate, buildAssignmentPrompt, evidenceKinds, extractAgentReportJsonText, fuelEndpoint, normalizeEvidenceDigest, parseAgentReport, parseJsonObjectCandidate, pickModelCandidate, requireStampedExecutionClass, tierForRisk } from "./driver.js";
@@ -79,7 +80,7 @@ export function forgeTransportFailure(message) {
  * costs an evening. Deliberately narrow — an unmatched refusal degrades to an ordinary agent
  * failure, which is exactly today's behaviour.
  */
-export const SUBSCRIPTION_EXHAUSTED_PATTERN = /\b(?:usage|rate)[ _-]?limit(?:ed|s)?\b|\bquota (?:exceeded|exhausted|reached)\b|\b(?:http|status|code)\W{0,3}429\b|\b429\b(?=\W{0,3}too many)|too many requests|out of (?:credits|usage)/i;
+export const SUBSCRIPTION_EXHAUSTED_PATTERN = /\b(?:usage|rate|session)[ _-]?limit(?:ed|s)?\b|\b(?:daily|weekly|monthly) limit\b|\bquota (?:exceeded|exhausted|reached)\b|\b(?:http|status|code)\W{0,3}429\b|\b429\b(?=\W{0,3}too many)|too many requests|out of (?:credits|usage)/i;
 /**
  * Does this failure mean the plan is spent, rather than the prompt being wrong?
  *
@@ -94,8 +95,43 @@ export const SUBSCRIPTION_EXHAUSTED_PATTERN = /\b(?:usage|rate)[ _-]?limit(?:ed|
  * sentence in the same string.
  */
 export function subscriptionExhausted(message) {
+    if (agentTurnTimedOut(message))
+        return false;
     return SUBSCRIPTION_EXHAUSTED_PATTERN.test(message);
 }
+export function agentTurnTimedOut(message) {
+    return /^agent_turn_timeout:/i.test(message.trim());
+}
+function timeoutFailureBody(resolution, attemptId) {
+    const machineBound = resolution.source === "default"
+        || resolution.source === "machine"
+        || resolution.source === "clamped_to_machine";
+    const minutes = Math.round(resolution.timeoutMs / 60_000);
+    return {
+        failure: machineBound ? {
+            code: "agent_turn_timeout",
+            class: "environment",
+            disposition: "hold",
+            responsible_party: "computer_operator",
+            message: `The agent turn reached this computer's ${minutes}-minute execution limit.`,
+            next_action: "The computer operator can raise the Bridge agent timeout when this cohesive package needs longer. The product owner does not need to write technical constraints or split the package merely to fit the timer.",
+            diagnostic_detail: `agent_turn_timeout: ${resolution.timeoutMs}ms; source=${resolution.source}`,
+        } : {
+            code: "agent_turn_timeout",
+            class: "platform",
+            disposition: "stop",
+            responsible_party: "conduit",
+            message: `The agent turn reached Conduit's ${minutes}-minute package budget.`,
+            next_action: "Conduit must revise the mechanically derived execution budget or continue from a bounded checkpoint. The product owner does not need to author implementation constraints.",
+            diagnostic_detail: `agent_turn_timeout: ${resolution.timeoutMs}ms; source=${resolution.source}`,
+        },
+        error: `agent_turn_timeout: agent turn exceeded ${resolution.timeoutMs}ms`,
+        retryable: false,
+        idempotency_key: `bridge:agent-timeout:${attemptId}`,
+    };
+}
+class AgentTurnTimeoutError extends Error {
+}
 /**
  * When the window refills, if the vendor said so.
  *
@@ -302,6 +338,7 @@ const workPackageSchema = z.object({
         failure_output: z.string().min(1).max(12_000),
     }).optional(),
     working_language: z.enum(["en", "zh"]).optional(),
+    max_duration_ms: z.number().int().min(60_000).max(4 * 60 * 60_000).optional(),
 }).nullable().optional();
 const diagnosticRepairBriefSchema = z.object({
     root_cause: z.string().trim().min(1).max(2_000),
@@ -728,6 +765,10 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
     const task = taskDetailSchema.parse(detail.task);
     const executionContract = executionContractSchema.parse(detail.execution_contract ?? {});
     const workPackage = workPackageSchema.parse(detail.work_package) ?? null;
+    const agentTimeout = resolveAgentTimeout({
+        machineCeilingMs: timeoutMs,
+        packageBudgetMs: workPackage?.max_duration_ms,
+    });
     const executionKind = task.execution_kind;
     const diagnosis = executionKind === "diagnosis";
     const sourceAttemptId = task.source_attempt_id ?? executionContract.source_attempt_id ?? active.sourceAttemptId ?? null;
@@ -992,6 +1033,8 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
         executionClass,
         claimedHead: executionContract.claimed_head ?? startCommit,
         bootstrapResult: await bootstrapResultForWorkspace(workspace),
+        agentTimeoutMs: agentTimeout.timeoutMs,
+        agentTimeoutSource: agentTimeout.source,
     });
     await client.updateAttempt(taskId, { executionFacts });
     await client.attemptRequest(taskId, "progress", {
@@ -1067,6 +1110,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
             executionClass,
             resumeSessionId,
             timeoutMs,
+            maxDurationMs: workPackage?.max_duration_ms,
             model: selection.model,
             fuel,
             fuelSource,
@@ -1153,12 +1197,25 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
         }
         if (result.status === "failed") {
             const agentMessage = result.error ?? "Agent execution failed";
+            if (agentTurnTimedOut(agentMessage)) {
+                retainAttemptWorktree = true;
+                const response = await queueTerminal(client, taskId, {
+                    action: "fail",
+                    body: timeoutFailureBody(agentTimeout, active.attemptId),
+                });
+                retainAttemptWorktree = response.retain_worktree === true;
+                console.error(`Assignment ${taskId} timed out: ${redactSecrets(agentMessage)}`);
+                return;
+            }
             // The agent verifies inside its own tool loop, so its compiler/test output never reaches
             // result.error — production saw a bare git SHA and echoed source arrive as the "failure
             // reason", leaving Conductor nothing to diagnose. Re-run the project's bounded verification
             // in the attempt worktree to recover the real errors. Best-effort: keep the agent's own
             // message when there is no command, the command cannot run, or the tree actually verifies.
-            const verificationDetail = grants.includes("test_run")
+            // A vendor allowance refusal is already a precise environment diagnosis. Running repository
+            // verification after it can surface an unrelated pre-existing failure and overwrite the lane
+            // Hold with a false source-repair brief.
+            const verificationDetail = grants.includes("test_run") && !subscriptionExhausted(agentMessage)
                 ? await captureVerificationFailure({
                     workspace: attemptWorkspace,
                     verificationCommands: attemptBrief?.verification ?? [],
@@ -1218,6 +1275,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
                 fuel,
                 fuelSource,
                 timeoutMs,
+                maxDurationMs: workPackage?.max_duration_ms,
                 resumeSessionId: agentSessionId,
                 reason: "Agent claimed repository work but git shows none on the attempt branch; starting one land-only continuation turn instead of report-only repair.",
                 idempotencyKey: `bridge:progress:${active.attemptId}:claims-git-gate`,
@@ -1254,6 +1312,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
                         fuel,
                         fuelSource,
                         timeoutMs,
+                        maxDurationMs: workPackage?.max_duration_ms,
                         resumeSessionId: agentSessionId,
                         reason: "Agent claimed repository work but git shows none; starting land-only continuation instead of read-only report repair.",
                         idempotencyKey: `bridge:progress:${active.attemptId}:claims-git-gate-parse`,
@@ -1328,6 +1387,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
                             executionClass: "observe",
                             resumeSessionId,
                             timeoutMs,
+                            maxDurationMs: workPackage?.max_duration_ms,
                             model: selection.model,
                             fuel,
                             fuelSource,
@@ -1416,6 +1476,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
                 fuel,
                 fuelSource,
                 timeoutMs,
+                maxDurationMs: workPackage?.max_duration_ms,
                 resumeSessionId: agentSessionId,
                 reason: "Parsed Delivery claims repository work but git shows none; starting land-only continuation.",
                 idempotencyKey: `bridge:progress:${active.attemptId}:claims-git-gate-report`,
@@ -1463,6 +1524,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
                 fuel,
                 fuelSource,
                 timeoutMs,
+                maxDurationMs: workPackage?.max_duration_ms,
                 resumeSessionId: agentSessionId,
                 landContinuationUsed,
             });
@@ -1549,6 +1611,17 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
         else
             console.error(`Assignment ${taskId} Delivery was rejected and routed to Conductor repair.`);
     }
+    catch (error) {
+        if (!(error instanceof AgentTurnTimeoutError))
+            throw error;
+        retainAttemptWorktree = true;
+        const response = await queueTerminal(client, taskId, {
+            action: "fail",
+            body: timeoutFailureBody(agentTimeout, active.attemptId),
+        });
+        retainAttemptWorktree = response.retain_worktree === true;
+        console.error(`Assignment ${taskId} timed out: ${redactSecrets(error.message)}`);
+    }
     finally {
         releaseIdleSleep();
         clearInterval(renewTimer);
@@ -1616,12 +1689,15 @@ async function runLandContinuationTurn(input) {
         executionClass: "mutate_repo",
         resumeSessionId: input.resumeSessionId ?? undefined,
         timeoutMs: input.timeoutMs,
+        maxDurationMs: input.maxDurationMs,
         model: input.selection.model ?? undefined,
         fuel: input.fuel,
         fuelSource: input.fuelSource,
     });
     await learnDriverFuel(input.config, input.driver.name, input.fuelSource ?? "conduit", continuation);
     if (continuation.status === "failed") {
+        if (agentTurnTimedOut(continuation.error ?? ""))
+            throw new AgentTurnTimeoutError(continuation.error);
         throw new AgentNoLandCommitError(input.spec.repository?.base_commit ?? "unknown");
     }
     return {
@@ -1676,6 +1752,7 @@ async function finalizeRepositoryLand(input) {
         fuel: input.fuel,
         fuelSource: input.fuelSource,
         timeoutMs: input.timeoutMs,
+        maxDurationMs: input.maxDurationMs,
         resumeSessionId: input.resumeSessionId,
         reason: "Agent finished without landing repository changes; starting one land-only continuation turn.",
         idempotencyKey: `bridge:progress:${input.attemptId}:land-continuation`,

package/dist/ops.js

@@ -13,13 +13,13 @@ import { ConduitClient } from "./client.js";
 import { loadConfig } from "./config.js";
 import { ensureCheckout } from "./checkout.js";
 import { detectInstalledClients, probeAgentHealth } from "./detect.js";
-import { driverIdsFromDetectedLabels } from "./drivers.js";
+import { driverIdsFromDetectedLabels, laneDispatchBlock, laneStatuses } from "./drivers.js";
 import { BRIDGE_PROTOCOL_VERSION, describePreflightIssue, runBridgePreflight } from "./preflight.js";
 import { applyRunnerToolPath, readActiveRunnerServiceWorkspace, readStoredRunnerServiceOptions, runnerServiceWorkspaceWarnings } from "./service.js";
 import { bridgeVersion } from "./version.js";
 import { bootstrapManagedWorkspace } from "./workspace-bootstrap.js";
 export const OPS_VERBS = [
-    "connect", "enroll", "install", "switch", "online", "offline", "status", "doctor", "disconnect", "uninstall",
+    "connect", "enroll", "install", "switch", "online", "offline", "quota-clear", "status", "doctor", "disconnect", "uninstall",
 ];
 const LOCAL_FUEL_DRIVERS = new Set(["cursor", "pi", "kiro", "antigravity", "grok"]);
 /**
@@ -245,6 +245,24 @@ export async function runOps(verb, argv = [], deps = {}) {
     if (verb === "status") {
         const packageVersion = bridgeVersion();
         console.log(`Bridge: v${packageVersion} (protocol ${BRIDGE_PROTOCOL_VERSION})`);
+        // Print lanes through the same projection `drivers list` uses. These two commands disagreeing
+        // about whether a lane was usable is what sent an operator looking for a product fault when the
+        // real answer was a spent provider allowance.
+        try {
+            const laneConfig = await (deps.loadBridgeConfig ?? loadConfig)();
+            const statuses = laneStatuses(laneConfig);
+            for (const lane of statuses) {
+                const when = lane.observed_at ? `, observed ${lane.observed_at}` : "";
+                const reset = lane.resets_at ? `, resets ${lane.resets_at}` : lane.allowance === "unavailable" ? ", reset unknown" : "";
+                console.log(`Lane ${lane.id}: ${lane.state}, fuel ${lane.fuel}, allowance ${lane.allowance}${when}${reset}`);
+            }
+            const blocked = laneDispatchBlock(statuses);
+            // Never say READY on the strength of a login alone; dispatch is what the operator is asking about.
+            console.log(blocked ? `Machine dispatch: BLOCKED — ${blocked}` : "Machine dispatch: ready");
+        }
+        catch {
+            console.log("Lanes: unavailable (no local Bridge configuration)");
+        }
         try {
             const config = await (deps.loadBridgeConfig ?? loadConfig)();
             const controller = new AbortController();
@@ -343,12 +361,18 @@ export async function runOps(verb, argv = [], deps = {}) {
             console.log(`- ${describePreflightIssue(issue)}`);
         throw new Error("Fix the preflight issues before retrying Conduit work");
     }
-    // Lane toggles only need Bridge config + optional driver ids — not a full ops.env.
+    // Lane controls only need Bridge config + optional driver ids — not a full ops.env.
     if (verb === "online" || verb === "offline") {
         const drivers = await resolveDrivers(env, argv);
         runBridge(["drivers", verb, ...drivers]);
         return;
     }
+    if (verb === "quota-clear") {
+        if (argv.length !== 1)
+            throw new Error("Usage: ops quota-clear <driver>");
+        runBridge(["drivers", "quota", "clear", argv[0]]);
+        return;
+    }
     // Explicit install arguments are active-run inputs, not machine-wide defaults. Enrollment may
     // seed ops.env once; later project changes must not mutate it.
     let installEnv = env;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miraland-labs/conduit-bridge",
-  "version": "0.16.25",
+  "version": "0.16.27",
   "description": "Conduit Bridge CLI — join, connect, disconnect, multi-driver lanes, and run Claude Code / Codex / Cursor / OpenCode / Pi / Kiro / Antigravity / Grok Build agents for a Conduit organization",
   "type": "module",
   "bin": {