@evident-ai/runner-cdk 3.4.1-dev.31006db → 3.4.1-dev.38181ff

package/README.md

@@ -11,7 +11,7 @@ Reusable AWS CDK constructs for running an [Evident](https://evident.run) agent
 - **`EvidentMicrovmConstruct`** — a per-session AWS Lambda MicroVM that boots on demand
   and suspends between messages. Installing the `@dev` tag of this package is all you
   need: the image build context ships inside it (see [The MicroVM image](#the-microvm-image)
-  below), so there is no checkout of `sroze/evident` involved. See
+  below), so there is no checkout of the source repository involved. See
   [the AWS runner doc](https://evident.run/docs/aws-runner) for the full picture of both
   strategies.
 
@@ -76,8 +76,8 @@ agent.selfStopRoleArn;
 agent.replicaPrefix;
 ```
 
-For a complete working example, see `infrastructure/evident-runner/` in this repo — it is
-the construct's own dogfooding consumer.
+For a complete working example, see [`GETTING-STARTED.md`](./GETTING-STARTED.md) in this
+package — it is the construct's own dogfooding consumer.
 
 ## Props
 
@@ -121,10 +121,11 @@ context, which `cdk deploy` zips and uploads. The Lambda MicroVM service then bu
 image in *your* account, from a base image ARN you discover there — so, unlike the Fargate
 strategy, there is no registry image to pull.
 
-The context has two halves, and this package ships the half that is ours: the Dockerfile,
-the per-phase hook scripts and the bundled hook server, published inside the tarball at
-`dist/microvm-image-context/`. The other half is **your** repository, which is baked in as
-the agent's workspace. `stageMicrovmImageContext()` puts the two together:
+The context has three parts: this package supplies the Dockerfile, the per-phase hook
+scripts and the bundled hook server, published inside the tarball at
+`dist/microvm-image-context/`; **your** repository is baked in as the agent's workspace;
+and an optional overlay supplies deployment-specific build steps. `stageMicrovmImageContext()`
+puts them together:
 
 ```ts
 import path from 'node:path';
@@ -143,6 +144,8 @@ new EvidentMicrovmConstruct(this, 'Runner', {
     // token the agent pushes with arrives per-session, never baked in.
     originUrl: 'https://github.com/acme/widgets.git',
     destination: path.join(__dirname, '..', 'build', 'image'),
+    // Optional deployment-specific installs and build warm-up.
+    overlayDir: '/path/to/microvm-overlay',
   }),
   // Must match the published image these were baked into, so export them
   // rather than restating the numbers.
@@ -156,6 +159,11 @@ new EvidentMicrovmConstruct(this, 'Runner', {
 });
 ```
 
+Pass `overlayDir` to add deployment-specific build steps to the staged image. The
+directory provides `setup-root` for root-owned installs and `setup-workspace` for
+workspace build warm-up after dependency installation. See the [MicroVM image
+README](../../runner/docker-images/microvm/README.md) for the full overlay contract.
+
 Your repo does not have to be a pnpm workspace. If it commits a `pnpm-lock.yaml` the image
 pre-installs dependencies at build time (a faster first boot); if not, that step is skipped
 and the agent installs on first use.
@@ -164,7 +172,14 @@ 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. |
+| `extraImageEnvironment` | Non-secret values baked into every VM launched from this image version; every VM can read them, so never put secrets here. |
 | `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. |
+
+`extraImageEnvironment` is the runtime counterpart to an overlay. Use it when an
+overlay-installed component needs an environment variable after the VM boots. The
+values are baked into every VM launched from that image version and are readable by
+all of them, so never put a secret in this prop.
 
 ## Status / limitations
 
@@ -172,7 +187,6 @@ and the agent installs on first use.
   `npm install @evident-ai/runner-cdk@dev` (or `pnpm add`/`yarn add`); no checkout of
   this repo is required. It builds to a self-contained `dist/` (`pnpm --filter
   @evident-ai/runner-cdk build`) with no `workspace:`/`@evident/*` runtime dependency.
-  This repo's own consumer (`infrastructure/evident-runner`) still consumes it as a
-  `workspace:*` dependency for dogfooding.
+  Evident's own consumer still consumes it as a `workspace:*` dependency for dogfooding.
 - **AWS/ECS-specific.** Non-AWS clouds are an open question on the epic, not a supported
   path.

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/evident-scale-to-zero-construct.d.ts

@@ -17,7 +17,7 @@ export type EvidentScaleToZeroConstructProps = {
      * (`agents/<id>`) and is the single expected `agent_id` the waker checks.
      */
     evidentAgentId: string;
-    /** GitHub `owner/repo` the agent clones and works on (e.g. `sroze/evident`). */
+    /** GitHub `owner/repo` the agent clones and works on (e.g. `my-org/my-repo`). */
     gitRepo: string;
     /** Branch to clone. Defaults to `main` when omitted. */
     gitBranch?: string;

package/dist/evident-scale-to-zero-construct.js

@@ -168,9 +168,8 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             cluster,
             taskDefinition,
             serviceName,
-            // Starts at 1; the runner self-scales to 0 on idle. A deploy resets this to
-            // 1 (CFN), waking a sleeping agent that then re-naps (benign).
-            desiredCount: 1,
+            // Deliberately omit DesiredCount: CloudFormation leaves the existing service's
+            // self-stop/waker count alone; either 1 or 0 would re-assert it on every deploy.
             enableExecuteCommand: true,
             assignPublicIp: true,
             vpcSubnets: { subnetType: ec2.SubnetType.PUBLIC },

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

@@ -55,6 +55,12 @@ export interface EvidentMicrovmConstructProps {
     readonly gitUserName?: string;
     /** Optional git email the `/run` hook configures for agent commits. */
     readonly gitUserEmail?: string;
+    /**
+     * Non-secret values baked into every VM launched from this image version,
+     * typically values a deployment's overlay needs at runtime. Every VM can
+     * read them, so this must never contain a secret.
+     */
+    readonly extraImageEnvironment?: Record<string, string>;
     /**
      * TCP port the image's hook server listens on, baked into both the image
      * (`HOOKS_PORT` env var) and the `MicrovmImage`'s `hooks.port` — a mismatch
@@ -69,6 +75,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
@@ -131,6 +141,7 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
                 : {}),
             ...(props.gitUserName ? { GIT_USER_NAME: props.gitUserName } : {}),
             ...(props.gitUserEmail ? { GIT_USER_EMAIL: props.gitUserEmail } : {}),
+            ...props.extraImageEnvironment,
         };
         // ...and the hooks configuration every shape's image is built with.
         const imageHooks = {
@@ -249,6 +260,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/stage-context.d.ts

@@ -14,6 +14,12 @@ export interface StageMicrovmImageContextOptions {
     readonly originUrl: string;
     /** Directory to write the build context to. Removed and recreated. */
     readonly destination: string;
+    /**
+     * Overlay scripts the image build runs as root and as `runner`. The overlay
+     * ships inside the shared snapshot, so it may install software but must carry
+     * no credential. When omitted, deterministic no-op scripts are written.
+     */
+    readonly overlayDir?: string;
     /**
      * The published template to copy from. Defaults to the one inside this
      * package; named directly by the tests, which assert against a template they
@@ -23,11 +29,14 @@ export interface StageMicrovmImageContextOptions {
 }
 /**
  * Writes the build context AWS unpacks — the Dockerfile, the hook server, the
- * per-phase hook scripts and the repository — and returns its path. The result
- * is what `EvidentMicrovmConstruct`'s `imageSource` takes.
+ * per-phase hook scripts, the deployment overlay and the repository — and
+ * returns its path. The result is what `EvidentMicrovmConstruct`'s `imageSource`
+ * takes.
  *
- * The first three come from this package's published `dist/`, so a consumer
- * needs no checkout of `sroze/evident` and no copy of the Dockerfile or hook
- * scripts (#1528). Only `repositoryPath` is theirs to supply.
+ * The Dockerfile, hook server and phase hooks come from this package's
+ * published `dist/`, so a consumer needs no checkout of the source repository and no
+ * copy of those files (#1528). A caller may supply an overlay; the default is
+ * deterministic no-op scripts. `repositoryPath` is the only required caller
+ * input.
  */
 export declare function stageMicrovmImageContext(options: StageMicrovmImageContextOptions): string;