@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/runtime/channel-retry-sweep.ts

@@ -547,6 +547,7 @@ export async function sweepFailedEvents(
       },
       assistantId,
       trustContext,
+      author: trustContext,
       isInteractive:
         resolveRoutingStateFromRuntime(trustContext).promptWaitingAllowed,
       onEvent: observeAgentEvent,

package/src/runtime/guardian-action-message-composer.ts

@@ -1,182 +1,29 @@
 /**
- * Layered guardian action message composition system.
+ * Guardian action message composition.
  *
- * Generates user-visible copy for guardian action scenarios through a
- * priority chain:
- *   1. Generator-produced text (when provided by daemon)
- *   2. Deterministic fallback templates (natural, scenario-specific messages)
- *
- * Follows the same pattern as approval-message-composer.ts.
+ * Returns the deterministic, voice-friendly copy for a guardian action
+ * notice. The only notice left is the one the expiry sweep
+ * (`calls/guardian-action-sweep.ts`) sends to each place a guardian request
+ * was delivered once the request expires unanswered.
  */
-import type {
-  ComposeGuardianActionMessageOptions,
-  GuardianActionMessageContext,
-} from "./message-composer-types.js";
+import type { GuardianActionMessageContext } from "./message-composer-types.js";
 
 export type {
-  ComposeGuardianActionMessageOptions,
   GuardianActionMessageContext,
   GuardianActionMessageScenario,
 } from "./message-composer-types.js";
 
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Compose user-facing guardian action copy using the daemon-injected generator
- * when available, with deterministic fallback for reliability.
- *
- * The generator parameter is the daemon-provided function that knows about
- * providers. When absent (or in test env), only the deterministic fallback
- * is used.
- */
-export async function composeGuardianActionMessageGenerative(
-  context: GuardianActionMessageContext,
-  options: ComposeGuardianActionMessageOptions = {},
-): Promise<string> {
-  const fallbackText =
-    options.fallbackText?.trim() || getGuardianActionFallbackMessage(context);
-
-  if (process.env.NODE_ENV === "test") {
-    return fallbackText;
-  }
-
-  return fallbackText;
-}
-
-/** @internal Exported for use by the daemon-injected generator implementation. */
-export function includesRequiredKeywords(
-  text: string,
-  requiredKeywords: string[] | undefined,
-): boolean {
-  if (!requiredKeywords || requiredKeywords.length === 0) {
-    return true;
-  }
-  return requiredKeywords.every((keyword) => {
-    const re = new RegExp(`\\b${RegExp.escape(keyword)}\\b`, "i");
-    return re.test(text);
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Deterministic fallback templates
-// ---------------------------------------------------------------------------
-
-/**
- * Return a scenario-specific deterministic fallback message.
- *
- * Each template produces natural, conversational text suitable for voice
- * delivery.
- */
-export function getGuardianActionFallbackMessage(
+/** Compose the user-facing copy for a guardian action notice. */
+export function composeGuardianActionMessage(
   context: GuardianActionMessageContext,
 ): string {
-  const listedCodes = formatGuardianRequestCodes(context.requestCodes);
-
   switch (context.scenario) {
-    case "caller_timeout_acknowledgment":
-      return context.guardianIdentifier
-        ? `I wasn't able to reach ${context.guardianIdentifier} right now. I'm sorry about that.`
-        : "I wasn't able to reach the guardian right now. I'm sorry about that.";
-
-    case "caller_timeout_continue":
-      return "Would you like me to leave a message for them to get back to you, or is there anything else I can help with?";
-
-    case "guardian_late_answer_followup":
-      return context.callerIdentifier
-        ? `${context.callerIdentifier} called earlier with a question, but I wasn't able to connect them. Would you like to call them back?`
-        : "Someone called earlier with a question, but I wasn't able to connect them. Would you like to call them back?";
-
-    case "guardian_followup_dispatching":
-      return context.followupAction
-        ? `Got it, I'll ${context.followupAction} now.`
-        : "Got it, I'm taking care of that now.";
-
-    case "guardian_followup_completed":
-      return context.followupAction
-        ? `Done! I've ${context.followupAction} successfully.`
-        : "Done! That's been taken care of.";
-
-    case "guardian_followup_failed":
-      return context.failureReason
-        ? `I'm sorry, I wasn't able to complete that. ${context.failureReason}`
-        : "I'm sorry, I wasn't able to complete that. Please try again later.";
-
-    case "guardian_followup_declined_ack":
-      return "No problem. Let me know if you change your mind or need anything else.";
-
-    case "guardian_followup_clarification":
-      return "Sorry, I didn't quite catch that. Would you like to call them back or skip it for now?";
-
-    case "guardian_pending_disambiguation":
-      return listedCodes
-        ? `You have multiple pending guardian questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're answering.`
-        : "You have multiple pending guardian questions. Please prefix your reply with the reference code so I know which question you're answering.";
-
-    case "guardian_expired_disambiguation":
-      return listedCodes
-        ? `You have multiple expired guardian questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're answering.`
-        : "You have multiple expired guardian questions. Please prefix your reply with the reference code so I know which question you're answering.";
-
-    case "guardian_followup_disambiguation":
-      return listedCodes
-        ? `You have multiple pending follow-up questions. Please prefix your reply with the reference code (${listedCodes}) so I know which question you're responding to.`
-        : "You have multiple pending follow-up questions. Please prefix your reply with the reference code so I know which question you're responding to.";
-
-    case "guardian_stale_answered":
-      return "This question has already been answered from another channel.";
-
     case "guardian_stale_expired":
       return "That request has already expired. No further action is needed.";
 
-    case "guardian_stale_followup":
-      return "It looks like this follow-up has already been handled. No further action is needed.";
-
-    case "guardian_stale_superseded":
-      return "This request is no longer active. The call has ended and no further action is needed.";
-
-    case "guardian_unknown_code":
-      return context.unknownCode
-        ? `I don't recognize the code "${context.unknownCode}". Please check the reference code and try again.`
-        : "I don't recognize that reference code. Please check the code and try again.";
-
-    case "guardian_auto_matched":
-      return "Got it, routing your answer to the active request.";
-
-    case "guardian_superseded_remap":
-      return context.questionText
-        ? `Got it! Your answer has been applied to the current active request: "${context.questionText}"`
-        : "Got it! Your answer has been applied to the current active request on the call.";
-
-    case "followup_call_started":
-      return context.counterpartyPhone
-        ? `Got it! I'm calling ${context.counterpartyPhone} back now to relay your answer.`
-        : "Got it! I'm calling them back now to relay your answer.";
-
-    case "followup_action_failed":
-      return context.failureReason
-        ? `I'm sorry, I wasn't able to complete that. ${context.failureReason}`
-        : "I'm sorry, something went wrong and I couldn't complete that action. Please try again later.";
-
-    case "guardian_answer_delivery_failed":
-      return "I wasn't able to deliver your answer to the call. The call may have ended. Please try again or follow up directly.";
-
     default: {
       const _exhaustive: never = context.scenario;
       return `Guardian action update. ${String(_exhaustive)}`;
     }
   }
 }
-
-function formatGuardianRequestCodes(
-  requestCodes: string[] | undefined,
-): string {
-  if (!Array.isArray(requestCodes)) {
-    return "";
-  }
-  const cleaned = requestCodes
-    .map((code) => code.trim())
-    .filter((code) => code.length > 0);
-  return cleaned.join(", ");
-}

package/src/runtime/guardian-action-service.ts

@@ -16,21 +16,6 @@ import {
   isApprovalAction,
 } from "./channel-approval-types.js";
 
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/**
- * Legacy actions that map to canonical ones during client rollout.
- * All temporal/persistent approval variants collapse to approve_once.
- * Keep until all clients are updated and no in-flight buttons remain.
- */
-const LEGACY_ACTION_MAP: Record<string, string> = {
-  approve_10m: "approve_once",
-  approve_conversation: "approve_once",
-  approve_always: "approve_once",
-};
-
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -98,8 +83,8 @@ export async function processGuardianDecision(
 ): Promise<ProcessGuardianDecisionResult> {
   const { requestId, conversationId, channel, actorContext } = params;
 
-  // 1. Canonicalize legacy actions, then validate
-  const action = LEGACY_ACTION_MAP[params.action] ?? params.action;
+  // 1. Validate the action
+  const action = params.action;
   if (!isApprovalAction(action)) {
     return {
       ok: false,

package/src/runtime/guardian-reply-router.ts

@@ -1,13 +1,24 @@
 /**
- * Shared guardian reply router for inbound channel messages.
+ * Shared guardian reply router.
  *
- * Provides a single entry point (`routeGuardianReply`) for all inbound
- * guardian reply processing across Telegram and WhatsApp. Routes
+ * Provides a single entry point (`routeGuardianReply`) for every guardian
+ * reply typed in the app (`daemon/conversation-process.ts`,
+ * `routes/conversation-routes.ts`) and every reply or button press arriving
+ * on a channel (`routes/inbound-stages/guardian-reply-intercept.ts`). App
+ * card buttons decide through `processGuardianDecision()` instead. Routes
  * through a priority-ordered pipeline:
  *
- *   1. Deterministic callback/ref parsing (button presses with `apr:<requestId>:<action>`)
+ *   1. Deterministic callback/ref parsing (channel button presses with `apr:<requestId>:<action>`)
  *   2. Request code parsing (6-char alphanumeric prefix matching)
- *   3. NL classification via the conversational approval engine
+ *   2.5. Invite handoff: "open invite flow" with a pending access request
+ *        passes through to the normal assistant turn
+ *   2.55. Bare-text answer to the single pending question, in the
+ *        conversation it was asked in
+ *   2.6. Explicit approve/reject phrase: applied when exactly one request is
+ *        pending, answered with a disambiguation reply when several are
+ *   3. NL classification via the conversational approval engine, only when
+ *      the caller passes an `approvalConversationGenerator` (app sessions do
+ *      not, so for them 2.6 is the last plain-text stage)
  *
  * All decisions flow through `applyGuardianDecision`, which handles identity
  * validation, expiry checks, the atomic gateway CAS+outcome commit,
@@ -153,12 +164,6 @@ export interface GuardianReplyResult {
 // Callback data parser — format: "apr:<requestId>:<action>"
 // ---------------------------------------------------------------------------
 
-const LEGACY_CALLBACK_MAP: Record<string, string> = {
-  approve_10m: "approve_once",
-  approve_conversation: "approve_once",
-  approve_always: "approve_once",
-};
-
 interface ParsedCallback {
   requestId: string;
   action: ApprovalAction;
@@ -170,8 +175,7 @@ function parseCallbackAction(data: string): ParsedCallback | null {
     return null;
   }
   const requestId = parts[1];
-  const rawAction = parts.slice(2).join(":");
-  const action = LEGACY_CALLBACK_MAP[rawAction] ?? rawAction;
+  const action = parts.slice(2).join(":");
   if (!requestId || !isApprovalAction(action)) {
     return null;
   }
@@ -324,17 +328,8 @@ function notConsumed(): GuardianReplyResult {
 // ---------------------------------------------------------------------------
 
 /**
- * Route an inbound guardian reply through the guardian decision pipeline.
- *
- * This is the single entry point for all inbound guardian reply processing.
- * It handles messages from any channel (Telegram, WhatsApp) and
- * routes through priority-ordered matching:
- *
- *   1. Deterministic callback parsing (button presses)
- *   2. Request code parsing (6-char alphanumeric prefix)
- *   3. NL classification via the conversational approval engine
- *
- * All decisions flow through `applyGuardianDecision`.
+ * Route a guardian reply through the priority-ordered pipeline described in
+ * the file header. All decisions flow through `applyGuardianDecision`.
  */
 export async function routeGuardianReply(
   ctx: GuardianReplyContext,
@@ -395,7 +390,7 @@ export async function routeGuardianReply(
       const request = await getGuardianRequestOrNull(answerTap.requestId);
       if (
         request &&
-        resolveRequestInstructionMode(request) === "answer" &&
+        resolveGuardianInstructionModeForRequest(request) === "answer" &&
         parseQuestionAnswerActionId(answerTap.token) &&
         !request.callSessionId &&
         hasLiveQuestionInteraction(request.id)
@@ -588,7 +583,7 @@ export async function routeGuardianReply(
   if (messageText.length > 0 && pendingRequests.length === 1) {
     const soleRequest = pendingRequests[0];
     if (
-      resolveRequestInstructionMode(soleRequest) === "answer" &&
+      resolveGuardianInstructionModeForRequest(soleRequest) === "answer" &&
       !soleRequest.callSessionId &&
       soleRequest.sourceConversationId === conversationId &&
       hasLiveQuestionInteraction(soleRequest.id)
@@ -670,11 +665,11 @@ export async function routeGuardianReply(
     );
 
     if (engineResult.disposition === "keep_pending") {
-      // When the engine returns keep_pending with multiple pending requests,
-      // this likely means the NL classification understood a decision intent
-      // but runApprovalConversationTurn fail-closed because no targetRequestId
-      // was provided. In this case, produce a disambiguation reply instead of
-      // a generic "I couldn't process that" message.
+      // keep_pending covers model indecision and every fail-closed path in
+      // runApprovalConversationTurn (generator error, malformed output, a
+      // decision without the targetRequestId that multi-pending requires).
+      // With several requests pending, answer with a disambiguation reply
+      // instead of a generic "I couldn't process that" message.
       if (pendingRequestsForClassification.length > 1) {
         log.info(
           {
@@ -1012,12 +1007,6 @@ function inferActionFromText(
   return "approve_once";
 }
 
-function resolveRequestInstructionMode(
-  request?: Pick<GuardianRequestWire, "kind" | "toolName"> | null,
-): "approval" | "answer" {
-  return resolveGuardianInstructionModeForRequest(request);
-}
-
 // ---------------------------------------------------------------------------
 // Failure reason reply text
 // ---------------------------------------------------------------------------
@@ -1051,7 +1040,7 @@ function failureReplyText(
       return "Something went wrong with this request on our end, so I couldn't apply your decision.";
     case "invalid_action":
       return buildGuardianInvalidActionReply(
-        resolveRequestInstructionMode(request),
+        resolveGuardianInstructionModeForRequest(request),
         requestCode ?? undefined,
       );
     default:
@@ -1070,7 +1059,7 @@ function failureReplyText(
  */
 function composeCodeOnlyClarification(request: GuardianRequestWire): string {
   const code = request.requestCode ?? "unknown";
-  const mode = resolveRequestInstructionMode(request);
+  const mode = resolveGuardianInstructionModeForRequest(request);
   return buildGuardianCodeOnlyClarification(mode, {
     requestCode: code,
     questionText: request.questionText,
@@ -1094,7 +1083,7 @@ function composeDisambiguationReply(
   const lines: string[] = [];
   const requestsWithMode = pendingRequests.map((request) => ({
     request,
-    mode: resolveRequestInstructionMode(request),
+    mode: resolveGuardianInstructionModeForRequest(request),
   }));
 
   if (engineReplyText) {

package/src/runtime/http-server.ts

@@ -254,9 +254,9 @@ type AllWebSocketData =
 
 function virtualDesktopEnabled(): boolean {
   try {
-    return isVirtualDesktopEnabled(getConfig());
+    return isVirtualDesktopEnabled();
   } catch (err) {
-    log.warn({ err }, "Failed to read config for desktop stream gate");
+    log.warn({ err }, "Failed to check desktop stream gate");
     return false;
   }
 }

package/src/runtime/http-types.ts

@@ -70,6 +70,12 @@ export interface RuntimeMessageConversationOptions {
   };
   assistantId?: string;
   trustContext?: TrustContext;
+  /**
+   * The person whose own inbound message this turn persists. Channel ingress
+   * and its retry replay pass the sender's trust; it names the persisted user
+   * row's author (`PersistMessageOptions.author`).
+   */
+  author?: TrustContext;
   /**
    * Whether this turn should permit interactive approval prompts.
    * Channel ingress sets this true so confirmations can be resolved

package/src/runtime/message-composer-types.ts

@@ -13,36 +13,18 @@ export type ApprovalMessageScenario =
   | "standard_prompt"
   | "guardian_prompt"
   | "reminder_prompt"
-  | "guardian_delivery_failed"
-  | "guardian_request_forwarded"
-  | "guardian_disambiguation"
   | "guardian_identity_mismatch"
   | "request_pending_guardian"
-  | "guardian_decision_outcome"
-  | "guardian_expired_requester"
-  | "guardian_expired_guardian"
-  | "guardian_verify_success"
   | "guardian_verify_failed"
   | "guardian_verify_challenge_setup"
-  | "guardian_verify_status_bound"
-  | "guardian_verify_status_unbound"
-  | "guardian_deny_no_identity"
-  | "guardian_deny_no_binding"
-  | "requester_cancel"
-  | "approval_already_resolved"
-  | "guardian_text_unavailable";
+  | "approval_already_resolved";
 
 export interface ApprovalMessageContext {
   scenario: ApprovalMessageScenario;
   channel?: string;
   toolName?: string;
   requesterIdentifier?: string;
-  guardianIdentifier?: string;
-  pendingCount?: number;
-  decision?: "approved" | "denied";
   richUi?: boolean;
-  /** Pre-existing assistant text to reuse (macOS parity). */
-  assistantPreface?: string;
   verifyCommand?: string;
   ttlSeconds?: number;
   failureReason?: string;
@@ -77,49 +59,9 @@ export type ApprovalCopyGenerator = (
 // Guardian action message types
 // ---------------------------------------------------------------------------
 
-export type GuardianActionMessageScenario =
-  | "caller_timeout_acknowledgment"
-  | "caller_timeout_continue"
-  | "guardian_late_answer_followup"
-  | "guardian_followup_dispatching"
-  | "guardian_followup_completed"
-  | "guardian_followup_failed"
-  | "guardian_followup_declined_ack"
-  | "guardian_followup_clarification"
-  | "guardian_pending_disambiguation"
-  | "guardian_expired_disambiguation"
-  | "guardian_followup_disambiguation"
-  | "guardian_stale_answered"
-  | "guardian_stale_expired"
-  | "guardian_stale_followup"
-  | "guardian_stale_superseded"
-  | "guardian_superseded_remap"
-  | "guardian_unknown_code"
-  | "guardian_auto_matched"
-  | "followup_call_started"
-  | "followup_action_failed"
-  | "guardian_answer_delivery_failed";
+/** The one guardian-action notice still sent: a request expired unanswered. */
+export type GuardianActionMessageScenario = "guardian_stale_expired";
 
 export interface GuardianActionMessageContext {
   scenario: GuardianActionMessageScenario;
-  channel?: string;
-  questionText?: string;
-  callerIdentifier?: string;
-  guardianIdentifier?: string;
-  lateAnswerText?: string;
-  followupAction?: string;
-  failureReason?: string;
-  counterpartyPhone?: string;
-  requestCodes?: string[];
-  /** The code the guardian provided that was not recognized. */
-  unknownCode?: string;
-  /** The code of the active request that supersedes the one the guardian targeted. */
-  activeRequestCode?: string;
-}
-
-export interface ComposeGuardianActionMessageOptions {
-  fallbackText?: string;
-  requiredKeywords?: string[];
-  maxTokens?: number;
-  timeoutMs?: number;
 }

package/src/runtime/migrations/__tests__/vbundle-import-parity.test.ts

@@ -33,7 +33,10 @@ import { Readable } from "node:stream";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import { buildVBundle } from "../vbundle-builder.js";
-import { DefaultPathResolver } from "../vbundle-import-analyzer.js";
+import {
+  analyzeImport,
+  DefaultPathResolver,
+} from "../vbundle-import-analyzer.js";
 import { commitImport } from "../vbundle-importer.js";
 import { streamCommitImport } from "../vbundle-streaming-importer.js";
 import { defaultV1Options } from "./v1-test-helpers.js";
@@ -416,4 +419,67 @@ describe("vbundle import parity (buffer vs streaming)", () => {
     expect(bufferMap.has("marker.txt")).toBe(true);
     expect(streamMap.has("marker.txt")).toBe(true);
   });
+
+  test("F — debug-profile gateway entry: both importers drain it and write nothing", async () => {
+    const configJson = JSON.stringify({ version: 1 });
+    const { archive, manifest } = buildVBundle({
+      files: [
+        { path: "workspace/data/db/assistant.db", data: new Uint8Array(8) },
+        {
+          path: "workspace/config.json",
+          data: new TextEncoder().encode(configJson),
+        },
+        {
+          path: "gateway/export.tar.gz",
+          data: new TextEncoder().encode("not-a-real-tarball"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    // Preflight must not block on the gateway entry, or the CLI would
+    // refuse the restore before either importer runs.
+    const preflight = analyzeImport({
+      manifest,
+      pathResolver: new DefaultPathResolver(bufferWs),
+    });
+    expect(preflight.can_import).toBe(true);
+    expect(preflight.conflicts).toEqual([]);
+
+    mkdirSync(bufferWs, { recursive: true });
+    mkdirSync(streamWs, { recursive: true });
+
+    const bufferResult = commitImport({
+      archiveData: archive,
+      pathResolver: new DefaultPathResolver(bufferWs),
+      workspaceDir: bufferWs,
+    });
+    const streamResult = await streamCommitImport({
+      source: Readable.from([Buffer.from(archive)]),
+      pathResolver: new DefaultPathResolver(streamWs),
+      workspaceDir: streamWs,
+    });
+    if (!bufferResult.ok || !streamResult.ok) {
+      throw new Error("import unexpectedly failed");
+    }
+
+    const bufferMap = walkDiskTree(bufferWs);
+    const streamMap = walkDiskTree(streamWs);
+
+    expect(streamMap).toEqual(bufferMap);
+    expect(bufferMap.has("config.json")).toBe(true);
+    expect(bufferMap.has("data/db/assistant.db")).toBe(true);
+    for (const relPath of bufferMap.keys()) {
+      expect(relPath.startsWith("gateway")).toBe(false);
+    }
+    // Skipped silently, like a retired path: counted, but no
+    // "no known disk target" warning.
+    for (const { report } of [bufferResult, streamResult]) {
+      expect(report.warnings).toEqual([]);
+      const gateway = report.files.find(
+        (f) => f.path === "gateway/export.tar.gz",
+      );
+      expect(gateway?.action).toBe("skipped");
+    }
+  });
 });

package/src/runtime/migrations/__tests__/vbundle-import-policy.test.ts

@@ -15,6 +15,7 @@ import {
   isConfigArchivePath,
   isCredentialMetadataArchivePath,
   isLegacyPersonaArchivePath,
+  isLocalDevRuntimeVersion,
   isWorkspaceNamespacedArchivePath,
   LEGACY_USER_MD_ARCHIVE_PATH,
   partitionWorkspacePreserveSkipDirs,
@@ -257,4 +258,92 @@ describe("evaluateRuntimeCompatibility", () => {
       ),
     ).toEqual({ ok: true });
   });
+
+  // A `vel up` minikube assistant image is stamped
+  // `<pkg.version>-local.<ts>.<sha>` from the checkout's package.json,
+  // which only moves on release cuts, so the minimum bound cannot be
+  // decided from it; the explicit maximum ceiling still applies.
+  test("local dev runtime build skips the minimum bound", () => {
+    expect(
+      evaluateRuntimeCompatibility(
+        { min_runtime_version: "0.12.2-staging.4", max_runtime_version: null },
+        "0.12.1-local.20260916144827.2f409056e6",
+      ),
+    ).toEqual({ ok: true });
+  });
+
+  test("local dev runtime build within an explicit range passes", () => {
+    expect(
+      evaluateRuntimeCompatibility(
+        { min_runtime_version: "0.12.2", max_runtime_version: "0.12.5" },
+        "0.12.1-local.20260916144827.2f409056e6",
+      ),
+    ).toEqual({ ok: true });
+  });
+
+  test("local dev runtime build above max still fails", () => {
+    const compat = {
+      min_runtime_version: "0.7.0",
+      max_runtime_version: "0.7.5",
+    };
+    const runtime = "0.12.1-local.20260916144827.2f409056e6";
+    expect(evaluateRuntimeCompatibility(compat, runtime)).toEqual({
+      ok: false,
+      reason: "version_incompatible",
+      bundle_compat: compat,
+      runtime_version: runtime,
+    });
+  });
+
+  test("local dev runtime build with unparsable max fails open", () => {
+    expect(
+      evaluateRuntimeCompatibility(
+        { min_runtime_version: "0.7.0", max_runtime_version: "garbage" },
+        "0.12.1-local.20260916144827.2f409056e6",
+      ),
+    ).toEqual({ ok: true });
+  });
+
+  test("other prerelease builds are still gated", () => {
+    const compat = {
+      min_runtime_version: "0.12.2-staging.4",
+      max_runtime_version: null,
+    };
+    for (const runtime of [
+      "0.12.1-dev.202609151913.a151da3",
+      "0.12.1-staging.9",
+      "0.12.1",
+    ]) {
+      expect(evaluateRuntimeCompatibility(compat, runtime)).toEqual({
+        ok: false,
+        reason: "version_incompatible",
+        bundle_compat: compat,
+        runtime_version: runtime,
+      });
+    }
+  });
+});
+
+describe("isLocalDevRuntimeVersion", () => {
+  test("matches the local hatch / minikube version stamp", () => {
+    expect(
+      isLocalDevRuntimeVersion("0.12.1-local.20260916144827.2f409056e6"),
+    ).toBe(true);
+    expect(isLocalDevRuntimeVersion("0.0.0-local.1789584535000")).toBe(true);
+  });
+
+  test("rejects release, dev and staging builds and lookalikes", () => {
+    for (const version of [
+      "0.12.1",
+      "0.12.1-dev.202609151913.a151da3",
+      "0.12.2-staging.4",
+      "0.0.0-dev",
+      "0.0.0-legacy",
+      "0.12.1-localhost.1",
+      "local.0.12.1",
+      "",
+    ]) {
+      expect(isLocalDevRuntimeVersion(version)).toBe(false);
+    }
+  });
 });