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

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. 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
+  and suspends between messages. Installing the `@dev` tag of this package is all you
+  need: the image build context ships inside it (see [The MicroVM image](#the-microvm-image)
+  below), so there is no checkout of `sroze/evident` involved. See
   [the AWS runner doc](https://evident.run/docs/aws-runner) for the full picture of both
   strategies.
 
@@ -34,8 +34,9 @@ cluster can host several agents.
 ## Getting started
 
 For a full end-to-end walkthrough — shared infra, secrets without SOPS/KMS, the image,
-the two grants, deploy, and wiring the wake webhook — see
-[`GETTING-STARTED.md`](./GETTING-STARTED.md). The snippet below is the short version.
+the two grants, deploy, and wiring the wake webhook — see `GETTING-STARTED.md` in this
+package's directory (not published to npm; read it from a checkout of the repo). The
+snippet below is the short version.
 
 ```ts
 import { EvidentScaleToZeroConstruct } from "@evident-ai/runner-cdk";
@@ -111,7 +112,7 @@ the construct's own dogfooding consumer.
 
 This construct never builds an image. Pass any `ecs.ContainerImage` — from a registry, or
 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.
+`runner/docker-images/fargate`, so you can adopt the image, the construct, or both.
 
 ## The MicroVM image
 
@@ -126,6 +127,7 @@ the per-phase hook scripts and the bundled hook server, published inside the tar
 the agent's workspace. `stageMicrovmImageContext()` puts the two together:
 
 ```ts
+import path from 'node:path';
 import {
   EvidentMicrovmConstruct,
   HOOKS_PORT,
@@ -149,6 +151,8 @@ new EvidentMicrovmConstruct(this, 'Runner', {
   baseImageArn,
   baseImageVersion,
   doorbellSecret,
+  runnerSecret,
+  runnerOpencodeConfigPath: 'opencode.runner.jsonc',
 });
 ```
 
@@ -156,14 +160,19 @@ Your repo does not have to be a pnpm workspace. If it commits a `pnpm-lock.yaml`
 pre-installs dependencies at build time (a faster first boot); if not, that step is skipped
 and the agent installs on first use.
 
+| MicroVM prop | Omitted behavior |
+| --- | --- |
+| `runnerSecret` | No GitHub or MCP credentials are exported at `/run`. |
+| `runnerOpencodeConfigPath` | OpenCode uses the baked project configuration. Relative paths resolve from the workspace; absolute paths resolve in the image. |
+| `gitUserName` / `gitUserEmail` | The hook uses the Evident bot defaults for git identity. |
+
 ## Status / limitations
 
-- **Published to npm** as `@evident-ai/runner-cdk` (MIT) — see
-  [#957](https://github.com/sroze/evident/issues/957). Install it with `npm install
-  @evident-ai/runner-cdk` (or `pnpm add`/`yarn add`); no checkout of this repo is
-  required. It builds to a self-contained `dist/` (`pnpm --filter @evident-ai/runner-cdk
-  build`) with no `workspace:`/`@evident/*` runtime dependency. This repo's own
-  consumer (`infrastructure/evident-runner`) still consumes it as a `workspace:*`
-  dependency for dogfooding.
+- **Published to npm** as `@evident-ai/runner-cdk` (MIT). Install the `@dev` tag —
+  `npm install @evident-ai/runner-cdk@dev` (or `pnpm add`/`yarn add`); no checkout of
+  this repo is required. It builds to a self-contained `dist/` (`pnpm --filter
+  @evident-ai/runner-cdk build`) with no `workspace:`/`@evident/*` runtime dependency.
+  This repo's own consumer (`infrastructure/evident-runner`) still consumes it as a
+  `workspace:*` dependency for dogfooding.
 - **AWS/ECS-specific.** Non-AWS clouds are an open question on the epic, not a supported
   path.

package/dist/evident-scale-to-zero-construct.js

@@ -101,7 +101,7 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             // --endpoint / --tunnel). The agent is resolved from EVIDENT_AGENT_KEY.
             EVIDENT_API_URL: evidentApiUrl,
             EVIDENT_TUNNEL_URL: evidentTunnelUrl,
-            // Litestream replica target (read by packages/runner-synchroniser, which
+            // Litestream replica target (read by runner/synchroniser, which
             // generates /etc/evident/litestream.yml at boot).
             LITESTREAM_BUCKET: replicaBucket.bucketName,
             LITESTREAM_PREFIX: this.replicaPrefix,
@@ -115,10 +115,9 @@ class EvidentScaleToZeroConstruct extends constructs_1.Construct {
             // window (protected/active sessions are never touched). Tightened from 7d
             // to 24h per #537: at 7d, opencode.db was observed growing ~11x (77 MB ->
             // 849 MB) in ~24h, so 7d was far too permissive at the observed growth
-            // rate. 24h is a tighter mitigation while the growth's root cause is
-            // investigated (see also the OPENCODE_VERSION pin above and the
-            // [memwatch] telemetry in entrypoint.sh). Sweep runs on the default 1h
-            // interval and never touches a protected/active session.
+            // rate. 24h is the tighter mitigation that came out of that (see also the
+            // OPENCODE_VERSION pin above). Sweep runs on the default 1h interval and
+            // never touches a protected/active session.
             EVIDENT_SESSION_CLEANUP_MAX_AGE: '24h',
             CLUSTER: cluster.clusterName,
             SERVICE: serviceName,

package/dist/microvm/constants.js

@@ -1,9 +1,8 @@
 "use strict";
 // 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.
+// across them. The image template pins matching copies, guarded by
+// `microvm/image/dockerfile.test.ts`.
 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 = 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

package/dist/microvm/construct.d.ts

@@ -12,7 +12,7 @@ export interface EvidentMicrovmConstructProps {
     readonly imageSource: string;
     /**
      * ARN of the Lambda-managed base MicroVM image, from
-     * `aws lambda list-managed-microvm-images`. A string, not a `CfnParameter`
+     * `aws lambda-microvms list-managed-microvm-images`. A string, not a `CfnParameter`
      * built here: the caller creates the parameter at ITS OWN stack scope
      * (preserving its logical id) and passes its resolved value down — a
      * construct must not mint parameters into a consumer's stack.
@@ -20,7 +20,7 @@ export interface EvidentMicrovmConstructProps {
     readonly baseImageArn: string;
     /**
      * Version of the Lambda-managed base MicroVM image, from
-     * `aws lambda list-managed-microvm-images`. See `baseImageArn` for why this
+     * `aws lambda-microvms list-managed-microvm-images`. See `baseImageArn` for why this
      * is a plain string.
      */
     readonly baseImageVersion: string;
@@ -41,6 +41,20 @@ export interface EvidentMicrovmConstructProps {
      * in its own scope, and passes the result in either case.
      */
     readonly doorbellSecret: secretsmanager.ISecret;
+    /**
+     * Optional runner secret whose JSON values are exported by `/run`. Omitting it
+     * leaves GitHub and MCP credentials unavailable to a generic consumer.
+     */
+    readonly runnerSecret?: secretsmanager.ISecret;
+    /**
+     * Optional runner OpenCode overlay. Absolute paths are image paths; relative
+     * paths are resolved from the baked workspace by the `/run` hook.
+     */
+    readonly runnerOpencodeConfigPath?: string;
+    /** Optional git identity the `/run` hook configures for agent commits. */
+    readonly gitUserName?: string;
+    /** Optional git email the `/run` hook configures for agent commits. */
+    readonly gitUserEmail?: string;
     /**
      * TCP port the image's hook server listens on, baked into both the image
      * (`HOOKS_PORT` env var) and the `MicrovmImage`'s `hooks.port` — a mismatch

package/dist/microvm/construct.js

@@ -121,6 +121,12 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
             // already bakes in for its own runners (evident-scale-to-zero-construct.ts:191).
             // Safe to bake: identical for every VM from this image version.
             EVIDENT_SESSION_CLEANUP_MAX_AGE: '24h',
+            ...(props.runnerOpencodeConfigPath
+                ? { RUNNER_OPENCODE_CONFIG: props.runnerOpencodeConfigPath }
+                : {}),
+            ...(props.runnerSecret ? { RUNNER_SECRET_ARN: props.runnerSecret.secretArn } : {}),
+            ...(props.gitUserName ? { GIT_USER_NAME: props.gitUserName } : {}),
+            ...(props.gitUserEmail ? { GIT_USER_EMAIL: props.gitUserEmail } : {}),
         };
         // ...and the hooks configuration every shape's image is built with.
         const imageHooks = {
@@ -179,6 +185,8 @@ class EvidentMicrovmConstruct extends constructs_1.Construct {
         // customer account, and what Phase 4 (#263) has to tighten when this goes
         // multi-tenant.
         durableState.grantReadWrite(defaultImage.executionRole);
+        // The image receives only an ARN; `/run` reads the secret value at runtime.
+        props.runnerSecret?.grantRead(defaultImage.executionRole);
         // The shape catalogue the controller resolves a doorbell's `shape` field
         // against, and advertises over the describe channel (#723). One JSON
         // array, built with `Stack.toJsonString` — not `JSON.stringify` — because

package/dist/microvm/controller/handle-doorbell.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleDoorbell = handleDoorbell;
 const node_crypto_1 = require("node:crypto");
-const webhook_signature_1 = require("@evident/webhook-signature");
+const sdk_1 = require("@evident/sdk");
 const constants_1 = require("../constants");
 const doorbell_1 = require("./doorbell");
 const throttle_retry_1 = require("./throttle-retry");
@@ -175,7 +175,7 @@ async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, micr
     return compareImageVersions(running, latest) < 0;
 }
 async function handleDoorbell({ rawBody, signatureHeader, doorbellSecret, shapes, microvm, sleep, random, }) {
-    if (!(0, webhook_signature_1.verifyWakeSignature)(rawBody, signatureHeader, doorbellSecret)) {
+    if (!(0, sdk_1.verifyEvidentSignature)(rawBody, signatureHeader, doorbellSecret)) {
         return decide({
             statusCode: 401,
             action: 'rejected',

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` (packages/runner-cdk/microvm-image/hooks/common.sh's
+     * `evident run --idle-timeout` (runner/docker-images/microvm/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-context/Dockerfile

@@ -37,7 +37,7 @@ RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
 # 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 \
+    ca-certificates curl git jq less procps psmisc ripgrep \
     postgresql postgresql-contrib direnv \
     gnupg unzip \
   # --- GitHub CLI (`gh`) from the official apt repo ---
@@ -71,8 +71,8 @@ RUN apt-get update \
 # 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
+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 - \
@@ -171,10 +171,10 @@ 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 \
+RUN mkdir -p /var/lib/runner-pg /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 /var/lib/runner-pg /home/runner
 COPY --chown=10001:10001 repo ${WORKSPACE}
 WORKDIR ${WORKSPACE}
 USER runner
@@ -204,9 +204,12 @@ RUN git reset --quiet
 # 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/*'; \
+      && 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 packages build; the agent installs on first use."; \
+      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
 
 # Data dir for the local dev Postgres cluster; listens on 5433 to match this

package/dist/microvm-image-context/hook-server.js

@@ -275,14 +275,10 @@ var require_dist = __commonJS({
   }
 });
 
-// src/microvm/image/hook-server.ts
+// ../../runner/docker-images/microvm/hook-server.ts
 var import_lambda_microvm_runtime = __toESM(require_dist());
-
-// src/microvm/constants.ts
-var HOOKS_PORT = 8080;
 var HOOKS_DIR = "/etc/evident/hooks";
-
-// src/microvm/image/hook-server.ts
+var HOOKS_PORT = 8080;
 var server = (0, import_lambda_microvm_runtime.createNodeRuntime)({ hooksDir: HOOKS_DIR });
 var port = Number(process.env.HOOKS_PORT ?? HOOKS_PORT);
 server.listen(port, "0.0.0.0", () => {

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

@@ -2,8 +2,8 @@
 # Sourced by every hook script. Nothing here runs at image build time.
 #
 # These hooks are the SECOND shell speaking the runner-synchroniser CLI contract
-# (packages/runner-image/entrypoint.sh is the first), so both are held to it by
-# packages/runner-synchroniser/src/shell-contract.test.ts — which derives what
+# (runner/docker-images/fargate/entrypoint.sh is the first), so both are held to it by
+# runner/synchroniser/src/shell-contract.test.ts — which derives what
 # `run_synchroniser` below must handle from the subcommands this shell calls.
 
 # Installed from npm by the image (docker/Dockerfile's ARG
@@ -50,14 +50,47 @@ LITESTREAM_CONFIG_FILE="/dev/shm/evident-litestream.yml"
 # earlier boot cannot silently disable replication for the VM's whole life.
 SESSION_DB_NO_REPLICATE_MARKER="/dev/shm/evident-session-db-no-replicate"
 
-log() { echo "[hook:$(basename "$0")] $*"; }
-warn() { echo "[hook:$(basename "$0")] $*" >&2; }
-error() { echo "[hook:$(basename "$0")] ERROR: $*" >&2; }
+hook_name() { printf '%s' "${0##*/}"; }
+log() { echo "[hook:$(hook_name)] $*"; }
+warn() { echo "[hook:$(hook_name)] $*" >&2; }
+error() { echo "[hook:$(hook_name)] ERROR: $*" >&2; }
+
+session_db_recovery_report_path() {
+  local path="${EVIDENT_SESSION_DB_RECOVERY_REPORT:-}"
+  path="${path#"${path%%[![:space:]]*}"}"
+  path="${path%"${path##*[![:space:]]}"}"
+  if [ -n "${path}" ]; then
+    printf '%s\n' "${path}"
+    return 0
+  fi
+  local home="${HOME:-}"
+  home="${home#"${home%%[![:space:]]*}"}"
+  home="${home%"${home##*[![:space:]]}"}"
+  [ -n "${home}" ] || return 1
+  printf '%s\n' "${home}/.local/state/evident/session-db-recovery.jsonl"
+}
+
+report_session_db_giveup() {
+  local reason="$1" exit_code="${2:-null}" outcome path at
+  case "${reason}" in
+    synchroniser_config_unresolved|synchroniser_config_unevaluable|synchroniser_config_incomplete|litestream_config_unavailable|classification_fatal) outcome="restore_misconfigured" ;;
+    restore_deadline_exceeded|restore_tool_unusable|classification_unrecognised) outcome="fresh_session_db" ;;
+    *) warn "SESSION-DB-RECOVERY-REPORT-UNKNOWN-REASON: ${reason}"; return 0 ;;
+  esac
+  if ! path="$(session_db_recovery_report_path)"; then
+    warn "SESSION-DB-RECOVERY-REPORT-PATH-UNAVAILABLE"
+    return 0
+  fi
+  at="${EPOCHREALTIME:-}"
+  [ -n "${at}" ] || warn "SESSION-DB-RECOVERY-REPORT-TIMESTAMP-UNAVAILABLE"
+  printf '{"v":1,"event":"session_db_recovery","at":"%s","stage":"restore","outcome":"%s","severity":"error","reason":"%s","litestream_exit_code":%s,"attempt":null,"replica_objects":null,"replica_bytes":null,"quarantine_destination":null,"quarantined_objects":null,"quarantine_failed_objects":null,"quarantined_bytes":null,"verified_restore_point":null,"restore_points_tried":null,"replication_suspended":true}\n' "${at}" "${outcome}" "${reason}" "${exit_code}" >>"${path}" || warn "SESSION-DB-RECOVERY-REPORT-APPEND-FAILED"
+  return 0
+}
 
 # Returns the CLI's own exit code. Domain outcomes (nothing persisted yet, a
 # corrupt object) are LOGGED and exit 0, the predicates answer "no" with 10, and
 # `session-db-classify`'s three typed answers are 30 (fatal)/31 (replica
-# unusable)/32 (retry) — see `packages/runner-synchroniser/src/cli.ts`'s own
+# unusable)/32 (retry) — see `runner/synchroniser/src/cli.ts`'s own
 # comment for what each means, not restated here. Any OTHER non-zero status
 # means the tool itself broke, which is the only case worth an ERROR here —
 # EXCEPT 124/137 (a `timeout` deadline/SIGKILL) when the caller asked for one:
@@ -171,7 +204,7 @@ timed_synchroniser() {
 }
 
 # Exports what `runner-synchroniser` resolves its object-store location from
-# (packages/runner-synchroniser/src/config.ts). It treats either being empty as
+# (runner/synchroniser/src/config.ts). It treats either being empty as
 # "persistence disabled" and then reports every restore as a WARNING it still
 # exits 0 for — so an unset value has to be caught HERE, where it can still be
 # told apart from "the store is simply empty".
@@ -211,13 +244,13 @@ load_state_config() {
 # `model-auth-ready` therefore stays a boot-time diagnostic: its only output is
 # a log line, since the runtime forwards no hook stderr to the doorbell caller.
 
-# How long restore_credentials' shared step budget is, covering all THREE of
-# its synchroniser calls (restore claude, restore opencode, model-auth-ready)
-# as one window rather than a timeout apiece — a fixed per-call cap at the same
+# How long restore_credentials' shared step budget is, covering the runner-secret
+# fetch plus its three synchroniser calls (restore claude, restore opencode,
+# model-auth-ready) as one window rather than a timeout apiece — a fixed per-call cap at the same
 # total would false-fire on the ordinary case of one slow call (a slow S3 GET),
 # which is precisely the boot this exists to keep healthy. From #930's 3-boot
-# sample: the step measured ~3-5s total (~1.2s per call, three node cold
-# starts of a 1.8 MB bundle) — a WEAK estimate this file's own
+# sample: the step measured ~3-5s total (~1.2s per synchroniser call, three
+# node cold starts of a 1.8 MB bundle) — a WEAK estimate this file's own
 # SYNCHRONISER-TIMING lines are what will sharpen for real. Too tight and a
 # routine slow call boots this VM with no model credentials until an operator
 # reconnects it; too loose and a hung call burns more of the hook's own
@@ -229,6 +262,7 @@ CREDENTIAL_RESTORE_DEADLINE_SECONDS="${EVIDENT_CREDENTIAL_RESTORE_DEADLINE_SECON
 # and a call that ignored it would be unbounded again). Hard ceiling on the
 # step: DEADLINE + this = 10s, once — not per call.
 CREDENTIAL_RESTORE_KILL_GRACE_SECONDS=2
+GITHUB_PROBE_DEADLINE_SECONDS="${EVIDENT_GITHUB_PROBE_DEADLINE_SECONDS:-10}"
 
 # What is left of the shared step budget, in whole seconds, `step_started_s`
 # seconds after it began. `SECONDS` (a bash builtin with no failure mode,
@@ -268,12 +302,66 @@ bounded_restore_call() {
   return 0
 }
 
+fetch_runner_secret() {
+  local step_started_s="$1" remaining rc=0 payload value stderr_file started_ms populated=0 missing=0
+  if [ -z "${RUNNER_SECRET_ARN:-}" ]; then
+    log "runner secret is not configured; continuing without GitHub and MCP credentials"
+    return 0
+  fi
+  remaining="$(remaining_credential_budget "${step_started_s}")"
+  if [ "${remaining}" -lt 1 ]; then
+    warn "CREDENTIAL-RESTORE-SKIPPED: runner-secret skipped; the ${CREDENTIAL_RESTORE_DEADLINE_SECONDS}s credential-restore budget is exhausted"
+    return 0
+  fi
+  if ! stderr_file="$(mktemp /dev/shm/runner-secret-stderr.XXXXXX)"; then
+    warn "RUNNER-SECRET-STDERR-UNAVAILABLE: could not allocate diagnostic storage; continuing without runner credentials"
+    return 0
+  fi
+  started_ms="$(now_ms)"
+  payload="$(timeout -k "${CREDENTIAL_RESTORE_KILL_GRACE_SECONDS}" "${remaining}" aws secretsmanager get-secret-value --secret-id "${RUNNER_SECRET_ARN}" --query SecretString --output text 2>"${stderr_file}")" || rc=$?
+  log_elapsed_since runner-secret-fetch "${started_ms}" "${rc}"
+  if [ "${rc}" -eq 124 ] || [ "${rc}" -eq 137 ]; then
+    warn "CREDENTIAL-RESTORE-TIMEOUT: runner-secret did not finish within its ${remaining}s share of the ${CREDENTIAL_RESTORE_DEADLINE_SECONDS}s credential-restore deadline; continuing without it"
+    rm -f "${stderr_file}"
+    return 0
+  fi
+  if [ "${rc}" -ne 0 ]; then
+    warn "RUNNER-SECRET-UNREADABLE: $(<"${stderr_file}")"
+    rm -f "${stderr_file}"
+    return 0
+  fi
+  rm -f "${stderr_file}"
+  if ! jq -e 'type == "object"' >/dev/null 2>&1 <<<"${payload}"; then
+    warn "RUNNER-SECRET-UNPARSEABLE: secret value is not a JSON object"
+    return 0
+  fi
+  local -a populated_keys=()
+  for key in GH_TOKEN BRAVE_API_KEY CLOUDFLARE_API_TOKEN NEON_API_KEY; do
+    value="$(jq -r --arg k "${key}" '.[$k] // empty' <<<"${payload}")"
+    if [ -n "${value}" ]; then
+      export "${key}=${value}"
+      populated=$((populated + 1))
+      populated_keys+=("${key}")
+    else
+      missing=$((missing + 1))
+    fi
+  done
+  if [ "${populated}" -eq 0 ]; then
+    warn "RUNNER-SECRET-UNPOPULATED: populate the runner secret as documented in infrastructure/evident-microvm/README.md"
+  else
+    log "RUNNER-SECRET-OK: populated ${populated_keys[*]}; ${missing} allow-listed keys empty or absent"
+  fi
+  return 0
+}
+
 restore_credentials() {
   local step_started_ms step_started_s
   step_started_ms="$(now_ms)"
   step_started_s="${SECONDS}"
 
   load_state_config || return 1
+  # This shares the existing bounded window so /run's worst-case duration does not grow.
+  fetch_runner_secret "${step_started_s}"
   bounded_restore_call restore-claude "${step_started_s}" restore claude || return 1
   bounded_restore_call restore-opencode "${step_started_s}" restore opencode || return 1
 
@@ -313,7 +401,7 @@ infrastructure/evident-microvm/README.md."
   fi
   # The step total, in the SAME greppable shape as the per-call lines above, so
   # one query answers both "what does credential restore cost?" and "which of
-  # its three calls cost it". Bounded now by CREDENTIAL_RESTORE_DEADLINE_SECONDS
+  # its four operations cost it". Bounded now by CREDENTIAL_RESTORE_DEADLINE_SECONDS
   # + CREDENTIAL_RESTORE_KILL_GRACE_SECONDS as one shared window (see the
   # comment above that constant) rather than per call. `rc=0` is deliberate
   # here, not an absence of failure modes: a timed-out call already warned by
@@ -323,6 +411,55 @@ infrastructure/evident-microvm/README.md."
   return 0
 }
 
+apply_runner_opencode_config() {
+  if [ -z "${RUNNER_OPENCODE_CONFIG:-}" ]; then
+    log "runner OpenCode config is not configured; using the baked project config"
+    return 0
+  fi
+  local source="${RUNNER_OPENCODE_CONFIG}" target="opencode.json"
+  [[ "${source}" = /* ]] || source="${WORKSPACE}/${source}"
+  [ -f "${WORKSPACE}/opencode.jsonc" ] && target="opencode.jsonc"
+  if [ ! -f "${source}" ]; then
+    error "RUNNER-OPENCODE-CONFIG-MISSING: ${source} is not a file; headless turns will wedge on the first external-directory permission prompt (#563)"
+    return 0
+  fi
+  cp "${source}" "${WORKSPACE}/${target}"
+  git -C "${WORKSPACE}" update-index --skip-worktree "${target}" 2>/dev/null \
+    || warn "could not mark ${target} skip-worktree; it may show as a local change"
+  log "Applied runner OpenCode config ${source} to ${WORKSPACE}/${target}"
+}
+
+configure_github_access() {
+  if [ -z "${GH_TOKEN:-}" ]; then
+    warn "GITHUB-CREDENTIALS-MISSING: GH_TOKEN is unavailable; see RUNNER-SECRET-* above"
+    return 0
+  fi
+  export GIT_CONFIG_GLOBAL=/tmp/gitconfig
+  if ! : >"${GIT_CONFIG_GLOBAL}" ||
+    ! git config --global user.name "${GIT_USER_NAME:-evident-bot}" ||
+    ! git config --global user.email "${GIT_USER_EMAIL:-evident-bot@users.noreply.github.com}" ||
+    ! git config --global init.defaultBranch main ||
+    ! printf '%s\n' '#!/usr/bin/env bash' '[ "$1" = get ] || exit 0' 'echo username=x-access-token' 'echo "password=${GH_TOKEN}"' >/tmp/git-credential-helper.sh ||
+    ! chmod 0700 /tmp/git-credential-helper.sh ||
+    ! git config --global credential."https://github.com".helper /tmp/git-credential-helper.sh; then
+    warn "GITHUB-SETUP-FAILED: could not configure local git credentials; continuing without GitHub access"
+    return 0
+  fi
+  (
+    local output rc=0 login repo_url repo
+    output="$(timeout -k 1 "${GITHUB_PROBE_DEADLINE_SECONDS}" gh api user --jq .login 2>&1)" || rc=$?
+    if [ "${rc}" -eq 124 ] || [ "${rc}" -eq 137 ]; then warn "GITHUB-PROBE-TIMEOUT: auth probe exceeded ${GITHUB_PROBE_DEADLINE_SECONDS}s"; return; fi
+    if [ "${rc}" -ne 0 ]; then warn "GITHUB-AUTH-REJECTED: ${output}"; return; fi
+    log "GITHUB-AUTH-OK: ${output}"
+    repo_url="$(git -C "${WORKSPACE}" remote get-url origin 2>/dev/null || true)"
+    repo="$(printf '%s' "${repo_url}" | sed -E 's#(https://github.com/|git@github.com:)##; s#\.git$##')"
+    [ -n "${repo}" ] || return
+    output="$(timeout -k 1 "${GITHUB_PROBE_DEADLINE_SECONDS}" gh api "repos/${repo}" --jq .full_name 2>&1)" || rc=$?
+    if [ "${rc}" -eq 124 ] || [ "${rc}" -eq 137 ]; then warn "GITHUB-PROBE-TIMEOUT: repository probe for ${repo} exceeded ${GITHUB_PROBE_DEADLINE_SECONDS}s"; return; fi
+    [ "${rc}" -eq 0 ] || warn "GITHUB-REPO-INACCESSIBLE: ${repo}: ${output}"
+  ) &
+}
+
 # Best-effort by design: /suspend must still drop the tunnel and /terminate must
 # still clean up, so a flush that cannot happen is loud but never fatal.
 sync_credentials() {
@@ -337,7 +474,7 @@ sync_credentials() {
 # Writes NOTHING to S3 itself; replication back to S3 is started separately by
 # `start_litestream` (below) from the `run`/`resume` hooks. `ensure_litestream_config`/
 # `restore_session_db` are the MicroVM side of the same contract
-# packages/runner-image/entrypoint.sh's inlined restore already speaks, going
+# runner/docker-images/fargate/entrypoint.sh's inlined restore already speaks, going
 # through the SAME runner-synchroniser CLI.
 
 # Reads the ~30 MB litestream binary into the page cache, in the background, so
@@ -491,6 +628,24 @@ restore_session_db() {
   # suspend/resume and a /run retry, so a marker left by an earlier boot must
   # never silently disable replication for the rest of this VM's life.
   rm -f "${SESSION_DB_NO_REPLICATE_MARKER}"
+  local report_path
+  if report_path="$(session_db_recovery_report_path)"; then
+    # The default report directory is provisioned in the image, so this is a
+    # no-op there; a shared-path override (EVIDENT_SESSION_DB_RECOVERY_REPORT)
+    # can name a directory that isn't, and the typed synchroniser writer
+    # already creates it for that same override (session-db-recovery-report.ts).
+    # Best-effort only: report_session_db_giveup below still warns and
+    # continues if this didn't leave a writable path. `${path%/*}` leaves a
+    # bare relative filename (no `/`) unchanged rather than reducing to `.`
+    # like dirname(1) — without the explicit check, mkdir would create a
+    # directory AT the report path itself.
+    local report_dir="${report_path%/*}"
+    [ "${report_dir}" = "${report_path}" ] && report_dir="."
+    [ -d "${report_dir}" ] || mkdir -p "${report_dir}" 2>/dev/null || true
+    : >"${report_path}" || warn "SESSION-DB-RECOVERY-REPORT-TRUNCATE-FAILED"
+  else
+    warn "SESSION-DB-RECOVERY-REPORT-PATH-UNAVAILABLE"
+  fi
 
   # Config resolved ONCE here, in the synchroniser (config.ts owns
   # OPENCODE_DB_PATH; no second copy of that path here), exactly as
@@ -507,6 +662,7 @@ restore_session_db() {
   log_elapsed_since session-db-env "${env_started_ms}" "${env_rc}"
   if [ "${env_rc}" -ne 0 ]; then
     mark_no_replicate "could not resolve the runner-synchroniser configuration (see the ERROR above)"
+    report_session_db_giveup synchroniser_config_unresolved
     return 0
   fi
   # Guarded for the SAME reason as the substitution above, which is easy to miss:
@@ -517,10 +673,11 @@ restore_session_db() {
   # it is the whole lifecycle transition, so Q3 makes it a give-up instead.
   eval "${synchroniser_env}" || {
     mark_no_replicate "the runner-synchroniser configuration could not be evaluated; the installed bundle likely does not match this hook"
+    report_session_db_giveup synchroniser_config_unevaluable
     return 0
   }
 
-  # #931's exact lesson, one shell over (packages/runner-image/entrypoint.sh):
+  # #931's exact lesson, one shell over (runner/docker-images/fargate/entrypoint.sh):
   # the `|| { ... }` above only catches a non-zero EXIT — an `env` that exits
   # 0 with an INCOMPLETE contract (a runner-synchroniser version/build skew)
   # would otherwise abort right here under `set -u` the moment
@@ -531,6 +688,7 @@ restore_session_db() {
   # be actively wrong, not merely absent).
   if [ -z "${OPENCODE_DB_PATH+x}" ]; then
     mark_no_replicate "run_synchroniser env did not define OPENCODE_DB_PATH; the installed runner-synchroniser build likely does not match this hook"
+    report_session_db_giveup synchroniser_config_incomplete
     return 0
   fi
 
@@ -548,6 +706,7 @@ restore_session_db() {
 
   if ! ensure_litestream_config; then
     mark_no_replicate "could not generate ${LITESTREAM_CONFIG_FILE} (see the error above)"
+    report_session_db_giveup litestream_config_unavailable
     return 0
   fi
 
@@ -566,18 +725,20 @@ restore_session_db() {
     124 | 137)
       discard_session_db_debris
       mark_no_replicate "SESSION-DB-RESTORE-TRUNCATED: litestream restore did not finish within the ${SESSION_DB_RESTORE_DEADLINE_SECONDS}s deadline (+${SESSION_DB_RESTORE_KILL_GRACE_SECONDS}s kill grace), ${SECONDS}s into the hook; opencode starts with a fresh session DB and nothing is replicated this boot"
+      report_session_db_giveup restore_deadline_exceeded "${restore_rc}"
       return 0
       ;;
     125 | 126 | 127)
       error "litestream restore could not even run (timeout exited ${restore_rc})"
       discard_session_db_debris
       mark_no_replicate "restore tool is broken (timeout exited ${restore_rc}); opencode starts with a fresh session DB and nothing is replicated this boot"
+      report_session_db_giveup restore_tool_unusable "${restore_rc}"
       return 0
       ;;
   esac
 
   local classify_rc=0
-  run_synchroniser session-db-classify "${restore_rc}" 1 --on-unusable-replica=leave || classify_rc=$?
+  run_synchroniser session-db-classify "${restore_rc}" 1 --on-unusable-replica=leave --fresh-db-fallback || classify_rc=$?
   case "${classify_rc}" in
     0) ;; # restored, or no replica yet — the CLI already logged which
     31)
@@ -587,8 +748,8 @@ restore_session_db() {
       # half-restored DB, so the marker stays; a 31 is structurally guaranteed
       # to be a FRESH one, and replicating it starts a new backup chain instead
       # of leaving this boot with a zero-width backup window. Same reasoning,
-      # and same one-line change, as packages/runner-image/entrypoint.sh's `31)`.
-      warn "SESSION-DB-REPLICA-UNUSABLE: booting with a fresh opencode.db and starting a fresh backup chain this boot (see the WARNING above)"
+      # and same one-line change, as runner/docker-images/fargate/entrypoint.sh's `31)`.
+      warn "SESSION-DB-REPLICA-UNUSABLE: booting with a fresh opencode.db and replicating into the existing prefix this boot (see the WARNING above)"
       ;;
     32)
       # The CLI's own contract for 32 is "re-run litestream restore and ask
@@ -602,11 +763,13 @@ restore_session_db() {
       # fresh rather than fail /run.
       discard_session_db_debris
       mark_no_replicate "session-db-classify returned fatal (30); see the FATAL message above"
+      report_session_db_giveup classification_fatal
       ;;
     *)
       # run_synchroniser already logged the "tool broke" ERROR for this.
       discard_session_db_debris
       mark_no_replicate "session-db-classify exited ${classify_rc}, which is none of its documented answers"
+      report_session_db_giveup classification_unrecognised
       ;;
   esac
 
@@ -1018,7 +1181,7 @@ flush_session_db() {
 # returned its 200, so it is deliberately outside that arithmetic.
 #
 # EVIDENT_IDLE_TIMEOUT_SECONDS, deliberately the SAME env var name
-# packages/runner-image/entrypoint.sh uses for the ECS runner's own
+# runner/docker-images/fargate/entrypoint.sh uses for the ECS runner's own
 # idle-timeout flag, so an operator who knows one knows the other. A
 # non-numeric override must never silently DROP the flag — that degrades to
 # an always-on VM burning ~$2.40/day, exactly the bug this closes — so it
@@ -1057,7 +1220,7 @@ start_tunnel() {
   # into a MicroVM, so it is the ONLY way to seed model credentials on a runner
   # that is already up — the S3 credential store is read at /run and /resume,
   # never mid-life. The allow-list stays a single directory, as on ECS
-  # (packages/runner-image/entrypoint.sh): the flag is repeatable, but every
+  # (runner/docker-images/fargate/entrypoint.sh): the flag is repeatable, but every
   # extra entry widens what Evident can write into a VM that executes agent
   # code. ${HOME} is set by the image (ENV HOME=/home/runner) and `set -u` makes
   # an unset one abort rather than silently allow-list "/.claude".
@@ -1104,7 +1267,7 @@ CLI_SHUTDOWN_CEILING_SECONDS=32
 # everything else in the hook. 10 s is ~4x the measured shutdown and gives a
 # provable worst case of 10 + the 10 s `suspend` spends in sync_credentials
 # before us = 20 s, inside the ~55 s the in-VM server allows this script
-# (DEFAULT_TIMEOUT_SECONDS, packages/lambda-microvm-runtime/src/runtime.ts),
+# (DEFAULT_TIMEOUT_SECONDS, aws/lambda-microvm-runtime/src/runtime.ts),
 # itself inside AWS's 60 s (HOOK_TIMEOUT_SECONDS, src/constants.ts) —
 # overrunning that fails the whole lifecycle transition, which is worse than the
 # kill this replaces. The residual cost is a drain longer than 10 s being

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

@@ -61,7 +61,7 @@ start_litestream
 # measures in ~2 s (see the waker note in common.sh).
 #
 # Safe to leave running past the hook's own exit: the runtime waits on the
-# script's `'exit'`, not `'close'` (packages/lambda-microvm-runtime/src/
+# script's `'exit'`, not `'close'` (aws/lambda-microvm-runtime/src/
 # runtime.ts), so a lingering child never delays the HTTP response. Its stdio
 # is deliberately NOT redirected — that inherited fd is how the RUNNER-KEY-*
 # line reaches CloudWatch, which is the whole point of running it at all.

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

@@ -79,7 +79,13 @@ check_runner_key "${runner_key}" "${api_url}" || exit 1
 restore_session_db
 log "session DB restore done ${SECONDS}s into the hook"
 
-# 7 — opencode. Started here, not at build time: a warm process in the shared
+# 7 — apply the overlay before OpenCode resolves its project configuration.
+apply_runner_opencode_config
+
+# 8 — configure git after credentials are restored and before agent shells start.
+configure_github_access
+
+# 9 — opencode. Started here, not at build time: a warm process in the shared
 # snapshot would carry its installation id and database into every VM. Not
 # waited on: a slow opencode boot is not a reason to fail /run (the tunnel CLI
 # auto-starts opencode when it finds none healthy,
@@ -87,14 +93,14 @@ log "session DB restore done ${SECONDS}s into the hook"
 # reclaims a runner that never comes online).
 start_opencode
 
-# 8 — begin replicating the session DB (#812 WI-3), now that opencode has
+# 10 — begin replicating the session DB (#812 WI-3), now that opencode has
 # opened it and before any work can arrive over the tunnel. Bare, like
 # restore_session_db above: start_litestream never returns non-zero (every
 # guard inside it is its own `return 0`), so there is nothing here for
 # `set -e` to abort on.
 start_litestream
 
-# 9 — the first per-VM identity on the wire. The subshell's umask makes the file
+# 11 — the first per-VM identity on the wire. The subshell's umask makes the file
 # unreadable to anyone else from the moment it exists, before the key is in it.
 (
   umask 077

package/dist/waker/construct.js

@@ -56,7 +56,7 @@ class EvidentWaker extends constructs_1.Construct {
             runtime: lambda.Runtime.NODEJS_22_X,
             // Pre-bundled at PACKAGE build time (`pnpm --filter @evident-ai/runner-cdk
             // build`, see scripts/build.ts), not at synth time: esbuild inlines
-            // @evident/webhook-signature's HMAC verifier into
+            // @evident/sdk's HMAC verifier into
             // dist/waker-lambda/handler.js, so neither this package's published npm
             // artifact (which ships dist/ already built) nor a consuming app needs
             // that private workspace package, or esbuild, on synth's PATH. Requires

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evident-ai/runner-cdk",
-  "version": "0.1.1-dev.da88f8e",
+  "version": "3.4.1-dev.1856549",
   "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,13 +15,14 @@
   ],
   "scripts": {
     "build": "pnpm run build-bundled-deps && ts-node scripts/build.ts",
-    "//build-bundled-deps": "scripts/build.ts esbuild-bundles src/microvm/image/hook-server.ts, which imports @evident-ai/lambda-microvm-runtime by its built `main`. Chained into `build` rather than left to turbo's `^build` because publish-runner-cdk.yaml invokes `pnpm --filter @evident-ai/runner-cdk build` directly, which bypasses turbo entirely.",
-    "build-bundled-deps": "pnpm --filter @evident-ai/lambda-microvm-runtime build",
+    "//build-bundled-deps": "scripts/build.ts esbuild-bundles runner/docker-images/microvm/hook-server.ts, which imports @evident-ai/lambda-microvm-runtime by its built `main`. @evident-ai/lambda-microvm-cdk is a workspace:* devDependency whose types resolve through its own dist/, so tsc --project tsconfig.build.json cannot compile src/microvm/{shapes,construct}.ts without it. Chained into `build` rather than left to turbo's `^build` because publish-runner-cdk.yaml and infrastructure/evident-runner's build-runner-cdk-dep invoke `pnpm --filter @evident-ai/runner-cdk build` directly, which bypasses turbo entirely.",
+    "build-bundled-deps": "pnpm --filter @evident-ai/lambda-microvm-cdk build && pnpm --filter @evident-ai/lambda-microvm-runtime build",
     "typecheck": "tsc --noEmit",
     "test": "node --test --require ts-node/register 'src/**/*.test.ts'",
     "format": "prettier --write 'src/**/*.ts'",
     "lint": "eslint 'src/**/*.ts' --max-warnings=0"
   },
+  "//peerDependencies": "@evident-ai/lambda-microvm-cdk is a registry range here, never workspace:*: publish-runner-cdk.yaml ships this package with `npm publish`, not `pnpm publish`, so pnpm's workspace-protocol substitution never runs and a workspace: range would reach npm literally, breaking every external install. Enforced by src/published-surface.test.ts. The matching devDependency is workspace:* so this monorepo's own build compiles against aws/lambda-microvm-cdk's source.",
   "peerDependencies": {
     "@evident-ai/lambda-microvm-cdk": "^0.1.1",
     "aws-cdk-lib": "^2.240.0",
@@ -31,16 +32,17 @@
     "@aws-sdk/client-ecs": "^3.682.0",
     "@aws-sdk/client-lambda-microvms": "^3.1095.0",
     "@aws-sdk/client-secrets-manager": "^3.682.0",
-    "@evident-ai/lambda-microvm-cdk": "^0.1.1",
+    "@evident-ai/lambda-microvm-cdk": "workspace:*",
     "@evident-ai/lambda-microvm-runtime": "workspace:*",
-    "@evident/webhook-signature": "workspace:*",
+    "@evident/sdk": "workspace:*",
     "@types/node": "^22",
     "aws-cdk-lib": "^2.240.0",
     "constructs": "^10.5.0",
     "esbuild": "^0.25.2",
     "prettier": "^3.3.3",
     "ts-node": "^10.9.2",
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "runner-microvm-image": "workspace:*"
   },
   "publishConfig": {
     "access": "public"
@@ -48,9 +50,9 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/sroze/evident.git",
-    "directory": "packages/runner-cdk"
+    "directory": "aws/runner-cdk"
   },
   "homepage": "https://evident.run",
-  "author": "Evident <contact@evident.run>",
+  "author": "Evident <hello@evident.run>",
   "license": "MIT"
 }