@miraland-labs/conduit-bridge 0.16.22 → 0.16.24

package/dist/cli.js

@@ -14,6 +14,7 @@ import { detectInstalledClients, localFuelOnlyClients, suggestFuelSource } from
 import { DRIVERS } from "./driver.js";
 import { driversHeartbeatReport, driverLabel, heartbeatStatusForDrivers, isSupportedDriverId, listDriverLanes, onlineDriverIds, seedDriversFromDetection, seedDriverLanes, setDriverFuel, setDriversOnline, } from "./drivers.js";
 import { buildWorkspaceBrief } from "./brief.js";
+import { BOOTSTRAP_RESULTS, buildSovereignExecutionFacts } from "./execution-facts.js";
 import { ensureCheckout } from "./checkout.js";
 import { buildOnShiftIntentProof, maybeApplyOnShiftIntent } from "./on-shift-apply.js";
 import { loadOpsEnv, OPS_VERBS, runOps } from "./ops.js";
@@ -37,6 +38,12 @@ function parseFuelSource(value) {
         return value;
     throw new Error("Fuel source must be conduit or local");
 }
+function parseBootstrapResult(value) {
+    const result = BOOTSTRAP_RESULTS.find((candidate) => candidate === value);
+    if (!result)
+        throw new Error(`Bootstrap result must be one of: ${BOOTSTRAP_RESULTS.join(", ")}`);
+    return result;
+}
 async function connect() {
     const { values } = parseArgs({ args: process.argv.slice(3), options: { url: { type: "string" }, code: { type: "string" }, fuel: { type: "string" } } });
     if (!values.url || !values.code)
@@ -319,7 +326,7 @@ async function installService() {
     let config = await loadConfig();
     const { values } = parseArgs({ args: process.argv.slice(3), options: {
             workspace: { type: "string" }, interval: { type: "string" }, "agent-timeout-minutes": { type: "string" },
-            "ensure-checkout": { type: "string" },
+            "ensure-checkout": { type: "string" }, "bootstrap-result": { type: "string" },
         } });
     if (!values.workspace) {
         throw new Error(`Usage: ${bridgeUsage("install-service", "--workspace", "<repository-path>", "[--ensure-checkout <repository-url>]")} (workspace required; uses online driver lanes)`);
@@ -329,6 +336,9 @@ async function installService() {
         throw new Error(`No online driver lanes. Run \`${bridgeUsage("drivers", "online", AGENT_PLACEHOLDER)}\` first.`);
     }
     const workspace = resolve(values.workspace);
+    const bootstrapResult = values["bootstrap-result"]
+        ? parseBootstrapResult(values["bootstrap-result"])
+        : undefined;
     if (values["ensure-checkout"]) {
         const result = await ensureCheckout(workspace, values["ensure-checkout"]);
         console.log(result === "cloned"
@@ -340,6 +350,7 @@ async function installService() {
         interval: values.interval,
         agentTimeoutMinutes: values["agent-timeout-minutes"],
         ensureCheckout: values["ensure-checkout"],
+        bootstrapResult,
     });
     console.log(`Installed Conduit Bridge v${bridgeVersion()} (protocol ${BRIDGE_PROTOCOL_VERSION}) runner service (${result.platform}): ${result.path}`);
     console.log(`Online lanes: ${onlineDriverIds(config).join(", ")}. Toggle with \`${bridgeUsage("drivers", "online|offline", "…")}\`.`);
@@ -466,9 +477,13 @@ async function runner() {
     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" },
+            "bootstrap-result": { type: "string" },
         } });
     let config = await loadConfig();
     const fuelOverride = parseFuelSource(values.fuel);
+    const bootstrapResult = values["bootstrap-result"]
+        ? parseBootstrapResult(values["bootstrap-result"])
+        : undefined;
     if (fuelOverride) {
         config.fuelSource = fuelOverride;
         await saveConfigPrefs(config);
@@ -511,7 +526,7 @@ async function runner() {
             const preflight = workspace
                 ? await cachedBridgePreflight({ config, workspace, brief: currentBrief ?? undefined })
                 : unavailableWorkspacePreflight({ config });
-            const hb = await heartbeat(client, config, workspace, currentBrief, preflight);
+            const hb = await heartbeat(client, config, workspace, currentBrief, preflight, undefined, bootstrapResult);
             if (hb.staleBridge) {
                 console.error(`Bridge update required: running protocol ${BRIDGE_PROTOCOL_VERSION}; control plane requires protocol ${hb.requiredProtocol ?? "unknown"} (minimum Bridge ${hb.minimumVersion ?? "unknown"}). Reinstall the latest Bridge, then restart this runner.`);
                 await new Promise((resolveSleep) => setTimeout(resolveSleep, Math.max(intervalMs, 60_000)));
@@ -548,7 +563,7 @@ async function runner() {
             }
             const intentProof = buildOnShiftIntentProof({ currentWorkspace: workspace, onShift: hb.on_shift });
             if (intentProof) {
-                await heartbeat(client, config, workspace, currentBrief, preflight, intentProof);
+                await heartbeat(client, config, workspace, currentBrief, preflight, intentProof, bootstrapResult);
             }
             await renewLeases(client, config);
             if (workspace && onlineDriverIds(config).length) {
@@ -561,7 +576,19 @@ async function runner() {
                     heartbeat: async () => {
                         const currentBrief = await buildWorkspaceBrief(workspace).catch(() => brief);
                         const preflight = await cachedBridgePreflight({ config, workspace, brief: currentBrief ?? undefined });
-                        await heartbeat(client, config, workspace, currentBrief, preflight);
+                        await heartbeat(client, config, workspace, currentBrief, preflight, undefined, bootstrapResult);
+                    },
+                    beforeClaim: async (driverId) => {
+                        // Never let the five-minute heartbeat cache span a CLI upgrade into a certified claim.
+                        // Publish the fresh probe first; the Control Plane then remains the authority for the
+                        // exact version frozen onto the claim response and event.
+                        const currentBrief = await buildWorkspaceBrief(workspace).catch(() => brief);
+                        const preflight = await cachedBridgePreflight({ config, workspace, brief: currentBrief ?? undefined }, { force: true });
+                        const hb = await heartbeat(client, config, workspace, currentBrief, preflight, undefined, bootstrapResult);
+                        if (hb.staleBridge)
+                            return false;
+                        const lane = preflight.drivers.find((candidate) => candidate.id === driverId);
+                        return preflight.ready && lane?.ready === true && typeof lane.version === "string" && lane.version.length > 0;
                     },
                     heartbeatIntervalMs: intervalMs,
                 }, running, {});
@@ -578,19 +605,29 @@ async function runner() {
         await new Promise((resolveSleep) => setTimeout(resolveSleep, intervalMs));
     }
 }
-async function heartbeat(client, config, workspacePath, brief, preflight, intentProof) {
+async function heartbeat(client, config, workspacePath, brief, preflight, intentProof, bootstrapResult) {
     const online = onlineDriverIds(config);
     const status = heartbeatStatusForDrivers(online);
+    const version = bridgeVersion();
+    const executionFacts = await buildSovereignExecutionFacts({
+        workspace: workspacePath,
+        brief,
+        workspaceClean: preflight.workspace_clean,
+        bridgeVersion: version,
+        bridgeProtocol: BRIDGE_PROTOCOL_VERSION,
+        bootstrapResult,
+    });
     const response = await client.request("/runner/v1/heartbeat", { method: "POST", body: JSON.stringify({
             status,
             capabilities: config.capabilities,
             lease_capacity: config.leaseCapacity,
             workspace_path: workspacePath,
             fuel_source: config.fuelSource === "local" ? "local" : "conduit",
-            bridge_version: bridgeVersion(),
+            bridge_version: version,
             bridge_protocol: BRIDGE_PROTOCOL_VERSION,
             drivers: driversHeartbeatReport(config, config.activeAttempts),
             preflight,
+            execution_facts: executionFacts,
             ...(intentProof ? { on_shift_intent_proof: intentProof } : {}),
             ...(brief ? { workspace_brief: brief } : {}),
         }) });

package/dist/execution-facts.js

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import { access, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { normalizeRepositoryUrl } from "./brief.js";
+const execFileAsync = promisify(execFile);
+export const EXECUTION_CLASSES = ["observe", "observe_network", "publish_artifact", "verify", "mutate_repo"];
+export const BOOTSTRAP_RESULTS = ["not_applicable", "not_run", "installed", "failed"];
+/**
+ * Lockfiles are hashed, never uploaded. The set is intentionally explicit and root-scoped so a
+ * dependency change becomes a durable identity without moving repository contents onto Conduit.
+ */
+const LOCKFILE_NAMES = [
+    "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml",
+    "Cargo.lock", "poetry.lock", "Pipfile.lock", "go.sum", "Gemfile.lock", "composer.lock",
+];
+/** Stable identity for the exact bounded verification command list used by Bridge. */
+export function verificationCommandsDigest(commands) {
+    const normalized = [...new Set(commands.map((command) => command.trim()).filter(Boolean))];
+    if (!normalized.length)
+        return null;
+    return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+}
+/**
+ * Hash the root lockfiles in deterministic name order. Missing or unreadable lockfiles are simply
+ * absent from the identity; a workspace with no readable lockfile reports null rather than an
+ * invented digest.
+ */
+export async function lockfileDigest(workspace) {
+    const hash = createHash("sha256");
+    let found = false;
+    for (const name of LOCKFILE_NAMES) {
+        try {
+            const contents = await readFile(join(workspace, name));
+            hash.update(name);
+            hash.update("\0");
+            hash.update(contents);
+            hash.update("\0");
+            found = true;
+        }
+        catch {
+            // A missing or unreadable optional lockfile contributes no claim.
+        }
+    }
+    return found ? hash.digest("hex") : null;
+}
+/**
+ * Report whether a JavaScript workspace has dependencies installed. This is an observed state, not
+ * a promise that Bridge will run a package manager during execution. Managed installs already run
+ * `npm ci` before the service is advertised, so a present node_modules directory is the durable
+ * local evidence available on later heartbeats.
+ */
+export async function bootstrapResultForWorkspace(workspace) {
+    if (!workspace)
+        return "not_applicable";
+    try {
+        await access(join(workspace, "package.json"));
+    }
+    catch {
+        return "not_applicable";
+    }
+    try {
+        const lockfile = await Promise.any(LOCKFILE_NAMES.map(async (name) => {
+            await access(join(workspace, name));
+            return true;
+        }));
+        void lockfile;
+    }
+    catch {
+        return "not_run";
+    }
+    try {
+        const dependencies = await stat(join(workspace, "node_modules"));
+        return dependencies.isDirectory() ? "installed" : "not_run";
+    }
+    catch {
+        return "not_run";
+    }
+}
+/** Read the source/attempt tree's Git cleanliness without returning its contents. */
+export async function workspaceIsClean(workspace) {
+    try {
+        const result = await execFileAsync("git", ["-C", workspace, "status", "--porcelain", "--untracked-files=normal"], {
+            timeout: 15_000,
+            windowsHide: true,
+        });
+        return result.stdout.trim().length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read only the bounded HEAD identity retained when an attempt terminates. */
+export async function finalCommitForWorkspace(workspace) {
+    try {
+        const result = await execFileAsync("git", ["-C", workspace, "rev-parse", "HEAD"], {
+            timeout: 15_000,
+            windowsHide: true,
+        });
+        return commitOrNull(result.stdout.trim());
+    }
+    catch {
+        return null;
+    }
+}
+function commitOrNull(value) {
+    return value && /^[0-9a-f]{40,64}$/i.test(value) ? value.toLowerCase() : null;
+}
+/** Build one self-contained heartbeat/attempt snapshot from existing Bridge observations. */
+export async function buildSovereignExecutionFacts(input) {
+    const repository = input.brief?.repository?.trim();
+    return {
+        os: process.platform,
+        architecture: process.arch,
+        repository_fingerprint: repository ? normalizeRepositoryUrl(repository) : null,
+        claimed_head: commitOrNull(input.claimedHead ?? input.brief?.base_commit),
+        lockfile_digest: input.workspace ? await lockfileDigest(input.workspace) : null,
+        bootstrap_result: input.bootstrapResult ?? await bootstrapResultForWorkspace(input.workspace),
+        bridge_version: input.bridgeVersion,
+        bridge_protocol: input.bridgeProtocol,
+        execution_class: input.executionClass ?? null,
+        verification_commands_digest: verificationCommandsDigest(input.brief?.verification ?? []),
+        workspace_clean: input.workspaceClean,
+        final_commit: commitOrNull(input.finalCommit),
+    };
+}

package/dist/execution.js

@@ -10,6 +10,9 @@ import { attemptWorktreePath, createAttemptWorktree, proveResumeWorktree, quaran
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { buildWorkspaceBrief, ensureCommitAvailable, normalizeRepositoryUrl, resolveAttemptStartCommit } from "./brief.js";
+import { buildSovereignExecutionFacts, bootstrapResultForWorkspace, finalCommitForWorkspace, workspaceIsClean } from "./execution-facts.js";
+import { BRIDGE_PROTOCOL_VERSION } from "./preflight.js";
+import { bridgeVersion } from "./version.js";
 import { ensureDeliveryPullRequest } from "./ensure-pull-request.js";
 import { ensureLandCommit } from "./ensure-land-commit.js";
 import { AgentNoLandCommitError, agentNoLandCommitMessage, requiresLandCommit } from "./land-contract.js";
@@ -538,7 +541,9 @@ export async function pumpExecutionSlots(client, config, workspace, brief, timeo
         }
         if (!laneDriver || !driverId)
             break;
-        const claimed = await claimNextAssignment(client, config, workspace, brief, driverId, processOnlineIds);
+        const claimed = await claimNextAssignment(client, config, workspace, brief, driverId, processOnlineIds, {
+            beforeClaim: supervision?.beforeClaim,
+        });
         if (!claimed)
             break;
         const taskId = claimed.taskId;
@@ -557,7 +562,7 @@ export async function pumpExecutionSlots(client, config, workspace, brief, timeo
     return progressed;
 }
 /** Claim one assignment when under capacity; does not start the agent (multi-slot pump does). */
-export async function claimNextAssignment(client, config, workspace, brief, driverId, processOnlineIds) {
+export async function claimNextAssignment(client, config, workspace, brief, driverId, processOnlineIds, options = {}) {
     if (Object.keys(config.activeAttempts).length >= config.leaseCapacity)
         return null;
     const data = await client.request("/runner/v1/assignments");
@@ -607,6 +612,10 @@ export async function claimNextAssignment(client, config, workspace, brief, driv
         console.error(`Assignment ${assignment.id} rejected before claim: ${rejection}`);
         return null;
     }
+    if (selectedDriverId && options.beforeClaim && !await options.beforeClaim(selectedDriverId)) {
+        console.warn(`Assignment ${assignment.id} held before claim: driver ${selectedDriverId} preflight is not ready`);
+        return null;
+    }
     console.log(`Claiming ${assignment.execution_kind} assignment ${assignment.id} (attempt ${assignment.attempt_id})`);
     const fuelMode = selectedDriverId ? resolveDriverFuel(config, selectedDriverId) : undefined;
     const fuelProvenance = selectedDriverId ? resolveDriverFuelProvenance(config, selectedDriverId) : undefined;
@@ -631,7 +640,9 @@ export async function executeNextAssignment(client, config, driver, workspace, b
     if (Object.keys(config.activeAttempts).length)
         return recoverActiveAttempt(client, config, driver, workspace, brief, timeoutMs, supervision);
     const preferredDriverId = Object.entries(DRIVERS).find(([, candidate]) => candidate === driver)?.[0] ?? null;
-    const claimed = await claimNextAssignment(client, config, workspace, brief, preferredDriverId);
+    const claimed = await claimNextAssignment(client, config, workspace, brief, preferredDriverId, null, {
+        beforeClaim: supervision?.beforeClaim,
+    });
     if (!claimed)
         return false;
     const selectedDriver = claimedAssignmentDriver(driver, claimed.driverId);
@@ -899,8 +910,20 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
             normativeRefs: normativeMaterialized,
         });
     const resuming = Boolean(options.forceResumeSessionId);
+    const executionFacts = await buildSovereignExecutionFacts({
+        workspace: attemptWorkspace,
+        brief: attemptBrief,
+        workspaceClean: await workspaceIsClean(workspace),
+        bridgeVersion: bridgeVersion(),
+        bridgeProtocol: BRIDGE_PROTOCOL_VERSION,
+        executionClass,
+        claimedHead: executionContract.claimed_head ?? startCommit,
+        bootstrapResult: await bootstrapResultForWorkspace(workspace),
+    });
+    await client.updateAttempt(taskId, { executionFacts });
     await client.attemptRequest(taskId, "progress", {
         phase: diagnosis ? "inspecting" : "changing",
+        execution_facts: executionFacts,
         message: resuming
             ? `Resuming ${driver.name} after Bridge restart with proven session and worktree.`
             : diagnosis
@@ -1587,6 +1610,10 @@ async function submitFinishedDelivery(client, taskId) {
     const active = client.attempt(taskId);
     if (!active.delivery)
         throw new Error("Finished agent run is missing its persisted Delivery data");
+    const finalCommit = active.delivery.report.head_commit?.toLowerCase() ?? null;
+    if (finalCommit && active.executionFacts) {
+        await client.updateAttempt(taskId, { executionFacts: { ...active.executionFacts, final_commit: finalCommit } });
+    }
     const terminal = await prepareDelivery(client, active.attemptId, taskId, active.delivery.report);
     await client.attemptRequest(taskId, "progress", { phase: "preparing_delivery", message: "Agent finished; submitting the Delivery.", idempotency_key: `bridge:progress:${active.attemptId}:delivery` });
     return queueTerminal(client, taskId, terminal);
@@ -1862,7 +1889,19 @@ function retainDiagnosticWorktree(response) {
     return response.retain_worktree === true || response.status === "invalid_lease";
 }
 async function queueTerminal(client, taskId, terminal) {
-    await client.updateAttempt(taskId, { phase: "terminal_pending", terminal });
+    const active = client.attempt(taskId);
+    let executionFacts = active.executionFacts;
+    if (executionFacts && executionFacts.final_commit === null && active.worktreePath) {
+        const finalCommit = await finalCommitForWorkspace(active.worktreePath);
+        if (finalCommit) {
+            executionFacts = { ...executionFacts, final_commit: finalCommit };
+            await client.updateAttempt(taskId, { executionFacts });
+        }
+    }
+    const body = executionFacts && !terminal.body.execution_facts
+        ? { ...terminal.body, execution_facts: executionFacts }
+        : terminal.body;
+    await client.updateAttempt(taskId, { phase: "terminal_pending", terminal: { ...terminal, body } });
     return flushTerminal(client, taskId);
 }
 export async function flushTerminal(client, taskId) {

package/dist/land-contract.js

@@ -19,11 +19,6 @@ export const AGENT_NO_LAND_COMMIT_PREFIX = "Agent did not land repository change
 export function agentNoLandCommitMessage(baseCommit) {
     return `${AGENT_NO_LAND_COMMIT_PREFIX}: the attempt branch has no commit after base ${baseCommit.slice(0, 12)}.`;
 }
-/** Legacy ensureDeliveryPullRequest text — kept recognizable for stored failures. */
-export const LEGACY_NO_LAND_COMMIT_PATTERN = /no commit after base .*; this run produced no change to deliver/i;
-export function isAgentNoLandCommitMessage(message) {
-    return message.startsWith(AGENT_NO_LAND_COMMIT_PREFIX) || LEGACY_NO_LAND_COMMIT_PATTERN.test(message);
-}
 export class AgentNoLandCommitError extends Error {
     baseCommit;
     constructor(baseCommit) {

package/dist/ops.js

@@ -570,6 +570,7 @@ export async function runOps(verb, argv = [], deps = {}) {
         }
         const workspace = resolve(expandOpsValue(installEnv.CONDUIT_WORKSPACE));
         const drivers = await (deps.resolveInstallDrivers ?? resolveInstallDrivers)(installEnv, installArgv);
+        let bootstrapResult;
         if (installEnv.CONDUIT_REPO) {
             const checkout = deps.ensureCheckout ?? ensureCheckout;
             const result = await checkout(workspace, installEnv.CONDUIT_REPO);
@@ -587,7 +588,7 @@ export async function runOps(verb, argv = [], deps = {}) {
                 && !isAbsolute(managedRelative));
             if (managedCheckout) {
                 const bootstrap = deps.bootstrapWorkspace ?? bootstrapManagedWorkspace;
-                const bootstrapResult = bootstrap(workspace);
+                bootstrapResult = bootstrap(workspace);
                 if (bootstrapResult === "installed")
                     console.log(`Installed locked project dependencies in ${workspace}`);
             }
@@ -616,6 +617,8 @@ export async function runOps(verb, argv = [], deps = {}) {
         const installArgs = ["install-service", "--workspace", workspace];
         if (installEnv.CONDUIT_REPO)
             installArgs.push("--ensure-checkout", installEnv.CONDUIT_REPO);
+        if (bootstrapResult)
+            installArgs.push("--bootstrap-result", bootstrapResult);
         console.log(`Bridge: v${bridgeVersion()} (protocol ${BRIDGE_PROTOCOL_VERSION})`);
         console.log(`Installing runner for ${workspace} (drivers: ${drivers.join(", ")})`);
         runBridge(installArgs);

package/dist/preflight.js

@@ -16,9 +16,31 @@ function modelsFingerprint(config) {
     }).join(";");
     return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
 }
-// Protocol 8 reports the resolved lane fuel and credential provenance in heartbeat and claim, so
-// the control plane can freeze what will actually run before the agent spends tokens.
-export const BRIDGE_PROTOCOL_VERSION = 8;
+// Protocol 9 adds the Bridge-observed driver interface cohort to every preflight lane.
+export const BRIDGE_PROTOCOL_VERSION = 9;
+/** Keep the version identity within the same bound accepted by the heartbeat schema. */
+export const MAX_DRIVER_VERSION_LENGTH = 200;
+/**
+ * Turn one successful CLI version probe into a stable, bounded identity.
+ *
+ * A probe is deliberately stricter than "some output": warnings, multiple lines, control
+ * sequences, and overlong output cannot be assigned to a particular CLI version. Returning null
+ * makes the lane unready, so a stale/truncated prefix can never be used for certification.
+ */
+export function parseDriverVersion(result) {
+    if (result.code !== 0)
+        return null;
+    const streams = [result.stdout, result.stderr]
+        .filter((value) => typeof value === "string")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (streams.length !== 1)
+        return null;
+    const version = streams[0];
+    if (version.length > MAX_DRIVER_VERSION_LENGTH || /[\r\n\u0000-\u001f\u007f]/u.test(version))
+        return null;
+    return version;
+}
 const execFileAsync = promisify(execFile);
 async function defaultCommandRunner(command, args, cwd) {
     try {
@@ -44,6 +66,55 @@ const DRIVER_COMMAND = {
 function executableFor(driver) {
     return driver === "codex" ? resolveCodexExecutable() : DRIVER_COMMAND[driver] ?? driver;
 }
+/**
+ * Primary-driver interface surfaces used by the existing AgentDriver implementations. This is
+ * deliberately not a hash of all help prose: vendor copy edits must not manufacture a new cohort.
+ */
+const DRIVER_INTERFACE_CONTRACTS = {
+    "claude-code": {
+        adapter_revision: 1,
+        help_args: ["--help"],
+        required: ["outputformat", "allowedtools", "disallowedtools"],
+        observed: ["outputformat", "allowedtools", "disallowedtools", "permissionmode", "resume", "model"],
+    },
+    codex: {
+        adapter_revision: 1,
+        help_args: ["exec", "--help"],
+        required: ["json", "sandbox"],
+        observed: ["json", "sandbox", "model", "config"],
+    },
+    cursor: {
+        adapter_revision: 1,
+        help_args: ["--help"],
+        required: ["outputformat", "workspace"],
+        observed: ["outputformat", "workspace", "trust", "force", "resume", "model"],
+    },
+};
+function normalizedHelpSurface(value) {
+    return value.toLowerCase().replace(/[-_\s]/g, "");
+}
+/**
+ * Fingerprint only what a bounded, non-spending interface probe can prove. It is not a claim that
+ * vendor semantics or model quality stayed identical; per-attempt gates and field outcomes remain
+ * authoritative for those facts.
+ */
+async function driverCompatibilityFingerprint(driver, workspace, run) {
+    const contract = DRIVER_INTERFACE_CONTRACTS[driver];
+    if (!contract)
+        return null;
+    const help = await run(executableFor(driver), contract.help_args, workspace);
+    if (help.code !== 0)
+        return null;
+    const surface = normalizedHelpSurface(`${help.stdout}\n${help.stderr}`);
+    if (!contract.required.every((signal) => surface.includes(signal)))
+        return null;
+    const features = contract.observed.map((signal) => [signal, surface.includes(signal)]);
+    return createHash("sha256").update(JSON.stringify({
+        driver,
+        adapter_revision: contract.adapter_revision,
+        features,
+    })).digest("hex");
+}
 async function localAuthenticationReady(driver, workspace, run) {
     if (driver === "claude-code")
         return hasClaudeLogin();
@@ -106,23 +177,25 @@ export async function runBridgePreflight(input, deps = {}) {
         const diagnosisReadOnly = supportsReadOnlyDiagnosis(driver);
         const fuel = resolveDriverFuel(input.config, driver);
         if (localFuelOnlyDriver(driver) && fuel !== "local") {
-            return { issue: { code: "driver_fuel_mismatch", driver }, snapshot: { id: driver, version: null, ready: false, diagnosis_read_only: diagnosisReadOnly } };
+            return { issue: { code: "driver_fuel_mismatch", driver }, snapshot: { id: driver, version: null, ready: false, diagnosis_read_only: diagnosisReadOnly, compatibility_fingerprint: null } };
         }
         const version = await run(executableFor(driver), ["--version"], input.workspace);
-        const versionText = `${version.stdout}${version.stderr}`.trim().slice(0, 200) || null;
-        if (version.code !== 0 || !`${version.stdout}${version.stderr}`.trim()) {
-            return { issue: { code: "driver_missing", driver }, snapshot: { id: driver, version: versionText, ready: false, diagnosis_read_only: diagnosisReadOnly } };
+        const versionText = parseDriverVersion(version);
+        if (!versionText) {
+            return { issue: { code: "driver_missing", driver }, snapshot: { id: driver, version: null, ready: false, diagnosis_read_only: diagnosisReadOnly, compatibility_fingerprint: null } };
         }
         if (fuel === "local" && !await localAuthenticationReady(driver, input.workspace, run)) {
-            return { issue: { code: "driver_not_authenticated", driver }, snapshot: { id: driver, version: versionText, ready: false, diagnosis_read_only: diagnosisReadOnly } };
+            return { issue: { code: "driver_not_authenticated", driver }, snapshot: { id: driver, version: versionText, ready: false, diagnosis_read_only: diagnosisReadOnly, compatibility_fingerprint: null } };
         }
         // Reported, not probed: the window state was learned from the vendor's last refusal and read
         // back through laneQuota, which retires a passed reset. Nothing is executed here, so a lane
         // running dry costs the heartbeat nothing.
         const quota = fuel === "local" ? laneQuota(input.config, driver) ?? undefined : undefined;
+        const compatibilityFingerprint = await driverCompatibilityFingerprint(driver, input.workspace, run);
         return {
             issue: null,
-            snapshot: { id: driver, version: versionText, ready: quota?.exhausted !== true, diagnosis_read_only: diagnosisReadOnly, ...(quota ? { quota } : {}) },
+            snapshot: { id: driver, version: versionText, ready: quota?.exhausted !== true, diagnosis_read_only: diagnosisReadOnly,
+                compatibility_fingerprint: compatibilityFingerprint, ...(quota ? { quota } : {}) },
         };
     }));
     issues.push(...driverChecks.map((check) => check.issue).filter((issue) => issue !== null));
@@ -137,10 +210,10 @@ export async function runBridgePreflight(input, deps = {}) {
 }
 let cached = null;
 /** Keep auth probes off the 15-second heartbeat hot path while still expiring readiness promptly. */
-export async function cachedBridgePreflight(input) {
+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]);
-    if (cached?.key === key && Date.now() - cached.at < 5 * 60_000)
+    if (!options.force && cached?.key === key && Date.now() - cached.at < 5 * 60_000)
         return cached.report;
     const report = await runBridgePreflight(input);
     cached = { key, at: Date.now(), report };
@@ -157,7 +230,7 @@ export function unavailableWorkspacePreflight(input) {
         ready: false,
         checked_at: new Date().toISOString(),
         workspace_clean: false,
-        drivers: online.map((id) => ({ id, version: null, ready: false, diagnosis_read_only: supportsReadOnlyDiagnosis(id) })),
+        drivers: online.map((id) => ({ id, version: null, ready: false, diagnosis_read_only: supportsReadOnlyDiagnosis(id), compatibility_fingerprint: null })),
         models_fingerprint: modelsFingerprint(input.config),
         issues,
     };

package/dist/service.js

@@ -30,6 +30,8 @@ export function runnerProgramArguments(options = {}) {
         args.push("--interval", options.interval);
     if (options.agentTimeoutMinutes)
         args.push("--agent-timeout-minutes", options.agentTimeoutMinutes);
+    if (options.bootstrapResult)
+        args.push("--bootstrap-result", options.bootstrapResult);
     return args;
 }
 /**

package/package.json

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