@evident-ai/runner-cdk 3.5.2-dev.e22029a → 3.5.2-dev.f258bd6

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

@@ -33,143 +33,53 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stageMicrovmImageContext = stageMicrovmImageContext;
+exports.MICROVM_WORKSPACE_DIRECTORY = void 0;
+exports.stageMicrovmBuildContext = stageMicrovmBuildContext;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
 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');
+/** The fixed directory that contains the workspace in a staged build context. */
+exports.MICROVM_WORKSPACE_DIRECTORY = 'workspace';
 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) {
+/** Names the path when git cannot determine whether the repository is shallow. */
+function isShallowRepository(sourcePath) {
     try {
-        return git(['rev-parse', '--is-shallow-repository'], repositoryPath) === 'true';
+        return git(['rev-parse', '--is-shallow-repository'], sourcePath) === 'true';
     }
     catch (err) {
-        throw new Error(`${repositoryPath} is not a usable git repository: ` +
+        throw new Error(`${sourcePath} is not a usable git repository: ` +
             `${err instanceof Error ? err.message : String(err)}`);
     }
 }
-/**
- * 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
- * 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, ` +
+/** Clones a full repository while normalising the bytes that affect the image asset hash. */
+function stageRepository(sourcePath, stagedWorkspacePath, workspaceOriginUrl) {
+    if (isShallowRepository(sourcePath)) {
+        throw new Error(`refusing to stage a shallow checkout (${sourcePath}): 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)}`);
-}
-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);
-    }
+    git(['clone', '--quiet', '--single-branch', `file://${sourcePath}`, stagedWorkspacePath], path.dirname(stagedWorkspacePath));
+    git(['remote', 'set-url', 'origin', workspaceOriginUrl], stagedWorkspacePath);
+    git(['-c', 'pack.threads=1', 'repack', '-adfqF'], stagedWorkspacePath);
+    (0, node_fs_1.rmSync)(path.join(stagedWorkspacePath, '.git', 'index'), { force: true });
+    (0, node_fs_1.rmSync)(path.join(stagedWorkspacePath, '.git', 'logs'), { recursive: true, force: true });
+    console.log(`[stage] repo ${git(['rev-parse', 'HEAD'], stagedWorkspacePath)}`);
 }
 /**
- * Writes the build context AWS unpacks — the Dockerfile, the hook server, the
- * per-phase hook scripts, the deployment overlay and the repository — and
- * returns its path. The result is what `EvidentMicrovmConstruct`'s `imageSource`
- * takes.
+ * Stages customer-owned image inputs in a fresh temporary directory.
  *
- * 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. A caller may supply an overlay; the default is
- * deterministic no-op scripts. `repositoryPath` is the only required caller
- * input.
+ * Staging keeps the image asset hash a pure function of the workspace commit while
+ * leaving the customer in control of the Dockerfile and its build context.
  */
-function stageMicrovmImageContext(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);
-    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');
-    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);
+function stageMicrovmBuildContext(options) {
+    const buildContextPath = path.resolve(options.buildContextPath);
+    if (!(0, node_fs_1.existsSync)(buildContextPath) || !(0, node_fs_1.existsSync)(path.join(buildContextPath, 'Dockerfile'))) {
+        throw new Error(`MicroVM build context ${buildContextPath} does not exist or has no Dockerfile`);
     }
-    stageRepository(repositoryPath, path.join(destination, 'repo'), originUrl);
-    return destination;
+    const stagedPath = (0, node_fs_1.mkdtempSync)(path.join((0, node_os_1.tmpdir)(), 'evident-microvm-'));
+    (0, node_fs_1.cpSync)(buildContextPath, stagedPath, { recursive: true });
+    stageRepository(path.resolve(options.workspaceRepositoryPath), path.join(stagedPath, exports.MICROVM_WORKSPACE_DIRECTORY), options.workspaceOriginUrl);
+    return stagedPath;
 }

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

@@ -3,7 +3,7 @@ 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;
+    controllerSigningSecret: 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. */

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

@@ -64,13 +64,13 @@ class ImageVersionReporter extends constructs_1.Construct {
             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: constants_1.DOORBELL_SECRET_KEY,
+                CONTROLLER_SIGNING_SECRET_ARN: props.controllerSigningSecret.secretArn,
+                CONTROLLER_SIGNING_SECRET_KEY: constants_1.CONTROLLER_SIGNING_SECRET_KEY,
                 EVIDENT_API_URL: props.evidentApiUrl,
                 EVIDENT_RUNNER_ID: props.evidentRunnerId,
             },
         });
-        props.doorbellSecret.grantRead(handler);
+        props.controllerSigningSecret.grantRead(handler);
         const provider = new cr.Provider(this, 'Provider', {
             onEventHandler: handler,
         });

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

@@ -9,8 +9,8 @@ export type ReporterEvent = {
     };
 };
 export type ReporterConfig = {
-    doorbellSecretArn: string;
-    doorbellSecretKey: string;
+    controllerSigningSecretArn: string;
+    controllerSigningSecretKey: string;
     evidentApiUrl: string;
     evidentRunnerId: string;
 };

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

@@ -7,17 +7,17 @@ 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) {
+async function fetchControllerSigningSecret(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`);
+        throw new Error(`controller signing 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`);
+        throw new Error(`controller signing secret ${secretArn} is missing a non-empty '${secretKey}' field`);
     }
     return value;
 }
@@ -43,7 +43,7 @@ function response() {
     return { PhysicalResourceId: PHYSICAL_RESOURCE_ID };
 }
 const runtimeDependencies = {
-    getSecret: fetchDoorbellSecret,
+    getSecret: fetchControllerSigningSecret,
     fetch: globalThis.fetch,
 };
 async function handleImageVersionReport(event, getConfig, dependencies = runtimeDependencies) {
@@ -57,10 +57,12 @@ async function handleImageVersionReport(event, getConfig, dependencies = runtime
         versions = readImageVersions(event.ResourceProperties?.imageVersions);
         const config = getConfig();
         runnerId = config.evidentRunnerId;
-        const secret = await dependencies.getSecret(config.doorbellSecretArn, config.doorbellSecretKey);
+        const secret = await dependencies.getSecret(config.controllerSigningSecretArn, config.controllerSigningSecretKey);
         const body = JSON.stringify({
             type: 'runner.microvm_image_versions_reported',
             versions,
+            // The API orders reports by this value because replacing an image restarts its version counter.
+            reporter_clock_ms: Date.now(),
         });
         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`;
@@ -96,8 +98,8 @@ async function handleImageVersionReport(event, getConfig, dependencies = runtime
     return response();
 }
 const handler = (event) => handleImageVersionReport(event, () => ({
-    doorbellSecretArn: requireEnv('DOORBELL_SECRET_ARN'),
-    doorbellSecretKey: requireEnv('DOORBELL_SECRET_KEY'),
+    controllerSigningSecretArn: requireEnv('CONTROLLER_SIGNING_SECRET_ARN'),
+    controllerSigningSecretKey: requireEnv('CONTROLLER_SIGNING_SECRET_KEY'),
     evidentApiUrl: requireEnv('EVIDENT_API_URL'),
     evidentRunnerId: requireEnv('EVIDENT_RUNNER_ID'),
 }));

package/dist/microvm/shapes.d.ts

@@ -5,11 +5,8 @@ import { type MicrovmMemoryMiB } from '@evident-ai/lambda-microvm-cdk';
  * there is no launch-time resource dial — so "a bigger machine" means "a
  * different shape", each backed by its own `MicrovmImage`.
  *
- * `constructId` and `imageName` are carried **explicitly** rather than
- * derived from `name`, because for the default shape they are frozen
- * deployment identity (see the comment on `MICROVM_SHAPES` below): deriving
- * them would let an innocent rename of `name` silently rebuild the live
- * image. Every other shape is free to name these however is convenient.
+ * `name` is also the `MicrovmImage` child id, so it identifies both the
+ * controller-facing shape and the image resource built for it.
  */
 export interface MicrovmShape {
     /** The stable id a doorbell asks for; crosses the wire to Evident. */
@@ -27,8 +24,6 @@ export interface MicrovmShape {
      * it must be the first entry in `MICROVM_SHAPES`.
      */
     readonly isDefault: boolean;
-    /** The `MicrovmImage` construct id within the stack. */
-    readonly constructId: string;
     /** The account-unique `imageName` passed to `MicrovmImage`. */
     readonly imageName: string;
 }
@@ -45,28 +40,22 @@ export interface MicrovmShape {
  * making the construction-order contract enforceable rather than a
  * convention.
  *
- * The default entry's `constructId` ("Image") and `imageName`
- * ("evident-microvm") are FROZEN: they are today's live, hand-deployed
- * image's identity. Changing either destroys and rebuilds it (~4m45s,
- * measured) plus a window with no image. Its `description` is copied
- * verbatim from the image that is live today so the deploy changes nothing
- * about it.
+ * The default entry's `name` ("standard") and `imageName`
+ * ("evident-microvm-standard") are FROZEN: `name` crosses the wire and
+ * identifies the image child, while `imageName` is account-unique. Changing
+ * either replaces the image, so both values remain stable after deployment.
  *
  * "Frozen" means unchanged under OUR OWN synth (no `microvm:*` context set —
  * `main.ts` passes none). `imageName` MAY carry a customer's
  * `microvm:namePrefix` (`deployment.ts`'s `resolveShapeCatalogue`) — that is
- * account-scoped naming, not a change to this module. `constructId` stays
- * frozen unconditionally, with no override anywhere: it is the
- * CloudFormation logical-id path, and prefixing it is the resource
- * replacement this whole file's FROZEN warning exists to prevent.
+ * account-scoped naming, not a change to this module.
  */
 export declare const MICROVM_SHAPES: readonly MicrovmShape[];
 /**
  * Validates a shape list at synth time. Deliberately lean
  * (`code-simplicity.mdc`): this is a hand-edited constant list in a typed
- * file, so it only checks what `tsc` cannot already catch — CDK itself
- * rejects a duplicate `constructId`, so that one needs no check here, and no
- * byte-budget cap is applied (the image ARNs are unresolved tokens at synth,
- * so a rendered size is not measurable anyway).
+ * file, so it only checks what `tsc` cannot already catch. No byte-budget cap
+ * is applied because the image ARNs are unresolved tokens at synth, so a
+ * rendered size is not measurable anyway.
  */
 export declare function validateShapes(shapes: readonly MicrovmShape[]): readonly MicrovmShape[];

package/dist/microvm/shapes.js

@@ -16,20 +16,15 @@ const lambda_microvm_cdk_1 = require("@evident-ai/lambda-microvm-cdk");
  * making the construction-order contract enforceable rather than a
  * convention.
  *
- * The default entry's `constructId` ("Image") and `imageName`
- * ("evident-microvm") are FROZEN: they are today's live, hand-deployed
- * image's identity. Changing either destroys and rebuilds it (~4m45s,
- * measured) plus a window with no image. Its `description` is copied
- * verbatim from the image that is live today so the deploy changes nothing
- * about it.
+ * The default entry's `name` ("standard") and `imageName`
+ * ("evident-microvm-standard") are FROZEN: `name` crosses the wire and
+ * identifies the image child, while `imageName` is account-unique. Changing
+ * either replaces the image, so both values remain stable after deployment.
  *
  * "Frozen" means unchanged under OUR OWN synth (no `microvm:*` context set —
  * `main.ts` passes none). `imageName` MAY carry a customer's
  * `microvm:namePrefix` (`deployment.ts`'s `resolveShapeCatalogue`) — that is
- * account-scoped naming, not a change to this module. `constructId` stays
- * frozen unconditionally, with no override anywhere: it is the
- * CloudFormation logical-id path, and prefixing it is the resource
- * replacement this whole file's FROZEN warning exists to prevent.
+ * account-scoped naming, not a change to this module.
  */
 exports.MICROVM_SHAPES = [
     {
@@ -38,18 +33,16 @@ exports.MICROVM_SHAPES = [
         description: 'Evident per-session runner: an arm64 image that boots with no identity and acquires one at /run.',
         memoryMiB: 4096,
         isDefault: true,
-        // FROZEN — see the file-level comment. Do not rename either string.
-        constructId: 'Image',
-        imageName: 'evident-microvm',
+        // FROZEN — name crosses the wire and imageName is account-unique.
+        imageName: 'evident-microvm-standard',
     },
 ];
 /**
  * Validates a shape list at synth time. Deliberately lean
  * (`code-simplicity.mdc`): this is a hand-edited constant list in a typed
- * file, so it only checks what `tsc` cannot already catch — CDK itself
- * rejects a duplicate `constructId`, so that one needs no check here, and no
- * byte-budget cap is applied (the image ARNs are unresolved tokens at synth,
- * so a rendered size is not measurable anyway).
+ * file, so it only checks what `tsc` cannot already catch. No byte-budget cap
+ * is applied because the image ARNs are unresolved tokens at synth, so a
+ * rendered size is not measurable anyway.
  */
 function validateShapes(shapes) {
     if (shapes.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-cdk",
-  "version": "3.5.2-dev.e22029a",
+  "version": "3.5.2-dev.f258bd6",
   "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,8 +15,8 @@
   ],
   "scripts": {
     "build": "pnpm run build-bundled-deps && ts-node scripts/build.ts && node -e 'const m=require(\"./package.json\").main; if (!require(\"node:fs\").existsSync(m)) { console.error(`build produced no ${m}`); process.exit(1); }'",
-    "//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",
+    "//build-bundled-deps": "Builds the workspace dependencies whose dist/ output the direct runner-cdk build chain consumes: lambda-microvm-cdk for the public construct types, lambda-microvm-runtime for runner-microvm-image's hook-server bundle, and runner-microvm-image for that bundle itself. 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 && pnpm --filter runner-microvm-image build",
     "typecheck": "tsc --noEmit",
     "test": "node --test --require ts-node/register 'src/**/*.test.ts'",
     "format": "prettier --write 'src/**/*.ts'",

package/dist/microvm-image-context/Dockerfile

@@ -1,190 +0,0 @@
-# Generic MicroVM runner image
-#
-# 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
-# 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.
-# `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`.
-#
-# 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: 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
-# 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 psmisc ripgrep \
-    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 \
-  # --- 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.16
-ARG LITESTREAM_SHA256=678022e4103145302598e35d37f8718392d42e153feeb1e2d4a64dd0cd3aaf10
-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. 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
-
-# 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 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, 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
-# 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
-#
-# 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/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 /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
-
-# 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
-
-# Deployment-specific dependency installation and build work belongs here. This runs
-# as `runner` in `${WORKSPACE}`, so everything it writes is agent-writable.
-#
-# 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
-
-# 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"]