@miraland-labs/conduit-bridge 0.16.106 → 0.16.108

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 { bridgeCause, executionFactChangedSignal, verificationRedBaseSignal, verificationScopeConflictSignal } from "./failure-signal.js";
+import { agentOutputCause, boundedDetail, 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";
@@ -113,7 +113,7 @@ export function providerQuotaFailure(detail) {
         responsible_party: "computer_operator",
         message: `The agent lane on this computer has spent its subscription allowance.${refills ? ` ${refills}` : ""}`,
         next_action: "Wait for the allowance to refill, bring another agent lane online to start sooner, or point this lane's model settings at a model that still has allowance.",
-        diagnostic_detail: detail,
+        diagnostic_detail: boundedDetail(detail),
     };
 }
 /**
@@ -185,7 +185,7 @@ 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. */
+/** Two finalize messages with builders of their own in the twin and the cause table. */
 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;
@@ -204,10 +204,12 @@ export function classifyFinalizeFailure(message) {
         return { retryable: false, error: message };
     if (FINALIZE_ENVIRONMENT_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.
+    // Bridge names the contract defect it found (K3); an unknown throw below stays prose until its
+    // own site names a code.
     if (FINALIZE_CONTRACT_PATTERN.test(message)) {
+        // The scope conflict Holds (contract/hold), and the runner's envelope schema admits only
+        // contract/rework from a supplied envelope — sending it would refuse the whole report. It stays
+        // prose until the finalize site emits it as a typed signal (K3 step 2b design).
         const failure = CONTRACT_SCOPE_CONFLICT_MESSAGE.test(message)
             ? undefined
             : VERIFICATION_UNWITNESSABLE_MESSAGE.test(message)
@@ -1205,7 +1207,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                         error: message,
                         retryable,
                         failure: retryable
-                            ? bridgeCause("agent_execution_failed", message)
+                            ? bridgeCause(forgeTransportFailure(message) ? "forge_unreachable" : "agent_execution_failed", message)
                             : bridgeCause(message.startsWith(NORMATIVE_REF_PREFIX) ? "execution_contract_failed" : "execution_unclassified", message),
                         idempotency_key: `bridge:normative-ref:${active.attemptId}`,
                     },
@@ -1278,7 +1280,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                     responsible_party: "computer_operator",
                     message: "Conductor is waiting for a diagnostic lane that can enforce read-only access.",
                     next_action: "Bring a Claude Code, Codex, Cursor, or Grok Build lane online on this computer, then Recheck. Do not author compiler constraints for the agent.",
-                    diagnostic_detail: detail,
+                    diagnostic_detail: boundedDetail(detail),
                 },
                 error: detail,
                 retryable: false,
@@ -1450,7 +1452,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                     responsible_party: "computer_operator",
                     message: "Conductor cannot prove that diagnosis will leave the retained worktree unchanged.",
                     next_action: "Restore a readable Git worktree on this computer, then Recheck.",
-                    diagnostic_detail: detail,
+                    diagnostic_detail: boundedDetail(detail),
                 },
                 error: detail,
                 retryable: false,
@@ -1653,7 +1655,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                                 ? "The selected diagnostic lane wrote to a worktree it was only allowed to inspect."
                                 : "Conductor cannot prove that diagnosis left the retained worktree unchanged.",
                             next_action: "Bring a diagnostic lane online that enforces read-only repository access, then Recheck.",
-                            diagnostic_detail: detail,
+                            diagnostic_detail: boundedDetail(detail),
                         },
                         error: detail,
                         retryable: false,
@@ -1666,11 +1668,15 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
             }
             if (result.status === "failed") {
                 const message = result.error ?? "Read-only diagnosis failed";
+                // A spent allowance keeps its prose reading here (the control plane quotes the reset clock
+                // from it); a computer fact in the CLI's words is named by code, as on the authoring path.
+                const diagnosisCause = providerQuotaRefusal(message) ? null : agentOutputCause(message);
                 const response = await queueTerminal(client, taskId, {
                     action: "fail",
                     body: {
                         error: message,
                         retryable: retryableAgentFailure(message),
+                        ...(diagnosisCause ? { failure: bridgeCause(diagnosisCause, message) } : {}),
                         idempotency_key: `bridge:diagnosis-fail:${active.attemptId}`,
                     },
                 });
@@ -1750,6 +1756,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                 : null;
             const abortPrefix = agentModelAbortPrefix(selection.model);
             const modelAborted = agentModelAborted(`${agentMessage}\n${result.signal?.stderr_tail ?? ""}`);
+            const agentCause = agentOutputCause(agentMessage);
             // T52: the epoch's second abort is not a retryable model swap — the first one already bought
             // the T34 retry, and a tier that aborts twice runs for the whole attempt budget (R12: three
             // "Agent Looping Detected" runs on the cursor CLI default). Hold on the tier instead.
@@ -1781,8 +1788,10 @@ 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.
+                    // Bridge's own readings of the vendor's words name the cause, in the order the control plane
+                    // always applied: a computer fact (sign-in, incompatible or missing CLI), then a model abort,
+                    // then a spent allowance, each later one winning.
+                    ...(!bindingRequired && !verificationDetail && agentCause ? { failure: bridgeCause(agentCause, message) } : {}),
                     ...(modelAborted && !bindingRequired && !verificationDetail ? { failure: bridgeCause("agent_model_abort", message) } : {}),
                     ...(providerQuotaRefusal(agentMessage) ? { failure: providerQuotaFailure(agentMessage) } : {}),
                     ...(signal ? { signal } : {}),
@@ -2950,7 +2959,7 @@ function deliveryReportRepairFailure(detail) {
         responsible_party: "conduit",
         message: "Conduit could not prepare a valid delivery report from the completed agent run.",
         next_action: "Conductor will prepare bounded recovery guidance. You do not need to edit technical constraints.",
-        diagnostic_detail: detail,
+        diagnostic_detail: boundedDetail(detail),
     };
 }
 /**
@@ -3085,7 +3094,7 @@ export async function flushTerminal(client, taskId) {
                             responsible_party: "conduit",
                             message: "The completed delivery report did not match the owner-approved acceptance criteria.",
                             next_action: "Conductor will prepare bounded recovery guidance. You do not need to edit technical constraints.",
-                            diagnostic_detail: detail,
+                            diagnostic_detail: boundedDetail(detail),
                         },
                         idempotency_key: `bridge:delivery-rejected:${active.attemptId}`,
                     },

package/dist/failure-signal.js

@@ -85,6 +85,9 @@ export const failureSignalSchema = z.object({
  */
 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." },
+    driver_not_authenticated: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "The selected agent CLI is not signed in.", next_action: "Sign in to the agent CLI on this computer, then recheck readiness." },
+    driver_incompatible: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "The installed agent CLI is incompatible with this Bridge driver.", next_action: "Update Bridge or the agent CLI to a compatible version, then recheck readiness." },
+    driver_missing: { class: "environment", disposition: "hold", responsible_party: "computer_operator", message: "The selected agent CLI is not available to Bridge.", next_action: "Install the CLI or repair the background service PATH, 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." },
@@ -103,9 +106,79 @@ 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. */
+/**
+ * The control plane's envelope schema bounds `diagnostic_detail` at 20,000 characters and refuses
+ * the whole terminal report otherwise: the run's words are cut here, never the report.
+ */
+export function boundedDetail(text) {
+    const trimmed = text.trim();
+    return trimmed.length > 20_000 ? `${trimmed.slice(0, 19_999)}…` : trimmed;
+}
 export function bridgeCause(code, detail) {
     const cause = BRIDGE_CAUSES[code];
-    return { code, ...cause, ...(detail?.trim() ? { diagnostic_detail: detail.trim() } : {}) };
+    const text = detail ? boundedDetail(detail) : "";
+    return { code, ...cause, ...(text ? { diagnostic_detail: text } : {}) };
+}
+/**
+ * Bridge's reading of the agent CLI's own words for three computer facts: not signed in, an
+ * incompatible CLI, a CLI that is not there. Vendor knowledge, held once, beside the other vendor
+ * patterns above; the control plane reads the code, never the sentence.
+ *
+ * Deliberately not bare `401`/`unauthorized`: those appear constantly in ordinary test and HTTP
+ * output, and matching them would reclassify a real verify failure as an environment Hold.
+ */
+const DRIVER_NOT_AUTHENTICATED = /driver[_ ]not[_ ]authenticated|not logged in|no login|not authenticated|login required|no api key|api key not found|missing api key|invalid api key|use \/login|\b401\b[^\n]{0,80}(?:api key|auth|credential|token)|(?:api key|auth|credential|token)[^\n]{0,80}\b401\b/i;
+const DRIVER_INCOMPATIBLE = /unknown (?:option|argument)|unrecognized (?:option|argument)|could not verify the installed cli|took "[^"]*" as its prompt|usage of agy|headless mode cannot prompt for|was auto-denied/i;
+const DRIVER_MISSING = /\benoent\b|agent cli is missing|driver[_ ]missing/i;
+export function agentOutputCause(output) {
+    if (DRIVER_NOT_AUTHENTICATED.test(output))
+        return "driver_not_authenticated";
+    if (DRIVER_INCOMPATIBLE.test(output))
+        return "driver_incompatible";
+    if (DRIVER_MISSING.test(output))
+        return "driver_missing";
+    return null;
+}
+/**
+ * Bridge `validateChangeScope` names the paths the approved change scope does not contain. The
+ * paths follow the colon, on one line, comma-separated.
+ */
+const CONTRACT_SCOPE_CONFLICT_PATTERN = /Agent reported changes outside the approved scope:[ \t]*(.+)/i;
+/**
+ * The approved change scope, when Bridge names it on its own line after the offending paths
+ * (`validateChangeScope` and the dry run's scope refusal both do, since T31). `.` in the paths
+ * pattern above never crosses this line, so the two extractions cannot collide.
+ */
+const APPROVED_CHANGE_SCOPE_LINE = /^approved change scope:[ \t]*(.+)$/im;
+/** The offered scope, bounded and ready to append after a colon-terminated sentence. */
+export function approvedScopeNote(detail) {
+    const scope = APPROVED_CHANGE_SCOPE_LINE.exec(detail)?.[1]?.trim();
+    if (!scope)
+        return "";
+    return `; approved change scope: ${scope.length > 1_500 ? `${scope.slice(0, 1_499)}…` : scope}`;
+}
+/** The work package asks for paths its own change scope does not contain. */
+export const CONTRACT_SCOPE_CONFLICT_CODE = "contract_scope_conflict";
+/**
+ * The defect is in the work package, not in the run: the contract told the engine to write paths
+ * the approved change scope does not contain. No agent, no diagnosis and no retry can widen a
+ * change scope, so this failure never enters the repair loop. It Holds on the initiative author
+ * (`hold`, not `rework`: a rework disposition seeds the repair outbox), and the Hold stays open
+ * until a plan revision replaces the work package.
+ */
+export function contractScopeConflictFailure(detail) {
+    const paths = CONTRACT_SCOPE_CONFLICT_PATTERN.exec(detail)?.[1]?.trim() ?? "";
+    // The offending paths are quoted verbatim, inside the envelope message bound.
+    const named = paths.length > 1_500 ? `${paths.slice(0, 1_499)}…` : paths;
+    return {
+        code: CONTRACT_SCOPE_CONFLICT_CODE,
+        class: "contract",
+        disposition: "hold",
+        responsible_party: "initiative_author",
+        message: `This work package had to write paths its approved change scope does not contain: ${named}${approvedScopeNote(detail)}`,
+        next_action: "Open revision and either add these paths to the change scope or make verification write to a temporary directory.",
+        diagnostic_detail: boundedDetail(detail),
+    };
 }
 /** A reset time as a person reads it: "2026-09-10 09:36 UTC". Every reset is stored ISO in UTC. */
 function resetClock(resetsAt) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miraland-labs/conduit-bridge",
-  "version": "0.16.106",
+  "version": "0.16.108",
   "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": {