@evident-ai/runner-cdk 0.1.1-dev.d96ef8a → 0.1.1-dev.da88f8e

package/README.md

@@ -9,9 +9,9 @@ Reusable AWS CDK constructs for running an [Evident](https://evident.run) agent
   `desiredCount 0`, and an HMAC-authenticated waker Lambda scales it back up on the next
   message. You pay for the time the agent is actually working.
 - **`EvidentMicrovmConstruct`** — a per-session AWS Lambda MicroVM that boots on demand
-  and suspends between messages. It is not yet at Fargate's install-only parity here:
-  building its runner image still means cloning the `sroze/evident` repo (tracked in
-  [#1528](https://github.com/sroze/evident/issues/1528)). See
+  and suspends between messages. Installing this package is all you need: the image build
+  context ships inside it (see [The MicroVM image](#the-microvm-image) below), so there is
+  no checkout of `sroze/evident` involved. See
   [the AWS runner doc](https://evident.run/docs/aws-runner) for the full picture of both
   strategies.
 
@@ -113,6 +113,49 @@ This construct never builds an image. Pass any `ecs.ContainerImage` — from a r
 built from a `Dockerfile` you control. The generic runner image lives separately in
 `packages/runner-image`, so you can adopt the image, the construct, or both.
 
+## The MicroVM image
+
+`EvidentMicrovmConstruct`'s `imageSource` is a **local directory** holding the image build
+context, which `cdk deploy` zips and uploads. The Lambda MicroVM service then builds the
+image in *your* account, from a base image ARN you discover there — so, unlike the Fargate
+strategy, there is no registry image to pull.
+
+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:
+
+```ts
+import {
+  EvidentMicrovmConstruct,
+  HOOKS_PORT,
+  HOOK_TIMEOUT_SECONDS,
+  stageMicrovmImageContext,
+} from '@evident-ai/runner-cdk';
+
+new EvidentMicrovmConstruct(this, 'Runner', {
+  imageSource: stageMicrovmImageContext({
+    // A full (non-shallow) clone: the agent branches, commits and opens PRs.
+    repositoryPath: '/path/to/your/checkout',
+    // Credential-free — this string ships inside the shared snapshot. The
+    // token the agent pushes with arrives per-session, never baked in.
+    originUrl: 'https://github.com/acme/widgets.git',
+    destination: path.join(__dirname, '..', 'build', 'image'),
+  }),
+  // Must match the published image these were baked into, so export them
+  // rather than restating the numbers.
+  hooksPort: HOOKS_PORT,
+  hookTimeoutSeconds: HOOK_TIMEOUT_SECONDS,
+  baseImageArn,
+  baseImageVersion,
+  doorbellSecret,
+});
+```
+
+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.
+
 ## Status / limitations
 
 - **Published to npm** as `@evident-ai/runner-cdk` (MIT) — see

package/dist/controller-lambda/handler.js

@@ -50464,7 +50464,7 @@ function createRuntimeMicrovm(executionRoleArn) {
           // Claude-agents guidance recommending `maxIdleDurationSeconds: 120`
           // targets VMs reached inbound and does not apply here. Idle is instead
           // decided IN the VM by `evident run --idle-timeout`
-          // (docker/hooks/common.sh's `IDLE_TIMEOUT_SECONDS`), whose
+          // (packages/runner-cdk/microvm-image/hooks/common.sh's `IDLE_TIMEOUT_SECONDS`), whose
           // clean exit is what drives the controller's own `suspend()` below via
           // the `runner.suspend_requested` doorbell. See `idle-policy.test.ts`
           // in this directory, which scans this file's source for the key and

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export { EvidentScaleToZeroConstruct, type EvidentScaleToZeroConstructProps, } f
 export { EvidentWaker, type EvidentWakerProps } from './waker/construct';
 export { EvidentMicrovmConstruct, type EvidentMicrovmConstructProps } from './microvm/construct';
 export { MICROVM_SHAPES, validateShapes, type MicrovmShape } from './microvm/shapes';
-export { MICROVM_MAX_RUN_SECONDS } from './microvm/constants';
+export { MICROVM_MAX_RUN_SECONDS, HOOKS_PORT, HOOK_TIMEOUT_SECONDS, } from './microvm/constants';
+export { stageMicrovmImageContext, type StageMicrovmImageContextOptions, } from './microvm/image/stage-context';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MICROVM_MAX_RUN_SECONDS = exports.validateShapes = exports.MICROVM_SHAPES = exports.EvidentMicrovmConstruct = exports.EvidentWaker = exports.EvidentScaleToZeroConstruct = void 0;
+exports.stageMicrovmImageContext = exports.HOOK_TIMEOUT_SECONDS = exports.HOOKS_PORT = exports.MICROVM_MAX_RUN_SECONDS = exports.validateShapes = exports.MICROVM_SHAPES = exports.EvidentMicrovmConstruct = exports.EvidentWaker = exports.EvidentScaleToZeroConstruct = void 0;
 var evident_scale_to_zero_construct_1 = require("./evident-scale-to-zero-construct");
 Object.defineProperty(exports, "EvidentScaleToZeroConstruct", { enumerable: true, get: function () { return evident_scale_to_zero_construct_1.EvidentScaleToZeroConstruct; } });
 var construct_1 = require("./waker/construct");
@@ -12,3 +12,9 @@ Object.defineProperty(exports, "MICROVM_SHAPES", { enumerable: true, get: functi
 Object.defineProperty(exports, "validateShapes", { enumerable: true, get: function () { return shapes_1.validateShapes; } });
 var constants_1 = require("./microvm/constants");
 Object.defineProperty(exports, "MICROVM_MAX_RUN_SECONDS", { enumerable: true, get: function () { return constants_1.MICROVM_MAX_RUN_SECONDS; } });
+// The two values a consumer MUST pass to `EvidentMicrovmConstruct` for them
+// to match the published image they were baked into (#1528).
+Object.defineProperty(exports, "HOOKS_PORT", { enumerable: true, get: function () { return constants_1.HOOKS_PORT; } });
+Object.defineProperty(exports, "HOOK_TIMEOUT_SECONDS", { enumerable: true, get: function () { return constants_1.HOOK_TIMEOUT_SECONDS; } });
+var stage_context_1 = require("./microvm/image/stage-context");
+Object.defineProperty(exports, "stageMicrovmImageContext", { enumerable: true, get: function () { return stage_context_1.stageMicrovmImageContext; } });

package/dist/microvm/constants.d.ts

@@ -1,3 +1,6 @@
+export declare const HOOKS_PORT = 8080;
+export declare const HOOKS_DIR = "/etc/evident/hooks";
+export declare const HOOK_TIMEOUT_SECONDS = 60;
 export declare const RUN_HOOK_PAYLOAD_MAX_BYTES = 16384;
 export declare const SUSPENDING_POLL_ATTEMPTS = 4;
 export declare const SUSPENDING_POLL_INTERVAL_MS = 500;

package/dist/microvm/constants.js

@@ -1,14 +1,25 @@
 "use strict";
-// Shared literals for the MicroVM controller. Every controller module imports
-// from here rather than restating a value that must match across them.
-//
-// Split from `infrastructure/evident-microvm/src/constants.ts` (#1476): the
-// hook/image values (`HOOKS_DIR`, `HOOKS_PORT`, `HOOK_TIMEOUT_SECONDS`) stay
-// there because `image/hook-server.ts` — bundled into the Docker image by a
-// different pipeline — imports them too and cannot take an npm dependency on
-// this construct package.
+// Shared literals for the MicroVM controller and for the image it launches.
+// Every module imports from here rather than restating a value that must match
+// across them — including `microvm/image/hook-server.ts`, which runs inside the
+// image and is esbuild-bundled into the published build context by
+// `scripts/build.ts`, so these values reach the image as inlined constants.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MICROVM_MAX_RUN_SECONDS = exports.SUSPENDING_POLL_INTERVAL_MS = exports.SUSPENDING_POLL_ATTEMPTS = exports.RUN_HOOK_PAYLOAD_MAX_BYTES = void 0;
+exports.MICROVM_MAX_RUN_SECONDS = exports.SUSPENDING_POLL_INTERVAL_MS = exports.SUSPENDING_POLL_ATTEMPTS = exports.RUN_HOOK_PAYLOAD_MAX_BYTES = exports.HOOK_TIMEOUT_SECONDS = exports.HOOKS_DIR = exports.HOOKS_PORT = void 0;
+// The port the image's hook server binds, baked into the published Dockerfile
+// (`ENV HOOKS_PORT`) and passed to the construct as `hooksPort`. Exported from
+// the package index because a consumer building the published image context
+// MUST pass the value it was baked with — the construct's own docstring warns
+// that a mismatch means AWS probes a port nothing binds.
+exports.HOOKS_PORT = 8080;
+// One executable per lifecycle phase. A phase with no script is a no-op, which
+// is why the image ships none for `ready` or `validate`: nothing Evident-specific
+// may run before the snapshot, so there is nothing for them to do.
+exports.HOOKS_DIR = '/etc/evident/hooks';
+// Seconds AWS allows a Run/Resume/Suspend/Terminate hook, passed to the
+// construct as `hookTimeoutSeconds`. Exported for the same reason as
+// `HOOKS_PORT`: the hooks are built against it.
+exports.HOOK_TIMEOUT_SECONDS = 60;
 // AWS caps `runHookPayload` at 16 KiB; anything larger is rejected at its API,
 // so the controller checks it before spending a call.
 exports.RUN_HOOK_PAYLOAD_MAX_BYTES = 16384;

package/dist/microvm/construct.js

@@ -81,7 +81,9 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
         // ANDed with the age condition and counts newer noncurrent versions of
         // the SAME key, but litestream's LTX keys are txid-unique and churn by
         // DELETE, so a churned key has exactly one noncurrent version and zero
-        // newer ones.
+        // newer ones. `expiredObjectDeleteMarker` reaps the delete marker itself once
+        // its noncurrent version is gone — without it, the version index grows
+        // unboundedly, one marker per churned LTX key.
         const durableState = new s3.Bucket(this, 'DurableState', {
             encryption: s3.BucketEncryption.S3_MANAGED,
             blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
@@ -98,6 +100,7 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
                 {
                     id: 'ExpireNoncurrentVersions',
                     noncurrentVersionExpiration: cdk.Duration.days(7),
+                    expiredObjectDeleteMarker: true,
                 },
             ],
         });

package/dist/microvm/controller/microvm-client.d.ts

@@ -49,7 +49,7 @@ export interface MicrovmClient {
      * (docs/spikes/lambda-microvms-phase0/README.md). AWS's own Claude-agents
      * guidance recommending `maxIdleDurationSeconds: 120` targets VMs reached
      * inbound and does not apply here. Idle is instead decided IN the VM by
-     * `evident run --idle-timeout` (docker/hooks/common.sh's
+     * `evident run --idle-timeout` (packages/runner-cdk/microvm-image/hooks/common.sh's
      * `IDLE_TIMEOUT_SECONDS`), whose clean exit drives this
      * client's own `suspend()` via the `runner.suspend_requested` doorbell.
      */

package/dist/microvm/image/stage-context.d.ts

@@ -0,0 +1,33 @@
+export interface StageMicrovmImageContextOptions {
+    /**
+     * The repository baked into the image as the agent's workspace. This is the
+     * CONSUMER's repository, not Evident's — the image is a dev box for whatever
+     * codebase the agent works on. Must be a full (non-shallow) clone.
+     */
+    readonly repositoryPath: string;
+    /**
+     * `origin` of the baked repository, as the VM will see it. Must be a
+     * credential-free URL (typically `https://github.com/<owner>/<repo>.git`):
+     * this string ships inside the shared snapshot, so a token in it would be
+     * baked into every VM. The credential arrives per-VM instead.
+     */
+    readonly originUrl: string;
+    /** Directory to write the build context to. Removed and recreated. */
+    readonly destination: 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
+     * built themselves rather than whichever `dist/` happens to be present.
+     */
+    readonly templateDir?: string;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function stageMicrovmImageContext(options: StageMicrovmImageContextOptions): string;

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

@@ -0,0 +1,148 @@
+"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.stageMicrovmImageContext = stageMicrovmImageContext;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+/**
+ * The image build context template published inside this package.
+ *
+ * Resolved from the PACKAGE ROOT, THREE directories above `__dirname` — either
+ * compiled (`dist/microvm/image`) or via ts-node (`src/microvm/image`) — the
+ * same way `microvm/construct.ts` resolves the controller Lambda asset, but one
+ * `..` deeper because this file sits a directory below it. It is
+ * written by `scripts/build.ts` at PACKAGE build time, not at stage time, so a
+ * consumer needs no esbuild and no checkout of this repo (#1528).
+ */
+const TEMPLATE_DIR = path.resolve(__dirname, '..', '..', '..', 'dist', 'microvm-image-context');
+function git(args, cwd) {
+    return (0, node_child_process_1.execFileSync)('git', args, { cwd, encoding: 'utf8' }).trim();
+}
+/**
+ * `git rev-parse --is-shallow-repository` throws an opaque `execFileSync`
+ * error (e.g. "not a git repository") when `repositoryPath` isn't usable at
+ * all, so that failure is rethrown naming the path.
+ */
+function isShallowRepository(repositoryPath) {
+    try {
+        return git(['rev-parse', '--is-shallow-repository'], repositoryPath) === 'true';
+    }
+    catch (err) {
+        throw new Error(`${repositoryPath} is not a usable git repository: ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Clones the caller's repository into the build context, so the Dockerfile can
+ * ship the workspace already installed.
+ *
+ * `file://` rather than a plain path: a path triggers git's local-clone
+ * optimisation, which copies the whole object store — every branch and worktree
+ * ref on the staging machine (50 MB here). The file transport negotiates like a
+ * network fetch and packs only what the checked-out branch reaches (9 MB), with
+ * one branch and one remote-tracking ref. Ignored files, `node_modules` first
+ * among them, are not part of a clone at all.
+ */
+function stageRepository(repositoryPath, destination, originUrl) {
+    if (isShallowRepository(repositoryPath)) {
+        throw new Error(`refusing to stage a shallow checkout (${repositoryPath}): the agent branches, ` +
+            'commits and opens PRs, so the image needs real history. Run `git fetch --unshallow`.');
+    }
+    // Absolute on both sides: `file://` needs an absolute path to mean anything,
+    // and the clone's cwd is the destination's parent (the only directory both
+    // are guaranteed to resolve against).
+    git(['clone', '--quiet', '--single-branch', `file://${repositoryPath}`, destination], path.dirname(destination));
+    // The clone points `origin` at this machine's filesystem; the VM's origin is
+    // the caller's own remote over HTTPS, with no credential in it.
+    git(['remote', 'set-url', 'origin', originUrl], destination);
+    // The asset hash of the resulting image must be a pure function of the commit,
+    // or every deploy publishes a new `AWS::Lambda::MicrovmImage` version and wedges
+    // the stack at its per-image version ceiling. Two things break that purity:
+    // - `pack-objects`' delta search is multithreaded (`pack.threads` defaults to
+    //   the CPU count) and its output varies run to run; `-f`/`-F`
+    //   (`--no-reuse-delta`/`--no-reuse-object`) additionally stop it from reusing
+    //   whatever packing the source checkout happened to have. All three together
+    //   make the pack a pure function of the object set, independent of the source.
+    // - `.git/index` carries stat data (inode/mtime/size) and `.git/logs/**` carries
+    //   wall-clock reflog timestamps; neither is byte-stable for a fixed commit.
+    git(['-c', 'pack.threads=1', 'repack', '-adfqF'], destination);
+    (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`);
+    }
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+function stageMicrovmImageContext(options) {
+    const { originUrl, 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);
+    const destination = path.resolve(options.destination);
+    if (!(0, node_fs_1.existsSync)(templateDir)) {
+        throw new Error(`the MicroVM image context template is missing from ${templateDir}. It is written by ` +
+            "this package's build (`pnpm --filter @evident-ai/runner-cdk build`) and ships in the " +
+            'published tarball, so an installed copy should always have it.');
+    }
+    (0, node_fs_1.rmSync)(destination, { recursive: true, force: true });
+    (0, node_fs_1.mkdirSync)(destination, { recursive: true });
+    (0, node_fs_1.copyFileSync)(path.join(templateDir, 'Dockerfile'), path.join(destination, 'Dockerfile'));
+    (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);
+    }
+    stageRepository(repositoryPath, path.join(destination, 'repo'), originUrl);
+    return destination;
+}

package/dist/microvm-image-context/Dockerfile

@@ -0,0 +1,224 @@
+# Evident per-session MicroVM image (#558, epic #556)
+#
+# 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.
+#
+# 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
+# anything unique or secret baked in here is shared by every VM launched from
+# 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.
+#
+# No `--platform` on FROM: AWS builds this natively on Graviton. Build it
+# locally with `docker build --platform linux/arm64`.
+#
+# Node major tracks `.nvmrc` / the root `engines.node` (22) so the image runs
+# the same runtime as CI — `evident-runner/src/node-version.test.ts` fails if
+# they drift. The Debian codename is pinned explicitly (`bookworm`, what
+# `node:22-slim` resolves to today) so a future default bump to a newer Debian
+# can't silently change the apt package set this image asserts on below.
+FROM node:22-bookworm-slim
+
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+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.
+#   - 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
+# once cascaded into shared libs and swept `procps` out of the runner image. The
+# binary assertion further down fails the build if any required binary is gone.
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    ca-certificates curl git jq less procps ripgrep \
+    postgresql postgresql-contrib direnv \
+    gnupg unzip \
+  # --- GitHub CLI (`gh`) from the official apt repo ---
+  && mkdir -p -m 755 /etc/apt/keyrings \
+  && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+       -o /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+  && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+       > /etc/apt/sources.list.d/github-cli.list \
+  && apt-get update \
+  && apt-get install -y --no-install-recommends gh \
+  # --- AWS CLI v2 (aarch64 bundle; this image is arm64 only) ---
+  && curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o /tmp/awscliv2.zip \
+  && 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/*
+
+# Litestream — replicates the OpenCode SQLite session DB to S3 so history
+# survives VM replacement. Pinned + checksum-verified: a wrong LITESTREAM_SHA256
+# fails the build at `sha256sum -c`. The checksum is for the arm64 tarball and
+# is NOT interchangeable with the ECS runner image's. Note the release tag keeps
+# the `v` but the filename does not.
+# `/run` restores opencode.db from S3 (#812 WI-2) — one bounded `litestream
+# restore` attempt — then starts a backgrounded `litestream replicate` once
+# opencode has opened the DB (WI-3); `/suspend`/`/resume`/`/terminate` flush,
+# restart and stop it in turn (WI-4). Do not remove as dead code.
+ARG LITESTREAM_VERSION=0.5.13
+ARG LITESTREAM_SHA256=ef47997794ce8dd87a64b44622d556b3a693b135fd72e0cf47cc42ac2e979051
+RUN curl -fsSL -o /tmp/litestream.tar.gz \
+      "https://github.com/benbjohnson/litestream/releases/download/v${LITESTREAM_VERSION}/litestream-${LITESTREAM_VERSION}-linux-arm64.tar.gz" \
+  && echo "${LITESTREAM_SHA256}  /tmp/litestream.tar.gz" | sha256sum -c - \
+  && tar -C /usr/local/bin -xzf /tmp/litestream.tar.gz litestream \
+  && chmod +x /usr/local/bin/litestream \
+  && rm -f /tmp/litestream.tar.gz \
+  && litestream version
+
+# The AI agent runtime, the Evident CLI and the Claude Code CLI, installed
+# globally and pinned via build args so image versions are reproducible.
+# OPENCODE_VERSION is a DELIBERATE PIN, not a floating tag — see #537: a
+# 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
+# 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.
+ARG OPENCODE_VERSION=1.18.3
+ARG EVIDENT_CLI_VERSION=dev
+ARG CLAUDE_CODE_VERSION=latest
+ARG RUNNER_SYNCHRONISER_VERSION=dev
+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}" \
+  && opencode --version \
+  && 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 \
+       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 \
+     || { echo "FATAL: curl TLS smoke test failed (broken TLS libs)" >&2; exit 1; }
+
+# Non-root user that owns the workspace. uid/gid pinned to 10001 for stable file
+# ownership (opencode.db, ~/.claude/.credentials.json) across rebuilds.
+RUN groupadd --system --gid 10001 runner \
+  && useradd --system --uid 10001 --gid 10001 \
+       --create-home --home-dir /home/runner runner
+
+# The hook server: the ONLY process this image starts, and it starts nothing
+# itself until AWS calls a hook. It is an esbuild bundle of
+# src/microvm/image/hook-server.ts, placed next to this Dockerfile by
+# `stageMicrovmImageContext()` — which is why this file is not buildable
+# straight from the source tree.
+COPY hook-server.js /usr/local/lib/evident/hook-server.js
+
+# One executable per lifecycle phase. There is deliberately no `ready` and no
+# `validate` script: the snapshot is shared by every VM started from this image
+# version, so nothing per-VM may run before /run — which leaves those two phases
+# with nothing to do, and the runtime answers them 200 without running anything.
+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.
+#
+# 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
+# snapshot is exactly right. No credential is involved either — the repo travels
+# in the build context (cloned by `stageMicrovmImageContext()` from a local
+# checkout), not through a `git clone` needing a token. `origin` is the plain
+# HTTPS GitHub URL; the credential that makes it fetchable and pushable arrives
+# 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
+# `/var/lib/dbus` is writable by it, so without this the regeneration is a
+# 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 \
+  && 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
+COPY --chown=10001:10001 repo ${WORKSPACE}
+WORKDIR ${WORKSPACE}
+USER runner
+
+# The staged context deliberately ships no `.git/index` (it is not byte-stable,
+# so shipping it would re-roll the image version on every deploy) — without this
+# reset the agent's workspace reports ~1400 files as staged deletions. Runs as
+# `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.
+#
+# 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/*'; \
+    else \
+      echo "[workspace-prep] no pnpm-lock.yaml in the baked repository — skipping the dependency install and the packages build; 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
+# Port AWS calls the MicroVM hooks on.
+ENV HOOKS_PORT=8080
+# OpenCode loopback port the CLI tunnels to (matches `evident run` default).
+ENV OPENCODE_PORT=4096
+
+EXPOSE 8080
+
+# No ENTRYPOINT shell: the hook server is started directly, and it must be the
+# only thing running until AWS calls /run.
+CMD ["node", "/usr/local/lib/evident/hook-server.js"]