@kontextmind/kxm 0.7.23 → 0.7.24

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

@@ -16261,6 +16261,7 @@ var VnextSchemaRegistry = class {
   migrationReceiptValidator;
   permissionDiffValidator;
   runEventValidator;
+  driveReceiptValidator;
   constructor(schemasDir = DEFAULT_SCHEMA_DIR) {
     this.schemasDir = resolve(schemasDir);
     this.ajv = new import__.Ajv2020({ allErrors: true, strict: true, strictRequired: false });
@@ -16277,6 +16278,7 @@ var VnextSchemaRegistry = class {
     const migrationReceiptFile = "migration-receipt.schema.json";
     const permissionDiffFile = "permission-diff.schema.json";
     const runEventFile = "run-event.schema.json";
+    const driveReceiptFile = "drive-receipt.schema.json";
     this.ajv.addSchema(readJsonObject(join2(this.schemasDir, localBindingsFile)));
     this.ajv.addSchema(readJsonObject(join2(this.schemasDir, templateProvenanceFile)));
     this.ajv.addSchema(readJsonObject(join2(this.schemasDir, initOperationFile)));
@@ -16285,6 +16287,7 @@ var VnextSchemaRegistry = class {
     this.ajv.addSchema(readJsonObject(join2(this.schemasDir, migrationReceiptFile)));
     this.ajv.addSchema(readJsonObject(join2(this.schemasDir, permissionDiffFile)));
     this.ajv.addSchema(readJsonObject(join2(this.schemasDir, runEventFile)));
+    this.ajv.addSchema(readJsonObject(join2(this.schemasDir, driveReceiptFile)));
     for (const [kind, definition] of Object.entries(RESOURCE_SCHEMA)) {
       const validator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${definition.file}`);
       if (!validator) throw new Error(`schema did not compile: ${definition.file}`);
@@ -16298,6 +16301,7 @@ var VnextSchemaRegistry = class {
     const migrationReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${migrationReceiptFile}`);
     const permissionDiffValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${permissionDiffFile}`);
     const runEventValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${runEventFile}`);
+    const driveReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${driveReceiptFile}`);
     if (!localBindingsValidator) throw new Error(`schema did not compile: ${localBindingsFile}`);
     if (!templateProvenanceValidator) throw new Error(`schema did not compile: ${templateProvenanceFile}`);
     if (!initOperationValidator) throw new Error(`schema did not compile: ${initOperationFile}`);
@@ -16306,6 +16310,7 @@ var VnextSchemaRegistry = class {
     if (!migrationReceiptValidator) throw new Error(`schema did not compile: ${migrationReceiptFile}`);
     if (!permissionDiffValidator) throw new Error(`schema did not compile: ${permissionDiffFile}`);
     if (!runEventValidator) throw new Error(`schema did not compile: ${runEventFile}`);
+    if (!driveReceiptValidator) throw new Error(`schema did not compile: ${driveReceiptFile}`);
     this.localBindingsValidator = localBindingsValidator;
     this.templateProvenanceValidator = templateProvenanceValidator;
     this.initOperationValidator = initOperationValidator;
@@ -16314,6 +16319,7 @@ var VnextSchemaRegistry = class {
     this.migrationReceiptValidator = migrationReceiptValidator;
     this.permissionDiffValidator = permissionDiffValidator;
     this.runEventValidator = runEventValidator;
+    this.driveReceiptValidator = driveReceiptValidator;
   }
   validate(kind, value, file) {
     const definition = RESOURCE_SCHEMA[kind];
@@ -16346,6 +16352,9 @@ var VnextSchemaRegistry = class {
   validatePermissionDiff(value, file) {
     return this.validateAuxiliary(value, file, "kxm.permission-diff.v1", this.permissionDiffValidator);
   }
+  validateDriveReceipt(value, file) {
+    return this.validateAuxiliary(value, file, "kxm.drive-receipt.v1", this.driveReceiptValidator);
+  }
   validateAuxiliary(value, file, identity, validator) {
     if (value.schema !== identity) {
       return [issue2("schema", "schema_identity_mismatch", file, `expected ${identity}, received ${String(value.schema)}`)];
@@ -16366,6 +16375,25 @@ function validateRunEvent(value, file) {
     )]);
   }
 }
+function validateDriveReceipt(value, file) {
+  const registry = cachedRunEventRegistry ??= new VnextSchemaRegistry();
+  if (!value || typeof value !== "object" || Array.isArray(value) || value.schema !== "kxm.drive-receipt.v1") {
+    throw new VnextConfigError([issue2(
+      "schema",
+      "drive_receipt_invalid",
+      file,
+      "expected kxm.drive-receipt.v1"
+    )]);
+  }
+  if (!registry.driveReceiptValidator(value)) {
+    throw new VnextConfigError([issue2(
+      "schema",
+      "drive_receipt_invalid",
+      file,
+      registry.ajv.errorsText(registry.driveReceiptValidator.errors, { separator: "; " })
+    )]);
+  }
+}
 function schemaIssue(file, error) {
   const location = error.instancePath || "/";
   const suffix = error.params && "additionalProperty" in error.params ? ` (${String(error.params.additionalProperty)})` : "";
@@ -17817,7 +17845,36 @@ var VnextRuntimeRegistry = class {
   }
 };
 var VNEXT_RUN_EVENT_SCHEMA = "kxm.run-event.v1";
-var VNEXT_EVENT_STORE_SCHEMA_VERSION = 3;
+function hashVnextDriveLog(events) {
+  const body = events.map((event) => `${event.eventId}:${event.sequence}`).join("\n");
+  return `sha256:${createHash3("sha256").update(body, "utf8").digest("hex")}`;
+}
+function verifyVnextDriveReceipt(receipt, events, foldedStatus, binding) {
+  const reasons = [];
+  if (receipt.runId !== binding.runId) {
+    reasons.push(`runId ${receipt.runId} != binding ${binding.runId}`);
+  }
+  if (receipt.driveId !== binding.driveId) {
+    reasons.push(`driveId ${receipt.driveId} != binding ${binding.driveId}`);
+  }
+  const last = events[events.length - 1];
+  const currentLast = last?.sequence ?? 0;
+  if (receipt.lastSequence !== currentLast) {
+    reasons.push(`lastSequence ${receipt.lastSequence} != log ${currentLast}`);
+  }
+  const prefix = events.filter((event) => event.sequence >= 1 && event.sequence <= receipt.lastSequence);
+  if (hashVnextDriveLog(prefix) !== receipt.logHash) {
+    reasons.push("logHash mismatch");
+  }
+  if (receipt.settlement.status !== foldedStatus) {
+    reasons.push(`settlement.status ${receipt.settlement.status} != folded ${foldedStatus}`);
+  }
+  if (reasons.length === 0) return { verified: true };
+  return { verified: false, divergence: reasons.join("; ") };
+}
+var VNEXT_EVENT_STORE_SCHEMA_VERSION = 4;
+var VNEXT_DRIVE_RECEIPT_SCHEMA = "kxm.drive-receipt.v1";
+var DRIVE_RECEIPT_MAX_BYTES = 8 * 1024;
 var EVENT_STORE_TABLES = {
   runs: ["run_id", "project_id", "home_runtime_id", "workflow_id", "prompt_sha256", "status", "config_revision", "memory_revision", "executor_policy_revision", "tool_policy_revision", "created_at", "updated_at"],
   events: ["project_id", "run_id", "sequence", "event_id", "event_type", "command_id", "occurred_at", "recorded_at", "monotonic_ns", "config_revision", "memory_revision", "executor_policy_revision", "tool_policy_revision", "payload", "schema", "home_runtime_id"],
@@ -17896,7 +17953,8 @@ var EVENT_STORE_TABLES = {
     "outcome",
     "settled_event_id",
     "content_hash"
-  ]
+  ],
+  drive_receipts: ["drive_id", "run_id", "project_id", "opened_sequence", "last_sequence", "closed_at", "schema", "receipt"]
 };
 var EVENT_STORE_SCHEMA = `
 CREATE TABLE runs (
@@ -18038,7 +18096,40 @@ CREATE TABLE gate_evidence (
 ) STRICT;
 CREATE UNIQUE INDEX gate_evidence_key ON gate_evidence(run_id, step_id, step_attempt, evidence_key) WHERE evidence_key IS NOT NULL;
 CREATE INDEX gate_evidence_run ON gate_evidence(run_id);
+CREATE TABLE drive_receipts (
+  drive_id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  opened_sequence INTEGER NOT NULL,
+  last_sequence INTEGER NOT NULL,
+  closed_at TEXT NOT NULL,
+  schema TEXT NOT NULL,
+  receipt TEXT NOT NULL
+) STRICT;
+CREATE INDEX drive_receipts_run ON drive_receipts(run_id);
+`;
+var DRIVE_RECEIPTS_DDL = `
+CREATE TABLE IF NOT EXISTS drive_receipts (
+  drive_id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  project_id TEXT NOT NULL,
+  opened_sequence INTEGER NOT NULL,
+  last_sequence INTEGER NOT NULL,
+  closed_at TEXT NOT NULL,
+  schema TEXT NOT NULL,
+  receipt TEXT NOT NULL
+) STRICT;
+CREATE INDEX IF NOT EXISTS drive_receipts_run ON drive_receipts(run_id);
 `;
+var EVENT_STORE_MIGRATIONS = [
+  {
+    fromVersion: 3,
+    toVersion: 4,
+    migrate(database) {
+      database.exec(DRIVE_RECEIPTS_DDL);
+    }
+  }
+];
 var VnextRunEventStore = class {
   path;
   database;
@@ -18047,7 +18138,8 @@ var VnextRunEventStore = class {
     this.database = openDatabase(this.path, "run event store", {
       schema: EVENT_STORE_SCHEMA,
       version: VNEXT_EVENT_STORE_SCHEMA_VERSION,
-      tables: EVENT_STORE_TABLES
+      tables: EVENT_STORE_TABLES,
+      migrations: EVENT_STORE_MIGRATIONS
     });
   }
   close() {
@@ -18204,6 +18296,38 @@ var VnextRunEventStore = class {
       ON CONFLICT(run_id) DO UPDATE SET last_sequence = excluded.last_sequence, state = excluded.state
     `).run(row.runId, row.lastSequence, row.state);
   }
+  insertDriveReceipt(receipt) {
+    validateDriveReceipt(receipt, "drive-receipt");
+    const canonical = vnextCanonicalJson(receipt);
+    if (Buffer.byteLength(canonical, "utf8") > DRIVE_RECEIPT_MAX_BYTES) {
+      throw runtimeError("drive_receipt_invalid", receipt.driveId, `drive receipt exceeds ${DRIVE_RECEIPT_MAX_BYTES} bytes`);
+    }
+    const result = this.database.prepare(`
+      INSERT INTO drive_receipts (drive_id, run_id, project_id, opened_sequence, last_sequence, closed_at, schema, receipt)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(drive_id) DO NOTHING
+    `).run(
+      receipt.driveId,
+      receipt.runId,
+      receipt.projectId,
+      receipt.openedSequence,
+      receipt.lastSequence,
+      receipt.closedAt,
+      receipt.schema,
+      canonical
+    );
+    return { inserted: Number(result.changes) === 1 };
+  }
+  driveReceipt(driveId) {
+    const row = this.database.prepare("SELECT receipt FROM drive_receipts WHERE drive_id = ?").get(driveId);
+    return row ? parseDriveReceipt(row.receipt) : void 0;
+  }
+  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 ?
+    `).all(runId, limit);
+    return rows.map((row) => parseDriveReceipt(row.receipt));
+  }
   insertCapability(row) {
     this.database.prepare(`
       INSERT INTO attempt_capabilities (attempt_id, run_id, assignment_id, step_id, step_attempt, producer_id, capability_hash, state)
@@ -18438,6 +18562,11 @@ var VnextRunEventStore = class {
     }
   }
 };
+function parseDriveReceipt(raw) {
+  const parsed = JSON.parse(raw);
+  validateDriveReceipt(parsed, "drive-receipt");
+  return parsed;
+}
 function runFromRow(row) {
   if (typeof row.memory_revision !== "string" || row.memory_revision.length === 0) {
     throw runtimeError("runtime_schema_shape_invalid", row.run_id, "memory_revision is required");
@@ -19066,6 +19195,9 @@ function foldVnextRunState(run, plan, events, options = {}) {
       case "run.cancel_requested":
         foldCancelRequested(state, event);
         break;
+      case "run.drive_opened":
+        foldDriveOpened(state, event);
+        break;
       case "step.entered":
         foldStepEntered(state, plan, event);
         break;
@@ -19277,6 +19409,17 @@ function isProvenFailure(state, plan) {
   const used = state.stepAttempts[stepId] ?? 0;
   return Boolean(step && used >= step.maxAttempts);
 }
+function foldDriveOpened(state, event) {
+  if (state.status !== "running" && state.status !== "blocked_uncertain") {
+    throw runtimeError("run_events_illegal", state.runId, "run.drive_opened is only legal while running or blocked_uncertain");
+  }
+  const driveId = stringPayload(event, "driveId");
+  const mode = stringPayload(event, "mode");
+  if (mode !== "simulated" && mode !== "live") {
+    throw runtimeError("run_events_illegal", state.runId, "run.drive_opened mode must be simulated or live");
+  }
+  state.drive = { driveId, mode, openedSequence: event.sequence };
+}
 function foldCancelRequested(state, event) {
   if (state.cancelRequested || TERMINAL_RUN.has(state.status)) {
     throw runtimeError("run_events_illegal", state.runId, "duplicate run.cancel_requested is not legal");
@@ -19925,7 +20068,8 @@ function freezeState(state) {
     transitionsUsed: state.transitionsUsed,
     cancelRequested: state.cancelRequested,
     ...state.terminalReason !== void 0 ? { terminalReason: state.terminalReason } : {},
-    ...state.terminalReason !== void 0 && state.status === "failed" ? { failureReason: state.terminalReason } : {}
+    ...state.terminalReason !== void 0 && state.status === "failed" ? { failureReason: state.terminalReason } : {},
+    ...state.drive !== void 0 ? { drive: Object.freeze({ ...state.drive }) } : {}
   };
   return Object.freeze(frozen);
 }
@@ -23839,6 +23983,110 @@ async function driveAdmitted(context, runId, producer, token, options = {}) {
 function newDriveId(runId, token, runtimeId, monotonicNs) {
   return `drv_${createHash10("sha256").update(`${runId}\0${token}\0${runtimeId}\0${monotonicNs}`, "utf8").digest("hex").slice(0, 24)}`;
 }
+function driveErrorSummary(error) {
+  const raw = error instanceof VnextConfigError ? error.issues[0]?.code : void 0;
+  const className = raw && /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/.test(raw) ? raw : "drive-failure";
+  return { class: className, component: "vnext-engine", retryable: false };
+}
+function receiptHandoff(handoff) {
+  return {
+    reason: handoff.reason,
+    detail: handoff.detail,
+    ...handoff.field !== void 0 ? { field: handoff.field } : {},
+    ...handoff.stepId !== void 0 ? { stepId: handoff.stepId } : {}
+  };
+}
+function appendDriveOpened(context, runId, driveId, mode) {
+  return context.eventStore.transaction(() => {
+    const run = requireRun(context, runId);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const sequence = context.eventStore.nextSequence(runId);
+    const event = {
+      ...vnextEventBase(context, run, now, vnextMonotonicNs()),
+      eventId: newVnextEventId(),
+      eventType: "run.drive_opened",
+      sequence,
+      payload: { driveId, mode }
+    };
+    context.eventStore.appendEvent(event);
+    const next = foldStoredVnextRun(context, run);
+    persistVnextRunState(context, runId, next, sequence);
+    return { sequence, occurredAt: now };
+  });
+}
+function recordDriveReceipt(context, session, closeInfo) {
+  if (isVnextRuntimeContextClosed(context)) return;
+  try {
+    const run = context.eventStore.run(session.runId);
+    if (!run) return;
+    const state = foldStoredVnextRun(context, run);
+    const events = context.eventStore.events(session.runId, 0, 1e6);
+    if (events.length === 0) return;
+    const opened = state.drive;
+    const openedEvent = opened ? events.find((event) => event.sequence === opened.openedSequence && event.eventType === "run.drive_opened") : events.find((event) => event.eventType === "run.drive_opened" && event.payload.driveId === session.driveId);
+    const last = events[events.length - 1];
+    const openedSequence = opened?.openedSequence ?? openedEvent?.sequence;
+    if (openedSequence === void 0) return;
+    const receipt = {
+      schema: VNEXT_DRIVE_RECEIPT_SCHEMA,
+      driveId: session.driveId,
+      runId: session.runId,
+      projectId: run.projectId,
+      homeRuntimeId: session.homeRuntimeId,
+      mode: session.mode,
+      openedAt: openedEvent?.occurredAt ?? session.openedAt,
+      openedSequence,
+      closedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      lastSequence: last.sequence,
+      logHash: hashVnextDriveLog(events.filter((event) => event.sequence >= 1 && event.sequence <= last.sequence)),
+      settlement: {
+        kind: closeInfo.kind,
+        status: state.status,
+        reason: closeInfo.reason ?? state.terminalReason ?? "",
+        ...closeInfo.kind === "handoff" && closeInfo.handoff ? { handoff: receiptHandoff(closeInfo.handoff) } : {},
+        ...closeInfo.error !== void 0 ? { error: closeInfo.error } : {}
+      },
+      budget: null,
+      producer: { id: closeInfo.producerId, closed: closeInfo.producerClosed }
+    };
+    context.eventStore.insertDriveReceipt(receipt);
+  } catch {
+  }
+}
+function vnextDrivePollProjection(context, runId, state) {
+  if (!state.drive) return void 0;
+  const events = context.eventStore.events(runId, 0, 1e6);
+  const openedEvent = events.find((event) => event.sequence === state.drive.openedSequence);
+  let receipt = null;
+  let unreadable = false;
+  try {
+    receipt = context.eventStore.driveReceipt(state.drive.driveId) ?? null;
+  } catch {
+    unreadable = true;
+  }
+  const projection = {
+    driveId: state.drive.driveId,
+    mode: state.drive.mode,
+    openedAt: openedEvent?.occurredAt ?? "",
+    receipt: unreadable ? null : receipt,
+    verified: false
+  };
+  if (unreadable) {
+    projection.divergence = "receipt unreadable";
+    return projection;
+  }
+  if (!receipt) {
+    projection.divergence = "no receipt";
+    return projection;
+  }
+  const checked = verifyVnextDriveReceipt(receipt, events, state.status, {
+    runId,
+    driveId: state.drive.driveId
+  });
+  projection.verified = checked.verified;
+  if (checked.divergence !== void 0) projection.divergence = checked.divergence;
+  return projection;
+}
 function inflightAttemptId(state) {
   const leftover = unreconciledPanelAttemptId(state);
   if (leftover) return leftover;
@@ -23986,13 +24234,15 @@ var VnextRunScheduler = class _VnextRunScheduler {
               throw error;
             }
             const driveId = newDriveId(runId, token, this.context.homeRuntimeId, vnextMonotonicNs());
+            const openedMeta = appendDriveOpened(this.context, runId, driveId, options.mode);
             const session = {
               driveId,
               runId,
               token,
               homeRuntimeId: this.context.homeRuntimeId,
               mode: options.mode,
-              openedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              openedAt: openedMeta.occurredAt,
+              producerId: producer.id,
               controller: new AbortController(),
               settled
             };
@@ -24001,10 +24251,30 @@ var VnextRunScheduler = class _VnextRunScheduler {
             resolveOpen({ driveId, settled });
             try {
               const result = await driveAdmitted(this.context, runId, producer, token, driveOptions);
+              const kind = result.handoff ? "handoff" : isTerminalRunStatus(result.state.status) ? "terminal" : "unsettled";
+              recordDriveReceipt(this.context, session, {
+                kind,
+                ...result.state.terminalReason !== void 0 ? { reason: result.state.terminalReason } : result.handoff ? { reason: result.handoff.reason } : {},
+                ...result.handoff ? { handoff: result.handoff } : {},
+                producerId: producer.id,
+                producerClosed: false
+              });
               pending.resolve(result);
               return result;
             } catch (error) {
               recordBareDriveFailure(this.context, runId);
+              let foldedStatus;
+              try {
+                foldedStatus = foldStoredVnextRun(this.context, requireRun(this.context, runId)).status;
+              } catch {
+                foldedStatus = void 0;
+              }
+              recordDriveReceipt(this.context, session, {
+                kind: foldedStatus !== void 0 && isTerminalRunStatus(foldedStatus) ? "terminal" : "unsettled",
+                error: driveErrorSummary(error),
+                producerId: producer.id,
+                producerClosed: false
+              });
               pending.reject(error);
               throw error;
             }
@@ -26248,6 +26518,19 @@ async function waitForDriveSessions(settled, graceMs) {
     if (timeout !== void 0) clearTimeout(timeout);
   }
 }
+async function driveSessionStillPending(settled) {
+  let pending = true;
+  void settled.then(
+    () => {
+      pending = false;
+    },
+    () => {
+      pending = false;
+    }
+  );
+  await Promise.resolve();
+  return pending;
+}
 async function startVnextRuntimeSupervisor(options = {}) {
   const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
   const paths = vnextRuntimePaths(options.stateRoot !== void 0 ? { stateRoot: options.stateRoot } : {});
@@ -26351,7 +26634,9 @@ async function startVnextRuntimeSupervisorInner(paths, requestedPortOption, now)
           const bundle = loadVnextProject(projectRoot, {});
           if (request.method === "GET" && !sub) {
             const projected = rebuildVnextRunProjection(context, runId);
-            sendJson(response, 200, { ok: true, run: projected });
+            const folded = foldStoredVnextRun(context, projected);
+            const drive = vnextDrivePollProjection(context, runId, folded);
+            sendJson(response, 200, { ok: true, run: projected, ...drive !== void 0 ? { drive } : {} });
             return;
           }
           if (request.method === "POST" && sub === "drive") {
@@ -26568,6 +26853,15 @@ async function startVnextRuntimeSupervisorInner(paths, requestedPortOption, now)
       }
     }
     await waitForDriveSessions(openSessions.map(({ session }) => session.settled), runtimeStopGraceMs());
+    for (const { context, session } of openSessions) {
+      if (!await driveSessionStillPending(session.settled)) continue;
+      recordDriveReceipt(context, session, {
+        kind: "unsettled",
+        reason: "runtime_shutdown_grace_expired",
+        producerId: session.producerId,
+        producerClosed: false
+      });
+    }
     for (const context of contexts.values()) closeVnextRuntimeContext(context);
     contexts.clear();
     const closed = new Promise((resolveStop) => server.close(() => resolveStop()));

package/plugins/kxm/package.json

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

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

@@ -473,6 +473,42 @@ export async function cmdVnextRun(runtime: Runtime, workflow: string | undefined
   }
 }
 
+interface VnextStatusDrive {
+  driveId?: string;
+  mode?: string;
+  openedAt?: string;
+  receipt?: {
+    settlement?: { kind?: string; status?: string; reason?: string };
+  } | null;
+  verified?: boolean;
+  divergence?: string;
+}
+
+function formatDriveStatusLine(runStatus: string, drive: VnextStatusDrive | undefined): string | undefined {
+  if (!drive || typeof drive.driveId !== "string" || drive.driveId.length === 0) return undefined;
+  const receipt = drive.receipt ?? null;
+  if (receipt === null) {
+    if (runStatus === "running" || runStatus === "blocked_uncertain") {
+      return `drive ${drive.driveId}: open`;
+    }
+    return `drive ${drive.driveId}: no receipt (orphaned)`;
+  }
+  const kind = receipt.settlement?.kind;
+  const reason = typeof receipt.settlement?.reason === "string" ? receipt.settlement.reason : "";
+  if (kind === "unsettled") {
+    return `drive ${drive.driveId}: unsettled ${reason}`.trimEnd();
+  }
+  if (kind === "handoff") {
+    return drive.verified === true
+      ? `drive ${drive.driveId}: handoff (receipt verified)`
+      : `drive ${drive.driveId}: handoff`;
+  }
+  if (drive.verified === true) {
+    return `drive ${drive.driveId}: completed (receipt verified)`;
+  }
+  return `drive ${drive.driveId}: completed`;
+}
+
 export async function cmdVnextRunStatus(runtime: Runtime, runId: string): Promise<number> {
   try {
     const projectRoot = discoverVnextProjectRoot(runtime.cwd);
@@ -480,10 +516,17 @@ export async function cmdVnextRunStatus(runtime: Runtime, runId: string): Promis
       print(runtime.io, runtime.json, { ok: false, command: "runs status", error: "project_required" }, "kxm runs status requires a vNext project (run kxm init first)");
       return 1;
     }
-    const supervisor = await ensureVnextSupervisor({ env: runtime.env });
-    const result = await vnextRuntimeRequest(supervisor, "GET", `/v1/runs/${encodeURIComponent(runId)}?projectRoot=${encodeURIComponent(projectRoot)}`);
+    const supervisor = await (vnextDriveCliSeams.ensureSupervisor ?? ensureVnextSupervisor)({ env: runtime.env });
+    const result = await (vnextDriveCliSeams.runtimeRequest ?? vnextRuntimeRequest)(supervisor, "GET", `/v1/runs/${encodeURIComponent(runId)}?projectRoot=${encodeURIComponent(projectRoot)}`);
     const run = result.run as { runId: string; status: string; workflowId: string; configRevision: string; updatedAt: string };
-    print(runtime.io, runtime.json, { ok: true, command: "runs status", run }, `run ${run.runId}: ${run.status} (workflow ${run.workflowId}, updated ${run.updatedAt})`);
+    const drive = result.drive as VnextStatusDrive | undefined;
+    const driveLine = formatDriveStatusLine(run.status, drive);
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: true, command: "runs status", run, ...(drive !== undefined ? { drive } : {}) },
+      `run ${run.runId}: ${run.status} (workflow ${run.workflowId}, updated ${run.updatedAt})${driveLine ? `\n${driveLine}` : ""}`,
+    );
     return 0;
   } catch (error) {
     if (error instanceof VnextConfigError) {

package/plugins/kxm/src/cli.ts

@@ -382,7 +382,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     }));
   const runCmd = addGlobalOptions(program.command("runs").description("Inspect vNext runs"));
   runCmd.helpCommand("help", "Show runs help");
-  addGlobalOptions(runCmd.command("status").description("Show the projected status of a run"))
+  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(this: Command, runId: string) {
       result.code = await cmdVnextRunStatus(runtimeFrom(ctx, this), runId);

package/plugins/kxm/src/database.ts

@@ -420,7 +420,7 @@ export function discoverProjectStores(projectRoot: string, options: { hubDataPat
         stores.push({
           storeId: `events:${key}`,
           sourcePath: join(eventsDir, entry.name),
-          maxSupportedVersion: 3,
+          maxSupportedVersion: 4,
         });
       }
     }
@@ -537,6 +537,8 @@ export function restoreBackup(
     let maxSupported = 3;
     if (store.storeId === "registry" || store.storeId === "binding-store") {
       maxSupported = 1;
+    } else if (store.storeId.startsWith("events:")) {
+      maxSupported = 4;
     }
 
     let targetPath = store.sourcePath;

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.23";
+const VERSION = "0.7.24";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/vnext-config.ts

@@ -166,6 +166,7 @@ export class VnextSchemaRegistry {
   readonly migrationReceiptValidator: ValidateFunction;
   readonly permissionDiffValidator: ValidateFunction;
   readonly runEventValidator: ValidateFunction;
+  readonly driveReceiptValidator: ValidateFunction;
 
   constructor(schemasDir = DEFAULT_SCHEMA_DIR) {
     this.schemasDir = resolve(schemasDir);
@@ -183,6 +184,7 @@ export class VnextSchemaRegistry {
     const migrationReceiptFile = "migration-receipt.schema.json";
     const permissionDiffFile = "permission-diff.schema.json";
     const runEventFile = "run-event.schema.json";
+    const driveReceiptFile = "drive-receipt.schema.json";
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, localBindingsFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, templateProvenanceFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, initOperationFile)));
@@ -191,6 +193,7 @@ export class VnextSchemaRegistry {
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, migrationReceiptFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, permissionDiffFile)));
     this.ajv.addSchema(readJsonObject(join(this.schemasDir, runEventFile)));
+    this.ajv.addSchema(readJsonObject(join(this.schemasDir, driveReceiptFile)));
     for (const [kind, definition] of Object.entries(RESOURCE_SCHEMA) as [VnextResourceKind, { identity: string; file: string }][]) {
       const validator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${definition.file}`);
       if (!validator) throw new Error(`schema did not compile: ${definition.file}`);
@@ -204,6 +207,7 @@ export class VnextSchemaRegistry {
     const migrationReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${migrationReceiptFile}`);
     const permissionDiffValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${permissionDiffFile}`);
     const runEventValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${runEventFile}`);
+    const driveReceiptValidator = this.ajv.getSchema(`https://schemas.kxm.dev/vnext/${driveReceiptFile}`);
     if (!localBindingsValidator) throw new Error(`schema did not compile: ${localBindingsFile}`);
     if (!templateProvenanceValidator) throw new Error(`schema did not compile: ${templateProvenanceFile}`);
     if (!initOperationValidator) throw new Error(`schema did not compile: ${initOperationFile}`);
@@ -212,6 +216,7 @@ export class VnextSchemaRegistry {
     if (!migrationReceiptValidator) throw new Error(`schema did not compile: ${migrationReceiptFile}`);
     if (!permissionDiffValidator) throw new Error(`schema did not compile: ${permissionDiffFile}`);
     if (!runEventValidator) throw new Error(`schema did not compile: ${runEventFile}`);
+    if (!driveReceiptValidator) throw new Error(`schema did not compile: ${driveReceiptFile}`);
     this.localBindingsValidator = localBindingsValidator;
     this.templateProvenanceValidator = templateProvenanceValidator;
     this.initOperationValidator = initOperationValidator;
@@ -220,6 +225,7 @@ export class VnextSchemaRegistry {
     this.migrationReceiptValidator = migrationReceiptValidator;
     this.permissionDiffValidator = permissionDiffValidator;
     this.runEventValidator = runEventValidator;
+    this.driveReceiptValidator = driveReceiptValidator;
   }
 
   validate(kind: VnextResourceKind, value: JsonObject, file: string): VnextConfigIssue[] {
@@ -261,6 +267,10 @@ export class VnextSchemaRegistry {
     return this.validateAuxiliary(value, file, "kxm.permission-diff.v1", this.permissionDiffValidator);
   }
 
+  validateDriveReceipt(value: JsonObject, file: string): VnextConfigIssue[] {
+    return this.validateAuxiliary(value, file, "kxm.drive-receipt.v1", this.driveReceiptValidator);
+  }
+
   private validateAuxiliary(value: JsonObject, file: string, identity: string, validator: ValidateFunction): VnextConfigIssue[] {
     if (value.schema !== identity) {
       return [issue("schema", "schema_identity_mismatch", file, `expected ${identity}, received ${String(value.schema)}`)];
@@ -285,6 +295,27 @@ export function validateRunEvent(value: unknown, file: string): void {
   }
 }
 
+/** Validate a drive receipt against `kxm.drive-receipt.v1`. Throws `drive_receipt_invalid`. */
+export function validateDriveReceipt(value: unknown, file: string): void {
+  const registry = (cachedRunEventRegistry ??= new VnextSchemaRegistry());
+  if (!value || typeof value !== "object" || Array.isArray(value) || (value as JsonObject).schema !== "kxm.drive-receipt.v1") {
+    throw new VnextConfigError([issue(
+      "schema",
+      "drive_receipt_invalid",
+      file,
+      "expected kxm.drive-receipt.v1",
+    )]);
+  }
+  if (!registry.driveReceiptValidator(value)) {
+    throw new VnextConfigError([issue(
+      "schema",
+      "drive_receipt_invalid",
+      file,
+      registry.ajv.errorsText(registry.driveReceiptValidator.errors, { separator: "; " }),
+    )]);
+  }
+}
+
 function schemaIssue(file: string, error: ErrorObject): VnextConfigIssue {
   const location = error.instancePath || "/";
   const suffix = error.params && "additionalProperty" in error.params