@evident-ai/runner-cdk 3.4.1-dev.59c7df3 → 3.4.1-dev.6f7da9c

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

@@ -66,8 +66,8 @@ function isShallowRepository(repositoryPath) {
     }
 }
 /**
- * Clones the caller's repository into the build context, so the Dockerfile can
- * ship the workspace already installed.
+ * Clones the caller's repository into the build context for the Dockerfile to
+ * bake as a checked-out but uninstalled workspace.
  *
  * `file://` rather than a plain path: a path triggers git's local-clone
  * optimisation, which copies the whole object store — every branch and worktree
@@ -102,21 +102,37 @@ function stageRepository(repositoryPath, destination, originUrl) {
     (0, node_fs_1.rmSync)(path.join(destination, '.git', 'index'), { force: true });
     (0, node_fs_1.rmSync)(path.join(destination, '.git', 'logs'), { recursive: true, force: true });
     console.log(`[stage] repo ${git(['rev-parse', 'HEAD'], destination)}`);
-    if (!(0, node_fs_1.existsSync)(path.join(destination, 'pnpm-lock.yaml'))) {
-        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 +148,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-version-reporter/construct.d.ts

@@ -0,0 +1,35 @@
+import { Construct } from 'constructs';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import type { MicrovmImageBuildInputs } from '@evident-ai/lambda-microvm-cdk';
+export type ImageVersionReporterProps = {
+    /** The secret whose value is the same HMAC key the controller verifies every doorbell against. */
+    doorbellSecret: secretsmanager.ISecret;
+    /** Base URL of Evident's own API — non-secret. */
+    evidentApiUrl: string;
+    /** The pool runner id the report is filed against — non-secret, public UUID. */
+    evidentRunnerId: string;
+    /** Shape name -> the `Fn::GetAtt LatestActiveImageVersion` published this deploy. */
+    imageVersions: Record<string, string>;
+    /**
+     * Shape name -> {@link MicrovmImageBuildInputs}, a STRUCTURED object (never
+     * a delimiter-joined string — see its docstring for why flattening is
+     * unsafe) that changes whenever THIS deploy's build inputs change. Unlike
+     * `imageVersions`' `Fn::GetAtt` (a runtime attribute of the MicroVM image
+     * service, whose deploy-time propagation to a dependent resource this
+     * construct cannot itself guarantee), every field here is either a
+     * synth-time-computed literal or a plain `Ref`/`Fn::GetAtt` to a resource
+     * IN THIS STACK — CloudFormation diffs the full resolved property tree, so
+     * a change anywhere in this object is a certain, not merely likely,
+     * re-invocation trigger.
+     */
+    buildTriggers: Record<string, MicrovmImageBuildInputs>;
+};
+/**
+ * Deploy-time push: reports each shape's just-published MicroVM image version to
+ * Evident, once per deploy that actually changes it. `imageVersions` is the
+ * payload; `buildTriggers` is what guarantees re-invocation on exactly the
+ * deploy that matters, independent of `imageVersions`' own resolution timing.
+ */
+export declare class ImageVersionReporter extends Construct {
+    constructor(scope: Construct, id: string, props: ImageVersionReporterProps);
+}

package/dist/microvm/image-version-reporter/construct.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImageVersionReporter = void 0;
+const path = __importStar(require("path"));
+const cdk = __importStar(require("aws-cdk-lib"));
+const constructs_1 = require("constructs");
+const lambda = __importStar(require("aws-cdk-lib/aws-lambda"));
+const cr = __importStar(require("aws-cdk-lib/custom-resources"));
+/** The JSON field name inside the doorbell secret, same key the controller reads. */
+const DOORBELL_SECRET_KEY = 'DOORBELL_SECRET';
+/**
+ * Deploy-time push: reports each shape's just-published MicroVM image version to
+ * Evident, once per deploy that actually changes it. `imageVersions` is the
+ * payload; `buildTriggers` is what guarantees re-invocation on exactly the
+ * deploy that matters, independent of `imageVersions`' own resolution timing.
+ */
+class ImageVersionReporter extends constructs_1.Construct {
+    constructor(scope, id, props) {
+        super(scope, id);
+        const handler = new lambda.Function(this, 'Function', {
+            runtime: lambda.Runtime.NODEJS_22_X,
+            // Pre-bundled at PACKAGE build time, same reasoning as the waker's and the
+            // controller's own `Code.fromAsset` (see their comments) — resolved from
+            // the PACKAGE ROOT, two directories below this file either compiled
+            // (`dist/microvm/image-version-reporter`) or via ts-node
+            // (`src/microvm/image-version-reporter`).
+            code: lambda.Code.fromAsset(path.join(__dirname, '..', '..', '..', 'dist', 'image-version-reporter-lambda')),
+            handler: 'handler.handler',
+            memorySize: 128,
+            // A deploy hook must not hold CloudFormation for its default 1 h — this is
+            // the hard stop; the handler's own internal REPORT_TIMEOUT_MS is well under it.
+            timeout: cdk.Duration.seconds(30),
+            environment: {
+                // ARN + field name only, never the value (mirrors the controller and waker).
+                DOORBELL_SECRET_ARN: props.doorbellSecret.secretArn,
+                DOORBELL_SECRET_KEY: DOORBELL_SECRET_KEY,
+                EVIDENT_API_URL: props.evidentApiUrl,
+                EVIDENT_RUNNER_ID: props.evidentRunnerId,
+            },
+        });
+        props.doorbellSecret.grantRead(handler);
+        const provider = new cr.Provider(this, 'Provider', {
+            onEventHandler: handler,
+        });
+        new cdk.CustomResource(this, 'Resource', {
+            serviceToken: provider.serviceToken,
+            properties: {
+                imageVersions: props.imageVersions,
+                // Not read by the handler — its only job is to be a property value
+                // CloudFormation can see change (a structured object, so any field
+                // changing anywhere is a real property diff), so the resource is
+                // invoked on exactly the deploy that changes a build input.
+                buildTriggers: props.buildTriggers,
+            },
+        });
+    }
+}
+exports.ImageVersionReporter = ImageVersionReporter;

package/dist/microvm/image-version-reporter/handler.d.ts

@@ -0,0 +1,26 @@
+export type ImageVersionPair = {
+    shape: string;
+    image_version: string;
+};
+export type ReporterEvent = {
+    RequestType: 'Create' | 'Update' | 'Delete';
+    ResourceProperties?: {
+        imageVersions?: unknown;
+    };
+};
+export type ReporterConfig = {
+    doorbellSecretArn: string;
+    doorbellSecretKey: string;
+    evidentApiUrl: string;
+    evidentRunnerId: string;
+};
+type ReporterDependencies = {
+    getSecret: (secretArn: string, secretKey: string) => Promise<string>;
+    fetch: typeof fetch;
+};
+type ReporterResponse = {
+    PhysicalResourceId: string;
+};
+export declare function handleImageVersionReport(event: ReporterEvent, getConfig: () => ReporterConfig, dependencies?: ReporterDependencies): Promise<ReporterResponse>;
+export declare const handler: (event: ReporterEvent) => Promise<ReporterResponse>;
+export {};

package/dist/microvm/image-version-reporter/handler.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = void 0;
+exports.handleImageVersionReport = handleImageVersionReport;
+const node_crypto_1 = require("node:crypto");
+const client_secrets_manager_1 = require("@aws-sdk/client-secrets-manager");
+const PHYSICAL_RESOURCE_ID = 'evident-image-version-report';
+const REPORT_TIMEOUT_MS = 5_000;
+const secrets = new client_secrets_manager_1.SecretsManagerClient({});
+async function fetchDoorbellSecret(secretArn, secretKey) {
+    const { SecretString } = await secrets.send(new client_secrets_manager_1.GetSecretValueCommand({ SecretId: secretArn }));
+    if (!SecretString) {
+        throw new Error(`doorbell secret ${secretArn} has no SecretString`);
+    }
+    const parsed = JSON.parse(SecretString);
+    const value = parsed !== null && typeof parsed === 'object'
+        ? parsed[secretKey]
+        : undefined;
+    if (typeof value !== 'string' || value === '') {
+        throw new Error(`doorbell secret ${secretArn} is missing a non-empty '${secretKey}' field`);
+    }
+    return value;
+}
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`missing required env var ${name}`);
+    }
+    return value;
+}
+function readImageVersions(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('imageVersions must be an object');
+    }
+    return Object.entries(value).map(([shape, imageVersion]) => {
+        if (typeof imageVersion !== 'string') {
+            throw new Error(`imageVersions.${shape} must be a string`);
+        }
+        return { shape, image_version: imageVersion };
+    });
+}
+function response() {
+    return { PhysicalResourceId: PHYSICAL_RESOURCE_ID };
+}
+const runtimeDependencies = {
+    getSecret: fetchDoorbellSecret,
+    fetch: globalThis.fetch,
+};
+async function handleImageVersionReport(event, getConfig, dependencies = runtimeDependencies) {
+    if (event.RequestType === 'Delete') {
+        return response();
+    }
+    let runnerId = 'unknown';
+    let versions = [];
+    let responseStatus;
+    try {
+        versions = readImageVersions(event.ResourceProperties?.imageVersions);
+        const config = getConfig();
+        runnerId = config.evidentRunnerId;
+        const secret = await dependencies.getSecret(config.doorbellSecretArn, config.doorbellSecretKey);
+        const body = JSON.stringify({
+            type: 'runner.microvm_image_versions_reported',
+            versions,
+        });
+        const signature = (0, node_crypto_1.createHmac)('sha256', secret).update(body).digest('hex');
+        const url = `${config.evidentApiUrl.replace(/\/+$/, '')}/v1/runners/${encodeURIComponent(runnerId)}/microvm-image-versions`;
+        const result = await dependencies.fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-evident-signature': signature,
+            },
+            body,
+            signal: AbortSignal.timeout(REPORT_TIMEOUT_MS),
+        });
+        responseStatus = result.status;
+        console.log('runner.microvm_image_versions_reported', {
+            runnerId,
+            versions,
+            status: result.status,
+        });
+        if (!result.ok) {
+            throw new Error(`Evident returned HTTP ${result.status}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn('MicroVM image version report failed', {
+            operation: event.RequestType,
+            runnerId,
+            versions,
+            ...(responseStatus === undefined ? {} : { status: responseStatus }),
+            error: message,
+        });
+    }
+    return response();
+}
+const handler = (event) => handleImageVersionReport(event, () => ({
+    doorbellSecretArn: requireEnv('DOORBELL_SECRET_ARN'),
+    doorbellSecretKey: requireEnv('DOORBELL_SECRET_KEY'),
+    evidentApiUrl: requireEnv('EVIDENT_API_URL'),
+    evidentRunnerId: requireEnv('EVIDENT_RUNNER_ID'),
+}));
+exports.handler = handler;

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, dependency
+# installation 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 \
@@ -150,8 +130,8 @@ COPY hook-server.js /usr/local/lib/evident/hook-server.js
 COPY hooks /etc/evident/hooks
 
 # Workspace: the repository the agent works on, baked in. A resumed VM must be
-# useful in milliseconds, and a clone + install costs minutes — so both happen
-# here, and the image is deliberately large in exchange.
+# useful in milliseconds, while a clone costs minutes — so the checkout happens
+# here; dependency installation and build warm-up belong to the deployment overlay.
 #
 # This does not weaken the boot split: source, git history and node_modules are
 # neither secret nor per-VM-unique, so sharing them across every VM from this
@@ -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,36 +171,13 @@ 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.
-#
-# 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
-# only survive within a single layer — split in two and the image carries both
-# copies. `--frozen-lockfile` because the committed lockfile is the whole reason
-# this is bakeable at all: installing against anything else would bake a
-# dependency set nobody committed.
-#
-# Guarded on a committed `pnpm-lock.yaml` so `microvm:repositoryPath` can point
-# 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.
+# Deployment-specific dependency installation and build work belongs here. This runs
+# as `runner` in `${WORKSPACE}`, so everything it writes is agent-writable.
 #
-# 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).
-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'; \
-    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."; \
-    fi
+# Keep the overlay's install and build in one layer: pnpm hard-links `node_modules`
+# into its content-addressed store, and hard links only survive within a single layer.
+RUN /etc/evident/overlay/setup-workspace
 
-# 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
 # Port AWS calls the MicroVM hooks on.
 ENV HOOKS_PORT=8080
 # OpenCode loopback port the CLI tunnels to (matches `evident run` default).