@kontextmind/kxm 0.7.22 → 0.7.24

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

@@ -2,12 +2,13 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { HubClient } from "./client.ts";
+import { resolveClientHubAuthToken } from "./hub-env.ts";
 import { defaultProjectName } from "./project-name.ts";
 import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } from "./commands.ts";
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.22";
+const VERSION = "0.7.24";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;
@@ -34,10 +35,6 @@ function textResult(value: unknown) {
   return { content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }] };
 }
 
-function optionalString(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
 function asRecord(value: unknown): Record<string, unknown> {
   return value && typeof value === "object" && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -83,12 +80,13 @@ async function ensureClient(): Promise<HubClient> {
   if (starting) return starting;
   starting = (async () => {
     const projectDir = process.env.KXM_PROJECT_DIR || process.env.CLAUDE_PROJECT_DIR || process.cwd();
-    const authToken = optionalString(process.env.KXM_AUTH_TOKEN);
+    const project = defaultProjectName(projectDir, process.env);
+    const authToken = resolveClientHubAuthToken(process.env, project);
     const candidate = new HubClient({
       serverUrl: process.env.KXM_SERVER_URL?.trim() || "http://127.0.0.1:7331",
       name: process.env.KXM_AGENT_NAME?.trim() || `claude-${process.pid}`,
       purpose: process.env.KXM_AGENT_PURPOSE?.trim() || "Claude Code implementation and review agent",
-      project: defaultProjectName(projectDir, process.env),
+      project,
       model: "claude-code",
       ...(authToken ? { authToken } : {}),
     });

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

package/plugins/kxm/src/vnext-engine-fold.ts

@@ -107,6 +107,12 @@ export interface VnextRunCurrentStep {
   readonly evidenceRefs?: readonly { id: string; kind: string; hash: string; status: string }[] | undefined;
 }
 
+export interface VnextRunDriveBinding {
+  readonly driveId: string;
+  readonly mode: "simulated" | "live";
+  readonly openedSequence: number;
+}
+
 export interface VnextRunState {
   readonly schema: typeof VNEXT_RUN_STATE_SCHEMA;
   readonly runId: string;
@@ -120,6 +126,7 @@ export interface VnextRunState {
   readonly cancelRequested: boolean;
   readonly terminalReason?: string | undefined;
   readonly failureReason?: string | undefined;
+  readonly drive?: VnextRunDriveBinding | undefined;
 }
 
 interface MutableAttempt {
@@ -171,6 +178,7 @@ interface MutableState {
   awaitingTransition: boolean;
   cancelCommandId?: string | undefined;
   lastTerminalTransition?: VnextTerminalStatus | undefined;
+  drive?: VnextRunDriveBinding | undefined;
 }
 
 function emptyPanel(): MutablePanel {
@@ -462,6 +470,9 @@ export function foldVnextRunState(
       case "run.cancel_requested":
         foldCancelRequested(state, event);
         break;
+      case "run.drive_opened":
+        foldDriveOpened(state, event);
+        break;
       case "step.entered":
         foldStepEntered(state, plan!, event);
         break;
@@ -694,6 +705,18 @@ function isProvenFailure(state: MutableState, plan: VnextCompiledPlan | undefine
   return Boolean(step && used >= step.maxAttempts);
 }
 
+function foldDriveOpened(state: MutableState, event: VnextRunEvent): void {
+  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: MutableState, event: VnextRunEvent): void {
   if (state.cancelRequested || TERMINAL_RUN.has(state.status)) {
     throw runtimeError("run_events_illegal", state.runId, "duplicate run.cancel_requested is not legal");
@@ -1379,6 +1402,7 @@ function freezeState(state: MutableState): VnextRunState {
     cancelRequested: state.cancelRequested,
     ...(state.terminalReason !== undefined ? { terminalReason: state.terminalReason } : {}),
     ...(state.terminalReason !== undefined && state.status === "failed" ? { failureReason: state.terminalReason } : {}),
+    ...(state.drive !== undefined ? { drive: Object.freeze({ ...state.drive }) } : {}),
   };
   return Object.freeze(frozen);
 }

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

@@ -66,12 +66,17 @@ import {
   type VnextRuntimeContext,
 } from "./vnext-runtime.ts";
 import {
+  hashVnextDriveLog,
   newVnextAssignmentId,
   newVnextAttemptId,
   newVnextEventId,
   projectRuntimeKey,
   runtimeError,
+  verifyVnextDriveReceipt,
+  VNEXT_DRIVE_RECEIPT_SCHEMA,
   type VnextAttemptCapabilityRow,
+  type VnextDriveReceipt,
+  type VnextDriveReceiptHandoff,
   type VnextGateAttemptRow,
   type VnextGateEvidenceRow,
   type VnextGateObservationRow,
@@ -79,7 +84,7 @@ import {
   type VnextRunRecord,
   type VnextRunStatus,
 } from "./vnext-runtime-store.ts";
-import { vnextCanonicalJson, type JsonValue, type VnextProjectBundle } from "./vnext-config.ts";
+import { VnextConfigError, vnextCanonicalJson, type JsonValue, type VnextProjectBundle } from "./vnext-config.ts";
 import { evaluateArtifactsGate } from "./vnext-engine-artifacts.ts";
 import { createCommandObserver } from "./vnext-engine-command.ts";
 import {
@@ -432,6 +437,149 @@ function newDriveId(runId: string, token: string, runtimeId: string, monotonicNs
   return `drv_${createHash("sha256").update(`${runId}\0${token}\0${runtimeId}\0${monotonicNs}`, "utf8").digest("hex").slice(0, 24)}`;
 }
 
+export interface VnextDrivePollProjection {
+  driveId: string;
+  mode: "simulated" | "live";
+  openedAt: string;
+  receipt: VnextDriveReceipt | null;
+  verified: boolean;
+  divergence?: string;
+}
+
+export interface VnextDriveReceiptCloseInfo {
+  kind: "terminal" | "handoff" | "unsettled";
+  reason?: string;
+  handoff?: VnextRunHandoff;
+  error?: { class: string; component: string; retryable: boolean };
+  producerId: string;
+  producerClosed: boolean;
+}
+
+function driveErrorSummary(error: unknown): { class: string; component: string; retryable: boolean } {
+  const raw = error instanceof VnextConfigError ? error.issues[0]?.code : undefined;
+  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: VnextRunHandoff): VnextDriveReceiptHandoff {
+  return {
+    reason: handoff.reason,
+    detail: handoff.detail,
+    ...(handoff.field !== undefined ? { field: handoff.field } : {}),
+    ...(handoff.stepId !== undefined ? { stepId: handoff.stepId } : {}),
+  };
+}
+
+function appendDriveOpened(
+  context: VnextRuntimeContext,
+  runId: string,
+  driveId: string,
+  mode: "simulated" | "live",
+): { sequence: number; occurredAt: string } {
+  return context.eventStore.transaction(() => {
+    const run = requireRun(context, runId);
+    const now = new Date().toISOString();
+    const sequence = context.eventStore.nextSequence(runId);
+    const event: VnextRunEvent = {
+      ...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 };
+  });
+}
+
+export function recordDriveReceipt(
+  context: VnextRuntimeContext,
+  session: VnextDriveSession,
+  closeInfo: VnextDriveReceiptCloseInfo,
+): void {
+  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, 1_000_000);
+    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 === undefined) return;
+    const receipt: VnextDriveReceipt = {
+      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: 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 !== undefined ? { error: closeInfo.error } : {}),
+      },
+      budget: null,
+      producer: { id: closeInfo.producerId, closed: closeInfo.producerClosed },
+    };
+    context.eventStore.insertDriveReceipt(receipt);
+  } catch {
+    // The drive result governs; a missing receipt is visible on poll.
+  }
+}
+
+export function vnextDrivePollProjection(
+  context: VnextRuntimeContext,
+  runId: string,
+  state: VnextRunState,
+): VnextDrivePollProjection | undefined {
+  if (!state.drive) return undefined;
+  const events = context.eventStore.events(runId, 0, 1_000_000);
+  const openedEvent = events.find((event) => event.sequence === state.drive!.openedSequence);
+  let receipt: VnextDriveReceipt | null = null;
+  let unreadable = false;
+  try {
+    receipt = context.eventStore.driveReceipt(state.drive.driveId) ?? null;
+  } catch {
+    unreadable = true;
+  }
+  const projection: VnextDrivePollProjection = {
+    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 !== undefined) projection.divergence = checked.divergence;
+  return projection;
+}
+
 function inflightAttemptId(state: VnextRunState): string | undefined {
   const leftover = unreconciledPanelAttemptId(state);
   if (leftover) return leftover;
@@ -595,13 +743,15 @@ export class VnextRunScheduler {
               throw error;
             }
             const driveId = newDriveId(runId, token, this.context.homeRuntimeId, vnextMonotonicNs());
+            const openedMeta = appendDriveOpened(this.context, runId, driveId, options.mode);
             const session: VnextDriveSession = {
               driveId,
               runId,
               token,
               homeRuntimeId: this.context.homeRuntimeId,
               mode: options.mode,
-              openedAt: new Date().toISOString(),
+              openedAt: openedMeta.occurredAt,
+              producerId: producer.id,
               controller: new AbortController(),
               settled,
             };
@@ -610,10 +760,30 @@ export 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 !== undefined ? { 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: string | undefined;
+              try {
+                foldedStatus = foldStoredVnextRun(this.context, requireRun(this.context, runId)).status;
+              } catch {
+                foldedStatus = undefined;
+              }
+              recordDriveReceipt(this.context, session, {
+                kind: foldedStatus !== undefined && isTerminalRunStatus(foldedStatus as VnextRunStatus) ? "terminal" : "unsettled",
+                error: driveErrorSummary(error),
+                producerId: producer.id,
+                producerClosed: false,
+              });
               pending.reject(error);
               throw error;
             }

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

@@ -26,6 +26,7 @@ export interface VnextDriveSession {
   homeRuntimeId: string;
   mode: "simulated" | "live";
   openedAt: string;
+  producerId: string;
   controller: AbortController;
   settled: Promise<unknown>;
 }

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

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { DatabaseSync } from "./sqlite.ts";
-import { VnextConfigError, validateRunEvent, vnextCanonicalJson, type JsonValue, type VnextConfigIssue, type VnextConfigOptions } from "./vnext-config.ts";
+import { VnextConfigError, validateDriveReceipt, validateRunEvent, vnextCanonicalJson, type JsonValue, type VnextConfigIssue, type VnextConfigOptions } from "./vnext-config.ts";
 import { vnextUserStateRoot } from "./vnext-bindings.ts";
 
 /* ------------------------------------------------------------------ *
@@ -364,6 +364,73 @@ export interface VnextRunStateRow {
   state: string;
 }
 
+export interface VnextDriveReceiptHandoff {
+  reason: string;
+  field?: string;
+  stepId?: string;
+  detail: string;
+}
+
+export interface VnextDriveReceiptSettlement {
+  kind: "terminal" | "handoff" | "unsettled";
+  status: string;
+  reason: string;
+  handoff?: VnextDriveReceiptHandoff;
+  error?: { class: string; component: string; retryable: boolean };
+}
+
+export interface VnextDriveReceipt {
+  schema: typeof VNEXT_DRIVE_RECEIPT_SCHEMA;
+  driveId: string;
+  runId: string;
+  projectId: string;
+  homeRuntimeId: string;
+  mode: "simulated" | "live";
+  openedAt: string;
+  openedSequence: number;
+  closedAt: string;
+  lastSequence: number;
+  logHash: string;
+  settlement: VnextDriveReceiptSettlement;
+  budget: null;
+  producer: { id: string; closed: boolean };
+}
+
+/** sha256 over `eventId:sequence` for events 1..lastSequence, in sequence order. */
+export function hashVnextDriveLog(events: readonly { eventId: string; sequence: number }[]): string {
+  const body = events.map((event) => `${event.eventId}:${event.sequence}`).join("\n");
+  return `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+}
+
+export function verifyVnextDriveReceipt(
+  receipt: VnextDriveReceipt,
+  events: readonly VnextRunEvent[],
+  foldedStatus: string,
+  binding: { runId: string; driveId: string },
+): { verified: boolean; divergence?: string } {
+  const reasons: string[] = [];
+  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("; ") };
+}
+
 export interface VnextAttemptCapabilityRow {
   attemptId: string;
   runId: string;
@@ -472,7 +539,9 @@ export interface VnextCommandRecord {
   recordedAt: string;
 }
 
-export const VNEXT_EVENT_STORE_SCHEMA_VERSION = 3;
+export const VNEXT_EVENT_STORE_SCHEMA_VERSION = 4;
+export const VNEXT_DRIVE_RECEIPT_SCHEMA = "kxm.drive-receipt.v1";
+export const DRIVE_RECEIPT_MAX_BYTES = 8 * 1024;
 
 const 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"],
@@ -497,6 +566,7 @@ const EVENT_STORE_TABLES = {
     "evidence_id", "attempt_id", "observation_id", "run_id", "project_id", "home_runtime_id", "step_id", "step_attempt",
     "assignment_id", "effect_id", "evidence_key", "kind", "expect", "outcome", "settled_event_id", "content_hash",
   ],
+  drive_receipts: ["drive_id", "run_id", "project_id", "opened_sequence", "last_sequence", "closed_at", "schema", "receipt"],
 } as const;
 
 const EVENT_STORE_SCHEMA = `
@@ -639,8 +709,43 @@ 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);
 `;
 
+const 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);
+`;
+
+const EVENT_STORE_MIGRATIONS = [
+  {
+    fromVersion: 3,
+    toVersion: 4,
+    migrate(database: DatabaseSync): void {
+      database.exec(DRIVE_RECEIPTS_DDL);
+    },
+  },
+];
+
 export class VnextRunEventStore {
   readonly path: string;
   private readonly database: DatabaseSync;
@@ -651,6 +756,7 @@ export class VnextRunEventStore {
       schema: EVENT_STORE_SCHEMA,
       version: VNEXT_EVENT_STORE_SCHEMA_VERSION,
       tables: EVENT_STORE_TABLES,
+      migrations: EVENT_STORE_MIGRATIONS,
     });
   }
 
@@ -871,6 +977,43 @@ export class VnextRunEventStore {
     `).run(row.runId, row.lastSequence, row.state);
   }
 
+  insertDriveReceipt(receipt: VnextDriveReceipt): { inserted: boolean } {
+    validateDriveReceipt(receipt, "drive-receipt");
+    const canonical = vnextCanonicalJson(receipt as unknown as JsonValue);
+    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: string): VnextDriveReceipt | undefined {
+    const row = this.database.prepare("SELECT receipt FROM drive_receipts WHERE drive_id = ?").get(driveId) as
+      | { receipt: string }
+      | undefined;
+    return row ? parseDriveReceipt(row.receipt) : undefined;
+  }
+
+  driveReceiptsForRun(runId: string, limit = 20): VnextDriveReceipt[] {
+    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));
+  }
+
   insertCapability(row: VnextAttemptCapabilityRow): void {
     this.database.prepare(`
       INSERT INTO attempt_capabilities (attempt_id, run_id, assignment_id, step_id, step_attempt, producer_id, capability_hash, state)
@@ -1075,6 +1218,12 @@ export class VnextRunEventStore {
   }
 }
 
+function parseDriveReceipt(raw: string): VnextDriveReceipt {
+  const parsed = JSON.parse(raw) as unknown;
+  validateDriveReceipt(parsed, "drive-receipt");
+  return parsed as VnextDriveReceipt;
+}
+
 function runFromRow(row: {
   run_id: string;
   project_id: string;

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

@@ -23,7 +23,7 @@ import {
 } from "./vnext-runtime.ts";
 import { createVnextOneShotProducer } from "./vnext-oneshot-producer.ts";
 import { isProducerAdmitted } from "./producers.ts";
-import { VnextRunScheduler, createVnextSimulatedProducer, recoverVnextRun } from "./vnext-engine.ts";
+import { VnextRunScheduler, createVnextSimulatedProducer, recordDriveReceipt, recoverVnextRun, vnextDrivePollProjection } from "./vnext-engine.ts";
 import { vnextOpenDriveSessions } from "./vnext-runtime-owner.ts";
 
 /* ------------------------------------------------------------------ *
@@ -318,6 +318,16 @@ async function waitForDriveSessions(settled: Promise<unknown>[], graceMs: number
   }
 }
 
+async function driveSessionStillPending(settled: Promise<unknown>): Promise<boolean> {
+  let pending = true;
+  void settled.then(
+    () => { pending = false; },
+    () => { pending = false; },
+  );
+  await Promise.resolve();
+  return pending;
+}
+
 export interface VnextRuntimeSupervisor {
   server: Server;
   port: number;
@@ -446,7 +456,9 @@ async function startVnextRuntimeSupervisorInner(
           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 !== undefined ? { drive } : {}) });
             return;
           }
           if (request.method === "POST" && sub === "drive") {
@@ -684,6 +696,15 @@ async function startVnextRuntimeSupervisorInner(
       }
     }
     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<void>((resolveStop) => server.close(() => resolveStop()));