@miraland-labs/conduit-bridge 0.9.7 → 0.9.9

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.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`.
+**Package version:** `0.9.9` — heartbeat protocol 2 requires a clean workspace plus a ready, versioned driver lane before dispatch. Attempt worktrees fetch/start from the initiative base when the source tip is behind or history was rewritten, without resetting the source checkout. Also includes **ops** helpers for macOS / Linux / Windows, LaunchAgent/systemd **PATH** for `~/.local/bin`, disconnect/disengage, multi-driver lanes, shared slots **1–4**, worktrees, and optional `--ensure-checkout`. Protocol 1 heartbeats remain compatible for presence but cannot receive work.
 
 ## Prerequisites
 
@@ -63,6 +63,18 @@ npx @miraland-labs/conduit-bridge disconnect --yes
 
 **Capacity:** Connect-approved `lease_capacity` (1–4) is a **shared pool** for all online lanes on that computer.
 
+## Readiness and lane status
+
+Before agent spend, Bridge checks that the workspace is readable, matches the expected repository,
+and is clean; each online driver must be installed, compatible with its configured fuel, and signed
+in when local fuel is used. The same bounded report is sent on heartbeat so Conduit can place an
+environment failure on Hold without consuming an execution attempt. Fix the named issue and let a
+fresh heartbeat land before choosing **Recheck** in Activity.
+
+Conduit labels an exact driver/CLI version **Certified** only after two consecutive real canaries:
+repository delivery with PR/evidence and a successful rework cycle. All other lanes are
+**Experimental**. A lane runs only when its computer operator explicitly brings it online.
+
 ## Grant enforcement
 
 | Driver | Fuel | Mechanism |

package/dist/brief.js

@@ -43,6 +43,26 @@ export async function isBaseCommitAncestor(workspace, baseCommit, headCommit) {
         throw error;
     }
 }
+async function fetchOrigin(workspace) {
+    await execFileAsync("git", ["-C", workspace, "fetch", "--no-tags", "origin"], {
+        timeout: 120_000,
+        windowsHide: true,
+    });
+}
+/** Null when commits do not share history (e.g. orphan / force-pushed replacement tip). */
+async function gitMergeBase(workspace, left, right) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", workspace, "merge-base", left, right], {
+            timeout: 10_000,
+            windowsHide: true,
+        });
+        const sha = stdout.trim().toLowerCase();
+        return /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** True when `sha` is a local commit object, optionally after fetching it from origin. */
 export async function ensureCommitAvailable(workspace, sha) {
     const present = async () => {
@@ -67,10 +87,7 @@ export async function ensureCommitAvailable(workspace, sha) {
     }
     catch {
         try {
-            await execFileAsync("git", ["-C", workspace, "fetch", "--no-tags", "origin"], {
-                timeout: 120_000,
-                windowsHide: true,
-            });
+            await fetchOrigin(workspace);
         }
         catch {
             return false;
@@ -78,6 +95,47 @@ export async function ensureCommitAvailable(workspace, sha) {
     }
     return present();
 }
+/**
+ * Choose the commit an attempt worktree starts from for a required initiative base.
+ *
+ * Never rewrites the source checkout HEAD. Fetches missing objects when needed, prefers the claimed
+ * head when it already contains the base (rework), advances to the base when the workspace is merely
+ * behind, and falls back to the contract base when history was rewritten (force-push) so the owner
+ * does not have to manually reset before Recheck.
+ */
+export async function resolveAttemptStartCommit(workspace, requestedBase, claimedHead) {
+    if (!requestedBase)
+        return claimedHead;
+    const base = requestedBase.toLowerCase();
+    const claimed = claimedHead.toLowerCase();
+    if (await isBaseCommitAncestor(workspace, base, claimed).catch(() => false))
+        return claimed;
+    if (!(await ensureCommitAvailable(workspace, base).catch(() => false)))
+        return null;
+    await ensureCommitAvailable(workspace, claimed).catch(() => false);
+    if (await isBaseCommitAncestor(workspace, base, claimed).catch(() => false))
+        return claimed;
+    if (await isBaseCommitAncestor(workspace, claimed, base).catch(() => false))
+        return base;
+    // Shallow tip fetches can hide ancestry; deepen once before treating history as rewritten.
+    try {
+        await fetchOrigin(workspace);
+    }
+    catch {
+        /* offline / no origin — continue with objects already present */
+    }
+    if (await isBaseCommitAncestor(workspace, base, claimed).catch(() => false))
+        return claimed;
+    if (await isBaseCommitAncestor(workspace, claimed, base).catch(() => false))
+        return base;
+    // Unrelated histories (orphan / force-pushed default branch): honor the contract base for a fresh
+    // attempt worktree. Related-but-diverged tips can carry rework commits — refuse rather than drop them.
+    if (!(await ensureCommitAvailable(workspace, base).catch(() => false)))
+        return null;
+    if (await gitMergeBase(workspace, base, claimed) === null)
+        return base;
+    return null;
+}
 async function gitRemoteUrl(workspace) {
     try {
         const { common } = await gitDirectories(workspace);

package/dist/driver.js

@@ -345,7 +345,7 @@ export function codexSandboxForGrants(grants) {
 }
 /**
  * Codex exec arguments. The sandbox is the enforcement boundary: network stays
- * off inside workspace-write unless the assignment actually holds pr_create.
+ * off inside workspace-write unless the canonical contract requires external_network.
  */
 export function codexExecArgs(input, sandbox) {
     // exec is non-interactive by design (no approval flag), and `exec resume`
@@ -355,7 +355,7 @@ export function codexExecArgs(input, sandbox) {
         : ["exec", "--json", "--sandbox", sandbox];
     if (input.model)
         args.push("-m", input.model);
-    if (sandbox === "workspace-write" && input.grants.includes("pr_create")) {
+    if (sandbox === "workspace-write" && input.capabilities?.includes("external_network")) {
         args.push("-c", "sandbox_workspace_write.network_access=true");
     }
     if (input.resumeSessionId)

package/dist/execution.js

@@ -5,7 +5,7 @@ import { redactSecrets } from "./config.js";
 import { DRIVERS, agentReportTemplate, buildAssignmentPrompt, evidenceKinds, fuelEndpoint, parseAgentReport, pickModelCandidate, tierForRisk } from "./driver.js";
 import { pickDriverForClaim, resolveDriverFuel } from "./drivers.js";
 import { attemptWorktreePath, createAttemptWorktree, proveResumeWorktree, quarantineAttemptWorktree, removeAttemptWorktree, } from "./attempt-worktree.js";
-import { buildWorkspaceBrief, ensureCommitAvailable, isBaseCommitAncestor, normalizeRepositoryUrl } from "./brief.js";
+import { buildWorkspaceBrief, ensureCommitAvailable, normalizeRepositoryUrl, resolveAttemptStartCommit } from "./brief.js";
 import { ensureDeliveryPullRequest } from "./ensure-pull-request.js";
 /** Feedback text for changes_requested summaries (plain string or `{ feedback }`). */
 function changesRequestedFeedback(summary) {
@@ -45,6 +45,7 @@ const taskDetailSchema = z.object({
 const taskSpecSchema = z.object({
     goal: z.string().optional(), scope: z.array(z.string()).optional(), boundaries: z.array(z.string()).optional(),
     acceptance: z.array(z.string()).optional(), required_evidence: z.array(z.enum(evidenceKinds)).optional(),
+    required_capabilities: z.array(z.string()).optional(),
     change_scope: z.array(z.string()).optional(), work_role: z.string().optional(),
     repository: z.object({ url: z.string().optional(), base_commit: z.string().optional() }).nullable().optional(),
     risk_level: z.string().optional(),
@@ -229,7 +230,7 @@ export async function claimNextAssignment(client, config, workspace, brief, driv
             rejection = "workspace_head_changed";
     }
     if (!rejection && assignment.requested_base_commit && assignment.claimed_head) {
-        const startHead = await resolveStartHead(workspace, assignment.requested_base_commit, assignment.claimed_head);
+        const startHead = await resolveAttemptStartCommit(workspace, assignment.requested_base_commit, assignment.claimed_head);
         if (!startHead)
             rejection = "base_not_ancestor";
     }
@@ -245,25 +246,6 @@ export async function claimNextAssignment(client, config, workspace, brief, driv
     await client.claim(assignment.id, assignment.attempt_id, driverId ? { driverId } : undefined);
     return assignment.id;
 }
-/**
- * When a sibling merge advances task.base_commit past the machine checkout, the required base is a
- * descendant of claimed_head — not an ancestor. Fetch it and start from the advanced base instead of looping.
- */
-async function resolveStartHead(workspace, requestedBase, claimedHead) {
-    if (await isBaseCommitAncestor(workspace, requestedBase, claimedHead).catch(() => false))
-        return claimedHead;
-    await ensureCommitAvailable(workspace, requestedBase).catch(() => false);
-    if (await isBaseCommitAncestor(workspace, requestedBase, claimedHead).catch(() => false))
-        return claimedHead;
-    // Workspace is behind the required base (dependent package after merge).
-    if (await isBaseCommitAncestor(workspace, claimedHead, requestedBase).catch(() => false))
-        return requestedBase;
-    if (await ensureCommitAvailable(workspace, requestedBase).catch(() => false)
-        && await isBaseCommitAncestor(workspace, claimedHead, requestedBase).catch(() => false)) {
-        return requestedBase;
-    }
-    return null;
-}
 export async function executeNextAssignment(client, config, driver, workspace, brief, timeoutMs, supervision) {
     if (Object.keys(config.activeAttempts).length)
         return recoverActiveAttempt(client, config, driver, workspace, brief, timeoutMs, supervision);
@@ -303,7 +285,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
     }
     let worktreeStart = startCommit;
     if (executionContract.requested_base_commit) {
-        const resolved = await resolveStartHead(workspace, executionContract.requested_base_commit, startCommit);
+        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}` } });
             return;
@@ -399,6 +381,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
             prompt,
             workspace: attemptWorkspace,
             grants,
+            capabilities: spec.required_capabilities ?? [],
             verificationCommands: liveBrief?.verification ?? [],
             resumeSessionId,
             timeoutMs,
@@ -436,6 +419,7 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
                     // Preserve only existing read authority. No write, test, branch, or push
                     // capability is available while the agent repairs the response envelope.
                     grants: grants.filter((grant) => grant === "repo_read"),
+                    capabilities: [],
                     verificationCommands: [],
                     resumeSessionId: result.sessionId ?? undefined,
                     timeoutMs,

package/dist/preflight.js

@@ -3,7 +3,7 @@ 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;
+export const BRIDGE_PROTOCOL_VERSION = 2;
 const execFileAsync = promisify(execFile);
 async function defaultCommandRunner(command, args, cwd) {
     try {
@@ -70,22 +70,30 @@ export async function runBridgePreflight(input, deps = {}) {
         && normalizeRepositoryUrl(brief.repository) !== normalizeRepositoryUrl(input.expectedRepository)) {
         issues.push({ code: "workspace_repository_mismatch" });
     }
-    const driverIssues = await Promise.all(online.map(async (driver) => {
+    let workspaceClean = false;
+    if (brief) {
+        const status = await run("git", ["status", "--porcelain", "--untracked-files=normal"], input.workspace);
+        workspaceClean = status.code === 0 && status.stdout.trim().length === 0;
+        if (!workspaceClean)
+            issues.push({ code: status.code === 0 ? "workspace_dirty" : "workspace_unavailable" });
+    }
+    const driverChecks = await Promise.all(online.map(async (driver) => {
         const fuel = resolveDriverFuel(input.config, driver);
         if (localFuelOnlyDriver(driver) && fuel !== "local") {
-            return { code: "driver_fuel_mismatch", driver };
+            return { issue: { code: "driver_fuel_mismatch", driver }, snapshot: { id: driver, version: null, ready: false } };
         }
         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 { code: "driver_missing", driver };
+            return { issue: { code: "driver_missing", driver }, snapshot: { id: driver, version: versionText, ready: false } };
         }
         if (fuel === "local" && !await localAuthenticationReady(driver, input.workspace, run)) {
-            return { code: "driver_not_authenticated", driver };
+            return { issue: { code: "driver_not_authenticated", driver }, snapshot: { id: driver, version: versionText, ready: false } };
         }
-        return null;
+        return { issue: null, snapshot: { id: driver, version: versionText, ready: true } };
     }));
-    issues.push(...driverIssues.filter((issue) => issue !== null));
-    return { ready: issues.length === 0, checked_at: new Date().toISOString(), issues };
+    issues.push(...driverChecks.map((check) => check.issue).filter((issue) => issue !== null));
+    return { ready: issues.length === 0, checked_at: new Date().toISOString(), workspace_clean: workspaceClean, drivers: driverChecks.map((check) => check.snapshot), issues };
 }
 let cached = null;
 /** Keep auth probes off the 15-second heartbeat hot path while still expiring readiness promptly. */
@@ -108,6 +116,8 @@ export function describePreflightIssue(issue) {
         return "Workspace has no origin repository";
     if (issue.code === "workspace_repository_mismatch")
         return "Workspace origin does not match CONDUIT_REPO";
+    if (issue.code === "workspace_dirty")
+        return "Workspace has uncommitted or untracked changes";
     if (issue.code === "driver_missing")
         return `Agent CLI is missing from PATH${lane}`;
     if (issue.code === "driver_not_authenticated")

package/package.json

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