@evident-ai/runner-cdk 3.4.1-dev.1856549 → 3.4.1-dev.2b2679a

package/README.md

@@ -97,7 +97,7 @@ the construct's own dogfooding consumer.
 | `cluster`, `securityGroup`, `taskRole`, `logGroup`, `replicaBucket` | interfaces | Shared infra you create and pass in. |
 | `image` | `ecs.ContainerImage` | Your runner image. |
 | `agentSecret`, `wakerSecret` | `secretsmanager.ISecret` | Any Secrets Manager secret. |
-| `availableSecretKeys` | `Set<string>` | Keys present in the agent secret. Requires `EVIDENT_AGENT_KEY` + `GH_TOKEN`; MCP credentials (`BRAVE_API_KEY`, `CLOUDFLARE_API_TOKEN`, `NEON_API_KEY`) are injected only when listed. |
+| `availableSecretKeys` | `Set<string>` | Keys present in the agent secret. Every listed key is injected; `EVIDENT_AGENT_KEY` and `GH_TOKEN` are also injected for compatibility with adopters that do not enumerate their secret. |
 
 ### Two deliberate "no default" choices
 
@@ -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,15 +159,27 @@ 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.
 
 | MicroVM prop | Omitted behavior |
 | --- | --- |
-| `runnerSecret` | No GitHub or MCP credentials are exported at `/run`. |
+| `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
 

package/dist/controller-lambda/handler.js

@@ -42866,7 +42866,7 @@ Reference: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.ht
 // ../../node_modules/.pnpm/@aws-sdk+signature-v4-multi-region@3.996.42/node_modules/@aws-sdk/signature-v4-multi-region/dist-cjs/index.js
 var require_dist_cjs23 = __commonJS({
   "../../node_modules/.pnpm/@aws-sdk+signature-v4-multi-region@3.996.42/node_modules/@aws-sdk/signature-v4-multi-region/dist-cjs/index.js"(exports2) {
-    var { SignatureV4: SignatureV43, signatureV4aContainer } = require_dist_cjs17();
+    var { SignatureV4: SignatureV43, signatureV4aContainer } = require_dist_cjs2();
     var signatureV4CrtContainer = {
       CrtSignerV4: null
     };
@@ -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

@@ -61,13 +61,25 @@ export type EvidentScaleToZeroConstructProps = {
     replicaBucket: s3.IBucket;
     image: ecs.ContainerImage;
     /**
-     * Container secrets. Requires EVIDENT_AGENT_KEY + GH_TOKEN; the MCP
-     * credentials BRAVE_API_KEY / CLOUDFLARE_API_TOKEN / NEON_API_KEY are injected
-     * only if present (see availableSecretKeys).
+     * Container secrets. `availableSecretKeys` are injected by name; EVIDENT_AGENT_KEY
+     * and GH_TOKEN remain available to external adopters that do not enumerate keys.
+     *
+     * `agentSecret` always supplies EVIDENT_AGENT_KEY. When `capabilitySecret` is
+     * ALSO given (#1868 WI-2), every capability key (GH_TOKEN included) is injected
+     * from THAT secret instead, and `availableSecretKeys` is ignored — the two
+     * deploy targets (this one and the MicroVM stack) then read the same
+     * capability keys from the same shared secret rather than each carrying its
+     * own copy. When `capabilitySecret` is absent, behavior is unchanged: GH_TOKEN
+     * plus every `availableSecretKeys` entry, all from `agentSecret` — an external
+     * adopter passing only `agentSecret`/`availableSecretKeys` is unaffected.
      */
     agentSecret: secretsmanager.ISecret;
-    /** Key names present in the agent secret; gates the optional MCP creds. */
+    /** Key names present in the agent secret. Every listed key is injected into the container. */
     availableSecretKeys: Set<string>;
+    /** The shared capability secret (#1868 WI-2). See `agentSecret`'s doc above. */
+    capabilitySecret?: secretsmanager.ISecret;
+    /** Key names present in `capabilitySecret`. Ignored when `capabilitySecret` is absent. */
+    capabilityKeys?: Set<string>;
     /** Waker secret (EVIDENT_WAKE_SECRET), consumed by the waker at runtime. */
     wakerSecret: secretsmanager.ISecret;
 };

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

@@ -61,7 +61,7 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
     service;
     constructor(scope, id, props) {
         super(scope, id);
-        const { agentName, evidentAgentId, gitRepo, gitBranch, idleTimeoutSeconds, cpu, memoryLimitMiB, resourcePrefix = DEFAULT_RESOURCE_PREFIX, envName, evidentApiUrl, evidentTunnelUrl, extraEnvironment, cluster, securityGroup, taskRole, logGroup, replicaBucket, image, agentSecret, availableSecretKeys, wakerSecret, } = props;
+        const { agentName, evidentAgentId, gitRepo, gitBranch, idleTimeoutSeconds, cpu, memoryLimitMiB, resourcePrefix = DEFAULT_RESOURCE_PREFIX, envName, evidentApiUrl, evidentTunnelUrl, extraEnvironment, cluster, securityGroup, taskRole, logGroup, replicaBucket, image, agentSecret, availableSecretKeys, capabilitySecret, capabilityKeys, wakerSecret, } = props;
         this.replicaPrefix = `agents/${evidentAgentId}`;
         // A plain STRING (not service.serviceName) so the container env is static and
         // has no construct-ordering dependency on the service.
@@ -127,16 +127,22 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             ...extraEnvironment,
         };
         const secrets = {
+            // Identifies the runner to Evident. Always agentSecret — capabilitySecret
+            // never carries this key (#1868 WI-2: the two are a deliberate split, not
+            // a duplication of the same data).
             EVIDENT_AGENT_KEY: ecs.Secret.fromSecretsManager(agentSecret, 'EVIDENT_AGENT_KEY'),
-            GH_TOKEN: ecs.Secret.fromSecretsManager(agentSecret, 'GH_TOKEN'),
         };
-        // Optional MCP creds (consumed by opencode.runner.jsonc): BRAVE_API_KEY →
-        // brave-search, CLOUDFLARE_API_TOKEN → the Cloudflare MCP, NEON_API_KEY →
-        // the Neon MCP (read-only). Injected only if present in the SOPS file — a
-        // referenced-but-absent key fails ECS task startup, so an operator can
-        // enable an MCP by just adding its key + redeploy.
-        for (const key of ['BRAVE_API_KEY', 'CLOUDFLARE_API_TOKEN', 'NEON_API_KEY']) {
-            if (availableSecretKeys.has(key)) {
+        if (capabilitySecret !== undefined) {
+            for (const key of capabilityKeys ?? new Set()) {
+                secrets[key] = ecs.Secret.fromSecretsManager(capabilitySecret, key);
+            }
+        }
+        else {
+            // Legacy shape, unchanged: GH_TOKEN (required to clone this construct's
+            // workspace at boot) plus every availableSecretKeys entry, all from
+            // agentSecret — what every external adopter still gets.
+            secrets.GH_TOKEN = ecs.Secret.fromSecretsManager(agentSecret, 'GH_TOKEN');
+            for (const key of availableSecretKeys) {
                 secrets[key] = ecs.Secret.fromSecretsManager(agentSecret, key);
             }
         }
@@ -162,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
@@ -124,9 +134,14 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
             ...(props.runnerOpencodeConfigPath
                 ? { RUNNER_OPENCODE_CONFIG: props.runnerOpencodeConfigPath }
                 : {}),
-            ...(props.runnerSecret ? { RUNNER_SECRET_ARN: props.runnerSecret.secretArn } : {}),
+            ...(props.runnerSecret
+                ? {
+                    RUNNER_SECRET_ARN: props.runnerSecret.secretArn,
+                }
+                : {}),
             ...(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 = {
@@ -245,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/controller/shape-catalogue.d.ts

@@ -1,6 +1,6 @@
 /**
  * Parses the `MICROVM_SHAPES` environment variable (a JSON array, written by
- * CloudFormation from `infrastructure/evident-microvm/src/shapes.ts` at
+ * CloudFormation from `aws/runner-cdk/src/microvm/shapes.ts` at
  * deploy time — see D6/D7 in the plan) into a `ShapeCatalogue` the pure
  * decision core can query, without that core ever touching `process.env`
  * itself.