@evident-ai/runner-cdk 3.4.1-dev.cb56b3f → 3.4.1-dev.e91ca26

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,16 +172,21 @@ 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
 
 - **Published to npm** as `@evident-ai/runner-cdk` (MIT). Install the `@dev` tag —
   `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
@@ -50128,7 +50133,7 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
         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,

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/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

package/dist/microvm/construct.js

@@ -141,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 = {

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

@@ -129,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
@@ -287,11 +286,12 @@ async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
                 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, described.imageVersion);

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;

package/dist/microvm/image/stage-context.js

@@ -106,17 +106,36 @@ function stageRepository(repositoryPath, destination, originUrl) {
         console.log(`[stage] ${repositoryPath} has no pnpm-lock.yaml — the image build will skip dependency installation`);
     }
 }
+function stageScriptDirectory(source, destination) {
+    (0, node_fs_1.mkdirSync)(destination);
+    for (const entry of (0, node_fs_1.readdirSync)(source, { withFileTypes: true })) {
+        const sourcePath = path.join(source, entry.name);
+        const staged = path.join(destination, entry.name);
+        if (entry.isDirectory()) {
+            stageScriptDirectory(sourcePath, staged);
+            continue;
+        }
+        (0, node_fs_1.copyFileSync)(sourcePath, staged);
+        // Set modes here rather than inheriting them from the template, so they stay
+        // correct after an npm pack, zip, CI-cache or hand-copy round trip. The image
+        // executes extensionless scripts and sources `.sh` files.
+        (0, node_fs_1.chmodSync)(staged, entry.name.endsWith('.sh') ? 0o644 : 0o755);
+    }
+}
 /**
  * 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.
  */
 function stageMicrovmImageContext(options) {
-    const { originUrl, templateDir = TEMPLATE_DIR } = options;
+    const { originUrl, overlayDir, templateDir = TEMPLATE_DIR } = options;
     // `file://` and the clone below only mean anything against absolute paths,
     // and a caller may reasonably pass either.
     const repositoryPath = path.resolve(options.repositoryPath);
@@ -132,16 +151,27 @@ function stageMicrovmImageContext(options) {
     (0, node_fs_1.copyFileSync)(path.join(templateDir, 'hook-server.js'), path.join(destination, 'hook-server.js'));
     const hooksSource = path.join(templateDir, 'hooks');
     const hooksStage = path.join(destination, 'hooks');
-    (0, node_fs_1.mkdirSync)(hooksStage);
-    for (const entry of (0, node_fs_1.readdirSync)(hooksSource)) {
-        const staged = path.join(hooksStage, entry);
-        (0, node_fs_1.copyFileSync)(path.join(hooksSource, entry), staged);
-        // The runtime only runs a hook it can execute. Set here rather than
-        // inherited from the template, so the staged mode is a property of THIS
-        // function rather than of however the template reached disk — `npm pack`
-        // does carry the bit, but a zip-based vendoring, a CI cache restore or a
-        // hand-copied directory need not.
-        (0, node_fs_1.chmodSync)(staged, entry.endsWith('.sh') ? 0o644 : 0o755);
+    stageScriptDirectory(hooksSource, hooksStage);
+    const overlayStage = path.join(destination, 'overlay');
+    if (overlayDir === undefined) {
+        (0, node_fs_1.mkdirSync)(overlayStage);
+        for (const name of ['setup-root', 'setup-workspace']) {
+            const staged = path.join(overlayStage, name);
+            (0, node_fs_1.writeFileSync)(staged, '#!/usr/bin/env bash\n# No overlay supplied.\n', { mode: 0o755 });
+            (0, node_fs_1.chmodSync)(staged, 0o755);
+        }
+    }
+    else {
+        const resolvedOverlayDir = path.resolve(overlayDir);
+        if (!(0, node_fs_1.existsSync)(resolvedOverlayDir)) {
+            throw new Error(`overlay directory does not exist: ${resolvedOverlayDir}`);
+        }
+        for (const required of ['setup-root', 'setup-workspace']) {
+            if (!(0, node_fs_1.existsSync)(path.join(resolvedOverlayDir, required))) {
+                throw new Error(`overlay directory ${resolvedOverlayDir} is missing required script ${required}`);
+            }
+        }
+        stageScriptDirectory(resolvedOverlayDir, overlayStage);
     }
     stageRepository(repositoryPath, path.join(destination, 'repo'), originUrl);
     return destination;

package/dist/microvm-image-context/Dockerfile

@@ -1,7 +1,9 @@
-# Evident per-session MicroVM image (#558, epic #556)
+# Generic MicroVM runner image
 #
-# Same installed footprint as the ECS runner image, built for linux/arm64
-# (Lambda MicroVMs run on Graviton only) and with ONE process: the hook server.
+# Built for linux/arm64 (Lambda MicroVMs run on Graviton only) and with ONE
+# process: the hook server. `overlay/setup-root` and
+# `overlay/setup-workspace` are the extension point for deployment-specific
+# packages and build warm-up.
 #
 # THE BOOT SPLIT — the rule that governs everything below. AWS snapshots this
 # image ONCE at build and every MicroVM resumes from that same snapshot, so
@@ -9,7 +11,8 @@
 # this image version. Therefore this image must NOT start the tunnel
 # (`evident run`), clone the repo, or carry any credential, machine ID or
 # generated secret. Identity arrives per-VM in the `/run` hook payload.
-# `src/image/dockerfile.test.ts` fails the build if this regresses.
+# `aws/runner-cdk/src/microvm/image/dockerfile.test.ts` fails the build if this
+# regresses.
 #
 # No `--platform` on FROM: AWS builds this natively on Graviton. Build it
 # locally with `docker build --platform linux/arm64`.
@@ -27,9 +30,8 @@ RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
 
 # System tooling + GitHub CLI + AWS CLI, in a single layer.
 #   - awscli (v2): required — durable-state persistence uses `aws s3`.
-#   - procps, postgresql(+contrib), direnv: required at RUNTIME so the VM is a
-#     full dev box for this repo (local Postgres on 5433 as the non-root runner,
-#     no sudo). Listed explicitly so apt keeps them.
+#   - procps: required at RUNTIME for process inspection and debugging. Listed
+#     explicitly so apt keeps it.
 #   - gnupg, unzip: BUILD-ONLY (gh apt key / AWS CLI bundle); purged in this layer.
 #
 # Purge build-only packages BY NAME — do NOT use `apt-get autoremove`, which
@@ -38,7 +40,6 @@ RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
 RUN apt-get update \
   && apt-get install -y --no-install-recommends \
     ca-certificates curl git jq less procps psmisc ripgrep \
-    postgresql postgresql-contrib direnv \
     gnupg unzip \
   # --- GitHub CLI (`gh`) from the official apt repo ---
   && mkdir -p -m 755 /etc/apt/keyrings \
@@ -54,10 +55,6 @@ RUN apt-get update \
   && unzip -q /tmp/awscliv2.zip -d /tmp \
   && /tmp/aws/install \
   && aws --version \
-  # --- Put the PostgreSQL server binaries on PATH ---
-  #     On Debian initdb/pg_ctl/postgres/psql live under /usr/lib/postgresql/
-  #     <ver>/bin, not on PATH; symlink them into /usr/local/bin.
-  && ln -s /usr/lib/postgresql/*/bin/* /usr/local/bin/ 2>/dev/null || true \
   # --- Drop the build-only packages (BY NAME, no autoremove) + caches ---
   && apt-get purge -y gnupg unzip \
   && rm -rf /tmp/aws /tmp/awscliv2.zip /var/lib/apt/lists/*
@@ -87,7 +84,7 @@ RUN curl -fsSL -o /tmp/litestream.tar.gz \
 # floating `opencode-ai@latest` install was implicated in unbounded runner
 # memory growth / OOM kills. Keep it in lockstep with the ECS runner image's.
 # EVIDENT_CLI_VERSION is DELIBERATELY the floating `dev` tag, matching the ECS
-# runner image (infrastructure/evident-runner/src/base-image.ts). This is a
+# runner image. This is a
 # development environment: it should track the head of the CLI so changes are
 # testable without a version bump in every PR that touches a hook.
 # RUNNER_SYNCHRONISER_VERSION floats on `dev` for the identical reason.
@@ -104,27 +101,10 @@ RUN npm install -g \
   && evident --version \
   && npm cache clean --force
 
-# Playwright chromium + OS deps for E2E, baked at build time to avoid a slow
-# first-boot download.
-#
-# CRITICAL: this version MUST match the Playwright version the repo resolves for
-# `@playwright/test` (pnpm-lock.yaml → 1.58.0). The browser build is coupled to
-# the package version; if it drifts, a boot-time `playwright install`
-# re-downloads a different chromium. Bump in lockstep with @playwright/test.
-#
-# Browsers go to a SHARED PLAYWRIGHT_BROWSERS_PATH readable by the runtime
-# runner user (uid 10001), not root's ~/.cache.
-ENV PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright
-RUN npx playwright@1.58.0 install --with-deps chromium \
-  && chown -R 10001:10001 /opt/ms-playwright \
-  # Assert the browsers landed in the shared path (guard against a silent failure).
-  && test -n "$(ls -A /opt/ms-playwright 2>/dev/null)" \
-     || { echo "FATAL: Playwright browsers dir /opt/ms-playwright missing or empty after install" >&2; exit 1; }
-
 # Assert every REQUIRED runtime binary survived every layer above (fail loud).
 # Placed after the last install so it covers the apt purge, the litestream
 # extraction and the global npm installs in one pass.
-RUN for bin in ps pgrep pkill curl aws gh git jq rg psql pg_ctl initdb direnv litestream runner-synchroniser opencode evident timeout; do \
+RUN for bin in ps pgrep pkill curl aws gh git jq rg litestream runner-synchroniser opencode evident timeout; do \
        command -v "$bin" >/dev/null 2>&1 || { echo "FATAL: required binary '$bin' missing from image" >&2; exit 1; }; \
      done \
   && curl -fsS -o /dev/null https://cli.github.com \
@@ -162,8 +142,6 @@ COPY hooks /etc/evident/hooks
 # per-VM, so the agent is what brings this checkout up to date.
 ENV WORKSPACE=/workspace
 ENV HOME=/home/runner
-# Runner-owned PGDATA parent for the local dev Postgres cluster (initdb +
-# pg_ctl at boot, no sudo).
 #
 # The machine-id files are created EMPTY and runner-owned so that /run can
 # actually rewrite them: the hooks run as uid 10001, and neither `/etc` nor
@@ -171,10 +149,18 @@ ENV HOME=/home/runner
 # permanent no-op and every VM from this snapshot shares one machine id. Empty
 # is the correct unset state — it is the absence of an identity, so nothing
 # per-VM-unique enters the shared snapshot.
-RUN mkdir -p /var/lib/runner-pg /var/lib/dbus /home/runner/.local/state/evident \
+RUN mkdir -p /var/lib/dbus /home/runner/.local/state/evident \
   && install -o runner -g runner -m 0644 /dev/null /etc/machine-id \
   && install -o runner -g runner -m 0644 /dev/null /var/lib/dbus/machine-id \
-   && chown -R runner:runner /var/lib/runner-pg /home/runner
+  && chown -R runner:runner /home/runner
+
+# Deployment additions are always present because staging writes no-op defaults
+# when no overlay is supplied.
+COPY overlay /etc/evident/overlay
+# HOME is already /home/runner, so root-warmed npx/npm state must be runner-owned
+# or the runner's first npm/pnpm call would fail with EACCES.
+RUN /etc/evident/overlay/setup-root \
+  && chown -R runner:runner /home/runner
 COPY --chown=10001:10001 repo ${WORKSPACE}
 WORKDIR ${WORKSPACE}
 USER runner
@@ -185,8 +171,8 @@ USER runner
 # `runner` (not root) so the rebuilt index is runner-owned and writable later.
 RUN git reset --quiet
 
-# Dependencies and the shared builds everything else depends on. As the runner
-# user, so node_modules is writable by the agent's own later installs.
+# Dependencies for the baked workspace. Install as the runner user so
+# node_modules is writable by the agent's own later installs.
 #
 # ONE layer on purpose: pnpm hard-links node_modules into its content-addressed
 # store (which it puts at ${WORKSPACE}/.pnpm-store, gitignored), and hard links
@@ -199,22 +185,18 @@ RUN git reset --quiet
 # at a repository that is not a pnpm workspace at all: it is baked uninstalled
 # instead of failing the build, and the agent installs on first use.
 #
-# Nothing environment-specific is built: `vite build` inlines VITE_* at build
-# time and the migrations need a running Postgres, so the app builds and the dev
-# database stay per-VM (see entrypoint.sh's pre-warm in evident-runner).
+# Anything beyond dependency installation is deployment-specific and belongs in
+# `overlay/setup-workspace`.
 RUN if [ -f pnpm-lock.yaml ]; then \
-      pnpm install --frozen-lockfile \
-      && pnpm run build --filter='./packages/*' \
-        --filter='./aws/runner-cdk' \
-        --filter='./aws/lambda-microvm-cdk' \
-        --filter='./aws/lambda-microvm-runtime'; \
+      pnpm install --frozen-lockfile; \
     else \
-      echo "[workspace-prep] no pnpm-lock.yaml in the baked repository — skipping the dependency install and the workspace build; the agent installs on first use."; \
+      echo "[workspace-prep] no pnpm-lock.yaml in the baked repository — skipping the dependency install; the agent installs on first use."; \
     fi
 
-# Data dir for the local dev Postgres cluster; listens on 5433 to match this
-# repo's .envrc DSN postgres://postgres:postgres@localhost:5433/evident.
-ENV PGDATA=/var/lib/runner-pg/data
+# Runs as `runner` in `${WORKSPACE}`, after the install, so a project's build
+# output is writable by the agent.
+RUN /etc/evident/overlay/setup-workspace
+
 # Port AWS calls the MicroVM hooks on.
 ENV HOOKS_PORT=8080
 # OpenCode loopback port the CLI tunnels to (matches `evident run` default).

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

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

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

@@ -2,10 +2,8 @@
 #
 # Re-dial with the identity /run left behind. There is no step that could fetch
 # a fresh runner key, so the one from /run is what resumes. The CLI delegated by
-# start_tunnel owns the session-DB replicator's post-resume start. The interval
-# credential sync loop (#1868 WI-3) stays here because /suspend stops it too, so
-# a resumed VM that never restarted it here would never sync credentials again
-# for the rest of its life.
+# start_tunnel owns the credential loop and the session-DB replicator's
+# post-resume start.
 set -euo pipefail
 
 # shellcheck source=./common.sh
@@ -39,12 +37,18 @@ fi
   read -r runner_key
 } <"${CONTEXT_FILE}"
 
+# Restore the id so the resumed CLI can self-report and acknowledge any
+# outstanding recycle request (#1906). Older images may not have this file.
+if [ -s "${MICROVM_ID_FILE}" ]; then
+  MICROVM_ID="$(cat "${MICROVM_ID_FILE}")"
+  export MICROVM_ID
+fi
+
 # Tolerant, never fatal: a resume that fails costs the user their whole
 # session, so a broken durable-state config degrades to "no session-DB
 # replication" rather than a failed resume. The CLI's own guards handle the
 # rest — this needs no logic of its own.
 load_state_config || warn "could not resolve durable-state config; the session DB will not resume replicating"
-start_credential_sync
 
 # Diagnostic-only, unlike /run's gate: a failed resume costs the user their
 # whole session, so this never exits — it only converts a silent "resumed but
@@ -69,9 +73,8 @@ start_credential_sync
 # list, so a later edit cannot accidentally foreground the check again.
 ( check_runner_key "${runner_key}" "${api_url}" || true ) &
 
-# Not waited on: the CLI backs off and keeps retrying its own dial with no
-# attempt cap (apps/cli/src/lib/tunnel/connection.ts), and a control-plane
-# reclaim pass (the api-worker lifecycle cron) is what decides whether a
+# Not waited on: the Evident CLI backs off and keeps retrying its own dial with no
+# attempt cap, and Evident's control-plane reclaim pass is what decides whether a
 # runner that never reconnects gets suspended.
 start_tunnel "${runner_key}" "${api_url}" "${tunnel_url}"
 

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

@@ -28,7 +28,6 @@ cleanup() {
   stop_tunnel || warn "stop_tunnel failed while cleaning up"
   stop_opencode || warn "stop_opencode failed while cleaning up"
   kill_litestream || warn "kill_litestream failed while cleaning up"
-  stop_credential_sync || warn "stop_credential_sync failed while cleaning up"
 }
 trap cleanup EXIT
 
@@ -73,9 +72,12 @@ load_state_config || exit 1
 # it warns and this VM still boots.
 check_runner_key "${runner_key}" "${api_url}" || exit 1
 
-# 6 — the interval credential sync (#1868 WI-3). It stays before the context file
-# is written. Bare: every guard inside start_credential_sync is its own `return 0`.
-start_credential_sync
+# 6 — preserve the VM id across suspend/resume. The runtime always supplies it
+# for a /run hook, and the subshell keeps the persisted value protected.
+(
+  umask 077
+  printf '%s\n' "${MICROVM_ID}" >"${MICROVM_ID_FILE}"
+)
 
 # 7 — the first per-VM identity on the wire. The subshell's umask makes the file
 # unreadable to anyone else from the moment it exists, before the key is in it.
@@ -85,9 +87,8 @@ start_credential_sync
     >"${CONTEXT_FILE}"
 )
 
-# Not waited on: the CLI backs off and keeps retrying its own dial with no
-# attempt cap (apps/cli/src/lib/tunnel/connection.ts), and a control-plane
-# reclaim pass (the api-worker lifecycle cron) is what decides whether a
+# Not waited on: the Evident CLI backs off and keeps retrying its own dial with no
+# attempt cap, and Evident's control-plane reclaim pass is what decides whether a
 # runner that never connects gets suspended.
 start_tunnel "${runner_key}" "${api_url}" "${tunnel_url}" true true
 

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

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

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

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

package/dist/waker/construct.js

@@ -60,8 +60,7 @@ class EvidentWaker extends constructs_1.Construct {
             // dist/waker-lambda/handler.js, so neither this package's published npm
             // artifact (which ships dist/ already built) nor a consuming app needs
             // that private workspace package, or esbuild, on synth's PATH. Requires
-            // a build before synth when consuming this package via `workspace:*` —
-            // see infrastructure/evident-runner's README "local gate".
+            // a build before synth when consuming this package via `workspace:*`.
             //
             // Resolved from the PACKAGE ROOT (../.. ), not `__dirname` directly:
             // `__dirname` is `dist/waker` at runtime (compiled) but `src/waker` when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-cdk",
-  "version": "3.4.1-dev.cb56b3f",
+  "version": "3.4.1-dev.e91ca26",
   "description": "Reusable CDK constructs for an Evident agent runner: a single scale-to-zero Fargate runner (task + service + per-agent self-stop role + waker Lambda), or a per-session AWS Lambda MicroVM that boots on demand and suspends between messages. Instantiate once per agent from your own stack.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "pnpm run build-bundled-deps && ts-node scripts/build.ts",
-    "//build-bundled-deps": "scripts/build.ts esbuild-bundles runner/docker-images/microvm/hook-server.ts, which imports @evident-ai/lambda-microvm-runtime by its built `main`. @evident-ai/lambda-microvm-cdk is a workspace:* devDependency whose types resolve through its own dist/, so tsc --project tsconfig.build.json cannot compile src/microvm/{shapes,construct}.ts without it. Chained into `build` rather than left to turbo's `^build` because publish-runner-cdk.yaml and infrastructure/evident-runner's build-runner-cdk-dep invoke `pnpm --filter @evident-ai/runner-cdk build` directly, which bypasses turbo entirely.",
+    "//build-bundled-deps": "scripts/build.ts esbuild-bundles runner/docker-images/microvm/hook-server.ts, which imports @evident-ai/lambda-microvm-runtime by its built `main`. @evident-ai/lambda-microvm-cdk is a workspace:* devDependency whose types resolve through its own dist/, so tsc --project tsconfig.build.json cannot compile src/microvm/{shapes,construct}.ts without it. Chained into `build` rather than left to turbo's `^build` because callers outside turbo invoke `pnpm --filter @evident-ai/runner-cdk build` directly, which bypasses turbo entirely.",
     "build-bundled-deps": "pnpm --filter @evident-ai/lambda-microvm-cdk build && pnpm --filter @evident-ai/lambda-microvm-runtime build",
     "typecheck": "tsc --noEmit",
     "test": "node --test --require ts-node/register 'src/**/*.test.ts'",