@miraland-labs/conduit-bridge 0.16.105 → 0.16.107

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(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}`,
                     },
                 });
@@ -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}`,
             },
         });
@@ -1762,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}`,
@@ -1871,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}`,
                             },
                         });
@@ -1887,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}`,
                         },
                     });
@@ -2066,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}`,
                     },
                 });
@@ -2202,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",

package/dist/failure-signal.js

@@ -75,6 +75,41 @@ 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];
+    // The control plane's envelope schema bounds the detail at 20,000 characters and refuses the
+    // whole terminal report otherwise; the run's words are cut there, never the report.
+    const text = detail?.trim() ?? "";
+    return { code, ...cause, ...(text ? { diagnostic_detail: text.length > 20_000 ? `${text.slice(0, 19_999)}…` : text } : {}) };
+}
 /** 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`;

package/package.json

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