@evident-ai/runner-cdk 3.4.1-dev.59c7df3 → 3.4.1-dev.7e9dfeb

package/README.md

@@ -165,6 +165,7 @@ and the agent installs on first use.
 | `runnerSecret` | No GitHub or MCP credentials are exported at `/run`. When supplied, `/run` reads the JSON secret and exports every non-empty value whose key is a valid environment-variable name. |
 | `runnerOpencodeConfigPath` | OpenCode uses the baked project configuration. Relative paths resolve from the workspace; absolute paths resolve in the image. |
 | `gitUserName` / `gitUserEmail` | The hook uses the Evident bot defaults for git identity. |
+| `evidentApiUrl` / `evidentRunnerId` | No deploy-time report of the published image version — a byte-identical template to not having these props at all. Both non-secret (a URL, a public pool UUID) and both required together: set them if you have an Evident runner id configured for this provisioner, so each deploy that publishes a new image version tells Evident about it (a CloudFormation custom resource, HMAC-signed with `doorbellSecret`). A failure to report never fails your deploy — it warns and Evident reads that provisioner as *unknown*, never as up to date or stale. |
 
 ## Status / limitations
 

package/dist/controller-lambda/handler.js

@@ -49854,7 +49854,8 @@ function parseDoorbell(rawBody) {
     occurred_at: occurredAt,
     microvm_id: microvmId,
     run_payload: runPayload,
-    shape
+    shape,
+    recreate_on_outdated_image: recreateOnOutdatedImage
   } = body;
   if (type !== SUSPEND_EVENT_TYPE && type !== SHAPES_EVENT_TYPE && !isWakeType(type)) {
     return { ok: false, reason: DOORBELL_REJECTION.unsupportedType };
@@ -49885,10 +49886,14 @@ function parseDoorbell(rawBody) {
   if (Buffer.byteLength(runHookPayload, "utf8") > RUN_HOOK_PAYLOAD_MAX_BYTES) {
     return { ok: false, reason: DOORBELL_REJECTION.runPayloadTooLarge };
   }
-  return {
-    ok: true,
-    doorbell: shape === void 0 ? { ...fields, type, runHookPayload } : { ...fields, type, shape, runHookPayload }
-  };
+  const doorbell = { ...fields, type, runHookPayload };
+  if (shape !== void 0) {
+    doorbell.shape = shape;
+  }
+  if (recreateOnOutdatedImage === true) {
+    doorbell.recreateOnOutdatedImage = true;
+  }
+  return { ok: true, doorbell };
 }
 
 // src/microvm/controller/throttle-retry.ts
@@ -49949,6 +49954,7 @@ function decide({
   runnerId,
   microvmId,
   startedAt,
+  imageVersion,
   shapes,
   polled
 }) {
@@ -49966,6 +49972,7 @@ function decide({
       reason,
       ...microvmId === void 0 ? {} : { microvm_id: microvmId },
       ...startedAt === void 0 ? {} : { microvm_started_at: startedAt.toISOString() },
+      ...imageVersion === void 0 ? {} : { image_version: imageVersion },
       ...shapes === void 0 ? {} : { shapes },
       ...polled === true ? { polled: true } : {}
     }),
@@ -50122,10 +50129,11 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         runnerId: doorbell.runnerId,
         microvmId: doorbell.microvmId,
         polled,
-        startedAt: described.startedAt
+        startedAt: described.startedAt,
+        imageVersion: described.imageVersion
       });
     case "SUSPENDED":
-      if (await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
+      if (doorbell.recreateOnOutdatedImage === true && await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
         return runMicrovm(
           doorbell,
           shape,
@@ -50143,7 +50151,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         microvm,
         timing,
         polled,
-        described.startedAt
+        described.startedAt,
+        described.imageVersion
       );
     default:
       return runMicrovm(
@@ -50220,10 +50229,11 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
     runnerId: doorbell.runnerId,
     microvmId: started.microvmId,
     polled,
-    startedAt: started.startedAt
+    startedAt: started.startedAt,
+    imageVersion: started.imageVersion
   });
 }
-async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, startedAt) {
+async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, startedAt, imageVersion) {
   try {
     await withThrottleRetry(() => microvm.resume(microvmId), timing);
   } catch (error3) {
@@ -50248,7 +50258,8 @@ async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled
     runnerId: doorbell.runnerId,
     microvmId,
     polled,
-    startedAt
+    startedAt,
+    imageVersion
   });
 }
 async function suspendMicrovm(doorbell, microvm, timing) {
@@ -50443,7 +50454,7 @@ function createRuntimeMicrovm(executionRoleArn) {
       return latestActiveImageVersion;
     },
     async run({ imageIdentifier, runHookPayload, clientToken }) {
-      const { microvmId, startedAt } = await microvms.send(
+      const { microvmId, startedAt, imageVersion } = await microvms.send(
         new import_client_lambda_microvms.RunMicrovmCommand({
           imageIdentifier,
           executionRoleArn,
@@ -50476,7 +50487,7 @@ function createRuntimeMicrovm(executionRoleArn) {
       if (!microvmId) {
         throw new Error("RunMicrovm returned no microvmId");
       }
-      return { microvmId, startedAt };
+      return { microvmId, startedAt, imageVersion };
     },
     async resume(microvmId) {
       await microvms.send(new import_client_lambda_microvms.ResumeMicrovmCommand({ microvmIdentifier: microvmId }));

package/dist/image-version-reporter-lambda/handler.js

@@ -0,0 +1,129 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/microvm/image-version-reporter/handler.ts
+var handler_exports = {};
+__export(handler_exports, {
+  handleImageVersionReport: () => handleImageVersionReport,
+  handler: () => handler
+});
+module.exports = __toCommonJS(handler_exports);
+var import_node_crypto = require("node:crypto");
+var import_client_secrets_manager = require("@aws-sdk/client-secrets-manager");
+var PHYSICAL_RESOURCE_ID = "evident-image-version-report";
+var REPORT_TIMEOUT_MS = 5e3;
+var secrets = new import_client_secrets_manager.SecretsManagerClient({});
+async function fetchDoorbellSecret(secretArn, secretKey) {
+  const { SecretString } = await secrets.send(new import_client_secrets_manager.GetSecretValueCommand({ SecretId: secretArn }));
+  if (!SecretString) {
+    throw new Error(`doorbell secret ${secretArn} has no SecretString`);
+  }
+  const parsed = JSON.parse(SecretString);
+  const value = parsed !== null && typeof parsed === "object" ? parsed[secretKey] : void 0;
+  if (typeof value !== "string" || value === "") {
+    throw new Error(`doorbell secret ${secretArn} is missing a non-empty '${secretKey}' field`);
+  }
+  return value;
+}
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`missing required env var ${name}`);
+  }
+  return value;
+}
+function readImageVersions(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("imageVersions must be an object");
+  }
+  return Object.entries(value).map(([shape, imageVersion]) => {
+    if (typeof imageVersion !== "string") {
+      throw new Error(`imageVersions.${shape} must be a string`);
+    }
+    return { shape, image_version: imageVersion };
+  });
+}
+function response() {
+  return { PhysicalResourceId: PHYSICAL_RESOURCE_ID };
+}
+var runtimeDependencies = {
+  getSecret: fetchDoorbellSecret,
+  fetch: globalThis.fetch
+};
+async function handleImageVersionReport(event, getConfig, dependencies = runtimeDependencies) {
+  if (event.RequestType === "Delete") {
+    return response();
+  }
+  let runnerId = "unknown";
+  let versions = [];
+  let responseStatus;
+  try {
+    versions = readImageVersions(event.ResourceProperties?.imageVersions);
+    const config = getConfig();
+    runnerId = config.evidentRunnerId;
+    const secret = await dependencies.getSecret(config.doorbellSecretArn, config.doorbellSecretKey);
+    const body = JSON.stringify({
+      type: "runner.microvm_image_versions_reported",
+      versions
+    });
+    const signature = (0, import_node_crypto.createHmac)("sha256", secret).update(body).digest("hex");
+    const url = `${config.evidentApiUrl.replace(/\/+$/, "")}/v1/runners/${encodeURIComponent(
+      runnerId
+    )}/microvm-image-versions`;
+    const result = await dependencies.fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-evident-signature": signature
+      },
+      body,
+      signal: AbortSignal.timeout(REPORT_TIMEOUT_MS)
+    });
+    responseStatus = result.status;
+    console.log("runner.microvm_image_versions_reported", {
+      runnerId,
+      versions,
+      status: result.status
+    });
+    if (!result.ok) {
+      throw new Error(`Evident returned HTTP ${result.status}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn("MicroVM image version report failed", {
+      operation: event.RequestType,
+      runnerId,
+      versions,
+      ...responseStatus === void 0 ? {} : { status: responseStatus },
+      error: message
+    });
+  }
+  return response();
+}
+var handler = (event) => handleImageVersionReport(event, () => ({
+  doorbellSecretArn: requireEnv("DOORBELL_SECRET_ARN"),
+  doorbellSecretKey: requireEnv("DOORBELL_SECRET_KEY"),
+  evidentApiUrl: requireEnv("EVIDENT_API_URL"),
+  evidentRunnerId: requireEnv("EVIDENT_RUNNER_ID")
+}));
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  handleImageVersionReport,
+  handler
+});

package/dist/microvm/construct.d.ts

@@ -69,6 +69,24 @@ export interface EvidentMicrovmConstructProps {
      * running a hook).
      */
     readonly hookTimeoutSeconds: number;
+    /**
+     * Base URL of Evident's own API. Together with `evidentRunnerId`, opts this
+     * deploy into reporting each shape's published image version to Evident
+     * (#1903) — a CDK custom resource, triggered only when a deploy actually
+     * changes a version. Omitting BOTH leaves the template byte-for-byte
+     * identical to not having this prop at all: an adopter with no Evident
+     * runner id configured has nothing to report against. Supplying only one
+     * throws at synth — see `evidentRunnerId`.
+     */
+    readonly evidentApiUrl?: string;
+    /**
+     * The pool runner id (public, non-secret UUID) to report against — see
+     * `evidentApiUrl`. Mirrors `EvidentScaleToZeroConstructProps.evidentAgentId`'s
+     * "public (non-secret) Evident agent UUID" precedent. Must be supplied
+     * together with `evidentApiUrl`, or neither at all — supplying exactly one
+     * throws at construction rather than silently disabling the reporter.
+     */
+    readonly evidentRunnerId?: string;
 }
 /**
  * The customer-account half of the per-session runner (#558): the MicroVM

package/dist/microvm/construct.js

@@ -41,6 +41,7 @@ const lambda = __importStar(require("aws-cdk-lib/aws-lambda"));
 const s3 = __importStar(require("aws-cdk-lib/aws-s3"));
 const lambda_microvm_cdk_1 = require("@evident-ai/lambda-microvm-cdk");
 const shapes_1 = require("./shapes");
+const construct_1 = require("./image-version-reporter/construct");
 // Image hooks build the snapshot, so they get minutes where the runtime hooks
 // get AWS's 60 s.
 const IMAGE_HOOK_TIMEOUT_SECONDS = 600;
@@ -65,6 +66,15 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
         // Synth-time failure, before any construct exists.
         const shapes = (0, shapes_1.validateShapes)(props.shapes ?? shapes_1.MICROVM_SHAPES);
         const [defaultShape, ...additionalShapes] = shapes;
+        // D8's "both required together" is a synth-time contract, not just a
+        // README sentence: a caller supplying exactly one silently gets NO
+        // reporter and no warning (the `&&` check below just skips it), which
+        // reads as "configured" when it is not. Fail loudly instead.
+        if (Boolean(props.evidentApiUrl) !== Boolean(props.evidentRunnerId)) {
+            throw new Error('EvidentMicrovmConstruct: evidentApiUrl and evidentRunnerId must be supplied ' +
+                'together or not at all — supplying only one silently disables the image ' +
+                'version reporter rather than reporting a misconfiguration.');
+        }
         // The model credentials a runner restores at /run, and the litestream
         // session replica (it is `LITESTREAM_BUCKET` below), share one per-runner
         // prefix chosen at /run — synth can't name it, and lifecycle filters take
@@ -249,6 +259,22 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
             // HMAC verification of the doorbell body IS the auth, as for the ECS waker.
             authType: lambda.FunctionUrlAuthType.NONE,
         });
+        // Opt-in only (D8): both values present is what creates the reporter, so an
+        // adopter who supplies neither gets a template with no additional Lambda and
+        // no custom resource — this branch must not run for them.
+        if (props.evidentApiUrl && props.evidentRunnerId) {
+            new construct_1.ImageVersionReporter(this, 'ImageVersionReporter', {
+                doorbellSecret: props.doorbellSecret,
+                evidentApiUrl: props.evidentApiUrl,
+                evidentRunnerId: props.evidentRunnerId,
+                imageVersions: Object.fromEntries(shapes.map((shape) => [shape.name, images.get(shape.name).latestActiveImageVersion])),
+                // `buildInputs` already covers every property that can cause AWS
+                // to publish a new version for THIS shape's image (source, base
+                // image, memory, hooks, environment, description, build role —
+                // see its docstring); no additional encoding needed here.
+                buildTriggers: Object.fromEntries(shapes.map((shape) => [shape.name, images.get(shape.name).buildInputs])),
+            });
+        }
         this.functionUrl = functionUrl.url;
         this.shapeCatalogueJson = shapeCatalogueJson;
         this.durableStateBucket = durableState;

package/dist/microvm/controller/doorbell.d.ts

@@ -40,6 +40,11 @@ export type WakeDoorbell = DoorbellFields & {
      * shape" — the controller resolves it against the shape catalogue.
      */
     shape?: string;
+    /**
+     * Set only when the body carries the literal `true`. When absent, the
+     * suspended VM is always resumed because recreating it destroys its filesystem.
+     */
+    recreateOnOutdatedImage?: boolean;
 };
 export type Doorbell = WakeDoorbell | (DoorbellFields & {
     type: typeof SUSPEND_EVENT_TYPE;

package/dist/microvm/controller/doorbell.js

@@ -63,7 +63,7 @@ function parseDoorbell(rawBody) {
     if (typeof body !== 'object' || body === null || Array.isArray(body)) {
         return { ok: false, reason: exports.DOORBELL_REJECTION.invalidJson };
     }
-    const { type, runner_id: runnerId, occurred_at: occurredAt, microvm_id: microvmId, run_payload: runPayload, shape, } = body;
+    const { type, runner_id: runnerId, occurred_at: occurredAt, microvm_id: microvmId, run_payload: runPayload, shape, recreate_on_outdated_image: recreateOnOutdatedImage, } = body;
     if (type !== SUSPEND_EVENT_TYPE && type !== exports.SHAPES_EVENT_TYPE && !isWakeType(type)) {
         return { ok: false, reason: exports.DOORBELL_REJECTION.unsupportedType };
     }
@@ -95,13 +95,14 @@ function parseDoorbell(rawBody) {
     if (Buffer.byteLength(runHookPayload, 'utf8') > constants_1.RUN_HOOK_PAYLOAD_MAX_BYTES) {
         return { ok: false, reason: exports.DOORBELL_REJECTION.runPayloadTooLarge };
     }
-    // Omit `shape` entirely when absent, rather than setting it to `undefined`,
-    // so a body with no shape parses to exactly the same object as before this
-    // field existed.
-    return {
-        ok: true,
-        doorbell: shape === undefined
-            ? { ...fields, type, runHookPayload }
-            : { ...fields, type, shape, runHookPayload },
-    };
+    // Omit optional fields entirely when absent, rather than setting them to
+    // `undefined`, so older bodies keep the same parsed shape.
+    const doorbell = { ...fields, type, runHookPayload };
+    if (shape !== undefined) {
+        doorbell.shape = shape;
+    }
+    if (recreateOnOutdatedImage === true) {
+        doorbell.recreateOnOutdatedImage = true;
+    }
+    return { ok: true, doorbell };
 }

package/dist/microvm/controller/handle-doorbell.js

@@ -37,7 +37,7 @@ const LOG_ACTION = {
     rejected: 'reject',
     describe: 'describe',
 };
-function decide({ statusCode, action, reason, state, runnerId, microvmId, startedAt, shapes, polled, }) {
+function decide({ statusCode, action, reason, state, runnerId, microvmId, startedAt, imageVersion, shapes, polled, }) {
     const line = `[doorbell] state=${state ?? 'none'} action=${LOG_ACTION[action]} ` +
         `microvm_id=${microvmId ?? '-'} runner_id=${runnerId ?? '-'} reason=${reason}` +
         (polled === undefined ? '' : ` polled=${polled}`);
@@ -56,6 +56,7 @@ function decide({ statusCode, action, reason, state, runnerId, microvmId, starte
             reason,
             ...(microvmId === undefined ? {} : { microvm_id: microvmId }),
             ...(startedAt === undefined ? {} : { microvm_started_at: startedAt.toISOString() }),
+            ...(imageVersion === undefined ? {} : { image_version: imageVersion }),
             ...(shapes === undefined ? {} : { shapes }),
             ...(polled === true ? { polled: true } : {}),
         }),
@@ -128,9 +129,8 @@ function compareImageVersions(a, b) {
     return 0;
 }
 /**
- * Whether the SUSPENDED VM must be thrown away and recreated because a newer
- * image has been published since it booted — a resume would otherwise keep
- * that VM on its old baked-in hooks and repo checkout for up to 8 hours.
+ * Whether an opted-in doorbell should throw away and recreate the SUSPENDED VM
+ * because a newer image has been published since it booted.
  *
  * FAIL-SAFE, one direction only: recreating destroys the VM's filesystem
  * (only the credentials and `opencode.db` in the object store survive), so
@@ -283,16 +283,18 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
                 microvmId: doorbell.microvmId,
                 polled,
                 startedAt: described.startedAt,
+                imageVersion: described.imageVersion,
             });
         case 'SUSPENDED':
-            // A newer image has been published since this VM booted: resuming would
-            // keep it on the old baked-in hooks and repo checkout for up to 8 h, so
-            // take the same recreate path the arm below takes — which, passing no
-            // `imageVersion`, boots the latest (handler.ts's `run`).
-            if (await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
+            // False/absent disables silent automatic roll-forward; an explicit restart
+            // request (#1906) can still set the same wire flag. Recreate loses VM-local
+            // filesystem state; durable provider credentials survive in object storage,
+            // but a manual paste/upload not yet synced there may be lost (#2071).
+            if (doorbell.recreateOnOutdatedImage === true &&
+                (await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm))) {
                 return runMicrovm(doorbell, shape, microvm, timing, polled, REASON.imageVersionOutdated, state);
             }
-            return resumeMicrovm(doorbell, doorbell.microvmId, shape, microvm, timing, polled, described.startedAt);
+            return resumeMicrovm(doorbell, doorbell.microvmId, shape, microvm, timing, polled, described.startedAt, described.imageVersion);
         default:
             // TERMINATED, TERMINATING, not_found — gone or going, so a fresh VM either
             // way. This is what self-heals a stale `microvm_id`.
@@ -387,13 +389,13 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
         microvmId: started.microvmId,
         polled,
         startedAt: started.startedAt,
+        imageVersion: started.imageVersion,
     });
 }
 async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, 
-// Threaded in from the `describe()` result that led here — `ResumeMicrovm`
-// itself returns no `startedAt` (its response is empty), so this arm has no
-// timestamp of its own to report.
-startedAt) {
+// Both values come from the `describe()` result that led here because
+// `ResumeMicrovm` returns no lifecycle metadata of its own.
+startedAt, imageVersion) {
     try {
         await (0, throttle_retry_1.withThrottleRetry)(() => microvm.resume(microvmId), timing);
     }
@@ -411,6 +413,7 @@ startedAt) {
         microvmId,
         polled,
         startedAt,
+        imageVersion,
     });
 }
 async function suspendMicrovm(doorbell, microvm, timing) {

package/dist/microvm/controller/microvm-client.d.ts

@@ -69,6 +69,12 @@ export interface MicrovmClient {
          * none. Never synthesize one (e.g. `new Date()`) here or in any caller.
          */
         startedAt?: Date;
+        /**
+         * The image version this VM booted on, straight from `RunMicrovm`'s own
+         * `imageVersion`. Absent means AWS omitted it and must be read as UNKNOWN;
+         * see `MicrovmDescription.imageVersion` above.
+         */
+        imageVersion?: string;
     }>;
     resume(microvmId: string): Promise<void>;
     suspend(microvmId: string): Promise<void>;

package/dist/microvm/image-version-reporter/construct.d.ts

@@ -0,0 +1,35 @@
+import { Construct } from 'constructs';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import type { MicrovmImageBuildInputs } from '@evident-ai/lambda-microvm-cdk';
+export type ImageVersionReporterProps = {
+    /** The secret whose value is the same HMAC key the controller verifies every doorbell against. */
+    doorbellSecret: secretsmanager.ISecret;
+    /** Base URL of Evident's own API — non-secret. */
+    evidentApiUrl: string;
+    /** The pool runner id the report is filed against — non-secret, public UUID. */
+    evidentRunnerId: string;
+    /** Shape name -> the `Fn::GetAtt LatestActiveImageVersion` published this deploy. */
+    imageVersions: Record<string, string>;
+    /**
+     * Shape name -> {@link MicrovmImageBuildInputs}, a STRUCTURED object (never
+     * a delimiter-joined string — see its docstring for why flattening is
+     * unsafe) that changes whenever THIS deploy's build inputs change. Unlike
+     * `imageVersions`' `Fn::GetAtt` (a runtime attribute of the MicroVM image
+     * service, whose deploy-time propagation to a dependent resource this
+     * construct cannot itself guarantee), every field here is either a
+     * synth-time-computed literal or a plain `Ref`/`Fn::GetAtt` to a resource
+     * IN THIS STACK — CloudFormation diffs the full resolved property tree, so
+     * a change anywhere in this object is a certain, not merely likely,
+     * re-invocation trigger.
+     */
+    buildTriggers: Record<string, MicrovmImageBuildInputs>;
+};
+/**
+ * Deploy-time push: reports each shape's just-published MicroVM image version to
+ * Evident, once per deploy that actually changes it. `imageVersions` is the
+ * payload; `buildTriggers` is what guarantees re-invocation on exactly the
+ * deploy that matters, independent of `imageVersions`' own resolution timing.
+ */
+export declare class ImageVersionReporter extends Construct {
+    constructor(scope: Construct, id: string, props: ImageVersionReporterProps);
+}

package/dist/microvm/image-version-reporter/construct.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImageVersionReporter = void 0;
+const path = __importStar(require("path"));
+const cdk = __importStar(require("aws-cdk-lib"));
+const constructs_1 = require("constructs");
+const lambda = __importStar(require("aws-cdk-lib/aws-lambda"));
+const cr = __importStar(require("aws-cdk-lib/custom-resources"));
+/** The JSON field name inside the doorbell secret, same key the controller reads. */
+const DOORBELL_SECRET_KEY = 'DOORBELL_SECRET';
+/**
+ * Deploy-time push: reports each shape's just-published MicroVM image version to
+ * Evident, once per deploy that actually changes it. `imageVersions` is the
+ * payload; `buildTriggers` is what guarantees re-invocation on exactly the
+ * deploy that matters, independent of `imageVersions`' own resolution timing.
+ */
+class ImageVersionReporter extends constructs_1.Construct {
+    constructor(scope, id, props) {
+        super(scope, id);
+        const handler = new lambda.Function(this, 'Function', {
+            runtime: lambda.Runtime.NODEJS_22_X,
+            // Pre-bundled at PACKAGE build time, same reasoning as the waker's and the
+            // controller's own `Code.fromAsset` (see their comments) — resolved from
+            // the PACKAGE ROOT, two directories below this file either compiled
+            // (`dist/microvm/image-version-reporter`) or via ts-node
+            // (`src/microvm/image-version-reporter`).
+            code: lambda.Code.fromAsset(path.join(__dirname, '..', '..', '..', 'dist', 'image-version-reporter-lambda')),
+            handler: 'handler.handler',
+            memorySize: 128,
+            // A deploy hook must not hold CloudFormation for its default 1 h — this is
+            // the hard stop; the handler's own internal REPORT_TIMEOUT_MS is well under it.
+            timeout: cdk.Duration.seconds(30),
+            environment: {
+                // ARN + field name only, never the value (mirrors the controller and waker).
+                DOORBELL_SECRET_ARN: props.doorbellSecret.secretArn,
+                DOORBELL_SECRET_KEY: DOORBELL_SECRET_KEY,
+                EVIDENT_API_URL: props.evidentApiUrl,
+                EVIDENT_RUNNER_ID: props.evidentRunnerId,
+            },
+        });
+        props.doorbellSecret.grantRead(handler);
+        const provider = new cr.Provider(this, 'Provider', {
+            onEventHandler: handler,
+        });
+        new cdk.CustomResource(this, 'Resource', {
+            serviceToken: provider.serviceToken,
+            properties: {
+                imageVersions: props.imageVersions,
+                // Not read by the handler — its only job is to be a property value
+                // CloudFormation can see change (a structured object, so any field
+                // changing anywhere is a real property diff), so the resource is
+                // invoked on exactly the deploy that changes a build input.
+                buildTriggers: props.buildTriggers,
+            },
+        });
+    }
+}
+exports.ImageVersionReporter = ImageVersionReporter;

package/dist/microvm/image-version-reporter/handler.d.ts

@@ -0,0 +1,26 @@
+export type ImageVersionPair = {
+    shape: string;
+    image_version: string;
+};
+export type ReporterEvent = {
+    RequestType: 'Create' | 'Update' | 'Delete';
+    ResourceProperties?: {
+        imageVersions?: unknown;
+    };
+};
+export type ReporterConfig = {
+    doorbellSecretArn: string;
+    doorbellSecretKey: string;
+    evidentApiUrl: string;
+    evidentRunnerId: string;
+};
+type ReporterDependencies = {
+    getSecret: (secretArn: string, secretKey: string) => Promise<string>;
+    fetch: typeof fetch;
+};
+type ReporterResponse = {
+    PhysicalResourceId: string;
+};
+export declare function handleImageVersionReport(event: ReporterEvent, getConfig: () => ReporterConfig, dependencies?: ReporterDependencies): Promise<ReporterResponse>;
+export declare const handler: (event: ReporterEvent) => Promise<ReporterResponse>;
+export {};

package/dist/microvm/image-version-reporter/handler.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = void 0;
+exports.handleImageVersionReport = handleImageVersionReport;
+const node_crypto_1 = require("node:crypto");
+const client_secrets_manager_1 = require("@aws-sdk/client-secrets-manager");
+const PHYSICAL_RESOURCE_ID = 'evident-image-version-report';
+const REPORT_TIMEOUT_MS = 5_000;
+const secrets = new client_secrets_manager_1.SecretsManagerClient({});
+async function fetchDoorbellSecret(secretArn, secretKey) {
+    const { SecretString } = await secrets.send(new client_secrets_manager_1.GetSecretValueCommand({ SecretId: secretArn }));
+    if (!SecretString) {
+        throw new Error(`doorbell secret ${secretArn} has no SecretString`);
+    }
+    const parsed = JSON.parse(SecretString);
+    const value = parsed !== null && typeof parsed === 'object'
+        ? parsed[secretKey]
+        : undefined;
+    if (typeof value !== 'string' || value === '') {
+        throw new Error(`doorbell secret ${secretArn} is missing a non-empty '${secretKey}' field`);
+    }
+    return value;
+}
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`missing required env var ${name}`);
+    }
+    return value;
+}
+function readImageVersions(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('imageVersions must be an object');
+    }
+    return Object.entries(value).map(([shape, imageVersion]) => {
+        if (typeof imageVersion !== 'string') {
+            throw new Error(`imageVersions.${shape} must be a string`);
+        }
+        return { shape, image_version: imageVersion };
+    });
+}
+function response() {
+    return { PhysicalResourceId: PHYSICAL_RESOURCE_ID };
+}
+const runtimeDependencies = {
+    getSecret: fetchDoorbellSecret,
+    fetch: globalThis.fetch,
+};
+async function handleImageVersionReport(event, getConfig, dependencies = runtimeDependencies) {
+    if (event.RequestType === 'Delete') {
+        return response();
+    }
+    let runnerId = 'unknown';
+    let versions = [];
+    let responseStatus;
+    try {
+        versions = readImageVersions(event.ResourceProperties?.imageVersions);
+        const config = getConfig();
+        runnerId = config.evidentRunnerId;
+        const secret = await dependencies.getSecret(config.doorbellSecretArn, config.doorbellSecretKey);
+        const body = JSON.stringify({
+            type: 'runner.microvm_image_versions_reported',
+            versions,
+        });
+        const signature = (0, node_crypto_1.createHmac)('sha256', secret).update(body).digest('hex');
+        const url = `${config.evidentApiUrl.replace(/\/+$/, '')}/v1/runners/${encodeURIComponent(runnerId)}/microvm-image-versions`;
+        const result = await dependencies.fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-evident-signature': signature,
+            },
+            body,
+            signal: AbortSignal.timeout(REPORT_TIMEOUT_MS),
+        });
+        responseStatus = result.status;
+        console.log('runner.microvm_image_versions_reported', {
+            runnerId,
+            versions,
+            status: result.status,
+        });
+        if (!result.ok) {
+            throw new Error(`Evident returned HTTP ${result.status}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn('MicroVM image version report failed', {
+            operation: event.RequestType,
+            runnerId,
+            versions,
+            ...(responseStatus === undefined ? {} : { status: responseStatus }),
+            error: message,
+        });
+    }
+    return response();
+}
+const handler = (event) => handleImageVersionReport(event, () => ({
+    doorbellSecretArn: requireEnv('DOORBELL_SECRET_ARN'),
+    doorbellSecretKey: requireEnv('DOORBELL_SECRET_KEY'),
+    evidentApiUrl: requireEnv('EVIDENT_API_URL'),
+    evidentRunnerId: requireEnv('EVIDENT_RUNNER_ID'),
+}));
+exports.handler = handler;

package/dist/microvm-image-context/Dockerfile

@@ -95,13 +95,23 @@ ARG OPENCODE_VERSION=1.18.3
 ARG EVIDENT_CLI_VERSION=dev
 ARG CLAUDE_CODE_VERSION=latest
 ARG RUNNER_SYNCHRONISER_VERSION=dev
+#
+# @brave/brave-search-mcp-server is pinned (not a build arg — a single caller,
+# opencode.evident.jsonc, needs one version) and baked here for the same reason
+# as the ECS runner image: a cold `npx -y` install of it took ~38s in a fresh
+# MicroVM, over OpenCode's ~30s MCP connect timeout, so the server silently
+# failed to connect on every first turn after a boot. Baking it lets
+# opencode.evident.jsonc invoke the installed `brave-search-mcp-server` binary
+# directly instead of through `npx`.
 RUN npm install -g \
     "opencode-ai@${OPENCODE_VERSION}" \
     "@evident-ai/cli@${EVIDENT_CLI_VERSION}" \
     "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
     "@evident-ai/runner-synchroniser@${RUNNER_SYNCHRONISER_VERSION}" \
+    "@brave/brave-search-mcp-server@2.1.0" \
   && opencode --version \
   && evident --version \
+  && brave-search-mcp-server --help >/dev/null \
   && npm cache clean --force
 
 # Playwright chromium + OS deps for E2E, baked at build time to avoid a slow

package/dist/microvm-image-context/hooks/common.sh

@@ -21,11 +21,15 @@ OPENCODE_PORT="${OPENCODE_PORT:-4096}"
 # /proc/<pid>/environ, which runs as that same uid. /terminate removes it.
 # shellcheck disable=SC2034  # read by the scripts that source this file
 CONTEXT_FILE="/dev/shm/evident-run-context"
+
+# The runtime injects MICROVM_ID only into /run, never /resume. This tmpfs file
+# survives suspend/resume so /resume can restore the id for every fresh CLI
+# process to self-report and acknowledge a fulfilled recycle request (#1906).
+# shellcheck disable=SC2034  # read by the scripts that source this file
+MICROVM_ID_FILE="/dev/shm/evident-microvm-id"
 TUNNEL_PID_FILE="/dev/shm/evident-tunnel.pid"
 OPENCODE_PID_FILE="/dev/shm/evident-opencode.pid"
 LITESTREAM_PID_FILE="/dev/shm/evident-litestream.pid"
-CREDS_SYNC_PID_FILE="/dev/shm/evident-creds-sync.pid"
-CREDS_SYNC_LAST_ERROR_FILE="/dev/shm/evident-creds-sync.last-error"
 
 # Where the runner's credential store lives inside the durable-state bucket.
 # The BUCKET is the same for every VM from an image version, so the stack bakes
@@ -47,24 +51,29 @@ LITESTREAM_CONFIG_FILE="/dev/shm/evident-litestream.yml"
 # `/terminate` removes it with the rest of the per-VM state.
 SESSION_DB_NO_REPLICATE_MARKER="/dev/shm/evident-session-db-no-replicate"
 
+# Completion evidence for the CLI-owned credential flush. It lives in tmpfs,
+# is removed before every handshake, and is also removed by /terminate.
+CREDENTIAL_FLUSH_MARKER_FILE="/dev/shm/evident-credential-flush"
+
 hook_name() { printf '%s' "${0##*/}"; }
 log() { echo "[hook:$(hook_name)] $*"; }
 warn() { echo "[hook:$(hook_name)] $*" >&2; }
 error() { echo "[hook:$(hook_name)] ERROR: $*" >&2; }
 
-# Returns the CLI's own exit code. Domain outcomes (nothing persisted yet, a
-# corrupt object) are LOGGED and exit 0, the predicates answer "no" with 10, and
+# Returns the CLI's own exit code. `restore` logs domain outcomes and returns 0;
+# a non-zero status means the tool itself failed. `sync-once` returns 40 for
+# `failed`, `hashFailed`, and `localInvalid` (credentials not persisted), and 0
+# for every other outcome. The predicates answer "no" with 10, and
 # `session-db-classify`'s three typed answers are 30 (fatal)/31 (replica
 # unusable)/32 (retry), extended by `session-db-verify`'s 33 (integrity
 # exhausted, replica separated and local disposed) / 34 (could not prove
-# separation or disposal) — see `runner/synchroniser/src/cli.ts`'s own
-# comment for what each means, not restated here. Any OTHER non-zero status
+# separation or disposal). Any status outside a command's contractual answers
 # means the tool itself broke, which is the only case worth an ERROR here.
 run_synchroniser() {
   local rc=0
   "${SYNCHRONISER}" "$@" || rc=$?
   case "${rc}" in
-    0 | 10 | 30 | 31 | 32 | 33 | 34) ;;
+    0 | 10 | 30 | 31 | 32 | 33 | 34 | 40) ;;
     *) error "synchroniser '$*' exited ${rc}; the '${SYNCHRONISER}' command is missing from PATH, corrupt, or it threw" ;;
   esac
   return "${rc}"
@@ -317,7 +326,6 @@ regenerate_machine_id() {
 tunnel_is_running() { is_running "${TUNNEL_PID_FILE}"; }
 opencode_is_running() { is_running "${OPENCODE_PID_FILE}"; }
 litestream_is_running() { is_running "${LITESTREAM_PID_FILE}"; }
-creds_sync_is_running() { is_running "${CREDS_SYNC_PID_FILE}"; }
 
 # `jq -e` alone is not enough: its exit status reflects the LAST OUTPUT VALUE,
 # and an interpolation of a missing field is still a non-empty string, so a
@@ -462,149 +470,6 @@ kill_litestream() {
 }
 # --- litestream replicate (end) ----------------------------------------------
 
-# --- credential sync loop (#1868 WI-3, ECS parity) ---------------------------
-#
-# sync_credentials (above) covers the three boundary flushes /run's restore,
-# /suspend and /terminate already call. What it does NOT cover is a VM that
-# runs for a long time between those boundaries: a provider re-authenticated
-# through the proxied UI hours into a run would sit unflushed until the next
-# suspend/terminate, and a VM that dies without one (a crash, an OOM kill)
-# loses everything since boot. runner/docker-images/fargate/entrypoint.sh's
-# own sync_credentials_loop is the ECS side of the identical gap; this is the
-# same fix, backgrounded like the other long-lived services so it
-# outlives this hook process, `( … ) &` rather than `setsid`: a plain
-# backgrounded subshell is reparented to init and keeps running once its
-# parent hook script exits (verified: PPID=1, still alive, with no controlling
-# terminal in this image to send it a stray SIGHUP), and it inherits every
-# function this file defines, so it can call run_synchroniser directly with no
-# re-exec.
-
-# Bounded confirmation window `stop_credential_sync` polls after signalling the
-# loop. The loop's current child is one fast `run_synchroniser sync-once` call,
-# so this stays a short backstop rather than a graceful drain.
-CREDS_SYNC_STOP_WAIT_SECONDS=2
-
-# Best-effort per tick, exactly like sync_credentials above: a failed tick
-# must never end the loop, or a single transient S3 error would silently
-# disable sync for the rest of the VM's life.
-start_credential_sync() {
-  if [ -z "${PERSISTENCE_BUCKET:-}" ]; then
-    warn "CREDS-SYNC-DISABLED: LITESTREAM_BUCKET/LITESTREAM_PREFIX are not both set; no interval credential sync this boot."
-    return 0
-  fi
-
-  if creds_sync_is_running; then
-    warn "credential sync loop already running (pid $(cat "${CREDS_SYNC_PID_FILE}")); reusing it"
-    return 0
-  fi
-
-  # This is the same environment input runner-synchroniser validates. The
-  # variable is normally absent, so that ordinary case uses the documented
-  # default without a warning; a present invalid value is named and rejected.
-  local interval="${CREDS_SYNC_INTERVAL:-60}"
-  if [ -n "${CREDS_SYNC_INTERVAL+x}" ] && [[ ! "${CREDS_SYNC_INTERVAL}" =~ ^[1-9][0-9]*$ ]]; then
-    warn "CREDS-SYNC-INTERVAL-INVALID: CREDS_SYNC_INTERVAL='${CREDS_SYNC_INTERVAL}' is not a positive integer; using 60s"
-    interval=60
-  fi
-
-  rm -f "${CREDS_SYNC_LAST_ERROR_FILE}"
-
-  (
-    # Releases the fds this subshell inherited from the hook process before
-    # settling in for the VM's whole remaining life: nothing here writes to
-    # them (every synchroniser call already redirects its own), so there is
-    # no reason to keep holding the hook's original stdout/stderr open. A
-    # long-lived process that instead inherited a pipe's write end (a test
-    # harness reading the hook's own output, for one) would keep that pipe
-    # from ever reporting EOF — testing-guide.mdc's own lesson, and the same
-    # reason the long-lived services never inherit stdio either. That
-    # redirect also means `warn`/`log`/`error` calls in here go nowhere, so a
-    # failed sync-once is instead recorded to CREDS_SYNC_LAST_ERROR_FILE and
-    # surfaced by stop_credential_sync, which DOES have live stdio.
-    exec >/dev/null 2>&1 </dev/null
-
-    # A TERM this subshell receives (from stop_credential_sync, below) only
-    # kills THIS wrapper by default — its currently-running child (`sleep`,
-    # or a `run_synchroniser sync-once` call) is a separate process that
-    # would otherwise be orphaned and keep running, free to upload STALE
-    # credentials to S3 after the boundary flush that /suspend and
-    # /terminate perform immediately following the stop. Tracking the
-    # current child explicitly and forwarding the signal closes that race.
-    creds_sync_child_pid=""
-    trap 'trap - TERM; [ -n "${creds_sync_child_pid}" ] && kill -TERM "${creds_sync_child_pid}" 2>/dev/null; exit 0' TERM
-
-    while true; do
-      sleep "${interval}" &
-      creds_sync_child_pid=$!
-      wait "${creds_sync_child_pid}" 2>/dev/null
-      creds_sync_child_pid=""
-
-      run_synchroniser sync-once claude &
-      creds_sync_child_pid=$!
-      wait "${creds_sync_child_pid}" 2>/dev/null || echo "claude" >"${CREDS_SYNC_LAST_ERROR_FILE}"
-      creds_sync_child_pid=""
-
-      run_synchroniser sync-once opencode &
-      creds_sync_child_pid=$!
-      wait "${creds_sync_child_pid}" 2>/dev/null || echo "opencode" >"${CREDS_SYNC_LAST_ERROR_FILE}"
-      creds_sync_child_pid=""
-    done
-  ) &
-
-  echo $! >"${CREDS_SYNC_PID_FILE}"
-  log "CREDS-SYNC-STARTED: pid=$! interval=${interval}s"
-}
-
-# Signals the loop, then confirms (bounded — see CREDS_SYNC_STOP_WAIT_SECONDS)
-# that it and its current child are actually gone before returning: /suspend
-# and /terminate start their own boundary flush immediately after this call,
-# and an orphaned in-flight sync-once surviving past that point can overwrite
-# fresher credentials with stale ones. The TERM trap inside the loop (above)
-# forwards the signal to its current child almost instantly — this poll is a
-# defensive confirmation, not the primary mechanism, so it stays short; a
-# SIGKILL backstop covers a child that ignores TERM entirely.
-#
-# The DIED branch is a liveness report, not a no-op: every recovery/no-op path
-# must say what it found (development-workflow.mdc) — a stopped-before-called
-# loop and a died-on-its-own loop are different facts an operator needs told
-# apart, not the same "nothing to stop" line.
-stop_credential_sync() {
-  if [ ! -s "${CREDS_SYNC_PID_FILE}" ]; then
-    log "CREDS-SYNC-NOT-RUNNING: no credential sync loop to stop"
-    return 0
-  fi
-
-  local pid
-  pid="$(cat "${CREDS_SYNC_PID_FILE}")"
-  if ! process_is_alive "${pid}"; then
-    rm -f "${CREDS_SYNC_PID_FILE}"
-    warn "CREDS-SYNC-DIED: credential sync loop (pid=${pid}) had already exited before this stop"
-    return 0
-  fi
-
-  kill -TERM "${pid}" 2>/dev/null || true
-  rm -f "${CREDS_SYNC_PID_FILE}"
-
-  local waited_ms=0
-  while process_is_alive "${pid}" && [ "${waited_ms}" -lt $((CREDS_SYNC_STOP_WAIT_SECONDS * 1000)) ]; do
-    sleep 0.1
-    waited_ms=$((waited_ms + 100))
-  done
-
-  if process_is_alive "${pid}"; then
-    kill -KILL "${pid}" 2>/dev/null || true
-    warn "CREDS-SYNC-STOP-TIMEOUT: pid=${pid} still alive after ${CREDS_SYNC_STOP_WAIT_SECONDS}s; sent SIGKILL"
-  fi
-
-  if [ -s "${CREDS_SYNC_LAST_ERROR_FILE}" ]; then
-    warn "CREDS-SYNC-HAD-FAILURES: sync-once failed at least once for: $(tr '\n' ' ' <"${CREDS_SYNC_LAST_ERROR_FILE}")"
-    rm -f "${CREDS_SYNC_LAST_ERROR_FILE}"
-  fi
-
-  log "CREDS-SYNC-STOPPED: pid=${pid}"
-}
-# --- credential sync loop (end) -----------------------------------------------
-
 # --- flush_session_db (#812 WI-4) -------------------------------------------
 #
 # The checked, synchronous flush /suspend and /terminate need before they
@@ -681,11 +546,14 @@ flush_session_db() {
 # suspend it (#732). Sized from the measured cost of guessing wrong rather than
 # the saving: suspend reaches SUSPENDED in ~7 s and a resume is RUNNING in
 # ~0.6 s with the tunnel back ~2 s later (README, "Measured, end to end"), so
-# napping a VM whose user comes straight back costs ~10 s — against ~$0.30/h
-# that is cheap enough that the balance sits far nearer the floor than the
-# ceiling. Not AT the floor, though: the CLI's idle detector needs 2 clear poll
-# cycles (`run.ts`'s `idlePolls >= 2`, ≥4 s of real time), so a value near that
-# would spend more time suspending/resuming than idle.
+# napping a VM whose user comes straight back costs ~10 s — against the
+# legacy conservative baseline input of ~$0.30/h, AWS can burst a loaded VM
+# to a 16 GB / 8 vCPU peak (~$1.06/h at sustained full load—a worst-case
+# ceiling, not an expectation); that is cheap enough that the balance
+# sits far nearer the floor than the ceiling. Not AT the floor, though: the
+# CLI's idle detector needs 2 clear poll cycles (`run.ts`'s `idlePolls >= 2`,
+# ≥4 s of real time), so a value near that would spend more time
+# suspending/resuming than idle.
 # ECS's waker uses 900 s instead only because *its* cold start is far slower
 # than this VM's ~2 s resume — not evidence this default should match it.
 #
@@ -697,7 +565,9 @@ flush_session_db() {
 # runner/docker-images/fargate/entrypoint.sh uses for the ECS runner's own
 # idle-timeout flag, so an operator who knows one knows the other. A
 # non-numeric override must never silently DROP the flag — that degrades to
-# an always-on VM burning ~$2.40/day, exactly the bug this closes — so it
+# an always-on VM burning ~$7.17/day at baseline, or up to ~$25.49/day at
+# sustained full peak as load increases (a worst-case ceiling, not an
+# expectation), exactly the bug this closes — so it
 # warns and falls back to the default instead.
 #
 # Deliberately NOT in the /run payload yet: doing so would touch the doorbell
@@ -765,6 +635,7 @@ start_tunnel() {
     --litestream-config "${LITESTREAM_CONFIG_FILE}" \
     --litestream-pid-file "${LITESTREAM_PID_FILE}" \
     --session-db-no-replicate-marker "${SESSION_DB_NO_REPLICATE_MARKER}" \
+    --credential-sync-marker "${CREDENTIAL_FLUSH_MARKER_FILE}" \
     "${credential_flags[@]}" \
     "${session_db_flags[@]}" \
     "${opencode_config_flags[@]}" \
@@ -779,19 +650,17 @@ start_tunnel() {
 # whole seconds: 25 s in-flight drain (SHUTDOWN_DRAIN_TIMEOUT_MS,
 # apps/cli/src/commands/run.ts) + 2 s offline POST (notifyAgentDisconnected,
 # apps/cli/src/commands/agent-lookup.ts) + 5 s telemetry flush
-# (TELEMETRY_SHUTDOWN_TIMEOUT_MS, run.ts). Each of the three is bounded there, so
-# this is a ceiling rather than a typical cost — an idle suspend finishes in a
-# couple of seconds. This is the ONE place the budget is written down; the CLI
-# only points back here, because restating it in three places produced #657.
+# (TELEMETRY_SHUTDOWN_TIMEOUT_MS, run.ts) + 8.5 s pre-drain credential flush
+# + 8.5 s post-drain credential flush. Each phase is bounded there, so this is
+# a ceiling rather than a typical cost — an idle suspend finishes in a couple
+# of seconds. This is the ONE place the hand-maintained budget is written down;
+# the CLI points back here when its bounds change.
 #
-# DOCUMENTATION ONLY — nothing is derived from this any more. The wait below
-# used to be pinned above it, which is the reasoning that talked #699 into 40 s;
-# since #718 an exited CLI is noticed on the first poll, so the wait is a
-# backstop chosen on its own merits and the two numbers are unrelated. Nothing
-# cross-checks the 32 against apps/cli either: it is a hand-maintained sum of the
-# three bounds cited above, so if one of them moves, update it here.
+# DOCUMENTATION ONLY — nothing is derived from this value. It is the hand-maintained
+# sum of the five bounded phases above (25 + 2 + 5 + 8.5 + 8.5); update it here if
+# any of those bounds changes.
 # shellcheck disable=SC2034  # documentation; deliberately read by nothing
-CLI_SHUTDOWN_CEILING_SECONDS=32
+CLI_SHUTDOWN_CEILING_SECONDS=49
 
 # How long stop_tunnel waits for that shutdown before the SIGKILL backstop.
 # Since #718 this binds ONLY for a CLI that is still draining: one that has
@@ -867,6 +736,85 @@ stop_tunnel() {
   log "tunnel stopped ${outcome}"
 }
 
+# The CLI owns the interval loop and its boundary flush. Two seconds of slack
+# over the CLI's 8s flush deadline keeps this marker handshake inside the 55s
+# hook ceiling while leaving the fallback flush and tunnel stop budget intact.
+#
+# This bounds only the CLI's pre-drain flush, which always runs first and
+# unconditionally (run.ts's cleanup(), before the channel-work drain) — not
+# the CLI's post-drain second pass, which can take up to
+# SHUTDOWN_DRAIN_TIMEOUT_MS longer than this wait covers. A drain that
+# consumes the whole window loses the SECOND pass, not the credential
+# guarantee itself: the pre-drain flush already persisted everything on disk
+# at signal time, exactly what the old bash `sync_credentials` guaranteed in
+# one synchronous call — so the worst case here is no worse than before this
+# handshake existed, never a fresh data-loss window. See
+# docs/decisions/0063-microvm-boot-orchestration-in-cli.md's two-phase-flush
+# section for the full reasoning.
+CREDENTIAL_FLUSH_WAIT_SECONDS="${EVIDENT_CREDENTIAL_FLUSH_WAIT_SECONDS:-10}"
+
+# Remove the previous answer, signal the same CLI that stop_tunnel handles, and
+# wait for either its marker or its death. A fallback sync runs only after the
+# CLI is known to be absent, never alongside a live CLI that may still write.
+stop_runner_and_flush_credentials() {
+  rm -f "${CREDENTIAL_FLUSH_MARKER_FILE}"
+
+  if ! tunnel_is_running; then
+    warn "CREDS-FLUSH-NO-RUNNER: no live CLI at handshake entry"
+    stop_tunnel
+    sync_credentials
+    return 0
+  fi
+
+  local pid
+  pid="$(cat "${TUNNEL_PID_FILE}")"
+  kill -TERM "${pid}" 2>/dev/null || true
+
+  local waited_ms=0 marker_found=false runner_exited=false
+  while [ "${waited_ms}" -lt $((CREDENTIAL_FLUSH_WAIT_SECONDS * 1000)) ]; do
+    if [ -s "${CREDENTIAL_FLUSH_MARKER_FILE}" ]; then
+      marker_found=true
+      break
+    fi
+    if ! process_is_alive "${pid}"; then
+      runner_exited=true
+      break
+    fi
+    sleep 0.1
+    waited_ms=$((waited_ms + 100))
+  done
+
+  # The CLI can publish the marker and exit inside one poll tick. A final
+  # marker check after a death break preserves that answer instead of falling
+  # through to the fallback.
+  if [ "${runner_exited}" = true ] && [ -s "${CREDENTIAL_FLUSH_MARKER_FILE}" ]; then
+    marker_found=true
+    runner_exited=false
+  fi
+
+  if [ "${marker_found}" = true ]; then
+    local failures
+    failures="$(grep -Ev '^(claude|opencode)=ok$' "${CREDENTIAL_FLUSH_MARKER_FILE}" || true)"
+    if [ -n "${failures}" ]; then
+      warn "CREDS-FLUSH-HAD-FAILURES: ${failures//$'\n'/ }"
+    else
+      log "CREDS-FLUSH-OK"
+    fi
+    stop_tunnel
+    return 0
+  fi
+
+  if [ "${runner_exited}" = true ]; then
+    warn "CREDS-FLUSH-RUNNER-EXITED: CLI exited without a completion marker"
+    stop_tunnel
+    sync_credentials
+    return 0
+  fi
+
+  warn "CREDS-FLUSH-TIMEOUT: live CLI did not write a completion marker within ${CREDENTIAL_FLUSH_WAIT_SECONDS}s"
+  stop_tunnel
+}
+
 # --- check_runner_key (#1172) ------------------------------------------------
 #
 # Answers exactly one question before opencode/the tunnel start spending this

package/dist/microvm-image-context/hooks/resume

@@ -2,10 +2,8 @@
 #
 # Re-dial with the identity /run left behind. There is no step that could fetch
 # a fresh runner key, so the one from /run is what resumes. The CLI delegated by
-# start_tunnel owns the session-DB replicator's post-resume start. The interval
-# credential sync loop (#1868 WI-3) stays here because /suspend stops it too, so
-# a resumed VM that never restarted it here would never sync credentials again
-# for the rest of its life.
+# start_tunnel owns the credential loop and the session-DB replicator's
+# post-resume start.
 set -euo pipefail
 
 # shellcheck source=./common.sh
@@ -39,12 +37,18 @@ fi
   read -r runner_key
 } <"${CONTEXT_FILE}"
 
+# Restore the id so the resumed CLI can self-report and acknowledge any
+# outstanding recycle request (#1906). Older images may not have this file.
+if [ -s "${MICROVM_ID_FILE}" ]; then
+  MICROVM_ID="$(cat "${MICROVM_ID_FILE}")"
+  export MICROVM_ID
+fi
+
 # Tolerant, never fatal: a resume that fails costs the user their whole
 # session, so a broken durable-state config degrades to "no session-DB
 # replication" rather than a failed resume. The CLI's own guards handle the
 # rest — this needs no logic of its own.
 load_state_config || warn "could not resolve durable-state config; the session DB will not resume replicating"
-start_credential_sync
 
 # Diagnostic-only, unlike /run's gate: a failed resume costs the user their
 # whole session, so this never exits — it only converts a silent "resumed but

package/dist/microvm-image-context/hooks/run

@@ -28,7 +28,6 @@ cleanup() {
   stop_tunnel || warn "stop_tunnel failed while cleaning up"
   stop_opencode || warn "stop_opencode failed while cleaning up"
   kill_litestream || warn "kill_litestream failed while cleaning up"
-  stop_credential_sync || warn "stop_credential_sync failed while cleaning up"
 }
 trap cleanup EXIT
 
@@ -73,9 +72,12 @@ load_state_config || exit 1
 # it warns and this VM still boots.
 check_runner_key "${runner_key}" "${api_url}" || exit 1
 
-# 6 — the interval credential sync (#1868 WI-3). It stays before the context file
-# is written. Bare: every guard inside start_credential_sync is its own `return 0`.
-start_credential_sync
+# 6 — preserve the VM id across suspend/resume. The runtime always supplies it
+# for a /run hook, and the subshell keeps the persisted value protected.
+(
+  umask 077
+  printf '%s\n' "${MICROVM_ID}" >"${MICROVM_ID_FILE}"
+)
 
 # 7 — the first per-VM identity on the wire. The subshell's umask makes the file
 # unreadable to anyone else from the moment it exists, before the key is in it.

package/dist/microvm-image-context/hooks/suspend

@@ -8,11 +8,10 @@ set -euo pipefail
 # shellcheck source=./common.sh
 source "$(dirname "$0")/common.sh"
 
-# Stopped BEFORE the boundary flush (#1868 WI-3): the interval loop and this
-# flush must not race each other on the same credential stores.
-stop_credential_sync
-sync_credentials
-stop_tunnel
+# load_state_config exports PERSISTENCE_BUCKET, which flush_session_db below
+# requires; the CLI flush completes, or is proven absent, before teardown continues.
+load_state_config || warn "could not resolve durable-state config; neither the credential flush nor the session-DB flush below can run"
+stop_runner_and_flush_credentials
 
 # opencode is deliberately NOT stopped here (#812 WI-4) — it is inside the
 # snapshot and must resume with it — so a turn still in flight may not be

package/dist/microvm-image-context/hooks/terminate

@@ -8,11 +8,10 @@ set -uo pipefail
 # shellcheck source=./common.sh
 source "$(dirname "$0")/common.sh"
 
-# Stopped BEFORE the boundary flush (#1868 WI-3): the interval loop and this
-# flush must not race each other on the same credential stores.
-stop_credential_sync
-sync_credentials
-stop_tunnel
+# load_state_config exports PERSISTENCE_BUCKET, which flush_session_db below
+# requires; the CLI flush completes, or is proven absent, before teardown continues.
+load_state_config || warn "could not resolve durable-state config; neither the credential flush nor the session-DB flush below can run"
+stop_runner_and_flush_credentials
 
 # Writers stopped BEFORE litestream's final sync (#812 WI-4, the
 # ordered-shutdown invariant, plan §6): otherwise litestream could snapshot
@@ -32,6 +31,6 @@ flush_session_db
 # this hook runs under `set -u` (above), so an unbound one aborts the script
 # AT THIS LINE, leaving the runner key sitting in CONTEXT_FILE on a VM that is
 # being torn down. That is the one thing this line exists to prevent.
-rm -f "${CONTEXT_FILE}" "${SESSION_DB_NO_REPLICATE_MARKER}"
+rm -f "${CONTEXT_FILE}" "${SESSION_DB_NO_REPLICATE_MARKER}" "${CREDENTIAL_FLUSH_MARKER_FILE}"
 
 exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-cdk",
-  "version": "3.4.1-dev.59c7df3",
+  "version": "3.4.1-dev.7e9dfeb",
   "description": "Reusable CDK constructs for an Evident agent runner: a single scale-to-zero Fargate runner (task + service + per-agent self-stop role + waker Lambda), or a per-session AWS Lambda MicroVM that boots on demand and suspends between messages. Instantiate once per agent from your own stack.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",