@evident-ai/runner-cdk 3.5.2-dev.bcf1140 → 3.5.2-dev.cffa626

package/README.md

@@ -9,9 +9,9 @@ Reusable AWS CDK constructs for running an [Evident](https://evident.run) agent
   `desiredCount 0`, and an HMAC-authenticated waker Lambda scales it back up on the next
   message. You pay for the time the agent is actually working.
 - **`EvidentMicrovmConstruct`** — a per-session AWS Lambda MicroVM that boots on demand
-  and suspends between messages. Installing 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 the source repository involved. See
+  and suspends between messages. You provide a build-context directory and a full source
+  checkout to `stageMicrovmBuildContext`, then pass its returned directory as
+  `buildContextPath` (see [The MicroVM image](#the-microvm-image) below). 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 `GETTING-STARTED.md` (not published to npm); it is the
-construct's own dogfooding consumer.
+For the full end-to-end walkthrough for this construct, see
+[GETTING-STARTED.md](https://github.com/evident-run/evident-run/blob/main/aws/runner-cdk/GETTING-STARTED.md).
 
 ## Props
 
@@ -99,6 +99,26 @@ construct's own dogfooding consumer.
 | `agentSecret`, `wakerSecret` | `secretsmanager.ISecret` | Any Secrets Manager secret. |
 | `availableSecretKeys` | `Set<string>` | Keys present in the agent secret. Every listed key is injected; `EVIDENT_RUNNER_KEY` and `EVIDENT_AGENT_KEY` are injected from the `EVIDENT_AGENT_KEY` field, and `GH_TOKEN` is also injected for adopters that do not enumerate their secret. |
 
+### MicroVM props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `buildContextPath` | `string` | Directory containing your Dockerfile and every file it copies, normally the result of `stageMicrovmBuildContext()`. |
+| `baseImageArn` / `baseImageVersion` | `string` | The AWS-managed base MicroVM image values from `aws lambda-microvms list-managed-microvm-images`. |
+| `controllerSigningSecret` | `secretsmanager.ISecret` | Secret containing the shared HMAC key under the `CONTROLLER_SIGNING_SECRET` JSON field. |
+| `hooksPort` / `hookTimeoutSeconds` | `number` | Values exported by the base image contract. |
+| `shapes` | `readonly MicrovmShape[]?` | Shape catalogue to build. Defaults to the committed catalogue. |
+| `runnerSecret` | `secretsmanager.ISecret?` | Optional JSON secret whose values are exported by `/run`. |
+| `runnerOpencodeConfigPath` | `string?` | Optional baked OpenCode configuration path. |
+| `gitUserName` / `gitUserEmail` | `string?` | Optional git identity for agent commits. |
+| `extraImageEnvironment` | `Record<string,string>?` | Non-secret values baked into every VM launched from the image version. |
+| `evidentApiUrl` / `evidentRunnerId` | `string?` | Supply both to report published image versions to Evident, or omit both. |
+| `imageVersionPruning` | `boolean?` | Opts into construct-owned pruning for this deployment's images. Uses the engine defaults; omitting it creates no pruning resources. |
+
+The `DoorbellSecret` CloudFormation logical ID remains stable for Evident's own
+default stack. It identifies the deployed secret resource, not the customer-facing
+name of the signing key.
+
 ### Two deliberate "no default" choices
 
 - **The endpoints are required.** Defaulting them would either bake *our* dev environment
@@ -116,57 +136,73 @@ built from a `Dockerfile` you control. The generic runner image lives separately
 
 ## The MicroVM image
 
-`EvidentMicrovmConstruct`'s `imageSource` is a **local directory** holding the image build
-context, which `cdk deploy` zips and uploads. The Lambda MicroVM service then builds the
-image in *your* account, from a base image ARN you discover there — so, unlike the Fargate
-strategy, there is no registry image to pull.
+### Prune image versions
 
-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:
+MicroVM image versions are quota-bound. Opt into construct-owned pruning with one
+property:
+
+```ts
+new EvidentMicrovmConstruct(this, 'Runner', {
+  // ...other required MicroVM props
+  imageVersionPruning: true,
+});
+```
+
+This bounds the per-image version quota (`L-F8BECE9C`) for this deployment's shapes only.
+Retention follows the engine defaults, and pruning runs before the image publish for the
+deploy that invokes it. The custom-resource Lambda writes per-image verdicts and a summary
+to CloudWatch Logs. Use the `prune-microvm-image-versions` CLI for deployments that do not
+use this construct or that need non-default retention; see the
+`@evident-ai/lambda-microvm-cdk` package README for its flags and safety semantics.
+
+`EvidentMicrovmConstruct`'s `buildContextPath` is a **local directory** holding the
+Dockerfile you control and everything it copies. `cdk deploy` zips and uploads that
+directory, and the Lambda MicroVM service builds the image in *your* account. Start the
+Dockerfile from a pinned `ghcr.io/sroze/evident-microvm-base:X.Y.Z` tag; the base image
+contains the hook server, lifecycle hooks and common agent tooling.
+
+`stageMicrovmBuildContext()` combines your build-context directory with a full checkout
+of the workspace in a fresh temporary directory. The workspace is written at
+`workspace/`, and the returned path is the value for `buildContextPath`:
 
 ```ts
-import path from 'node:path';
 import {
   EvidentMicrovmConstruct,
   HOOKS_PORT,
   HOOK_TIMEOUT_SECONDS,
-  stageMicrovmImageContext,
+  stageMicrovmBuildContext,
 } from '@evident-ai/runner-cdk';
 
+const buildContextPath = stageMicrovmBuildContext({
+  // A full (non-shallow) clone: the agent branches, commits and opens PRs.
+  workspaceRepositoryPath: '/path/to/your/checkout',
+  // Credential-free: the token the agent pushes with arrives per-session.
+  workspaceOriginUrl: 'https://github.com/acme/widgets.git',
+  buildContextPath: '/path/to/your/microvm-build-context',
+});
+
 new EvidentMicrovmConstruct(this, 'Runner', {
-  imageSource: stageMicrovmImageContext({
-    // A full (non-shallow) clone: the agent branches, commits and opens PRs.
-    repositoryPath: '/path/to/your/checkout',
-    // Credential-free — this string ships inside the shared snapshot. The
-    // 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',
-  }),
+  buildContextPath,
   // Must match the published image these were baked into, so export them
   // rather than restating the numbers.
   hooksPort: HOOKS_PORT,
   hookTimeoutSeconds: HOOK_TIMEOUT_SECONDS,
   baseImageArn,
   baseImageVersion,
-  doorbellSecret,
+  controllerSigningSecret,
   runnerSecret,
   runnerOpencodeConfigPath: 'opencode.runner.jsonc',
 });
 ```
 
-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
-dependency installation and workspace build warm-up. See the [MicroVM image
-README](../../runner/docker-images/microvm/README.md) for the full overlay contract.
+Write project-specific installation and build steps in your Dockerfile. The [MicroVM base
+image README](../../runner/docker-images/microvm/README.md) documents the consumer
+contract, including the required `USER`, `WORKDIR`, ownership and `git reset --quiet`
+steps.
 
-The image bakes your repository checked out but not installed and makes no assumptions about
-its package manager. To speed up first boot, install dependencies from your overlay's
-`setup-workspace`; otherwise, the agent installs them on first use.
+The staged image includes your repository checkout, while your Dockerfile controls its
+package manager and build warm-up. Do not copy credentials into the build context or bake
+them into image environment variables.
 
 | MicroVM prop | Omitted behavior |
 | --- | --- |
@@ -174,12 +210,27 @@ its package manager. To speed up first boot, install dependencies from your over
 | `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.
+| `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 `controllerSigningSecret`). 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 environment for the image. 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.
+
+## Breaking changes in this release
+
+- `stageMicrovmImageContext` is removed. Use `stageMicrovmBuildContext()` with your
+  Dockerfile and build context.
+- `imageSource` is renamed to `buildContextPath`.
+- `MicrovmShape.constructId` is removed. CloudFormation child identity derives from
+  the shape `name`.
+- `doorbellSecret` is renamed to `controllerSigningSecret`.
+- The default shape's `imageName` changes to `evident-microvm-standard`. The
+  `AWS::Lambda::MicrovmImage` resource, its auto-created build role and execution
+  role, and both roles' default policies are replaced with the new shape identity.
+- The JSON field in the caller-supplied Secrets Manager secret changes from
+  `DOORBELL_SECRET` to `CONTROLLER_SIGNING_SECRET`. Rename that field in your own
+  secret. If you do not, the controller reads no signing key and every doorbell
+  returns HTTP 401 at runtime; TypeScript cannot catch this field-key change.
 
 ## Status / limitations
 

package/dist/controller-lambda/handler.js

@@ -49799,9 +49799,9 @@ var MICROVM_MAX_RUN_SECONDS = 28800;
 // src/microvm/controller/handle-doorbell.ts
 var import_node_crypto12 = require("node:crypto");
 
-// ../webhook-signature/src/verify-wake-signature.ts
+// ../../sdk/src/signature.ts
 var import_node_crypto11 = require("node:crypto");
-function verifyWakeSignature(rawBody, signatureHeader, secret) {
+function verifyEvidentSignature(rawBody, signatureHeader, secret) {
   if (!signatureHeader || !secret) {
     return false;
   }
@@ -49818,7 +49818,7 @@ function verifyWakeSignature(rawBody, signatureHeader, secret) {
   return (0, import_node_crypto11.timingSafeEqual)(providedBuffer, expectedBuffer);
 }
 
-// src/microvm/controller/doorbell.ts
+// src/microvm/controller/doorbell-request.ts
 var WAKE_EVENT_TYPES = ["agent.message_queued", "agent.wake_requested"];
 var SUSPEND_EVENT_TYPE = "runner.suspend_requested";
 var SHAPES_EVENT_TYPE = "runner.shapes_requested";
@@ -49838,7 +49838,7 @@ function nonBlankString(value) {
 function isWakeType(value) {
   return WAKE_EVENT_TYPES.includes(value);
 }
-function parseDoorbell(rawBody) {
+function parseDoorbellRequest(rawBody) {
   let body;
   try {
     body = JSON.parse(rawBody);
@@ -49979,9 +49979,9 @@ function decide({
     action: { kind: action }
   };
 }
-function clientTokenFor(doorbell) {
-  const generation = doorbell.microvmId ?? doorbell.occurredAt;
-  return (0, import_node_crypto12.createHash)("sha256").update(`${doorbell.runnerId}:${generation}`).digest("hex");
+function clientTokenFor(doorbellRequest) {
+  const generation = doorbellRequest.microvmId ?? doorbellRequest.occurredAt;
+  return (0, import_node_crypto12.createHash)("sha256").update(`${doorbellRequest.runnerId}:${generation}`).digest("hex");
 }
 function parseImageVersion(value) {
   const parts = value.trim().split(".");
@@ -50001,17 +50001,17 @@ function compareImageVersions(a7, b7) {
   }
   return 0;
 }
-async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, microvm) {
+async function shouldRecreateForNewerImage(doorbellRequest, shape, runningVersion, microvm) {
   if (runningVersion === void 0) {
     console.warn(
-      `[doorbell] GetMicrovm reported no imageVersion for runner ${doorbell.runnerId}; resuming`
+      `[doorbell] GetMicrovm reported no imageVersion for runner ${doorbellRequest.runnerId}; resuming`
     );
     return false;
   }
   const running = parseImageVersion(runningVersion);
   if (running === void 0) {
     console.warn(
-      `[doorbell] unparseable running imageVersion "${runningVersion}" for runner ${doorbell.runnerId}; resuming`
+      `[doorbell] unparseable running imageVersion "${runningVersion}" for runner ${doorbellRequest.runnerId}; resuming`
     );
     return false;
   }
@@ -50020,14 +50020,14 @@ async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, micr
     latestVersion = await microvm.latestImageVersion(shape.imageArn);
   } catch (error3) {
     console.warn(
-      `[doorbell] GetMicrovmImage failed for runner ${doorbell.runnerId}; resuming on the running image ${runningVersion}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] GetMicrovmImage failed for runner ${doorbellRequest.runnerId}; resuming on the running image ${runningVersion}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return false;
   }
   const latest = latestVersion === void 0 ? void 0 : parseImageVersion(latestVersion);
   if (latest === void 0) {
     console.warn(
-      `[doorbell] no comparable latest image version (${latestVersion ?? "none"}) for runner ${doorbell.runnerId}; resuming on the running image ${runningVersion}`
+      `[doorbell] no comparable latest image version (${latestVersion ?? "none"}) for runner ${doorbellRequest.runnerId}; resuming on the running image ${runningVersion}`
     );
     return false;
   }
@@ -50036,20 +50036,20 @@ async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, micr
 async function handleDoorbell({
   rawBody,
   signatureHeader,
-  doorbellSecret,
+  controllerSigningSecret,
   shapes,
   microvm,
   sleep: sleep4,
   random
 }) {
-  if (!verifyWakeSignature(rawBody, signatureHeader, doorbellSecret)) {
+  if (!verifyEvidentSignature(rawBody, signatureHeader, controllerSigningSecret)) {
     return decide({
       statusCode: 401,
       action: "rejected",
       reason: REASON.invalidSignature
     });
   }
-  const parsed = parseDoorbell(rawBody);
+  const parsed = parseDoorbellRequest(rawBody);
   if (!parsed.ok) {
     return decide({
       statusCode: 400,
@@ -50057,9 +50057,9 @@ async function handleDoorbell({
       reason: parsed.reason
     });
   }
-  const doorbell = parsed.doorbell;
+  const doorbellRequest = parsed.doorbell;
   const timing = { sleep: sleep4, random };
-  if (doorbell.type === SHAPES_EVENT_TYPE) {
+  if (doorbellRequest.type === SHAPES_EVENT_TYPE) {
     return decide({
       statusCode: 200,
       action: "describe",
@@ -50067,43 +50067,43 @@ async function handleDoorbell({
       shapes: shapes.advertise()
     });
   }
-  if (doorbell.type !== "runner.suspend_requested") {
-    const resolvedShape = shapes.resolve(doorbell.shape);
+  if (doorbellRequest.type !== "runner.suspend_requested") {
+    const resolvedShape = shapes.resolve(doorbellRequest.shape);
     if (resolvedShape === void 0) {
       return decide({
         statusCode: 400,
         action: "rejected",
         reason: REASON.unknownShape,
-        runnerId: doorbell.runnerId,
-        microvmId: doorbell.microvmId
+        runnerId: doorbellRequest.runnerId,
+        microvmId: doorbellRequest.microvmId
       });
     }
-    return handleWakeDoorbell(doorbell, resolvedShape, microvm, timing);
+    return handleWakeDoorbell(doorbellRequest, resolvedShape, microvm, timing);
   }
-  return suspendMicrovm(doorbell, microvm, timing);
+  return suspendMicrovm(doorbellRequest, microvm, timing);
 }
-async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
-  if (doorbell.microvmId === void 0) {
-    return runMicrovm(doorbell, shape, microvm, timing, false, REASON.noMicrovmId);
+async function handleWakeDoorbell(doorbellRequest, shape, microvm, timing) {
+  if (doorbellRequest.microvmId === void 0) {
+    return runMicrovm(doorbellRequest, shape, microvm, timing, false, REASON.noMicrovmId);
   }
   let described;
   let polled = false;
   try {
-    described = await microvm.describe(doorbell.microvmId);
+    described = await microvm.describe(doorbellRequest.microvmId);
     if (described.state === "SUSPENDING") {
-      described = await pollWhileSuspending(doorbell.microvmId, microvm, timing.sleep);
+      described = await pollWhileSuspending(doorbellRequest.microvmId, microvm, timing.sleep);
       polled = true;
     }
   } catch (error3) {
     console.error(
-      `[doorbell] GetMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] GetMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return decide({
       statusCode: 500,
       action: "none",
       reason: REASON.getStateFailed,
-      runnerId: doorbell.runnerId,
-      microvmId: doorbell.microvmId
+      runnerId: doorbellRequest.runnerId,
+      microvmId: doorbellRequest.microvmId
     });
   }
   const state3 = described.state;
@@ -50113,8 +50113,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
       action: "none",
       reason: REASON.suspendingPollExhausted,
       state: state3,
-      runnerId: doorbell.runnerId,
-      microvmId: doorbell.microvmId,
+      runnerId: doorbellRequest.runnerId,
+      microvmId: doorbellRequest.microvmId,
       polled
     });
   }
@@ -50126,16 +50126,16 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         action: "none",
         reason: state3 === "RUNNING" ? REASON.alreadyRunning : REASON.alreadyStarting,
         state: state3,
-        runnerId: doorbell.runnerId,
-        microvmId: doorbell.microvmId,
+        runnerId: doorbellRequest.runnerId,
+        microvmId: doorbellRequest.microvmId,
         polled,
         startedAt: described.startedAt,
         imageVersion: described.imageVersion
       });
     case "SUSPENDED":
-      if (doorbell.recreateOnOutdatedImage === true && await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
+      if (doorbellRequest.recreateOnOutdatedImage === true && await shouldRecreateForNewerImage(doorbellRequest, shape, described.imageVersion, microvm)) {
         return runMicrovm(
-          doorbell,
+          doorbellRequest,
           shape,
           microvm,
           timing,
@@ -50145,8 +50145,8 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         );
       }
       return resumeMicrovm(
-        doorbell,
-        doorbell.microvmId,
+        doorbellRequest,
+        doorbellRequest.microvmId,
         shape,
         microvm,
         timing,
@@ -50156,7 +50156,7 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
       );
     default:
       return runMicrovm(
-        doorbell,
+        doorbellRequest,
         shape,
         microvm,
         timing,
@@ -50182,14 +50182,14 @@ function isClientTokenParameterMismatch(error3) {
   const message = typeof e7.message === "string" ? e7.message.toLowerCase() : "";
   return message.includes("clienttoken") && message.includes("different request parameters");
 }
-async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, state3) {
+async function runMicrovm(doorbellRequest, shape, microvm, timing, polled, reason, state3) {
   let started;
   try {
     started = await withThrottleRetry(
       () => microvm.run({
         imageIdentifier: shape.imageArn,
-        runHookPayload: doorbell.runHookPayload,
-        clientToken: clientTokenFor(doorbell)
+        runHookPayload: doorbellRequest.runHookPayload,
+        clientToken: clientTokenFor(doorbellRequest)
       }),
       timing
     );
@@ -50198,26 +50198,26 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
       const name = error3 instanceof Error ? error3.name : "unknown";
       const message = error3 instanceof Error ? error3.message : String(error3);
       console.warn(
-        `[doorbell] RunMicrovm clientToken already used for runner ${doorbell.runnerId}: ${name}: ${message}`
+        `[doorbell] RunMicrovm clientToken already used for runner ${doorbellRequest.runnerId}: ${name}: ${message}`
       );
       return decide({
         statusCode: 200,
         action: "run",
         reason: REASON.runAlreadyStartedForToken,
         state: state3,
-        runnerId: doorbell.runnerId,
+        runnerId: doorbellRequest.runnerId,
         polled
       });
     }
     console.error(
-      `[doorbell] RunMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] RunMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return decide({
       statusCode: 500,
       action: "run",
       reason: REASON.runFailed,
       state: state3,
-      runnerId: doorbell.runnerId,
+      runnerId: doorbellRequest.runnerId,
       polled
     });
   }
@@ -50226,22 +50226,22 @@ async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, stat
     action: "run",
     reason,
     state: state3,
-    runnerId: doorbell.runnerId,
+    runnerId: doorbellRequest.runnerId,
     microvmId: started.microvmId,
     polled,
     startedAt: started.startedAt,
     imageVersion: started.imageVersion
   });
 }
-async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, startedAt, imageVersion) {
+async function resumeMicrovm(doorbellRequest, microvmId, shape, microvm, timing, polled, startedAt, imageVersion) {
   try {
     await withThrottleRetry(() => microvm.resume(microvmId), timing);
   } catch (error3) {
     console.error(
-      `[doorbell] ResumeMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] ResumeMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return runMicrovm(
-      doorbell,
+      doorbellRequest,
       shape,
       microvm,
       timing,
@@ -50255,21 +50255,21 @@ async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled
     action: "resume",
     reason: REASON.resumed,
     state: "SUSPENDED",
-    runnerId: doorbell.runnerId,
+    runnerId: doorbellRequest.runnerId,
     microvmId,
     polled,
     startedAt,
     imageVersion
   });
 }
-async function suspendMicrovm(doorbell, microvm, timing) {
-  const microvmId = doorbell.microvmId;
+async function suspendMicrovm(doorbellRequest, microvm, timing) {
+  const microvmId = doorbellRequest.microvmId;
   if (microvmId === void 0) {
     return decide({
       statusCode: 200,
       action: "none",
       reason: REASON.suspendWithoutMicrovmId,
-      runnerId: doorbell.runnerId
+      runnerId: doorbellRequest.runnerId
     });
   }
   let state3;
@@ -50277,13 +50277,13 @@ async function suspendMicrovm(doorbell, microvm, timing) {
     ({ state: state3 } = await microvm.describe(microvmId));
   } catch (error3) {
     console.error(
-      `[doorbell] GetMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] GetMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return decide({
       statusCode: 500,
       action: "none",
       reason: REASON.getStateFailed,
-      runnerId: doorbell.runnerId,
+      runnerId: doorbellRequest.runnerId,
       microvmId
     });
   }
@@ -50293,7 +50293,7 @@ async function suspendMicrovm(doorbell, microvm, timing) {
       action: "none",
       reason: REASON.suspendAlreadyGone,
       state: state3,
-      runnerId: doorbell.runnerId,
+      runnerId: doorbellRequest.runnerId,
       microvmId
     });
   }
@@ -50301,14 +50301,14 @@ async function suspendMicrovm(doorbell, microvm, timing) {
     await withThrottleRetry(() => microvm.suspend(microvmId), timing);
   } catch (error3) {
     console.error(
-      `[doorbell] SuspendMicrovm failed for runner ${doorbell.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
+      `[doorbell] SuspendMicrovm failed for runner ${doorbellRequest.runnerId}: ${error3 instanceof Error ? error3.message : String(error3)}`
     );
     return decide({
       statusCode: 500,
       action: "suspend",
       reason: REASON.suspendFailed,
       state: state3,
-      runnerId: doorbell.runnerId,
+      runnerId: doorbellRequest.runnerId,
       microvmId
     });
   }
@@ -50317,7 +50317,7 @@ async function suspendMicrovm(doorbell, microvm, timing) {
     action: "suspend",
     reason: REASON.suspended,
     state: state3,
-    runnerId: doorbell.runnerId,
+    runnerId: doorbellRequest.runnerId,
     microvmId
   });
 }
@@ -50413,20 +50413,20 @@ function parseShapeCatalogue(raw) {
 // src/microvm/controller/handler.ts
 var microvms = new import_client_lambda_microvms.LambdaMicrovmsClient({});
 var secrets = new import_client_secrets_manager.SecretsManagerClient({});
-var cachedDoorbellSecret;
-async function getDoorbellSecret(secretArn, key) {
-  if (cachedDoorbellSecret !== void 0) {
-    return cachedDoorbellSecret;
+var cachedControllerSigningSecret;
+async function getControllerSigningSecret(secretArn, key) {
+  if (cachedControllerSigningSecret !== void 0) {
+    return cachedControllerSigningSecret;
   }
   const { SecretString } = await secrets.send(new import_client_secrets_manager.GetSecretValueCommand({ SecretId: secretArn }));
   if (!SecretString) {
-    throw new Error(`doorbell secret ${secretArn} has no SecretString`);
+    throw new Error(`controller signing secret ${secretArn} has no SecretString`);
   }
   const value = JSON.parse(SecretString)[key];
   if (typeof value !== "string" || value === "") {
-    throw new Error(`doorbell secret ${secretArn} is missing a non-empty '${key}' field`);
+    throw new Error(`controller signing secret ${secretArn} is missing a non-empty '${key}' field`);
   }
-  cachedDoorbellSecret = value;
+  cachedControllerSigningSecret = value;
   return value;
 }
 function createRuntimeMicrovm(executionRoleArn) {
@@ -50468,14 +50468,9 @@ function createRuntimeMicrovm(executionRoleArn) {
           // No `idlePolicy` (AC5, #732) — deliberately, not an oversight.
           // `maxIdleDurationSeconds` measures INBOUND endpoint traffic only; our
           // runner is outbound-only (it dials the Cloudflare relay), so AWS sees
-          // an idle endpoint no matter how busy the agent is. Phase 0 measured
-          // this directly: a VM with `maxIdleDurationSeconds=60` and zero inbound
-          // traffic was suspended after 71 s while its guest process was alive
-          // and working (docs/spikes/lambda-microvms-phase0/README.md). AWS's own
-          // Claude-agents guidance recommending `maxIdleDurationSeconds: 120`
-          // targets VMs reached inbound and does not apply here. Idle is instead
+          // an idle endpoint no matter how busy the agent is. Idle is instead
           // decided IN the VM by `evident run --idle-timeout`
-          // (packages/runner-cdk/microvm-image/hooks/common.sh's `IDLE_TIMEOUT_SECONDS`), whose
+          // (runner/docker-images/microvm/hooks/common.sh's `IDLE_TIMEOUT_SECONDS`), whose
           // clean exit is what drives the controller's own `suspend()` below via
           // the `runner.suspend_requested` doorbell. See `idle-policy.test.ts`
           // in this directory, which scans this file's source for the key and
@@ -50506,9 +50501,9 @@ function requireEnv(name) {
 }
 var sleep3 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var handler = async (event) => {
-  const doorbellSecret = await getDoorbellSecret(
-    requireEnv("DOORBELL_SECRET_ARN"),
-    requireEnv("DOORBELL_SECRET_KEY")
+  const controllerSigningSecret = await getControllerSigningSecret(
+    requireEnv("CONTROLLER_SIGNING_SECRET_ARN"),
+    requireEnv("CONTROLLER_SIGNING_SECRET_KEY")
   );
   const shapes = parseShapeCatalogue(requireEnv("MICROVM_SHAPES"));
   const executionRoleArn = requireEnv("MICROVM_EXECUTION_ROLE_ARN");
@@ -50516,7 +50511,7 @@ var handler = async (event) => {
   const { statusCode, body } = await handleDoorbell({
     rawBody,
     signatureHeader: event.headers?.["x-evident-signature"],
-    doorbellSecret,
+    controllerSigningSecret,
     shapes,
     microvm: createRuntimeMicrovm(executionRoleArn),
     sleep: sleep3,

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

@@ -157,6 +157,13 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
         // Object Get/Put/Delete scoped to this agent's prefix. DeleteObject is
         // required: Litestream's retention/compaction prunes old LTX files.
         replicaBucket.grantReadWrite(taskRole, `${this.replicaPrefix}/*`);
+        // Vault credentials are read and conditionally written, so this shared prefix
+        // needs no delete or list permission; conditional writes use request headers.
+        taskRole.addToPrincipalPolicy(new iam.PolicyStatement({
+            sid: 'ReadWriteCredentialVaultObjects',
+            actions: ['s3:GetObject', 's3:PutObject'],
+            resources: [replicaBucket.arnForObjects('credential-vaults/*')],
+        }));
         this.service = new ecs.FargateService(this, 'Service', {
             cluster,
             taskDefinition,