@kontextmind/kxm 0.7.25 → 0.7.26

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.25",
+      "version": "0.7.26",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.25",
+  "version": "0.7.26",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.25",
+  "version": "0.7.26",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -33705,7 +33705,21 @@ ${driveLine}` : ""}`
     return 1;
   }
 }
-async function cmdVnextRunDrive(runtime, runId, simulated) {
+var DEFAULT_DRIVE_WAIT_MS = 6e4;
+var MAX_DRIVE_WAIT_MS = 6e5;
+function parseDriveWaitTimeoutMs(raw) {
+  if (raw === void 0) return DEFAULT_DRIVE_WAIT_MS;
+  const value = typeof raw === "number" ? raw : Number(typeof raw === "string" ? raw.trim() : raw);
+  if (!Number.isInteger(value) || value < 1 || value > MAX_DRIVE_WAIT_MS) return void 0;
+  return value;
+}
+function sleepMs(ms) {
+  return new Promise((resolve31) => setTimeout(resolve31, ms));
+}
+function driveWaitCompleted(drive) {
+  return drive?.verified === true && drive.receipt?.settlement?.kind === "terminal" && drive.receipt.settlement.status === "completed";
+}
+async function cmdVnextRunDrive(runtime, runId, simulated, options = {}) {
   try {
     const projectRoot = discoverVnextProjectRoot(runtime.cwd);
     if (!projectRoot) {
@@ -33717,8 +33731,19 @@ async function cmdVnextRunDrive(runtime, runId, simulated) {
       print(runtime.io, runtime.json, { ok: true, command: "runs drive", dryRun: true, runId, mode }, `drive plan: run ${runId} in ${mode} mode (no events written)`);
       return 0;
     }
+    const timeoutMs = options.wait === true ? parseDriveWaitTimeoutMs(options.timeoutMs) : DEFAULT_DRIVE_WAIT_MS;
+    if (options.wait === true && timeoutMs === void 0) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "runs drive", error: "run_drive_timeout_invalid" },
+        `run drive --wait --timeout-ms must be an integer between 1 and ${MAX_DRIVE_WAIT_MS}`
+      );
+      return 1;
+    }
     const supervisor = await (vnextDriveCliSeams.ensureSupervisor ?? ensureVnextSupervisor)({ env: runtime.env });
-    const result = await (vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest)(supervisor, "POST", `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`, { mode });
+    const request = vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest;
+    const result = await request(supervisor, "POST", `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`, { mode });
     const driveId = result.driveId;
     const poll = result.poll;
     const status = result.status;
@@ -33726,13 +33751,36 @@ async function cmdVnextRunDrive(runtime, runId, simulated) {
       print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "run_drive_io_failed" }, "run drive failed because a local operation did not complete");
       return 1;
     }
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "runs drive", runId, driveId, poll, mode, status },
-      `drive ${driveId}: accepted (poll ${poll})`
-    );
-    return 0;
+    if (options.wait !== true) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: true, command: "runs drive", runId, driveId, poll, mode, status },
+        `drive ${driveId}: accepted (poll ${poll})`
+      );
+      return 0;
+    }
+    const deadline = Date.now() + timeoutMs;
+    let interval = 25;
+    while (true) {
+      const stateResult = await request(supervisor, "GET", `/v1/runs/${encodeURIComponent(runId)}?projectRoot=${encodeURIComponent(projectRoot)}`);
+      const drive = stateResult.drive;
+      if (drive?.receipt) {
+        print(
+          runtime.io,
+          runtime.json,
+          { ok: driveWaitCompleted(drive), command: "runs drive", receipt: drive.receipt, verified: drive.verified === true },
+          JSON.stringify(drive.receipt, null, 2)
+        );
+        return driveWaitCompleted(drive) ? 0 : 1;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await sleepMs(Math.min(interval, remaining));
+      interval = Math.min(Math.floor(interval * 1.5), 250);
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "timeout" }, "drive wait timed out");
+    return 1;
   } catch (error) {
     if (error instanceof VnextConfigError) {
       print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "run_drive_failed", issues: error.issues }, `run drive failed: ${error.message}`);
@@ -33920,6 +33968,45 @@ async function cmdVnextRuntime(runtime, action) {
     return 1;
   }
 }
+async function cmdVnextRunReceipt(runtime, runId, options = {}) {
+  try {
+    const projectRoot = discoverVnextProjectRoot(runtime.cwd);
+    if (!projectRoot) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "project_required" }, "kxm runs receipt requires a vNext project (run kxm init first)");
+      return 1;
+    }
+    const supervisor = await (vnextDriveCliSeams.ensureSupervisor ?? ensureVnextSupervisor)({ env: runtime.env });
+    const result = await (vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest)(
+      supervisor,
+      "GET",
+      `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`
+    );
+    if (!Array.isArray(result.receipts)) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "run_receipt_io_failed" }, "run receipt failed because a local operation did not complete");
+      return 1;
+    }
+    const receipts = result.receipts;
+    if (receipts.length === 0) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "no_receipts" }, `run ${runId} has no drive receipts`);
+      return 1;
+    }
+    if (options.all === true) {
+      print(runtime.io, runtime.json, { ok: true, command: "runs receipt", receipts }, JSON.stringify(receipts, null, 2));
+      return 0;
+    }
+    const latest = receipts[0];
+    const settlement = latest && typeof latest === "object" && "settlement" in latest ? latest.settlement : latest;
+    print(runtime.io, runtime.json, { ok: true, command: "runs receipt", receipt: latest }, JSON.stringify(settlement, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof VnextConfigError) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "run_receipt_failed", issues: error.issues }, `run receipt failed: ${error.message}`);
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "run_receipt_io_failed" }, "run receipt failed because a local operation did not complete");
+    return 1;
+  }
+}
 
 // plugins/kxm/src/cli/tasks.ts
 async function cmdSuggest(runtime, promptParts) {
@@ -48695,8 +48782,14 @@ function createProgram(ctx, result) {
   addGlobalOptions(runCmd.command("status").description("Show the projected status of a run, including durable drive receipt state (open / receipt verified / unsettled / orphaned)")).argument("<runId>", "Run id").action(async function runStatusAction(runId) {
     result.code = await cmdVnextRunStatus(runtimeFrom(ctx, this), runId);
   });
-  addGlobalOptions(runCmd.command("drive").description("Drive a run with an explicit model-free simulation")).argument("<runId>", "Run id").option("--simulated", "Use the model-free simulation producer").action(async function runDriveAction(runId, options) {
-    result.code = await cmdVnextRunDrive(runtimeFrom(ctx, this), runId, options.simulated === true);
+  addGlobalOptions(runCmd.command("drive").description("Drive a run with an explicit model-free simulation")).argument("<runId>", "Run id").option("--simulated", "Use the model-free simulation producer").option("--wait", "Wait until a drive receipt is recorded; exits 0 only for a VERIFIED COMPLETED settlement").option("--timeout-ms <n>", "Wait timeout in milliseconds (default 60000, max 600000)").action(async function runDriveAction(runId, options) {
+    result.code = await cmdVnextRunDrive(runtimeFrom(ctx, this), runId, options.simulated === true, {
+      wait: options.wait === true,
+      ...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {}
+    });
+  });
+  addGlobalOptions(runCmd.command("receipt").description("Print the newest drive receipt for a run")).argument("<runId>", "Run id").option("--all", "Print the capped receipt list for the run").action(async function runReceiptAction(runId, options) {
+    result.code = await cmdVnextRunReceipt(runtimeFrom(ctx, this), runId, { all: options.all === true });
   });
   addGlobalOptions(runCmd.command("cancel").description("Durably request cancellation of a run")).argument("<runId>", "Run id").action(async function runCancelAction(runId) {
     result.code = await cmdVnextRunCancel(runtimeFrom(ctx, this), runId);

package/plugins/kxm/dist/mcp-server.js

@@ -17121,7 +17121,7 @@ async function deliverInboxNotification(messageId, delivered, notify) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.25";
+var VERSION = "0.7.26";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
 var meshClient;

package/plugins/kxm/dist/runtime.js

@@ -18764,9 +18764,15 @@ var VnextRunEventStore = class {
   }
   driveReceiptsForRun(runId, limit = 20) {
     const rows = this.database.prepare(`
-      SELECT receipt FROM drive_receipts WHERE run_id = ? ORDER BY closed_at DESC, drive_id DESC LIMIT ?
+      SELECT drive_id, receipt FROM drive_receipts WHERE run_id = ? ORDER BY closed_at DESC, drive_id DESC LIMIT ?
     `).all(runId, limit);
-    return rows.map((row) => parseDriveReceipt(row.receipt));
+    return rows.map((row) => {
+      try {
+        return parseDriveReceipt(row.receipt);
+      } catch {
+        return { driveId: row.drive_id, divergence: "receipt unreadable" };
+      }
+    });
   }
   insertCapability(row) {
     this.database.prepare(`
@@ -22103,6 +22109,9 @@ function clearVnextDriveSession(storePath, runId, token) {
   if (!current || current.token !== token) return;
   delete current.driveSession;
 }
+function vnextDriveSession(storePath, runId) {
+  return owners.get(storePath)?.admitted.get(runId)?.driveSession;
+}
 function vnextOpenDriveSessions(storePath) {
   const owner = owners.get(storePath);
   if (!owner) return [];
@@ -27388,6 +27397,20 @@ async function startVnextRuntimeSupervisorInner(paths, requestedPortOption, now)
             sendJson(response, 200, { ok: true, events });
             return;
           }
+          if (request.method === "GET" && sub === "drive") {
+            const run = context.eventStore.run(runId);
+            if (!run) throw runtimeError("run_unknown", runId, "run not found");
+            const activeSession = vnextDriveSession(context.eventStore.path, runId);
+            const session = activeSession ? {
+              driveId: activeSession.driveId,
+              mode: activeSession.mode,
+              openedAt: activeSession.openedAt,
+              deadlineAt: activeSession.deadlineAt ?? null
+            } : null;
+            const receipts = context.eventStore.driveReceiptsForRun(runId, 20);
+            sendJson(response, 200, { ok: true, session, receipts });
+            return;
+          }
           if (request.method === "POST" && sub === "cancel") {
             const body = await readJsonBody(request);
             const result = cancelVnextRun(context, runId, {
@@ -27421,6 +27444,43 @@ async function startVnextRuntimeSupervisorInner(paths, requestedPortOption, now)
             return;
           }
         }
+        const driveMatch = /^\/v1\/drives\/([A-Za-z0-9_-]+)$/.exec(url.pathname);
+        if (request.method === "GET" && driveMatch) {
+          const driveId = driveMatch[1];
+          const projectRoot = url.searchParams.get("projectRoot") ?? "";
+          if (!projectRoot) {
+            sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: "projectRoot query parameter is required" });
+            return;
+          }
+          const context = contextFor(projectRoot);
+          let receipt;
+          try {
+            receipt = context.eventStore.driveReceipt(driveId);
+          } catch {
+            sendJson(response, 200, { ok: true, receipt: null, verified: false, divergence: "receipt unreadable" });
+            return;
+          }
+          if (!receipt) {
+            sendJson(response, 404, { ok: false, error: "drive_receipt_missing", message: "receipt not found" });
+            return;
+          }
+          const runId = receipt.runId;
+          const stored = context.eventStore.run(runId);
+          if (!stored) {
+            sendJson(response, 200, { ok: true, receipt, verified: false, divergence: "run missing" });
+            return;
+          }
+          const state = foldStoredVnextRun(context, stored);
+          const events = context.eventStore.events(runId, 0, 1e6);
+          const checked = verifyVnextDriveReceipt(receipt, events, state.status, { runId, driveId });
+          sendJson(response, 200, {
+            ok: true,
+            receipt,
+            verified: checked.verified,
+            ...checked.divergence !== void 0 ? { divergence: checked.divergence } : {}
+          });
+          return;
+        }
         const projectRunsMatch = /^\/v1\/projects\/(prj_[A-Za-z0-9_-]+)\/runs$/.exec(url.pathname);
         if (request.method === "GET" && projectRunsMatch) {
           const projectRoot = url.searchParams.get("projectRoot") ?? "";

package/plugins/kxm/dist/vnext-runtime-supervisor.js

@@ -18324,9 +18324,15 @@ var VnextRunEventStore = class {
   }
   driveReceiptsForRun(runId, limit = 20) {
     const rows = this.database.prepare(`
-      SELECT receipt FROM drive_receipts WHERE run_id = ? ORDER BY closed_at DESC, drive_id DESC LIMIT ?
+      SELECT drive_id, receipt FROM drive_receipts WHERE run_id = ? ORDER BY closed_at DESC, drive_id DESC LIMIT ?
     `).all(runId, limit);
-    return rows.map((row) => parseDriveReceipt(row.receipt));
+    return rows.map((row) => {
+      try {
+        return parseDriveReceipt(row.receipt);
+      } catch {
+        return { driveId: row.drive_id, divergence: "receipt unreadable" };
+      }
+    });
   }
   insertCapability(row) {
     this.database.prepare(`
@@ -21668,6 +21674,9 @@ function clearVnextDriveSession(storePath, runId, token) {
   if (!current || current.token !== token) return;
   delete current.driveSession;
 }
+function vnextDriveSession(storePath, runId) {
+  return owners.get(storePath)?.admitted.get(runId)?.driveSession;
+}
 function vnextOpenDriveSessions(storePath) {
   const owner = owners.get(storePath);
   if (!owner) return [];
@@ -26902,6 +26911,20 @@ async function startVnextRuntimeSupervisorInner(paths, requestedPortOption, now)
             sendJson(response, 200, { ok: true, events });
             return;
           }
+          if (request.method === "GET" && sub === "drive") {
+            const run = context.eventStore.run(runId);
+            if (!run) throw runtimeError("run_unknown", runId, "run not found");
+            const activeSession = vnextDriveSession(context.eventStore.path, runId);
+            const session = activeSession ? {
+              driveId: activeSession.driveId,
+              mode: activeSession.mode,
+              openedAt: activeSession.openedAt,
+              deadlineAt: activeSession.deadlineAt ?? null
+            } : null;
+            const receipts = context.eventStore.driveReceiptsForRun(runId, 20);
+            sendJson(response, 200, { ok: true, session, receipts });
+            return;
+          }
           if (request.method === "POST" && sub === "cancel") {
             const body = await readJsonBody(request);
             const result = cancelVnextRun(context, runId, {
@@ -26935,6 +26958,43 @@ async function startVnextRuntimeSupervisorInner(paths, requestedPortOption, now)
             return;
           }
         }
+        const driveMatch = /^\/v1\/drives\/([A-Za-z0-9_-]+)$/.exec(url.pathname);
+        if (request.method === "GET" && driveMatch) {
+          const driveId = driveMatch[1];
+          const projectRoot = url.searchParams.get("projectRoot") ?? "";
+          if (!projectRoot) {
+            sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: "projectRoot query parameter is required" });
+            return;
+          }
+          const context = contextFor(projectRoot);
+          let receipt;
+          try {
+            receipt = context.eventStore.driveReceipt(driveId);
+          } catch {
+            sendJson(response, 200, { ok: true, receipt: null, verified: false, divergence: "receipt unreadable" });
+            return;
+          }
+          if (!receipt) {
+            sendJson(response, 404, { ok: false, error: "drive_receipt_missing", message: "receipt not found" });
+            return;
+          }
+          const runId = receipt.runId;
+          const stored = context.eventStore.run(runId);
+          if (!stored) {
+            sendJson(response, 200, { ok: true, receipt, verified: false, divergence: "run missing" });
+            return;
+          }
+          const state = foldStoredVnextRun(context, stored);
+          const events = context.eventStore.events(runId, 0, 1e6);
+          const checked = verifyVnextDriveReceipt(receipt, events, state.status, { runId, driveId });
+          sendJson(response, 200, {
+            ok: true,
+            receipt,
+            verified: checked.verified,
+            ...checked.divergence !== void 0 ? { divergence: checked.divergence } : {}
+          });
+          return;
+        }
         const projectRunsMatch = /^\/v1\/projects\/(prj_[A-Za-z0-9_-]+)\/runs$/.exec(url.pathname);
         if (request.method === "GET" && projectRunsMatch) {
           const projectRoot = url.searchParams.get("projectRoot") ?? "";

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxm-claude-plugin",
-  "version": "0.7.25",
+  "version": "0.7.26",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm-runs/SKILL.md

@@ -16,12 +16,16 @@ verbs under `runs`.
 | `kxm run [workflow] [prompt...]` | Create a vNext run (prompt is hashed, never stored raw) | `--json` |
 | `kxm runs list` | List recent runs for the current project | `--json` |
 | `kxm runs status <runId>` | Show projected run status | `--json` |
+| `kxm runs receipt <runId>` | Print the newest drive receipt for a run | `--json`, `--all` |
+| `kxm runs drive <runId> --wait` | Drive a run, then wait for a receipt; exits 0 only for a VERIFIED COMPLETED settlement | `--json`, `--simulated`, `--timeout-ms` (default 60000, max 600000) |
 | `kxm runs cancel <runId>` | Durably request cancellation | `--json` |
 
 ```bash
 kxm run default "implement the bounded slice" --json
 kxm runs list --json
 kxm runs status run_12345 --json
+kxm runs receipt run_12345 --json
+kxm runs drive run_12345 --simulated --wait --timeout-ms 60000 --json
 kxm runs cancel run_12345 --json
 ```
 

package/plugins/kxm/src/cli/vnext.ts

@@ -557,7 +557,32 @@ export async function cmdVnextRunStatus(runtime: Runtime, runId: string): Promis
   }
 }
 
-export async function cmdVnextRunDrive(runtime: Runtime, runId: string, simulated: boolean): Promise<number> {
+const DEFAULT_DRIVE_WAIT_MS = 60_000;
+const MAX_DRIVE_WAIT_MS = 600_000;
+
+function parseDriveWaitTimeoutMs(raw: number | string | undefined): number | undefined {
+  if (raw === undefined) return DEFAULT_DRIVE_WAIT_MS;
+  const value = typeof raw === "number" ? raw : Number(typeof raw === "string" ? raw.trim() : raw);
+  if (!Number.isInteger(value) || value < 1 || value > MAX_DRIVE_WAIT_MS) return undefined;
+  return value;
+}
+
+function sleepMs(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function driveWaitCompleted(drive: VnextStatusDrive | undefined): boolean {
+  return drive?.verified === true
+    && drive.receipt?.settlement?.kind === "terminal"
+    && drive.receipt.settlement.status === "completed";
+}
+
+export async function cmdVnextRunDrive(
+  runtime: Runtime,
+  runId: string,
+  simulated: boolean,
+  options: { wait?: boolean; timeoutMs?: number | string } = {},
+): Promise<number> {
   try {
     const projectRoot = discoverVnextProjectRoot(runtime.cwd);
     if (!projectRoot) {
@@ -569,8 +594,19 @@ export async function cmdVnextRunDrive(runtime: Runtime, runId: string, simulate
       print(runtime.io, runtime.json, { ok: true, command: "runs drive", dryRun: true, runId, mode }, `drive plan: run ${runId} in ${mode} mode (no events written)`);
       return 0;
     }
+    const timeoutMs = options.wait === true ? parseDriveWaitTimeoutMs(options.timeoutMs) : DEFAULT_DRIVE_WAIT_MS;
+    if (options.wait === true && timeoutMs === undefined) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "runs drive", error: "run_drive_timeout_invalid" },
+        `run drive --wait --timeout-ms must be an integer between 1 and ${MAX_DRIVE_WAIT_MS}`,
+      );
+      return 1;
+    }
     const supervisor = await (vnextDriveCliSeams.ensureSupervisor ?? ensureVnextSupervisor)({ env: runtime.env });
-    const result = await (vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest)(supervisor, "POST", `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`, { mode });
+    const request = vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest;
+    const result = await request(supervisor, "POST", `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`, { mode });
     const driveId = result.driveId;
     const poll = result.poll;
     const status = result.status;
@@ -578,13 +614,39 @@ export async function cmdVnextRunDrive(runtime: Runtime, runId: string, simulate
       print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "run_drive_io_failed" }, "run drive failed because a local operation did not complete");
       return 1;
     }
-    print(
-      runtime.io,
-      runtime.json,
-      { ok: true, command: "runs drive", runId, driveId, poll, mode, status },
-      `drive ${driveId}: accepted (poll ${poll})`,
-    );
-    return 0;
+
+    if (options.wait !== true) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: true, command: "runs drive", runId, driveId, poll, mode, status },
+        `drive ${driveId}: accepted (poll ${poll})`,
+      );
+      return 0;
+    }
+
+    const deadline = Date.now() + timeoutMs!;
+    let interval = 25;
+    while (true) {
+      const stateResult = await request(supervisor, "GET", `/v1/runs/${encodeURIComponent(runId)}?projectRoot=${encodeURIComponent(projectRoot)}`);
+      const drive = stateResult.drive as VnextStatusDrive | undefined;
+      if (drive?.receipt) {
+        print(
+          runtime.io,
+          runtime.json,
+          { ok: driveWaitCompleted(drive), command: "runs drive", receipt: drive.receipt, verified: drive.verified === true },
+          JSON.stringify(drive.receipt, null, 2),
+        );
+        return driveWaitCompleted(drive) ? 0 : 1;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await sleepMs(Math.min(interval, remaining));
+      interval = Math.min(Math.floor(interval * 1.5), 250);
+    }
+
+    print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "timeout" }, "drive wait timed out");
+    return 1;
   } catch (error) {
     if (error instanceof VnextConfigError) {
       print(runtime.io, runtime.json, { ok: false, command: "runs drive", error: "run_drive_failed", issues: error.issues }, `run drive failed: ${error.message}`);
@@ -772,3 +834,45 @@ export async function cmdVnextRuntime(runtime: Runtime, action: string): Promise
     return 1;
   }
 }
+
+export async function cmdVnextRunReceipt(runtime: Runtime, runId: string, options: { all?: boolean } = {}): Promise<number> {
+  try {
+    const projectRoot = discoverVnextProjectRoot(runtime.cwd);
+    if (!projectRoot) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "project_required" }, "kxm runs receipt requires a vNext project (run kxm init first)");
+      return 1;
+    }
+    const supervisor = await (vnextDriveCliSeams.ensureSupervisor ?? ensureVnextSupervisor)({ env: runtime.env });
+    const result = await (vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest)(
+      supervisor,
+      "GET",
+      `/v1/runs/${encodeURIComponent(runId)}/drive?projectRoot=${encodeURIComponent(projectRoot)}`,
+    );
+    if (!Array.isArray(result.receipts)) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "run_receipt_io_failed" }, "run receipt failed because a local operation did not complete");
+      return 1;
+    }
+    const receipts = result.receipts as unknown[];
+    if (receipts.length === 0) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "no_receipts" }, `run ${runId} has no drive receipts`);
+      return 1;
+    }
+    if (options.all === true) {
+      print(runtime.io, runtime.json, { ok: true, command: "runs receipt", receipts }, JSON.stringify(receipts, null, 2));
+      return 0;
+    }
+    const latest = receipts[0];
+    const settlement = latest && typeof latest === "object" && "settlement" in latest
+      ? (latest as { settlement: unknown }).settlement
+      : latest;
+    print(runtime.io, runtime.json, { ok: true, command: "runs receipt", receipt: latest }, JSON.stringify(settlement, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof VnextConfigError) {
+      print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "run_receipt_failed", issues: error.issues }, `run receipt failed: ${error.message}`);
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "runs receipt", error: "run_receipt_io_failed" }, "run receipt failed because a local operation did not complete");
+    return 1;
+  }
+}

package/plugins/kxm/src/cli.ts

@@ -107,6 +107,7 @@ import {
   cmdVnextRun,
   cmdVnextRunStatus,
   cmdVnextRunDrive,
+  cmdVnextRunReceipt,
   cmdVnextRunCancel,
   cmdVnextRunList,
   cmdHarnessList,
@@ -390,8 +391,19 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
   addGlobalOptions(runCmd.command("drive").description("Drive a run with an explicit model-free simulation"))
     .argument("<runId>", "Run id")
     .option("--simulated", "Use the model-free simulation producer")
-    .action(async function runDriveAction(this: Command, runId: string, options: { simulated?: boolean }) {
-      result.code = await cmdVnextRunDrive(runtimeFrom(ctx, this), runId, options.simulated === true);
+    .option("--wait", "Wait until a drive receipt is recorded; exits 0 only for a VERIFIED COMPLETED settlement")
+    .option("--timeout-ms <n>", "Wait timeout in milliseconds (default 60000, max 600000)")
+    .action(async function runDriveAction(this: Command, runId: string, options: { simulated?: boolean; wait?: boolean; timeoutMs?: string }) {
+      result.code = await cmdVnextRunDrive(runtimeFrom(ctx, this), runId, options.simulated === true, {
+        wait: options.wait === true,
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+      });
+    });
+  addGlobalOptions(runCmd.command("receipt").description("Print the newest drive receipt for a run"))
+    .argument("<runId>", "Run id")
+    .option("--all", "Print the capped receipt list for the run")
+    .action(async function runReceiptAction(this: Command, runId: string, options: { all?: boolean }) {
+      result.code = await cmdVnextRunReceipt(runtimeFrom(ctx, this), runId, { all: options.all === true });
     });
   addGlobalOptions(runCmd.command("cancel").description("Durably request cancellation of a run"))
     .argument("<runId>", "Run id")

package/plugins/kxm/src/mcp-server.ts

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.25";
+const VERSION = "0.7.26";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/vnext-runtime-store.ts

@@ -396,6 +396,10 @@ export interface VnextDriveReceipt {
   producer: { id: string; closed: boolean };
 }
 
+export type VnextDriveReceiptListItem =
+  | VnextDriveReceipt
+  | { readonly driveId: string; readonly divergence: string };
+
 export interface VnextDriveReceiptBudget {
   budgetMs: number;
   source: "workflow" | "project" | "both";
@@ -1014,11 +1018,17 @@ export class VnextRunEventStore {
     return row ? parseDriveReceipt(row.receipt) : undefined;
   }
 
-  driveReceiptsForRun(runId: string, limit = 20): VnextDriveReceipt[] {
+  driveReceiptsForRun(runId: string, limit = 20): VnextDriveReceiptListItem[] {
     const rows = this.database.prepare(`
-      SELECT receipt FROM drive_receipts WHERE run_id = ? ORDER BY closed_at DESC, drive_id DESC LIMIT ?
-    `).all(runId, limit) as Array<{ receipt: string }>;
-    return rows.map((row) => parseDriveReceipt(row.receipt));
+      SELECT drive_id, receipt FROM drive_receipts WHERE run_id = ? ORDER BY closed_at DESC, drive_id DESC LIMIT ?
+    `).all(runId, limit) as Array<{ drive_id: string; receipt: string }>;
+    return rows.map((row) => {
+      try {
+        return parseDriveReceipt(row.receipt);
+      } catch {
+        return { driveId: row.drive_id, divergence: "receipt unreadable" };
+      }
+    });
   }
 
   insertCapability(row: VnextAttemptCapabilityRow): void {

package/plugins/kxm/src/vnext-runtime-supervisor.ts

@@ -9,6 +9,7 @@ import {
   VnextRuntimeRegistry,
   projectRuntimeKey,
   runtimeError,
+  verifyVnextDriveReceipt,
   vnextRuntimePaths,
   type VnextRuntimePaths,
 } from "./vnext-runtime-store.ts";
@@ -24,7 +25,7 @@ import {
 import { createVnextOneShotProducer } from "./vnext-oneshot-producer.ts";
 import { isProducerAdmitted } from "./producers.ts";
 import { VnextRunScheduler, createVnextSimulatedProducer, recordDriveReceipt, recoverVnextRun, vnextDrivePollProjection } from "./vnext-engine.ts";
-import { vnextOpenDriveSessions } from "./vnext-runtime-owner.ts";
+import { vnextDriveSession, vnextOpenDriveSessions } from "./vnext-runtime-owner.ts";
 
 /* ------------------------------------------------------------------ *
  * Token management
@@ -551,6 +552,24 @@ async function startVnextRuntimeSupervisorInner(
             sendJson(response, 200, { ok: true, events });
             return;
           }
+
+          if (request.method === "GET" && sub === "drive") {
+            const run = context.eventStore.run(runId);
+            if (!run) throw runtimeError("run_unknown", runId, "run not found");
+
+            const activeSession = vnextDriveSession(context.eventStore.path, runId);
+            const session = activeSession
+              ? {
+                  driveId: activeSession.driveId,
+                  mode: activeSession.mode,
+                  openedAt: activeSession.openedAt,
+                  deadlineAt: activeSession.deadlineAt ?? null,
+                }
+              : null;
+            const receipts = context.eventStore.driveReceiptsForRun(runId, 20);
+            sendJson(response, 200, { ok: true, session, receipts });
+            return;
+          }
           if (request.method === "POST" && sub === "cancel") {
             const body = await readJsonBody(request);
             const result = cancelVnextRun(context, runId, {
@@ -585,6 +604,47 @@ async function startVnextRuntimeSupervisorInner(
           }
         }
 
+        const driveMatch = /^\/v1\/drives\/([A-Za-z0-9_-]+)$/.exec(url.pathname);
+        if (request.method === "GET" && driveMatch) {
+          const driveId = driveMatch[1] as string;
+          const projectRoot = url.searchParams.get("projectRoot") ?? "";
+          if (!projectRoot) {
+            sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: "projectRoot query parameter is required" });
+            return;
+          }
+          const context = contextFor(projectRoot);
+
+          let receipt;
+          try {
+            receipt = context.eventStore.driveReceipt(driveId);
+          } catch {
+            sendJson(response, 200, { ok: true, receipt: null, verified: false, divergence: "receipt unreadable" });
+            return;
+          }
+
+          if (!receipt) {
+            sendJson(response, 404, { ok: false, error: "drive_receipt_missing", message: "receipt not found" });
+            return;
+          }
+
+          const runId = receipt.runId;
+          const stored = context.eventStore.run(runId);
+          if (!stored) {
+            sendJson(response, 200, { ok: true, receipt, verified: false, divergence: "run missing" });
+            return;
+          }
+          const state = foldStoredVnextRun(context, stored);
+          const events = context.eventStore.events(runId, 0, 1_000_000);
+          const checked = verifyVnextDriveReceipt(receipt, events, state.status, { runId, driveId });
+          sendJson(response, 200, {
+            ok: true,
+            receipt,
+            verified: checked.verified,
+            ...(checked.divergence !== undefined ? { divergence: checked.divergence } : {}),
+          });
+          return;
+        }
+
         const projectRunsMatch = /^\/v1\/projects\/(prj_[A-Za-z0-9_-]+)\/runs$/.exec(url.pathname);
         if (request.method === "GET" && projectRunsMatch) {
           const projectRoot = url.searchParams.get("projectRoot") ?? "";