@miraland-labs/conduit-bridge 0.16.104 → 0.16.106

package/dist/cli.js

@@ -14,7 +14,7 @@ import { detectInstalledClients, localFuelOnlyClients, suggestFuelSource } from
 import { DRIVERS, MODEL_TIERS } from "./driver.js";
 import { driversHeartbeatReport, driverLabel, heartbeatStatusForDrivers, isSupportedDriverId, listDriverLanes, onlineDriverIds, seedDriversFromDetection, seedDriverLanes, setDriverFuel, setDriverModels, setDriversOnline, formatLaneTiers, laneDispatchBlock, laneStatuses, } from "./drivers.js";
 import { buildWorkspaceBrief } from "./brief.js";
-import { parseAgentTimeoutMinutes } from "./execution-budget.js";
+import { parseAgentTimeoutMinutes, parseMaxTurns, resolveMaxTurns } 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";
@@ -534,10 +534,26 @@ async function runner() {
     applyRunnerToolPath();
     const { values } = parseArgs({ args: process.argv.slice(3), options: {
             workspace: { type: "string" }, interval: { type: "string" }, once: { type: "boolean" },
-            "agent-timeout-minutes": { type: "string" }, fuel: { type: "string" }, "ensure-checkout": { type: "string" },
+            "agent-timeout-minutes": { type: "string" }, "max-turns": { type: "string" }, fuel: { type: "string" }, "ensure-checkout": { type: "string" },
             "bootstrap-result": { type: "string" },
         } });
     let config = await loadConfig();
+    // The cap is a machine setting, so it is written to the config the way `--fuel` is: the resident
+    // service, `ops status` and the readiness report then all read one number instead of each being
+    // told separately, and a runner started without the flag keeps the operator's last choice.
+    let maxTurnsOverride;
+    try {
+        maxTurnsOverride = parseMaxTurns(values["max-turns"]);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
+    if (maxTurnsOverride !== undefined) {
+        config.maxTurns = maxTurnsOverride;
+        await saveConfigPrefs(config);
+    }
     const fuelOverride = parseFuelSource(values.fuel);
     const bootstrapResult = values["bootstrap-result"]
         ? parseBootstrapResult(values["bootstrap-result"])
@@ -581,7 +597,7 @@ async function runner() {
         console.warn(`WARNING: no online driver lanes — ${bridgeUsage("drivers", "online", AGENT_PLACEHOLDER)}`);
     }
     const onlineLabel = onlineDriverIds(config).join(", ") || "(none)";
-    console.log(`Conduit runner (bridge v${bridgeVersion()}) connected to ${config.baseUrl}${workspace ? ` — workspace ${workspace}` : " — heartbeat only"} (lanes: ${onlineLabel}; machine fuel: ${config.fuelSource === "local" ? "local" : "conduit"}; slots: ${config.leaseCapacity})`);
+    console.log(`Conduit runner (bridge v${bridgeVersion()}) connected to ${config.baseUrl}${workspace ? ` — workspace ${workspace}` : " — heartbeat only"} (lanes: ${onlineLabel}; machine fuel: ${config.fuelSource === "local" ? "local" : "conduit"}; slots: ${config.leaseCapacity}; turn cap: ${resolveMaxTurns(config.maxTurns)})`);
     const running = new Map();
     for (;;) {
         let progressed = false;
@@ -591,6 +607,7 @@ async function runner() {
             config.drivers = latest.drivers;
             config.fuelSource = latest.fuelSource;
             config.leaseCapacity = latest.leaseCapacity;
+            config.maxTurns = latest.maxTurns;
             // Refresh before discovery: the brief and the readiness report must describe origin's code,
             // not whatever this checkout was left on. Cadence is the readiness report's own, not the beat.
             const refresh = workspace ? await reportedRefresh(workspace) : null;

package/dist/driver.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { boundedTail } from "./ensure-test-evidence.js";
-import { resolveAgentTimeout } from "./execution-budget.js";
-import { agentExitSignal, vendorKindForAntigravity } from "./failure-signal.js";
+import { resolveAgentTimeout, resolveMaxTurns } from "./execution-budget.js";
+import { agentExitSignal, turnCapSignal, vendorKindForAntigravity } from "./failure-signal.js";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, rm, rmdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
@@ -721,7 +721,8 @@ export const claudeCodeDriver = {
                 error: "No Bridge-mapped tools for active grants; refusing to start agent without an allow-list",
             };
         }
-        const args = ["-p", input.prompt, "--output-format", "json"];
+        const maxTurns = resolveMaxTurns(input.maxTurns);
+        const args = ["-p", input.prompt, "--output-format", "json", "--max-turns", String(maxTurns)];
         args.push(...modelArgs(claudeCodeDriver, input.model));
         if (input.resumeSessionId)
             args.push("--resume", input.resumeSessionId);
@@ -739,6 +740,18 @@ export const claudeCodeDriver = {
         }
         const sessionId = message?.session_id ?? null;
         const usage = claudeUsage(message);
+        // The CLI names this stop itself (`subtype: "error_max_turns"`, verified against claude 2.1.258),
+        // so the cap is read from the vendor's envelope rather than guessed from an exit code.
+        if (message?.subtype === "error_max_turns") {
+            return {
+                status: "failed",
+                resultText: message.result ?? null,
+                sessionId,
+                usage,
+                signal: turnCapSignal({ maxTurns, turns: usage.turns, model: input.model }),
+                error: `agent_turn_cap: the run reached the computer's cap of ${maxTurns} turns`,
+            };
+        }
         if (code !== 0 || !message || message.is_error) {
             return { status: "failed", resultText: message?.result ?? null, sessionId, usage, signal: agentExitSignal({ exit_code: code, stderr, stdout, model: input.model }), error: boundedTail(message?.result || stderr || `agent exited with code ${code}`, 20_000) };
         }

package/dist/execution-budget.js

@@ -75,3 +75,48 @@ function usableMs(value) {
         return undefined;
     return Math.round(value);
 }
+/**
+ * How many turns one attempt may spend on a lane whose CLI can be told.
+ *
+ * A turn is not a minute. The agent CLI re-sends the whole conversation every turn, so the tokens
+ * one attempt bills grow with the square of its turn count: a one-paragraph documentation edit on
+ * 2026-09-15 ran 33 turns for 1,029,028 input tokens and $5.27, and the timer never came close.
+ * Forty turns is what ordinary delivery work has needed; beyond it a run is looping, not working.
+ */
+export const DEFAULT_MAX_TURNS = 40;
+/**
+ * The widest cap a configuration may ask for. Past this the number is far more likely to be a
+ * mistake than an intention — and an attempt that needs a thousand turns is the defect itself.
+ */
+export const MAX_MAX_TURNS = 500;
+export class InvalidMaxTurnsError extends Error {
+}
+/**
+ * A turn cap from a command line, validated.
+ *
+ * Validated at startup rather than at use, for the reason `parseAgentTimeoutMinutes` records:
+ * `Number("abc")` is `NaN`, `NaN` is not nullish, and an unvalidated value flows past every `??`
+ * default and becomes the bound itself.
+ */
+export function parseMaxTurns(value) {
+    if (value === undefined)
+        return undefined;
+    const turns = Number(value);
+    if (!Number.isInteger(turns) || turns < 1 || turns > MAX_MAX_TURNS) {
+        throw new InvalidMaxTurnsError(`--max-turns must be a whole number of turns between 1 and ${MAX_MAX_TURNS}, got ${JSON.stringify(value)}`);
+    }
+    return turns;
+}
+/**
+ * The effective turn cap for one run.
+ *
+ * The default applies here, at the point the flag is written, so a call site that knows nothing
+ * about the machine's configuration still runs capped. An uncapped run is the incident.
+ */
+export function resolveMaxTurns(configured) {
+    if (typeof configured !== "number" || !Number.isInteger(configured))
+        return DEFAULT_MAX_TURNS;
+    if (configured < 1 || configured > MAX_MAX_TURNS)
+        return DEFAULT_MAX_TURNS;
+    return configured;
+}

package/dist/execution.js

@@ -13,7 +13,7 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { buildWorkspaceBrief, ensureCommitAvailable, fetchOrigin, normalizeRepositoryUrl, resolveAttemptStartCommit } from "./brief.js";
 import { buildSovereignExecutionFacts, bootstrapResultForWorkspace, changedExecutionFact, resumeExecutionFacts, workspaceIsClean } from "./execution-facts.js";
-import { executionFactChangedSignal, verificationRedBaseSignal, verificationScopeConflictSignal } from "./failure-signal.js";
+import { bridgeCause, executionFactChangedSignal, verificationRedBaseSignal, verificationScopeConflictSignal } from "./failure-signal.js";
 import { forgeTransportFailure } from "./transport-fault.js";
 import { managedWorkspacePath, switchManagedWorkspace } from "./on-shift-apply.js";
 import { formatResetMinute, parseQuotaResetAt } from "./quota-reset.js";
@@ -22,7 +22,7 @@ import { BRIDGE_PROTOCOL_VERSION } from "./preflight.js";
 import { bridgeVersion } from "./version.js";
 import { PULL_REQUEST_OPEN_FAILURE_PREFIX, ensureDeliveryPullRequest } from "./ensure-pull-request.js";
 import { ensureLandCommit } from "./ensure-land-commit.js";
-import { AgentNoLandCommitError, agentNoLandCommitMessage, requiresLandCommit } from "./land-contract.js";
+import { AGENT_NO_LAND_COMMIT_PREFIX, AgentNoLandCommitError, agentNoLandCommitMessage, requiresLandCommit } from "./land-contract.js";
 import { agentClaimsRepositoryWork, claimsVsGitMismatch, isLandTreeEmpty, reportClaimsRepositoryWork, } from "./land-git-reality.js";
 const execFileAsync = promisify(execFile);
 import { captureVerificationFailure, detectGateRanNothing, ensureTestEvidence, needsTestEvidence, runBoundedVerificationCommand, verificationEvidenceCommands, VerificationGateRanNothingError } from "./ensure-test-evidence.js";
@@ -185,6 +185,9 @@ class AgentTurnTimeoutError extends Error {
 /** Environment faults that must Hold — mirror CP ENVIRONMENT_FAILURES message patterns. */
 const FINALIZE_ENVIRONMENT_PATTERN = /base[_ ]not[_ ]ancestor|required base commit is not available|source[_ ]workspace[_ ]dirty|uncommitted changes|dirty workspace|workspace[_ ]head[_ ]changed|workspace[_ ]repository|workspace[_ ]unavailable|driver[_ ]not[_ ]authenticated|not logged in|no login|not authenticated|login required|no[_ ]online[_ ]driver|bridge[_ ]preflight|stale bridge|bridge version/i;
 /** Delivery-report / grant / evidence contract defects (non-retryable rework). */
+/** Two contract messages the control plane reads with builders of its own; they carry no code from here. */
+const CONTRACT_SCOPE_CONFLICT_MESSAGE = /Agent reported changes outside the approved scope:/i;
+const VERIFICATION_UNWITNESSABLE_MESSAGE = /verification produced (?:no|insufficient) output/i;
 const FINALIZE_CONTRACT_PATTERN = /missing required evidence|without the repo_write grant|pull_request_url|Artifact delivery requires|outside the approved scope|head commit|test evidence must include|Met acceptance criteria|Agent report|Agent reported|Agent did not land repository changes|Delivery report|Integration obligation not met|Normative reference unavailable|Normative marker not found/i;
 /**
  * Classify throws from ensureDeliveryPullRequest + validateDeliveryReport.
@@ -192,7 +195,7 @@ const FINALIZE_CONTRACT_PATTERN = /missing required evidence|without the repo_wr
  */
 export function classifyFinalizeFailure(message) {
     if (forgeTransportFailure(message))
-        return { retryable: true, error: message };
+        return { retryable: true, error: message, failure: bridgeCause("forge_unreachable", message) };
     // The control plane refused to open the change request — no forge connection resolves for this
     // organization or project, or the task's repository is not one that connection can open a change
     // request on. No retry and no rework can supply a connection, and the owner must read the control
@@ -201,8 +204,19 @@ export function classifyFinalizeFailure(message) {
         return { retryable: false, error: message };
     if (FINALIZE_ENVIRONMENT_PATTERN.test(message))
         return { retryable: false, error: message };
-    if (FINALIZE_CONTRACT_PATTERN.test(message))
-        return { retryable: false, error: message };
+    // Bridge names the contract defect it found (K3). A scope conflict keeps its own builder on the
+    // control plane, which quotes the paths; an unknown throw below stays prose until its own site
+    // names a code.
+    if (FINALIZE_CONTRACT_PATTERN.test(message)) {
+        const failure = CONTRACT_SCOPE_CONFLICT_MESSAGE.test(message)
+            ? undefined
+            : VERIFICATION_UNWITNESSABLE_MESSAGE.test(message)
+                ? bridgeCause("verification_unwitnessable", message)
+                : message.startsWith(AGENT_NO_LAND_COMMIT_PREFIX)
+                    ? bridgeCause("agent_no_land_commit", message)
+                    : bridgeCause("execution_contract_failed", message);
+        return { retryable: false, error: message, ...(failure ? { failure } : {}) };
+    }
     // Unknown finalize faults fail closed once — retrying burns the attempt budget (Invariant 22).
     // Distinct from execution_contract_failed so owners see a Bridge fault, not a contract lie.
     return { retryable: false, error: `Bridge finalize interrupted: ${message}` };
@@ -1060,7 +1074,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
     const liveBrief = await buildWorkspaceBrief(workspace).catch(() => brief);
     const liveRepository = liveBrief?.repository ? normalizeRepositoryUrl(liveBrief.repository) : null;
     if (executionContract.repository_fingerprint && liveRepository !== executionContract.repository_fingerprint) {
-        await queueTerminal(client, taskId, { action: "fail", body: { error: "Workspace repository changed after dispatch", retryable: true, idempotency_key: `bridge:workspace-mismatch:${active.attemptId}` } });
+        await queueTerminal(client, taskId, { action: "fail", body: { error: "Workspace repository changed after dispatch", retryable: true, failure: bridgeCause("workspace_repository_mismatch", "Workspace repository changed after dispatch"), idempotency_key: `bridge:workspace-mismatch:${active.attemptId}` } });
         console.error(`Assignment ${taskId} preflight failed: Workspace repository changed after dispatch`);
         return;
     }
@@ -1122,13 +1136,13 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
     }
     else {
         if (!startCommit) {
-            await queueTerminal(client, taskId, { action: "fail", body: { error: "No start commit for attempt worktree", retryable: true, idempotency_key: `bridge:no-start-commit:${active.attemptId}` } });
+            await queueTerminal(client, taskId, { action: "fail", body: { error: "No start commit for attempt worktree", retryable: true, failure: bridgeCause("agent_execution_failed", "No start commit for attempt worktree"), idempotency_key: `bridge:no-start-commit:${active.attemptId}` } });
             return;
         }
         if (executionContract.requested_base_commit) {
             const resolved = await resolveAttemptStartCommit(workspace, executionContract.requested_base_commit, startCommit);
             if (!resolved) {
-                await queueTerminal(client, taskId, { action: "fail", body: { error: "Required base commit is not available in this workspace", retryable: true, idempotency_key: `bridge:base-not-ancestor:${active.attemptId}` } });
+                await queueTerminal(client, taskId, { action: "fail", body: { error: "Required base commit is not available in this workspace", retryable: true, failure: bridgeCause("base_not_ancestor", "Required base commit is not available in this workspace"), idempotency_key: `bridge:base-not-ancestor:${active.attemptId}` } });
                 return;
             }
             worktreeStart = resolved;
@@ -1136,7 +1150,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
         else if (liveBrief?.base_commit && liveBrief.base_commit !== startCommit) {
             const reachable = await ensureCommitAvailable(workspace, startCommit).catch(() => false);
             if (!reachable) {
-                await queueTerminal(client, taskId, { action: "fail", body: { error: "Delivered head is not available in this workspace", retryable: true, idempotency_key: `bridge:workspace-mismatch:${active.attemptId}` } });
+                await queueTerminal(client, taskId, { action: "fail", body: { error: "Delivered head is not available in this workspace", retryable: true, failure: bridgeCause("agent_execution_failed", "Delivered head is not available in this workspace"), idempotency_key: `bridge:workspace-mismatch:${active.attemptId}` } });
                 console.error(`Assignment ${taskId} preflight failed: Delivered head is not available in this workspace`);
                 return;
             }
@@ -1153,7 +1167,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
             const message = code === "source_workspace_dirty"
                 ? "Source workspace has uncommitted changes; refuse to start an isolated attempt"
                 : `Unable to create attempt worktree: ${code}`;
-            await queueTerminal(client, taskId, { action: "fail", body: { error: message, retryable: true, idempotency_key: `bridge:worktree:${active.attemptId}:${code}` } });
+            await queueTerminal(client, taskId, { action: "fail", body: { error: message, retryable: true, ...(code === "source_workspace_dirty" ? { failure: bridgeCause("workspace_dirty", message) } : {}), idempotency_key: `bridge:worktree:${active.attemptId}:${code}` } });
             console.error(`Assignment ${taskId} worktree create failed: ${redactSecrets(message)}`);
             return;
         }
@@ -1190,6 +1204,9 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                     body: {
                         error: message,
                         retryable,
+                        failure: retryable
+                            ? bridgeCause("agent_execution_failed", message)
+                            : bridgeCause(message.startsWith(NORMATIVE_REF_PREFIX) ? "execution_contract_failed" : "execution_unclassified", message),
                         idempotency_key: `bridge:normative-ref:${active.attemptId}`,
                     },
                 });
@@ -1221,7 +1238,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
         // attempt budget when a pre-inversion task row still lacked the stamp.
         const response = await queueTerminal(client, taskId, {
             action: "fail",
-            body: { error: detail, retryable: false, idempotency_key: `bridge:fail:${active.attemptId}:missing-class` },
+            body: { error: detail, retryable: false, failure: bridgeCause("execution_unclassified", detail), idempotency_key: `bridge:fail:${active.attemptId}:missing-class` },
         });
         await removeReleasedDiagnosticWorktree(response);
         return;
@@ -1232,7 +1249,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
         console.error(`Assignment ${taskId}: ${detail}`);
         await queueTerminal(client, taskId, {
             action: "fail",
-            body: { error: detail, retryable: false, idempotency_key: `bridge:fail:${active.attemptId}:artifact-class` },
+            body: { error: detail, retryable: false, failure: bridgeCause("execution_unclassified", detail), idempotency_key: `bridge:fail:${active.attemptId}:artifact-class` },
         });
         return;
     }
@@ -1243,7 +1260,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
         console.error(`Assignment ${taskId}: ${detail}`);
         const response = await queueTerminal(client, taskId, {
             action: "fail",
-            body: { error: detail, retryable: false, idempotency_key: `bridge:fail:${active.attemptId}:class-floor` },
+            body: { error: detail, retryable: false, failure: bridgeCause("execution_unclassified", detail), idempotency_key: `bridge:fail:${active.attemptId}:class-floor` },
         });
         await removeReleasedDiagnosticWorktree(response);
         return;
@@ -1279,6 +1296,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
             body: {
                 error: "Diagnostic assignment is missing witnessed failure output",
                 retryable: true,
+                failure: bridgeCause("agent_execution_failed", "Diagnostic assignment is missing witnessed failure output"),
                 idempotency_key: `bridge:diagnosis-context-missing:${active.attemptId}`,
             },
         });
@@ -1298,6 +1316,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
             body: {
                 error: detail,
                 retryable: false,
+                failure: bridgeCause("missing_verification", detail),
                 idempotency_key: `bridge:missing-verification:${active.attemptId}`,
             },
         });
@@ -1565,6 +1584,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
             resumeSessionId,
             timeoutMs,
             maxDurationMs: workPackage?.max_duration_ms,
+            maxTurns: config.maxTurns,
             model: selection.model,
             fuel,
             fuelSource,
@@ -1707,9 +1727,14 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
             // 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.
-            if (grants.includes("test_run") && !subscriptionExhausted(agentMessage))
+            // T197: the machine's turn cap is such a diagnosis too. Recovering a verification failure
+            // after it would retype the signal as a Bridge verification witness, which classifies as a
+            // transient retry — the one verdict that would run the capped work again at the same price.
+            const turnCapReached = result.signal?.kind === "turn_cap";
+            const recoverVerification = grants.includes("test_run") && !subscriptionExhausted(agentMessage) && !turnCapReached;
+            if (recoverVerification)
                 watchdog.phase("verification");
-            const verificationDetail = grants.includes("test_run") && !subscriptionExhausted(agentMessage)
+            const verificationDetail = recoverVerification
                 ? await captureVerificationFailure({
                     workspace: attemptWorkspace,
                     verificationCommands: attemptBrief?.verification ?? [],
@@ -1756,6 +1781,9 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
             const response = await queueTerminal(client, taskId, { action: "fail", body: {
                     error: message,
                     retryable: bindingRequired ? false : retryableAgentFailure(agentMessage),
+                    // The abort is Bridge's own reading of the vendor's words, so Bridge names the cause; a spent
+                    // allowance, read the same way, wins over it as it always has.
+                    ...(modelAborted && !bindingRequired && !verificationDetail ? { failure: bridgeCause("agent_model_abort", message) } : {}),
                     ...(providerQuotaRefusal(agentMessage) ? { failure: providerQuotaFailure(agentMessage) } : {}),
                     ...(signal ? { signal } : {}),
                     idempotency_key: `bridge:fail:${active.attemptId}`,
@@ -1865,6 +1893,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                             body: {
                                 error: classified.error,
                                 retryable: classified.retryable,
+                                ...(classified.failure ? { failure: classified.failure } : {}),
                                 idempotency_key: `bridge:claims-git-gate:${active.attemptId}`,
                             },
                         });
@@ -1881,6 +1910,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                         body: {
                             error: classified.error,
                             retryable: classified.retryable,
+                            ...(classified.failure ? { failure: classified.failure } : {}),
                             idempotency_key: `bridge:claims-git-gate:${active.attemptId}`,
                         },
                     });
@@ -1953,6 +1983,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                             resumeSessionId,
                             timeoutMs,
                             maxDurationMs: workPackage?.max_duration_ms,
+                            maxTurns: config.maxTurns,
                             model: selection.model,
                             fuel,
                             fuelSource,
@@ -2059,6 +2090,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                     body: {
                         error: classified.error,
                         retryable: classified.retryable,
+                        ...(classified.failure ? { failure: classified.failure } : {}),
                         idempotency_key: `bridge:claims-git-gate-report:${active.attemptId}`,
                     },
                 });
@@ -2195,6 +2227,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                 body: {
                     error: classified.error,
                     retryable: classified.retryable,
+                    ...(!verificationFailed && classified.failure ? { failure: classified.failure } : {}),
                     ...(verificationFailed ? { signal: {
                             phase: "verification",
                             witness: "bridge",
@@ -2305,6 +2338,7 @@ async function runLandContinuationTurn(input) {
         resumeSessionId: input.resumeSessionId ?? undefined,
         timeoutMs: input.timeoutMs,
         maxDurationMs: input.maxDurationMs,
+        maxTurns: input.config.maxTurns,
         model: input.selection.model ?? undefined,
         fuel: input.fuel,
         fuelSource: input.fuelSource,

package/dist/failure-signal.js

@@ -17,7 +17,7 @@ export const failureSignalSchema = z.object({
     phase: z.enum(["claim", "checkout", "bootstrap", "agent", "verification", "delivery_report", "land"]),
     /** Who produced the evidence for this signal: Bridge itself, the agent CLI, or the vendor. */
     witness: z.enum(["bridge", "agent", "vendor"]),
-    kind: z.enum(["exit_code", "timeout", "denied_tool", "quota", "usage_error", "no_output", "contract", "verification_failed", "model_unbound", "stalled", "vendor_transient", "gateway_refusal", "unknown"]),
+    kind: z.enum(["exit_code", "timeout", "turn_cap", "denied_tool", "quota", "usage_error", "no_output", "contract", "verification_failed", "model_unbound", "stalled", "vendor_transient", "gateway_refusal", "unknown"]),
     /** The exact command when phase is verification or bootstrap. */
     command: z.string().max(2_000).optional(),
     /** The repository paths a Bridge check names as the cause, bounded so one signal stays readable. */
@@ -49,6 +49,17 @@ export const failureSignalSchema = z.object({
         pinned: z.string().max(200).nullable(),
         observed: z.string().max(200).nullable(),
     }).optional(),
+    /**
+     * The per-attempt turn cap the run reached, and the turns the vendor counted against it.
+     *
+     * Both numbers are the operator's own: the limit is this computer's setting, and the count is what
+     * the CLI said it spent. A card that only said "the run was stopped" would leave the operator
+     * unable to tell a cap that is too tight from work that is looping.
+     */
+    turn_cap: z.object({
+        limit: z.number().int().min(1),
+        turns: z.number().int().min(0),
+    }).optional(),
     /** The intelligence tier and driver named by a `model_unbound` signal: no configured candidate
      *  the retry could bind, so the run must not repeat the abort on the same or an unconfirmed name. */
     model_binding: z.object({
@@ -64,6 +75,38 @@ export const failureSignalSchema = z.object({
      */
     model: z.string().max(200).optional(),
 });
+/**
+ * The causes Bridge names itself — before the agent starts, or while finishing its report — as one
+ * table keyed by code, so Bridge sends the envelope and the control plane validates it (K3).
+ *
+ * Until 2026-09-15 Bridge wrote these causes as sentences chosen so the control plane's regex
+ * tables would recognise them; every wording change on either side was a silent reclassification.
+ * The texts here are those tables' texts, moved: one definition, read by both twins.
+ */
+export const BRIDGE_CAUSES = {
+    workspace_repository_mismatch: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "This checkout does not match the work package repository.", next_action: "Run Bridge from the matching repository checkout, then recheck readiness." },
+    workspace_unavailable: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "Bridge cannot read the configured workspace.", next_action: "Restore access to the workspace, then recheck readiness." },
+    workspace_head_changed: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "The checkout changed after Conduit prepared the assignment.", next_action: "Let the checkout settle, then recheck readiness." },
+    base_not_ancestor: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "Conduit could not prepare the required project version on this computer.", next_action: "No Git work is required from the product owner. Keep the computer and Bridge online, then try again so Bridge can refresh the project. If the hold returns, the computer operator should check Bridge's repository access." },
+    workspace_dirty: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "The source workspace has uncommitted changes.", next_action: "Commit, stash, or discard the local changes, then recheck readiness." },
+    missing_verification: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "This checkout has no verification commands Conduit can run for this package.", next_action: "Conductor will adjust how this package is verified. Open Connect only if the computer itself is unhealthy — you do not need to author test commands." },
+    verification_unwitnessable: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "The project's verification command runs but prints nothing, so test evidence cannot be witnessed.", next_action: "Fix the verification recipe in the checkout so it prints real output, then recheck readiness. You do not need to author test commands for the agent." },
+    execution_contract_failed: { class: "contract", disposition: "rework", responsible_party: "conduit", message: "The agent could not satisfy the approved execution contract.", next_action: "Review the last run and rework the same contract; change the plan only if its authority or outcome is wrong." },
+    agent_no_land_commit: { class: "contract", disposition: "rework", responsible_party: "conduit", message: "The agent finished without committing the repository changes this package requires.", next_action: "Retry implement. Conductor will brief a land-focused recovery attempt — you do not need to edit technical constraints." },
+    execution_unclassified: { class: "platform", disposition: "stop", responsible_party: "conduit", message: "Conduit could not classify this failure.", next_action: "Ask Conductor to diagnose the stopped run, then retry the same plan or open a revision. You do not need to translate the technical detail into agent constraints." },
+    forge_unreachable: { class: "transient", disposition: "retry", responsible_party: "conduit", message: "The connection to the code host failed mid-run.", next_action: "Nothing to repair here — the run stopped on a network fault, not on the work. Retry the same plan." },
+    agent_model_abort: { class: "transient", disposition: "retry", responsible_party: "conduit", message: "The agent CLI stopped its own run: it detected a loop, asked for a different model, or the prompt did not fit the context window.", next_action: "Conduit retries on another model of the same intelligence tier. The product owner does not need to author technical constraints." },
+    agent_execution_failed: { class: "transient", disposition: "retry", responsible_party: "conduit", message: "The agent run failed before delivery.", next_action: "Conduit will retry with bounded backoff while the authoring budget remains. No technical constraints are required from the owner." },
+};
+/** Is this string a code Bridge may name as a cause? Narrows a caller-supplied reason. */
+export function isBridgeCauseCode(value) {
+    return Object.prototype.hasOwnProperty.call(BRIDGE_CAUSES, value);
+}
+/** The envelope for a cause Bridge names by code, with the run's own words as the detail. */
+export function bridgeCause(code, detail) {
+    const cause = BRIDGE_CAUSES[code];
+    return { code, ...cause, ...(detail?.trim() ? { diagnostic_detail: detail.trim() } : {}) };
+}
 /** A reset time as a person reads it: "2026-09-10 09:36 UTC". Every reset is stored ISO in UTC. */
 function resetClock(resetsAt) {
     return `${resetsAt.slice(0, 16).replace("T", " ")} UTC`;
@@ -110,20 +153,45 @@ export function agentExitSignal(input) {
     const output = `${input.stderr ?? ""}\n${input.stdout ?? ""}`;
     const decisiveOutput = output.replace(CLAUDE_UNRECOGNIZED_MODEL_WARNING, "");
     const rejectedModel = Boolean(input.model) && MODEL_REJECTION.test(decisiveOutput);
+    const kind = TOOL_DENIAL.test(decisiveOutput) ? "denied_tool"
+        : GATEWAY_REFUSAL.test(decisiveOutput) ? "gateway_refusal"
+            : rejectedModel ? "usage_error"
+                : VENDOR_TRANSIENT.test(decisiveOutput) ? "vendor_transient"
+                    : "unknown";
+    // T196: the gateway's own words travel as the vendor message, whichever stream carried them.
+    // Claude Code prints "API Error: 400 Unknown model alias" on stdout, and the owner's card read
+    // "Conduit's gateway refused the agent's request:" followed by nothing (2026-09-15).
+    const refusalLine = kind === "gateway_refusal"
+        ? decisiveOutput.split("\n").map((line) => line.trim()).find((line) => GATEWAY_REFUSAL.test(line))
+        : undefined;
     return {
         phase: "agent",
         witness: "agent",
-        kind: TOOL_DENIAL.test(decisiveOutput) ? "denied_tool"
-            : GATEWAY_REFUSAL.test(decisiveOutput) ? "gateway_refusal"
-                : rejectedModel ? "usage_error"
-                    : VENDOR_TRANSIENT.test(decisiveOutput) ? "vendor_transient"
-                        : "unknown",
+        kind,
         exit_code: input.exit_code ?? null,
         ...(input.model ? { model: input.model } : {}),
+        ...(refusalLine ? { vendor_message: refusalLine.slice(0, 400) } : {}),
         ...(input.stderr?.trim() ? { stderr_tail: bounded2k(input.stderr) } : {}),
         ...(input.stdout?.trim() ? { stdout_tail: bounded2k(input.stdout) } : {}),
     };
 }
+/**
+ * The signal a driver emits when the machine's turn cap, not the work, ended the run.
+ *
+ * T197: the agent CLI re-sends the whole conversation every turn, so an attempt's token bill grows
+ * with the square of its turn count — 33 turns for one paragraph of documentation cost $5.27 on
+ * 2026-09-15, and nothing stopped it. The cap stops it; this signal makes the stop a decided
+ * environment Hold rather than a failure some later rule retries blind at the same price.
+ */
+export function turnCapSignal(input) {
+    return {
+        phase: "agent",
+        witness: "vendor",
+        kind: "turn_cap",
+        turn_cap: { limit: input.maxTurns, turns: input.turns },
+        ...(input.model ? { model: input.model } : {}),
+    };
+}
 /**
  * The signal Bridge emits when a pinned execution fact no longer matches the workspace.
  *
@@ -173,6 +241,24 @@ export function verificationScopeConflictSignal(paths) {
  * Bridge writes it, the classifier reads it, so the two sides agree on one string and not on prose.
  */
 export const VERIFICATION_FAILS_ON_BASE = "verification fails on the base commit";
+/**
+ * A shell reporting that a command the gate needs does not exist on this computer. Both the prose
+ * classifier and the base-gate rule read it: a gate that cannot start is a missing tool, never a
+ * red commit.
+ */
+export const WORKSPACE_DEPENDENCIES_MISSING_PATTERN = /(?:^|\n)\s*(?:\/(?:usr\/)?bin\/)?(?:ba|z|da)?sh:\s*(?:(?:\d+:\s*)?[^:\n]{1,120}:\s*(?:command\s+)?not found|command not found:\s*[^\n]+)\s*(?=\n|$)|(?:^|\n)\s*'[^'\n]+' is not recognized as an internal or external command/im;
+/** The one envelope for a gate whose tool is absent from the checkout, wherever it was noticed. */
+export function workspaceDependenciesMissingFailure(detail) {
+    return {
+        code: "workspace_dependencies_missing",
+        class: "environment",
+        disposition: "hold",
+        responsible_party: "conduit",
+        message: "The checkout is missing a locked tool required by its verification command.",
+        next_action: "Bridge must complete deterministic workspace bootstrap before authoring resumes. No plan or compiler constraints are needed from the owner.",
+        diagnostic_detail: detail,
+    };
+}
 /**
  * The signal Bridge emits when a gate exits non-zero on the base commit, before the agent starts.
  *
@@ -225,6 +311,8 @@ function quotedVendorText(signal) {
  * 8. verification run by Bridge, any other cause → the verify class: diagnose and brief a repair.
  * 9. contract, or a delivery_report phase → the delivery contract codes: rework.
  * 10. timeout → the turn reached its execution limit: stop.
+ * 11. turn_cap → the run reached the computer's per-attempt turn cap: Hold, on the operator, who
+ *     decides whether the work was looping or the cap is too tight. Never a silent retry.
  */
 export function classifyFailureSignal(signal) {
     // T90: ahead of every other rule, because a stalled attempt has no vendor evidence at all — the
@@ -335,6 +423,14 @@ export function classifyFailureSignal(signal) {
         && signal.vendor_message === VERIFICATION_FAILS_ON_BASE) {
         const command = signal.command ?? "the declared gate";
         const base = signal.base_commit ?? "the base commit";
+        const output = [signal.stderr_tail, signal.stdout_tail].filter(Boolean).join("\n");
+        // T198: a gate that could not start (`sh: tsc: not found`, exit 127) says nothing about the
+        // base commit. It is the computer's checkout that lacks a tool — an environment Hold that
+        // clears when the workspace is bootstrapped, not a contract Hold on the author that never
+        // clears. runner-2's first claim (2026-09-15) sat on the author for a missing `node_modules`.
+        if (signal.exit_code === 127 || WORKSPACE_DEPENDENCIES_MISSING_PATTERN.test(output)) {
+            return workspaceDependenciesMissingFailure([`$ ${command}`, `exit ${signal.exit_code ?? "unknown"}`, output].filter(Boolean).join("\n"));
+        }
         return {
             code: "verification_red_base",
             class: "contract",
@@ -425,6 +521,22 @@ export function classifyFailureSignal(signal) {
             diagnostic_detail: signal.stderr_tail,
         };
     }
+    // T197: the run was stopped by this computer's own turn cap. Retrying it spends the same money to
+    // reach the same cap, so the operator decides: raise the cap for work that genuinely needs the
+    // turns, or read the run and find why it was looping.
+    if (signal.kind === "turn_cap") {
+        const limit = signal.turn_cap?.limit ?? 0;
+        const spent = signal.turn_cap?.turns ?? 0;
+        return {
+            code: "agent_turn_cap_reached",
+            class: "environment",
+            disposition: "hold",
+            responsible_party: "computer_operator",
+            message: `The run hit this computer's turn cap of ${limit} turns after ${spent}, so Conduit stopped it before it spent more.`,
+            next_action: `Read the run: work that needs more turns gets a larger cap with \`npx @miraland-labs/conduit-bridge@latest runner --max-turns <n>\` on this computer, and a run that was looping needs the package narrowed. Then Recheck.`,
+            diagnostic_detail: `turn cap ${limit}; turns ${spent}`,
+        };
+    }
     return null;
 }
 /**

package/dist/investigation.js

@@ -325,6 +325,7 @@ export async function executeNextInvestigation(client, config, workspace, brief,
             fuelSource: investigationFuel,
             fuel,
             timeoutMs: Math.min(timeoutMs ?? assignment.budget.max_duration_ms, assignment.budget.max_duration_ms),
+            maxTurns: config.maxTurns,
         });
         await learnDriverFuel(config, driver.name, investigationFuel, result);
         if (result.status === "failed") {

package/dist/preflight.js

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { promisify } from "node:util";
 import { buildWorkspaceBrief, normalizeRepositoryUrl } from "./brief.js";
+import { resolveMaxTurns } from "./execution-budget.js";
 import { hasAntigravityLogin, hasClaudeLogin, hasGrokLogin, hasOpenAiLogin, hasOpenCodeLogin, driverExecutable, } from "./driver.js";
 import { laneQuota, laneTierBindings, localFuelOnlyDriver, onlineDriverIds, resolveDriverFuel, supportsReadOnlyDiagnosis } from "./drivers.js";
 /** Protocol 3: read-only diagnosis can reuse a retained failed-attempt worktree. */
@@ -228,7 +229,8 @@ export async function runBridgePreflight(input, deps = {}) {
         issues.push({ code: "driver_quota_exhausted" });
     }
     return { ready: issues.length === 0, checked_at: new Date().toISOString(), workspace_clean: workspaceClean,
-        drivers: driverChecks.map((check) => check.snapshot), models_fingerprint: modelsFingerprint(input.config), issues,
+        drivers: driverChecks.map((check) => check.snapshot), models_fingerprint: modelsFingerprint(input.config),
+        max_turns: resolveMaxTurns(input.config.maxTurns), issues,
         ...(input.managedRoot?.trim() ? { managed_root: input.managedRoot.trim() } : {}) };
 }
 let cached = null;
@@ -240,7 +242,7 @@ export const PREFLIGHT_CACHE_TTL_MS = 5 * 60_000;
 /** Keep auth probes off the 15-second heartbeat hot path while still expiring readiness promptly. */
 export async function cachedBridgePreflight(input, options = {}) {
     const online = input.processOnlineIds?.length ? input.processOnlineIds : onlineDriverIds(input.config);
-    const key = JSON.stringify([input.workspace, input.expectedRepository ?? "", online, input.config.fuelSource, input.config.drivers,
+    const key = JSON.stringify([input.workspace, input.expectedRepository ?? "", online, input.config.fuelSource, input.config.drivers, input.config.maxTurns ?? 0,
         input.refresh?.state ?? "", input.refresh?.local_commits ?? 0, input.managedRoot ?? ""]);
     if (!options.force && cached?.key === key && Date.now() - cached.at < PREFLIGHT_CACHE_TTL_MS)
         return cached.report;
@@ -262,6 +264,7 @@ export function unavailableWorkspacePreflight(input) {
         drivers: online.map((id) => ({ id, version: null, ready: false, diagnosis_read_only: supportsReadOnlyDiagnosis(id), compatibility_fingerprint: null,
             tiers: laneTierBindings(input.config, id) })),
         models_fingerprint: modelsFingerprint(input.config),
+        max_turns: resolveMaxTurns(input.config.maxTurns),
         issues,
         ...(input.managedRoot?.trim() ? { managed_root: input.managedRoot.trim() } : {}),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miraland-labs/conduit-bridge",
-  "version": "0.16.104",
+  "version": "0.16.106",
   "description": "Conduit Bridge CLI \u2014 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": {