@miraland-labs/conduit-bridge 0.9.5 → 0.9.7

package/README.md

@@ -2,7 +2,7 @@
 
 Local Bridge CLI for [Conduit](https://github.com/miralandlabs/conduit). Connects a computer to one organization, claims work, and drives a local agent.
 
-**Current npm:** `0.9.5` — **ops** helpers for macOS / Linux / Windows, LaunchAgent/systemd **PATH** for `~/.local/bin`, disconnect/disengage, multi-driver lanes, shared slots **1–4**, worktrees, optional `--ensure-checkout`.
+**Current npm:** `0.9.6` — **ops** helpers for macOS / Linux / Windows, LaunchAgent/systemd **PATH** for `~/.local/bin`, disconnect/disengage, multi-driver lanes, shared slots **1–4**, worktrees, optional `--ensure-checkout`.
 
 ## Prerequisites
 

package/dist/cli.js

@@ -18,6 +18,7 @@ import { ensureCheckout } from "./checkout.js";
 import { pumpExecutionSlots, renewLeases } from "./execution.js";
 import { installRunnerService, uninstallRunnerService } from "./service.js";
 import { OPS_VERBS, runOps } from "./ops.js";
+import { BRIDGE_PROTOCOL_VERSION, cachedBridgePreflight } from "./preflight.js";
 const [command] = process.argv.slice(2);
 /** Read our own package version so every runner start logs exactly which build is live. */
 function bridgeVersion() {
@@ -367,7 +368,7 @@ async function initOps() {
 async function opsCommand() {
     const verb = process.argv[3];
     if (!verb || !OPS_VERBS.includes(verb)) {
-        throw new Error(`Usage: ${bridgeUsage("ops", "<connect|install|online|offline|status|disconnect|uninstall>", "[driver…]")}`);
+        throw new Error(`Usage: ${bridgeUsage("ops", "<connect|install|online|offline|status|doctor|disconnect|uninstall>", "[driver…]")}`);
     }
     await runOps(verb, process.argv.slice(4));
 }
@@ -490,11 +491,17 @@ async function runner() {
             config.drivers = latest.drivers;
             config.fuelSource = latest.fuelSource;
             config.leaseCapacity = latest.leaseCapacity;
-            await heartbeat(client, config, workspace ? await buildWorkspaceBrief(workspace).catch(() => brief) : null, processOnlineIds);
+            const currentBrief = workspace ? await buildWorkspaceBrief(workspace).catch(() => brief) : null;
+            const preflight = workspace ? await cachedBridgePreflight({ config, workspace, processOnlineIds, brief: currentBrief ?? undefined }) : undefined;
+            await heartbeat(client, config, currentBrief, processOnlineIds, preflight);
             await renewLeases(client, config);
             if (workspace && (processDriver || onlineDriverIds(config).length)) {
                 progressed = await pumpExecutionSlots(client, config, workspace, brief, timeoutMs, {
-                    heartbeat: async () => heartbeat(client, config, await buildWorkspaceBrief(workspace).catch(() => brief), processOnlineIds),
+                    heartbeat: async () => {
+                        const currentBrief = await buildWorkspaceBrief(workspace).catch(() => brief);
+                        const preflight = await cachedBridgePreflight({ config, workspace, processOnlineIds, brief: currentBrief ?? undefined });
+                        await heartbeat(client, config, currentBrief, processOnlineIds, preflight);
+                    },
                     heartbeatIntervalMs: intervalMs,
                 }, running, { driver: processDriver, processOnlineIds });
             }
@@ -510,7 +517,7 @@ async function runner() {
         await new Promise((resolveSleep) => setTimeout(resolveSleep, intervalMs));
     }
 }
-async function heartbeat(client, config, brief, processOnlineIds) {
+async function heartbeat(client, config, brief, processOnlineIds, preflight) {
     // Process-level `--agent` override must count as online even when saved lanes are offline.
     const online = processOnlineIds?.length ? processOnlineIds : onlineDriverIds(config);
     const status = heartbeatStatusForDrivers(online);
@@ -519,7 +526,10 @@ async function heartbeat(client, config, brief, processOnlineIds) {
             capabilities: config.capabilities,
             lease_capacity: config.leaseCapacity,
             fuel_source: config.fuelSource === "local" ? "local" : "conduit",
+            bridge_version: bridgeVersion(),
+            bridge_protocol: BRIDGE_PROTOCOL_VERSION,
             drivers: driversHeartbeatReport(config, config.activeAttempts, processOnlineIds),
+            ...(preflight ? { preflight } : {}),
             ...(brief ? { workspace_brief: brief } : {}),
         }) });
 }

package/dist/driver.js

@@ -90,7 +90,9 @@ export function buildAssignmentPrompt(context) {
     const changeScope = packageContext?.change_scope?.length ? packageContext.change_scope : spec.change_scope;
     const evidence = packageContext?.required_evidence?.length ? packageContext.required_evidence : spec.required_evidence;
     const rework = packageContext?.rework_feedback ?? context.reworkFeedback;
-    const artifact = (packageContext?.deliverable ?? spec.deliverable) === "artifact";
+    const labeledArtifact = (packageContext?.deliverable ?? spec.deliverable) === "artifact";
+    // Research is discovery in the delivery report — never a published content-pack artifact.
+    const artifact = labeledArtifact && role !== "research";
     const lines = [
         `You are completing one delegated Conduit assignment as the ${role} role. Work only inside the current workspace.`,
         "",
@@ -451,10 +453,14 @@ export function cursorPermissionsForGrants(grants, verificationCommands = []) {
  * block. Real authority boundaries are the `.cursor/cli.json` shell allow-list and the delivery
  * contract (validateDeliveryReport rejects reported repository changes without repo_write, Invariant 9).
  */
+export function cursorSupportsWorkspaceTrust(helpOutput) {
+    return /(?:^|\s)--trust(?:\s|$)/m.test(helpOutput);
+}
 export function cursorRunArgs(input) {
-    // Do not pass --trust: current Cursor Agent CLI rejects it ("unknown option '--trust'").
     // Workspace authority is the operator-configured Bridge workspace; tool authority is .cursor/cli.json.
     const args = ["-p", "--output-format", "json", "--workspace", input.workspace];
+    if (input.trustWorkspace)
+        args.push("--trust");
     if (input.model)
         args.push("--model", input.model);
     if (input.resumeSessionId)
@@ -524,11 +530,15 @@ export const cursorDriver = {
         // `agent status` exits 0 either way, so the text is the signal.
         if (!process.env.CURSOR_API_KEY) {
             const status = await execute(executable, ["status"], input.workspace, 15_000, undefined, "local");
-            if (status.code !== 0 || /not logged in/i.test(status.stdout)) {
+            if (status.code !== 0 || !/logged in as/i.test(`${status.stdout}\n${status.stderr}`)) {
                 return { status: "failed", resultText: null, sessionId: null, error: "cursor has no login (set CURSOR_API_KEY or run `agent login`)" };
             }
         }
-        const configured = await withCursorPermissions(input.workspace, cursorPermissionsForGrants(input.grants, input.verificationCommands), () => execute(executable, cursorRunArgs(input), input.workspace, input.timeoutMs ?? 20 * 60_000, undefined, "local"));
+        // Cursor has alternated between accepting and rejecting --trust across releases. Detect the
+        // local contract instead of making either version fail every attempt worktree.
+        const help = await execute(executable, ["--help"], input.workspace, 15_000, undefined, "local");
+        const trustWorkspace = help.code === 0 && cursorSupportsWorkspaceTrust(`${help.stdout}\n${help.stderr}`);
+        const configured = await withCursorPermissions(input.workspace, cursorPermissionsForGrants(input.grants, input.verificationCommands), () => execute(executable, cursorRunArgs({ ...input, trustWorkspace }), input.workspace, input.timeoutMs ?? 20 * 60_000, undefined, "local"));
         const { code, stdout, stderr } = configured;
         const parsed = parseCursorOutput(stdout);
         if (code !== 0 || parsed.isError) {

package/dist/execution.js

@@ -21,6 +21,10 @@ function changesRequestedFeedback(summary) {
         return null;
     }
 }
+/** Failures that require an operator/configuration change must never burn the remaining attempts. */
+export function retryableAgentFailure(message) {
+    return !/unknown (?:option|argument)|unrecognized (?:option|argument)|not logged in|no login|not authenticated|login required|\bENOENT\b|could not verify the installed CLI|requires local fuel|No Bridge-mapped|preflight/i.test(message);
+}
 const assignmentSchema = z.object({
     id: z.string().uuid(),
     attempt_id: z.string().uuid(),
@@ -405,8 +409,9 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
         if (result.sessionId)
             config.sessions = { ...config.sessions, [taskId]: result.sessionId };
         if (result.status === "failed") {
-            await queueTerminal(client, taskId, { action: "fail", body: { error: result.error ?? "Agent execution failed", idempotency_key: `bridge:fail:${active.attemptId}` } });
-            console.error(`Assignment ${taskId} failed: ${redactSecrets(result.error ?? "unknown")}`);
+            const message = result.error ?? "Agent execution failed";
+            await queueTerminal(client, taskId, { action: "fail", body: { error: message, retryable: retryableAgentFailure(message), idempotency_key: `bridge:fail:${active.attemptId}` } });
+            console.error(`Assignment ${taskId} failed: ${redactSecrets(message)}`);
             return;
         }
         let report;
@@ -441,7 +446,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
             }
             catch (repairError) {
                 const message = repairError instanceof Error ? repairError.message : "Delivery report repair failed";
-                await queueTerminal(client, taskId, { action: "fail", body: { error: `Delivery report repair failed: ${message}`, retryable: true, idempotency_key: `bridge:delivery-repair-failed:${active.attemptId}` } });
+                await queueTerminal(client, taskId, { action: "fail", body: { error: `Delivery report repair failed: ${message}`, retryable: retryableAgentFailure(message), idempotency_key: `bridge:delivery-repair-failed:${active.attemptId}` } });
                 console.error(`Assignment ${taskId} report-only repair failed: ${redactSecrets(message)}`);
                 return;
             }
@@ -449,7 +454,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
                 config.sessions = { ...config.sessions, [taskId]: repaired.sessionId };
             if (repaired.status === "failed") {
                 const message = repaired.error ?? "Delivery report repair failed";
-                await queueTerminal(client, taskId, { action: "fail", body: { error: message, retryable: true, idempotency_key: `bridge:delivery-repair-failed:${active.attemptId}` } });
+                await queueTerminal(client, taskId, { action: "fail", body: { error: message, retryable: retryableAgentFailure(message), idempotency_key: `bridge:delivery-repair-failed:${active.attemptId}` } });
                 console.error(`Assignment ${taskId} report-only repair failed: ${redactSecrets(message)}`);
                 return;
             }
@@ -459,7 +464,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
             }
             catch (repairError) {
                 const message = repairError instanceof Error ? repairError.message : "Repaired delivery report was invalid";
-                await queueTerminal(client, taskId, { action: "fail", body: { error: `Delivery report repair exhausted: ${message}`, retryable: true, idempotency_key: `bridge:delivery-repair-invalid:${active.attemptId}` } });
+                await queueTerminal(client, taskId, { action: "fail", body: { error: `Delivery report repair exhausted: ${message}`, retryable: false, idempotency_key: `bridge:delivery-repair-invalid:${active.attemptId}` } });
                 console.error(`Assignment ${taskId} exhausted its report-only repair: ${redactSecrets(message)}`);
                 const replyTail = (repaired.resultText ?? "").slice(-8_000);
                 console.error(`Assignment ${taskId} repaired reply tail (${(repaired.resultText ?? "").length} chars total, redacted): ${redactSecrets(replyTail) || "<empty>"}`);
@@ -482,10 +487,9 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "Agent delivery report was invalid";
-            // Missing PR tooling / credential is retryable once the environment is fixed; other contract
-            // failures (scope, evidence mapping) stay non-retryable.
-            const retryable = /pull_request|merge_request|forge|GitHub|GitLab|gh |push|credential/i.test(message);
-            await queueTerminal(client, taskId, { action: "fail", body: { error: message, retryable, idempotency_key: `bridge:invalid-delivery:${active.attemptId}` } });
+            // Contract/tooling/credential failures need a human fix. Automatic retry would repeat the same
+            // state immediately and spend another attempt before the operator can change anything.
+            await queueTerminal(client, taskId, { action: "fail", body: { error: message, retryable: false, idempotency_key: `bridge:invalid-delivery:${active.attemptId}` } });
             console.error(`Assignment ${taskId} could not produce a valid Delivery: ${redactSecrets(message)}`);
             const replyTail = reportText.slice(-8_000);
             console.error(`Assignment ${taskId} agent reply tail (${reportText.length} chars total, redacted): ${redactSecrets(replyTail) || "<empty>"}`);
@@ -671,7 +675,10 @@ async function prepareDelivery(client, attemptId, taskId, report) {
 }
 export function validateDeliveryReport(report, spec, grants = []) {
     validateChangeScope(report, spec.change_scope ?? []);
-    if (spec.deliverable === "artifact") {
+    // Research findings live in the report. Do not demand a published pack URL for work_role=research
+    // even when a planner mis-labeled the package as deliverable=artifact.
+    const artifactDelivery = spec.deliverable === "artifact" && spec.work_role !== "research";
+    if (artifactDelivery) {
         const published = report.evidence.some((item) => {
             if (!["preview", "research", "documentation"].includes(item.kind))
                 return false;

package/dist/ops.js

@@ -6,8 +6,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join, resolve } from "node:path";
+import { loadConfig } from "./config.js";
+import { describePreflightIssue, runBridgePreflight } from "./preflight.js";
 export const OPS_VERBS = [
-    "connect", "install", "online", "offline", "status", "disconnect", "uninstall",
+    "connect", "install", "online", "offline", "status", "doctor", "disconnect", "uninstall",
 ];
 const LOCAL_FUEL_DRIVERS = new Set(["cursor", "kiro", "antigravity"]);
 export function defaultOpsEnvPath(home = homedir()) {
@@ -147,6 +149,25 @@ export async function runOps(verb, argv = [], deps = {}) {
         runBridge(["drivers"]);
         return;
     }
+    if (verb === "doctor") {
+        requireOpsEnv(env);
+        if (!env.CONDUIT_WORKSPACE)
+            throw new Error(`Set CONDUIT_WORKSPACE in ${defaultOpsEnvPath()}`);
+        const config = await (deps.loadBridgeConfig ?? loadConfig)();
+        const report = await (deps.preflight ?? runBridgePreflight)({
+            config,
+            workspace: resolve(expandOpsValue(env.CONDUIT_WORKSPACE)),
+            expectedRepository: env.CONDUIT_REPO || undefined,
+        });
+        console.log(`Bridge preflight: ${report.ready ? "READY" : "BLOCKED"}`);
+        if (report.ready) {
+            console.log("Workspace, online lanes, local fuel, CLI availability, and authentication are ready.");
+            return;
+        }
+        for (const issue of report.issues)
+            console.log(`- ${describePreflightIssue(issue)}`);
+        throw new Error("Fix the preflight issues before retrying Conduit work");
+    }
     // Lane toggles only need Bridge config + optional driver ids — not a full ops.env.
     if (verb === "online" || verb === "offline") {
         const drivers = resolveDrivers(env, argv);
@@ -177,6 +198,8 @@ export async function runOps(verb, argv = [], deps = {}) {
                 runBridge(["drivers", "fuel", id, "local"]);
         }
         runBridge(["drivers", "online", ...drivers]);
+        // Prove the exact local environment before installing a service that advertises availability.
+        runBridge(["ops", "doctor"]);
         if (host === "win32") {
             const runnerArgs = ["runner", "--workspace", workspace];
             if (env.CONDUIT_REPO)

package/dist/preflight.js

@@ -0,0 +1,116 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { buildWorkspaceBrief, normalizeRepositoryUrl } from "./brief.js";
+import { hasAntigravityLogin, hasClaudeLogin, hasOpenAiLogin, hasOpenCodeLogin, resolveCodexExecutable, } from "./driver.js";
+import { localFuelOnlyDriver, onlineDriverIds, resolveDriverFuel } from "./drivers.js";
+export const BRIDGE_PROTOCOL_VERSION = 1;
+const execFileAsync = promisify(execFile);
+async function defaultCommandRunner(command, args, cwd) {
+    try {
+        const result = await execFileAsync(command, args, { cwd, timeout: 15_000, windowsHide: true });
+        return { code: 0, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+    }
+    catch (error) {
+        const failure = error;
+        const code = typeof failure.code === "number" ? failure.code : 1;
+        return { code, stdout: typeof failure.stdout === "string" ? failure.stdout : "", stderr: typeof failure.stderr === "string" ? failure.stderr : "" };
+    }
+}
+const DRIVER_COMMAND = {
+    "claude-code": "claude",
+    codex: "codex",
+    cursor: "agent",
+    opencode: "opencode",
+    kiro: "kiro-cli",
+    antigravity: "agy",
+};
+function executableFor(driver) {
+    return driver === "codex" ? resolveCodexExecutable() : DRIVER_COMMAND[driver] ?? driver;
+}
+async function localAuthenticationReady(driver, workspace, run) {
+    if (driver === "claude-code")
+        return hasClaudeLogin();
+    if (driver === "codex")
+        return hasOpenAiLogin();
+    if (driver === "opencode")
+        return hasOpenCodeLogin();
+    if (driver === "antigravity")
+        return hasAntigravityLogin();
+    if (driver === "cursor") {
+        if (process.env.CURSOR_API_KEY)
+            return true;
+        const status = await run(executableFor(driver), ["status"], workspace);
+        return status.code === 0 && /logged in as/i.test(`${status.stdout}\n${status.stderr}`);
+    }
+    if (driver === "kiro") {
+        if (process.env.KIRO_API_KEY)
+            return true;
+        const status = await run(executableFor(driver), ["whoami"], workspace);
+        return status.code === 0 && !/not logged in|not authenticated|login required/i.test(`${status.stdout}\n${status.stderr}`);
+    }
+    return false;
+}
+export async function runBridgePreflight(input, deps = {}) {
+    const issues = [];
+    const online = input.processOnlineIds?.length ? input.processOnlineIds : onlineDriverIds(input.config);
+    const run = deps.runCommand ?? defaultCommandRunner;
+    const makeBrief = deps.buildBrief ?? buildWorkspaceBrief;
+    let brief = input.brief;
+    if (!online.length)
+        issues.push({ code: "no_online_driver" });
+    try {
+        brief ??= await makeBrief(input.workspace);
+    }
+    catch {
+        issues.push({ code: "workspace_unavailable" });
+    }
+    if (brief && !brief.repository)
+        issues.push({ code: "workspace_repository_missing" });
+    if (brief?.repository && input.expectedRepository
+        && normalizeRepositoryUrl(brief.repository) !== normalizeRepositoryUrl(input.expectedRepository)) {
+        issues.push({ code: "workspace_repository_mismatch" });
+    }
+    const driverIssues = await Promise.all(online.map(async (driver) => {
+        const fuel = resolveDriverFuel(input.config, driver);
+        if (localFuelOnlyDriver(driver) && fuel !== "local") {
+            return { code: "driver_fuel_mismatch", driver };
+        }
+        const version = await run(executableFor(driver), ["--version"], input.workspace);
+        if (version.code !== 0 || !`${version.stdout}${version.stderr}`.trim()) {
+            return { code: "driver_missing", driver };
+        }
+        if (fuel === "local" && !await localAuthenticationReady(driver, input.workspace, run)) {
+            return { code: "driver_not_authenticated", driver };
+        }
+        return null;
+    }));
+    issues.push(...driverIssues.filter((issue) => issue !== null));
+    return { ready: issues.length === 0, checked_at: new Date().toISOString(), issues };
+}
+let cached = null;
+/** Keep auth probes off the 15-second heartbeat hot path while still expiring readiness promptly. */
+export async function cachedBridgePreflight(input) {
+    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)
+        return cached.report;
+    const report = await runBridgePreflight(input);
+    cached = { key, at: Date.now(), report };
+    return report;
+}
+export function describePreflightIssue(issue) {
+    const lane = issue.driver ? ` (${issue.driver})` : "";
+    if (issue.code === "no_online_driver")
+        return "No agent lane is online";
+    if (issue.code === "workspace_unavailable")
+        return "Workspace cannot be read";
+    if (issue.code === "workspace_repository_missing")
+        return "Workspace has no origin repository";
+    if (issue.code === "workspace_repository_mismatch")
+        return "Workspace origin does not match CONDUIT_REPO";
+    if (issue.code === "driver_missing")
+        return `Agent CLI is missing from PATH${lane}`;
+    if (issue.code === "driver_not_authenticated")
+        return `Agent CLI is not logged in${lane}`;
+    return `Agent lane requires local fuel${lane}`;
+}

package/ops/conduit-ops

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
-# Usage: ./conduit-ops <connect|install|online|offline|status|disconnect|uninstall> [args…]
+# Usage: ./conduit-ops <connect|install|online|offline|status|doctor|disconnect|uninstall> [args…]
 set -euo pipefail
 if [[ $# -lt 1 ]]; then
-  echo "Usage: $0 <connect|install|online|offline|status|disconnect|uninstall> [args…]" >&2
+  echo "Usage: $0 <connect|install|online|offline|status|doctor|disconnect|uninstall> [args…]" >&2
   exit 1
 fi
 verb=$1

package/ops/conduit-ops.cmd

@@ -1,7 +1,7 @@
 @echo off
-REM Usage: conduit-ops.cmd <connect|install|online|offline|status|disconnect|uninstall> [args…]
+REM Usage: conduit-ops.cmd <connect|install|online|offline|status|doctor|disconnect|uninstall> [args…]
 if "%~1"=="" (
-  echo Usage: %~nx0 ^<connect^|install^|online^|offline^|status^|disconnect^|uninstall^> [args…]
+  echo Usage: %~nx0 ^<connect^|install^|online^|offline^|status^|doctor^|disconnect^|uninstall^> [args…]
   exit /b 1
 )
 npx --yes @miraland-labs/conduit-bridge@latest ops %*

package/ops/doctor.cmd

@@ -0,0 +1,3 @@
+@echo off
+npx --yes @miraland-labs/conduit-bridge@latest ops doctor %*
+if errorlevel 1 exit /b %errorlevel%

package/ops/doctor.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec npx --yes @miraland-labs/conduit-bridge@latest ops doctor "$@"

package/package.json

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