@miraland-labs/conduit-bridge 0.16.121 → 0.16.127

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.
 
-**Package version:** `0.16.95` — Conduit-fuel lanes bind organization aliases (T144), the Anthropic base URL is the origin (T148), the investigation lane resolves its model (T154); a hosted container image lives under `hosted/` (docs/HOSTED_RUNNER.md). Earlier (0.16.27) — work-package execution budgets reach every agent turn, are bounded by the machine ceiling, and expose their effective source for operations. Local-fuel provider refusals make the affected lane unavailable instead of repeatedly spending attempts; an operator who changes the lane's account or plan can invalidate that observation with `ops quota-clear <driver>`. Bridge discovers bounded repository verification commands, including Make targets `test`, `check`, `verify`, `replay`, `typecheck`, `lint`, and `build`. `ops disconnect` asks before it removes the runner service and clears credentials; pass `--yes` to skip the question. `ops.env` is enrollment/bootstrap defaults only: an explicit workspace does not inherit an old repository, and project switches do not rewrite global project state. `ops enroll` exchanges a single-use token, registers the machine, binds project affinity, provisions fuel keys, brings detected drivers online, and starts the runner in one command. On Linux, `ops install` refuses any effective systemd drop-in. A switch intent remains queued until the target runner heartbeat proves Bound. After every Bridge publish, operators must re-run `ops install` (LaunchAgent pins an absolute `cli.js`).
+**Package version:** `0.16.125` — the workspace brief reports `declared_demonstration` so the planner knows whether the repository can show itself (KERNEL.md §51). Earlier (0.16.124) — when a project declares `.conduit/demonstrate`, Bridge runs that bounded command at the delivered head and attaches a stamped `preview` row (KERNEL.md §47). Earlier (0.16.95) — Conduit-fuel lanes bind organization aliases (T144), the Anthropic base URL is the origin (T148), the investigation lane resolves its model (T154); a hosted container image lives under `hosted/` (docs/HOSTED_RUNNER.md). Earlier (0.16.27) — work-package execution budgets reach every agent turn, are bounded by the machine ceiling, and expose their effective source for operations. Local-fuel provider refusals make the affected lane unavailable instead of repeatedly spending attempts; an operator who changes the lane's account or plan can invalidate that observation with `ops quota-clear <driver>`. Bridge discovers bounded repository verification commands, including Make targets `test`, `check`, `verify`, `replay`, `typecheck`, `lint`, and `build`. `ops disconnect` asks before it removes the runner service and clears credentials; pass `--yes` to skip the question. `ops.env` is enrollment/bootstrap defaults only: an explicit workspace does not inherit an old repository, and project switches do not rewrite global project state. `ops enroll` exchanges a single-use token, registers the machine, binds project affinity, provisions fuel keys, brings detected drivers online, and starts the runner in one command. On Linux, `ops install` refuses any effective systemd drop-in. A switch intent remains queued until the target runner heartbeat proves Bound. After every Bridge publish, operators must re-run `ops install` (LaunchAgent pins an absolute `cli.js`).
 
 ## Prerequisites
 

package/dist/brief.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { isBoundedVerificationCommand } from "./execution-class.js";
+import { readDeclaredDemonstration } from "./ensure-demonstration-evidence.js";
 import { gitOriginUrl, headCommitOrNull } from "./git.js";
 const execFileAsync = promisify(execFile);
 const MANIFESTS = [
@@ -39,6 +40,7 @@ export async function buildWorkspaceBrief(workspace) {
         manifests,
         verification: await discoverVerificationCommands(workspace, files),
         declared_verification: declared,
+        declared_demonstration: await readDeclaredDemonstration(workspace),
     };
 }
 /**

package/dist/ensure-demonstration-evidence.js

@@ -0,0 +1,98 @@
+/**
+ * When the project declares how it shows itself, Bridge runs that command at the delivered head and
+ * attaches what it printed. The agent never authors this entry (KERNEL.md §47, "See it").
+ *
+ * `.conduit/demonstrate` is one bounded command, `#` comments allowed, absent by default. It runs
+ * with the same shape check, runner and bound as a verification command, and it is never a gate:
+ * a demonstration that fails, times out or prints nothing attaches as `unverifiable` with its
+ * reason, and cannot fail a criterion.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runBoundedVerificationCommand } from "./ensure-test-evidence.js";
+import { isRunnableVerificationCommand } from "./execution-class.js";
+/** Fixed name the control plane reads to place the row on the decision card. */
+export const DEMONSTRATION_ARTIFACT_NAME = "What it does (Bridge witness)";
+export const DEMONSTRATION_DECLARATION_PATH = ".conduit/demonstrate";
+/** The transcript is text the owner reads, not a log: the head, cut with a marker. */
+export const DEMONSTRATION_MAX_CHARS = 4_000;
+export function parseDeclaredDemonstration(text) {
+    for (const raw of text.split("\n")) {
+        const line = raw.split("#")[0].trim();
+        if (!line)
+            continue;
+        return isRunnableVerificationCommand(line) ? line : null;
+    }
+    return null;
+}
+export async function readDeclaredDemonstration(workspace) {
+    try {
+        return parseDeclaredDemonstration(await readFile(join(workspace, DEMONSTRATION_DECLARATION_PATH), "utf8"));
+    }
+    catch {
+        return null; // absent declaration, absent row
+    }
+}
+function boundedTranscript(text) {
+    const trimmed = text.trim();
+    const cut = trimmed.length > DEMONSTRATION_MAX_CHARS;
+    const kept = cut ? trimmed.slice(0, DEMONSTRATION_MAX_CHARS) : trimmed;
+    return [...kept.split("\n"), ...(cut ? [`… cut at ${DEMONSTRATION_MAX_CHARS.toLocaleString("en-US")} characters …`] : [])];
+}
+export async function ensureDemonstrationEvidence(input) {
+    const command = await readDeclaredDemonstration(input.workspace);
+    if (!command)
+        return input.report;
+    const run = input.runCommand ?? runBoundedVerificationCommand;
+    const withoutPrior = input.report.evidence.filter((item) => item.name !== DEMONSTRATION_ARTIFACT_NAME);
+    const attach = (details, witness, uri) => ({
+        ...input.report,
+        evidence: [...withoutPrior, {
+                kind: "preview",
+                name: DEMONSTRATION_ARTIFACT_NAME,
+                ...(uri ? { uri } : {}),
+                details: [`$ ${command}`, ...details],
+                acceptance_criteria: [],
+                witness,
+            }],
+    });
+    // A demonstration is repository code. Running it must consume the same explicit authority as a
+    // verification command; merely finding the declaration cannot grant shell execution to an
+    // observe-only package.
+    if (!input.grants.includes("test_run")) {
+        return attach(["Not run: this package does not hold test_run authority."], "unverifiable");
+    }
+    // The delivered code may demonstrate itself, but it may not author the command that earns the
+    // Bridge stamp in the same delivery. The declaration becomes a trusted project property only
+    // after an earlier delivery landed it. A missing path witness fails closed for the same reason.
+    if (input.changedPaths === null || input.changedPaths.includes(DEMONSTRATION_DECLARATION_PATH)) {
+        return attach([
+            `Not run: this delivery changed ${DEMONSTRATION_DECLARATION_PATH}; a delivery cannot author its own Bridge-witnessed demonstration.`,
+        ], "unverifiable");
+    }
+    let result;
+    try {
+        result = await run(command, input.workspace);
+    }
+    catch (error) {
+        return attach([`Could not run: ${error instanceof Error ? error.message : String(error)}`], "unverifiable");
+    }
+    if (result.code !== 0) {
+        return attach([...boundedTranscript(result.stderr || result.stdout), `exit ${result.code}`], "unverifiable");
+    }
+    if (!result.stdout.trim())
+        return attach(["The demonstration printed nothing."], "unverifiable");
+    const transcript = boundedTranscript(result.stdout);
+    // A line that is an https:// URL is the project publishing where to look; it becomes the preview reference.
+    const link = transcript.map((line) => line.trim()).find((line) => {
+        if (!line.startsWith("https://"))
+            return false;
+        try {
+            return new URL(line).protocol === "https:";
+        }
+        catch {
+            return false;
+        }
+    });
+    return attach(transcript, "bridge", link);
+}

package/dist/ensure-land-commit.js

@@ -51,7 +51,7 @@ export async function ensureLandCommit(input) {
     if (!requiresLandCommit({ grants: input.grants, spec: input.spec })) {
         return { kind: "skipped" };
     }
-    const base = input.spec.repository?.base_commit;
+    const base = input.baseCommit ?? input.spec.repository?.base_commit;
     if (!base)
         return { kind: "skipped" };
     const countAhead = input.countCommitsAhead ?? commitsAheadOfBase;

package/dist/ensure-pull-request.js

@@ -263,7 +263,7 @@ export async function ensureDeliveryPullRequest(input) {
     // files. GitHub then answers the pull-request call with an opaque 422 "No commits between main
     // and <branch>" (initiative efa56ccd, attempt 874fa0e3). Prove the branch carries work first, and
     // report the real condition instead of a forge validation error.
-    const base = input.spec.repository?.base_commit;
+    const base = input.baseCommit ?? input.spec.repository?.base_commit;
     if (base) {
         const ahead = await countAhead(input.workspace, base);
         if (ahead === 0) {

package/dist/execution.js

@@ -27,6 +27,7 @@ import { agentClaimsRepositoryWork, claimsVsGitMismatch, isLandTreeEmpty, report
 const execFileAsync = promisify(execFile);
 import { boundedTail, captureVerificationFailure, detectGateRanNothing, ensureTestEvidence, needsTestEvidence, runBoundedVerificationCommand, verificationEvidenceCommands, VerificationGateRanNothingError } from "./ensure-test-evidence.js";
 import { ensureChangeEvidence } from "./ensure-change-evidence.js";
+import { ensureDemonstrationEvidence } from "./ensure-demonstration-evidence.js";
 import { ensureNormativeEvidence } from "./ensure-normative-evidence.js";
 import { changedPathsSince, compareWorktreeState, diffStatSince, worktreeStateFingerprint, worktreeWrittenPaths } from "./git-witness.js";
 import { assertNormativeRefsMaterialized, checkNormativeMarkers, materializeNormativeRefs, NORMATIVE_MARKER_PREFIX, NORMATIVE_REF_PREFIX, parseNormativeRefs, } from "./normative-refs.js";
@@ -1803,7 +1804,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
         watchdog.phase("land");
         if (requiresLandCommit({ grants, spec })) {
             try {
-                const land = await ensureLandCommit({ workspace: attemptWorkspace, spec, grants });
+                const land = await ensureLandCommit({ workspace: attemptWorkspace, spec, grants, baseCommit: deliveryBaseCommit });
                 if (land.kind === "committed") {
                     await client.attemptRequest(taskId, "progress", {
                         phase: "preparing_delivery",
@@ -1825,6 +1826,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
             spec,
             grants,
             agentReply: reportText,
+            baseCommit: deliveryBaseCommit,
         })) {
             const continuation = await runLandContinuationTurn({
                 config,
@@ -1859,7 +1861,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
             report = parseAgentReport(reportText, spec.acceptance ?? []);
         }
         catch (error) {
-            const gitEmpty = await isLandTreeEmpty({ workspace: attemptWorkspace, spec, grants });
+            const gitEmpty = await isLandTreeEmpty({ workspace: attemptWorkspace, spec, grants, baseCommit: deliveryBaseCommit });
             const claimsWork = agentClaimsRepositoryWork(reportText);
             if (requiresLandCommit({ grants, spec }) && gitEmpty && claimsWork) {
                 if (!landContinuationUsed) {
@@ -2059,7 +2061,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
         if (!landContinuationUsed
             && requiresLandCommit({ grants, spec })
             && reportClaimsRepositoryWork(report)
-            && await isLandTreeEmpty({ workspace: attemptWorkspace, spec, grants })) {
+            && await isLandTreeEmpty({ workspace: attemptWorkspace, spec, grants, baseCommit: deliveryBaseCommit })) {
             const continuation = await runLandContinuationTurn({
                 config,
                 client,
@@ -2129,6 +2131,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                 maxDurationMs: workPackage?.max_duration_ms,
                 resumeSessionId: agentSessionId,
                 landContinuationUsed,
+                landBaseCommit: deliveryBaseCommit,
             });
             // Mechanical land path: the agent only pushes; Bridge pushes again if needed and the control
             // plane opens the change request with the organization's forge connection.
@@ -2140,6 +2143,7 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                 report,
                 spec,
                 grants,
+                baseCommit: deliveryBaseCommit,
                 title: task.objective,
                 repositoryFingerprint: executionContract.repository_fingerprint,
                 priorPullRequestUrl: executionContract.prior_pull_request_url,
@@ -2166,6 +2170,16 @@ async function runAttempt(client, config, driver, workspace, brief, taskId, watc
                 grants,
                 changedPaths: actualPaths,
             });
+            // §47 "See it": the project's own demonstration at the delivered head, never a gate.
+            const beforeDemonstration = report;
+            report = await ensureDemonstrationEvidence({
+                workspace: attemptWorkspace,
+                report,
+                grants,
+                changedPaths: actualPaths,
+            });
+            if (report !== beforeDemonstration)
+                await discardWorktreeWrites(attemptWorkspace);
             const integrationCheck = await checkIntegrationObligations(attemptWorkspace, parseIntegrationObligations(spec.integration_obligations));
             if (!integrationCheck.ok) {
                 throw new Error(`${INTEGRATION_OBLIGATION_PREFIX}: ${integrationCheck.failures.join("; ")}`);
@@ -2371,6 +2385,7 @@ async function finalizeRepositoryLand(input) {
             workspace: input.workspace,
             spec: input.spec,
             grants: input.grants,
+            baseCommit: input.landBaseCommit,
         });
         if (land.kind === "committed") {
             await input.client.attemptRequest(input.taskId, "progress", {
@@ -2392,7 +2407,7 @@ async function finalizeRepositoryLand(input) {
             throw error;
     }
     if (input.landContinuationUsed) {
-        throw new AgentNoLandCommitError(input.spec.repository?.base_commit ?? "unknown");
+        throw new AgentNoLandCommitError(input.landBaseCommit ?? input.spec.repository?.base_commit ?? "unknown");
     }
     const continuation = await runLandContinuationTurn({
         config: input.config,
@@ -2664,7 +2679,7 @@ async function prepareDelivery(client, attemptId, taskId, report) {
             metadata: {
                 details: item.details,
                 acceptance_criteria: item.acceptance_criteria,
-                ...(item.witness === "bridge" ? { witness: "bridge" } : {}),
+                ...(item.witness ? { witness: item.witness } : {}),
             },
             idempotency_key: `bridge:artifact:${attemptId}:${index + 1}`,
         });

package/dist/failure-signal.js

@@ -117,7 +117,7 @@ export const BRIDGE_CAUSES = {
     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: "conduit", message: "This checkout has no verification commands Conduit can run for this package.", next_action: "Conductor will adjust how this package is verified. You do not need to author test commands or rewrite the plan for tooling." },
+    missing_verification: { class: "environment", disposition: "hold", responsible_party: "conduit", message: "This checkout has no verification commands Conduit can run for this package.", next_action: "Open the initiative and request a revision: Conduit re-plans this package without test evidence this checkout cannot produce. You never author test commands yourself." },
     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." },

package/dist/investigation.js

@@ -790,18 +790,25 @@ export async function executeNextInvestigation(client, config, workspace, brief,
             : undefined;
         // T126: the prompt names the commands of the repository this lane opened — not the control
         // plane's idea of them — and carries the diff stat Bridge computed, since the lane cannot run git.
+        // Discover those commands from the delivered worktree, not the source checkout: a greenfield
+        // delivery can introduce its manifest and test gate in the commit this investigation verifies.
         const deliveryVerification = isDeliveryVerification(assignment);
+        const investigationBrief = deliveryVerification
+            ? await buildWorkspaceBrief(attemptWorkspace)
+            : liveBrief;
+        const verificationCommands = investigationBrief?.verification ?? [];
+        const declaredVerificationCommands = investigationBrief?.declared_verification ?? [];
         const gatesRun = deliveryVerification
             ? await runDeliveryVerificationGates({
                 workspace: attemptWorkspace,
-                verificationCommands: liveBrief?.verification ?? [],
-                declaredVerificationCommands: liveBrief?.declared_verification ?? [],
+                verificationCommands,
+                declaredVerificationCommands,
                 acceptance: assignment.acceptance ?? [],
                 runCommand: options.runVerificationCommand,
             })
             : [];
         const context = {
-            verificationCommands: liveBrief?.verification ?? [],
+            verificationCommands,
             diffStat: assignment.base_commit ? await diffStatSince(attemptWorkspace, assignment.base_commit) : null,
             gatesRun,
         };
@@ -815,7 +822,7 @@ export async function executeNextInvestigation(client, config, workspace, brief,
             workspace: attemptWorkspace,
             ...(selection.model ? { model: selection.model } : {}),
             grants: assignment.grants,
-            verificationCommands: liveBrief?.verification ?? [],
+            verificationCommands,
             deliverable: "repository",
             // The same signal the read-only diagnosis lane uses; it is what denies edits in the driver.
             workRole: "diagnose",

package/dist/land-git-reality.js

@@ -33,7 +33,7 @@ async function listUncommittedPaths(workspace) {
 export async function isLandTreeEmpty(input) {
     if (!requiresLandCommit({ grants: input.grants, spec: input.spec }))
         return false;
-    const base = input.spec.repository?.base_commit;
+    const base = input.baseCommit ?? input.spec.repository?.base_commit;
     if (!base)
         return false;
     const countAhead = input.countCommitsAhead ?? commitsAheadOfBase;

package/package.json

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