@evident-ai/runner-cdk 3.4.1-dev.f80aa1c → 3.4.1-dev.fb92ede

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

@@ -541,7 +541,7 @@ 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
@@ -551,8 +551,8 @@ flush_session_db() {
 # to a 16 GB / 8 vCPU peak (~$1.06/h at sustained full load—a worst-case
 # ceiling, not an expectation); that is cheap enough that the balance
 # sits far nearer the floor than the ceiling. Not AT the floor, though: the
-# CLI's idle detector needs 2 clear poll cycles (`run.ts`'s `idlePolls >= 2`,
-# ≥4 s of real time), so a value near that would spend more time
+# 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.
@@ -647,14 +647,14 @@ 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) + 8.5 s pre-drain credential flush
+# 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;
-# the CLI points back here when its bounds change.
+# a guard in the source repository keeps this number in step with the CLI's
+# declared bounds.
 #
 # 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
@@ -820,7 +820,7 @@ stop_runner_and_flush_credentials() {
 # 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

@@ -73,9 +73,8 @@ load_state_config || warn "could not resolve durable-state config; the session D
 # 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

@@ -87,9 +87,8 @@ check_runner_key "${runner_key}" "${api_url}" || exit 1
     >"${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/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.f80aa1c",
+  "version": "3.4.1-dev.fb92ede",
   "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'",