@evident-ai/runner-cdk 3.4.1-dev.1856549 → 3.4.1-dev.2b2679a

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

@@ -21,6 +21,12 @@ OPENCODE_PORT="${OPENCODE_PORT:-4096}"
 # /proc/<pid>/environ, which runs as that same uid. /terminate removes it.
 # shellcheck disable=SC2034  # read by the scripts that source this file
 CONTEXT_FILE="/dev/shm/evident-run-context"
+
+# The runtime injects MICROVM_ID only into /run, never /resume. This tmpfs file
+# survives suspend/resume so /resume can restore the id for every fresh CLI
+# process to self-report and acknowledge a fulfilled recycle request (#1906).
+# shellcheck disable=SC2034  # read by the scripts that source this file
+MICROVM_ID_FILE="/dev/shm/evident-microvm-id"
 TUNNEL_PID_FILE="/dev/shm/evident-tunnel.pid"
 OPENCODE_PID_FILE="/dev/shm/evident-opencode.pid"
 LITESTREAM_PID_FILE="/dev/shm/evident-litestream.pid"
@@ -37,90 +43,38 @@ STATE_PREFIX_FILE="/dev/shm/evident-state-prefix"
 # The generated litestream.yml (#812). tmpfs for the same two reasons as the
 # files above: it must never reach the block device (Q6, `docs`), and it
 # survives suspend/resume, which is what lets `/resume` start litestream again
-# with no regeneration cost. Regenerated only when absent or empty
-# (`ensure_litestream_config`, below).
+# with no regeneration cost. The CLI regenerates it only when absent or empty.
 LITESTREAM_CONFIG_FILE="/dev/shm/evident-litestream.yml"
 
-# Set when a `session-db-classify` answer of 31 (replica unusable), or a
-# restore this hook gave up on for its own reasons (a truncated `timeout`, a
-# broken tool), means this boot must NOT start `litestream replicate` — doing
-# so would let a partial/fresh local DB overwrite a replica this boot never
-# proved is safe to write over. Cleared at the top of every `restore_session_db`
-# call (i.e. every `/run`) before any other decision, so a marker left by an
-# earlier boot cannot silently disable replication for the VM's whole life.
+# Set by the CLI when session-DB restore or verification could not prove this
+# boot safe to replicate. The teardown hooks read it before flushing, and
+# `/terminate` removes it with the rest of the per-VM state.
 SESSION_DB_NO_REPLICATE_MARKER="/dev/shm/evident-session-db-no-replicate"
 
+# Completion evidence for the CLI-owned credential flush. It lives in tmpfs,
+# is removed before every handshake, and is also removed by /terminate.
+CREDENTIAL_FLUSH_MARKER_FILE="/dev/shm/evident-credential-flush"
+
 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
+# Returns the CLI's own exit code. `restore` logs domain outcomes and returns 0;
+# a non-zero status means the tool itself failed. `sync-once` returns 40 for
+# `failed`, `hashFailed`, and `localInvalid` (credentials not persisted), and 0
+# for every other outcome. The predicates answer "no" with 10, and
 # `session-db-classify`'s three typed answers are 30 (fatal)/31 (replica
-# 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:
-# that is an intentional bound firing, not a broken tool, so the caller
-# classifies it instead (restore_credentials, #930). A trailing
-# `--evident-deadline=N` (stripped below before forwarding to the CLI, and
-# never produced by anything but timed_synchroniser) is how a caller opts in;
-# every other caller — sync_credentials, restore_session_db's `env` /
-# `litestream-config` / `session-db-classify`, and this file's own contract
-# test — passes none, so 124/137 there still means a genuine external SIGKILL
-# (e.g. an OOM kill) and must keep producing the ERROR below.
+# unusable)/32 (retry), extended by `session-db-verify`'s 33 (integrity
+# exhausted, replica separated and local disposed) / 34 (could not prove
+# separation or disposal). Any status outside a command's contractual answers
+# means the tool itself broke, which is the only case worth an ERROR here.
 run_synchroniser() {
-  local -a call_args=("$@")
-  local deadline=""
-  local last=$(( ${#call_args[@]} - 1 ))
-  if [ "${last}" -ge 0 ] && [[ "${call_args[last]}" == --evident-deadline=* ]]; then
-    deadline="${call_args[last]#--evident-deadline=}"
-    call_args=("${call_args[@]:0:${last}}")
-  fi
-
   local rc=0
-  local -a launcher=()
-  [ -n "${deadline}" ] && launcher=(timeout -k "${CREDENTIAL_RESTORE_KILL_GRACE_SECONDS}" "${deadline}")
-  "${launcher[@]}" "${SYNCHRONISER}" "${call_args[@]}" || rc=$?
+  "${SYNCHRONISER}" "$@" || rc=$?
   case "${rc}" in
-    0 | 10 | 30 | 31 | 32) ;;
-    124 | 137)
-      [ -n "${deadline}" ] || error "synchroniser '${call_args[*]}' exited ${rc}; the '${SYNCHRONISER}' command is missing from PATH, corrupt, or it threw"
-      ;;
-    *) error "synchroniser '${call_args[*]}' exited ${rc}; the '${SYNCHRONISER}' command is missing from PATH, corrupt, or it threw" ;;
+    0 | 10 | 30 | 31 | 32 | 33 | 34 | 40) ;;
+    *) error "synchroniser '$*' exited ${rc}; the '${SYNCHRONISER}' command is missing from PATH, corrupt, or it threw" ;;
   esac
   return "${rc}"
 }
@@ -143,8 +97,8 @@ run_synchroniser() {
 # Never fails its caller: a timing line is diagnostics, and hardening a
 # currently-working path is worse than the gap it closes (#931). The `date`
 # fallback covers a pre-5.0 bash; a 0 means "could not read the clock", which
-# timed_synchroniser turns into `elapsed_ms=unknown` rather than aborting /run
-# under `set -e` — and rather than a 0 that would read as a fast healthy call.
+# `log_elapsed_since` turns into `elapsed_ms=unknown` rather than aborting a
+# hook under `set -e` — and rather than a 0 that would read as a fast healthy call.
 now_ms() {
   local now="${EPOCHREALTIME:-}"
   if [ -n "${now}" ]; then
@@ -155,16 +109,10 @@ now_ms() {
   date +%s%3N 2>/dev/null || echo 0
 }
 
-# Reports what one step COST, in a deliberately machine-greppable line (`op=`,
-# `elapsed_ms=`, `rc=`) so "how long does this actually take in the fleet?" is a
-# log query rather than another spike. `at_s` is where the step landed on the
-# hook's own SECONDS clock, which is what the pre-opencode budget in
-# hook-scripts.test.ts is derived against.
-#
-# Callable directly, not only through timed_synchroniser below, because the
-# steps that dominate the pre-opencode window CANNOT be wrapped: their stdout is
-# captured (`x="$(run_synchroniser env)"`, later `eval`'d), so a `log` line
-# emitted inside the substitution would be evaluated as configuration.
+# Reports what one pre-warm COST, in a deliberately machine-greppable line
+# (`op=`, `elapsed_ms=`, `rc=`) so "how long does this actually take in the
+# fleet?" is a log query rather than another spike. `at_s` is where the step
+# landed on the hook's own SECONDS clock.
 #
 # `unknown`, never a number, when either end failed to read the clock (now_ms's
 # 0). Subtracting them would report `elapsed_ms=0` — indistinguishable from a
@@ -183,26 +131,6 @@ log_elapsed_since() {
   log "SYNCHRONISER-TIMING op=${op} elapsed_ms=${elapsed_ms} rc=${rc} at_s=${SECONDS}"
 }
 
-# Runs ONE synchroniser call and reports what it COST, without changing what it
-# MEANS: the call's own status is returned untouched, so every caller's
-# `|| return 1` / `|| status=$?` keeps working exactly as before.
-#
-# `deadline` is an explicit parameter, forwarded to run_synchroniser as a
-# trailing `--evident-deadline=N` (never a global or dynamically-scoped
-# variable, #930) — every current caller (restore_credentials) always has a
-# positive remaining-budget value by the time it calls this, having already
-# decided to skip the call entirely otherwise.
-timed_synchroniser() {
-  local op="$1" deadline="$2"
-  shift 2
-
-  local started_ms rc=0
-  started_ms="$(now_ms)"
-  run_synchroniser "$@" "--evident-deadline=${deadline}" || rc=$?
-  log_elapsed_since "${op}" "${started_ms}" "${rc}"
-  return "${rc}"
-}
-
 # Exports what `runner-synchroniser` resolves its object-store location from
 # (runner/synchroniser/src/config.ts). It treats either being empty as
 # "persistence disabled" and then reports every restore as a WARNING it still
@@ -224,271 +152,32 @@ load_state_config() {
 
   # Mirrors runner-synchroniser's own persistenceEnabled predicate (config.ts):
   # both non-empty, already checked above, so by this point PERSISTENCE_BUCKET
-  # is just LITESTREAM_BUCKET. start_litestream and flush_session_db (#812
+  # is just LITESTREAM_BUCKET. The CLI's replicator and flush_session_db (#812
   # WI-3/WI-4) read ONLY this var, never LITESTREAM_BUCKET/LITESTREAM_PREFIX
   # directly, so every entry point agrees on one predicate regardless of which
-  # earlier step in THIS hook process set it: restore_session_db's
-  # `eval "$(run_synchroniser env)"` on /run, or this function on /resume,
-  # /suspend and /terminate, none of which ever call the synchroniser before
-  # needing the answer.
+  # earlier step in THIS hook process set it; /resume, /suspend and /terminate
+  # all use this same function before any teardown decision.
   export PERSISTENCE_BUCKET="${LITESTREAM_BUCKET}"
 }
 
-# /run starts no LLM task — it restores state, starts opencode and dials the
-# tunnel, none of which needs a model credential. Which credential a turn needs
-# depends on the model that turn's message asks for, so that question has no
-# single boot-time answer; it is answered per message, not here. What IS still
-# fatal is credential persistence being unavailable at all (an unset bucket/
-# prefix, or a broken synchroniser bundle) — that would silently drop refreshed
-# tokens on every suspend, so those two restores stay `|| return 1`.
-# `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 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 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
-# SIGTERM budget before the VM is destroyed mid-boot anyway. The env override
-# is for tests only, so they need not burn wall clock.
-CREDENTIAL_RESTORE_DEADLINE_SECONDS="${EVIDENT_CREDENTIAL_RESTORE_DEADLINE_SECONDS:-8}"
-# The SIGKILL backstop `timeout -k` applies after its own SIGTERM, exactly like
-# SESSION_DB_RESTORE_KILL_GRACE_SECONDS above (a bare `timeout` only SIGTERMs,
-# 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,
-# unlike `now_ms`) truncates, so a step that began at true time `s0` can read
-# less elapsed time than actually passed — the `- 1` restores the invariant
-# that no call is granted more than DEADLINE + GRACE from step start.
-remaining_credential_budget() {
-  local step_started_s="$1"
-  echo $(( CREDENTIAL_RESTORE_DEADLINE_SECONDS - (SECONDS - step_started_s) - 1 ))
-}
-
-# Runs one of the step's bounded calls: skips it with a named warn if the
-# shared budget is already exhausted, treats a timeout (124/137) as the
-# non-fatal warn-and-continue D1 approved, and keeps every other non-zero
-# fatal exactly as restore_credentials always has (`|| return 1` aborts /run
-# before opencode and the tunnel start).
-bounded_restore_call() {
-  local op="$1" step_started_s="$2"
-  shift 2
-
-  local remaining
-  remaining="$(remaining_credential_budget "${step_started_s}")"
-  if [ "${remaining}" -lt 1 ]; then
-    warn "CREDENTIAL-RESTORE-SKIPPED: ${op} skipped; the ${CREDENTIAL_RESTORE_DEADLINE_SECONDS}s credential-restore budget is exhausted"
-    return 0
-  fi
-
-  local rc=0
-  timed_synchroniser "${op}" "${remaining}" "$@" || rc=$?
-  case "${rc}" in
-    0) ;;
-    124 | 137)
-      warn "CREDENTIAL-RESTORE-TIMEOUT: ${op} did not finish within its ${remaining}s share of the ${CREDENTIAL_RESTORE_DEADLINE_SECONDS}s credential-restore deadline; continuing without it"
-      ;;
-    *) return 1 ;;
-  esac
-  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
-
-  # `restore` exits 0 whether it restored, found nothing, or discarded a corrupt
-  # object, so the synchroniser's own predicate is the only reliable answer to
-  # "can this VM authenticate a model right now". Its status is captured, not
-  # used as a condition, so it can never become this function's return status —
-  # `run` calls this bare (no `||`) under `set -euo pipefail`, and any
-  # non-zero return here would abort the hook before opencode and the tunnel
-  # ever start.
-  local auth_status=0 auth_remaining
-  auth_remaining="$(remaining_credential_budget "${step_started_s}")"
-  if [ "${auth_remaining}" -lt 1 ]; then
-    warn "CREDENTIAL-RESTORE-SKIPPED: model-auth-ready skipped; the ${CREDENTIAL_RESTORE_DEADLINE_SECONDS}s credential-restore budget is exhausted"
-  else
-    timed_synchroniser model-auth-ready "${auth_remaining}" model-auth-ready || auth_status=$?
-    case "${auth_status}" in
-      0) ;; # some model auth is configured; the two restores above already logged what they found
-      10)
-        warn "no model credentials under s3://${LITESTREAM_BUCKET}/${LITESTREAM_PREFIX}/ \
-(neither claude/credentials.json nor opencode/auth.json yielded valid JSON) and neither \
-ANTHROPIC_API_KEY nor OPENAI_API_KEY is set. This VM boots and connects; a turn that needs \
-a model provider fails until one is connected. See 'Seeding a credential store' in \
-infrastructure/evident-microvm/README.md."
-        ;;
-      124 | 137)
-        warn "CREDENTIAL-RESTORE-TIMEOUT: model-auth-ready did not finish within its ${auth_remaining}s share of the ${CREDENTIAL_RESTORE_DEADLINE_SECONDS}s credential-restore deadline; continuing without it"
-        ;;
-      *)
-        # run_synchroniser has already `error`ed the tool-broke line for a
-        # broken tool; any other unrecognised code lands here too. Do not
-        # claim there are no credentials — absent evidence is not contrary
-        # evidence (development-workflow.mdc).
-        warn "could not determine whether this VM has model credentials"
-        ;;
-    esac
-  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 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
-  # name above and is non-fatal by design (D1); every failure that DOES abort
-  # this step has already returned 1 above.
-  log_elapsed_since credential-restore-step "${step_started_ms}" 0
-  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.
+# Best-effort by design: the teardown hooks must still complete even when a
+# credential flush cannot happen.
 sync_credentials() {
   load_state_config || return 0
   run_synchroniser sync-once claude || true
   run_synchroniser sync-once opencode || true
 }
 
-# --- Session DB restore (#812 WI-2) ----------------------------------------
-#
-# Restores opencode.db from S3 before opencode opens it — the read half only.
-# 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
-# runner/docker-images/fargate/entrypoint.sh's inlined restore already speaks, going
-# through the SAME runner-synchroniser CLI.
+# --- boot pre-warms ----------------------------------------------------------
 
 # Reads the ~30 MB litestream binary into the page cache, in the background, so
 # the FIRST exec of it does not pay that read on the critical path.
 #
-# Why it is on the critical path at all: restore_session_db must finish before
-# start_opencode, and HOOK_SIGTERM_SECONDS is a POINT on the hook's SECONDS
-# clock, so a second spent here is a second taken from the rest of /run — and a
-# /run that overruns is SIGTERMed mid-boot and its VM destroyed. (Until #1172
-# the binding point was the tighter in-hook opencode readiness deadline; that
-# deadline is gone, the hook's own SIGTERM is not.)
-# Boot measurements put ~6.6-7.3s between the credential restore and the
-# litestream version line, of which only ~0.2s is accounted for by the two node
-# calls in between — the remainder is INFERRED to be this read, never measured.
+# The pre-warm overlaps the CLI's node startup and auth round trip, so the first
+# litestream operation does not also pay the binary's cold page-cache read.
+# Boot measurements put ~6.6-7.3s before the litestream version line, of which
+# only ~0.2s is accounted for by the two node calls in between — the remainder
+# is INFERRED to be this read, never measured.
 # The `litestream-prewarm` and `litestream-version` timings are what settle it
 # on the next boot.
 #
@@ -515,272 +204,40 @@ prewarm_litestream() {
   log "pre-warming ${binary} in the background"
 }
 
-# Generates ${LITESTREAM_CONFIG_FILE} from runner-synchroniser's own renderer
-# — the SAME config module the credential restore/sync already goes through,
-# so there is no second copy of the bucket/prefix/path logic to drift
-# (litestream-config.ts's own header makes the same point). Only when absent
-# or empty, so `/resume` (WI-4) restarting litestream after a suspend/resume
-# snapshot — /dev/shm intact — pays nothing to regenerate it.
-#
-# Returns 1 on failure — fatal to the CALLER, never to the hook: every caller
-# (restore_session_db here, start_litestream in WI-3) must still let opencode
-# and the tunnel start regardless.
-ensure_litestream_config() {
-  if [ -s "${LITESTREAM_CONFIG_FILE}" ]; then
-    return 0
-  fi
-
-  # Timed OUTSIDE the substitution, not with timed_synchroniser: this call's
-  # stdout IS the config, so a timing line emitted inside `$(...)` would land in
-  # litestream.yml.
-  local rendered config_started_ms config_rc=0
-  config_started_ms="$(now_ms)"
-  rendered="$(run_synchroniser litestream-config)" || config_rc=$?
-  log_elapsed_since litestream-config "${config_started_ms}" "${config_rc}"
-  if [ "${config_rc}" -ne 0 ]; then
-    error "could not generate ${LITESTREAM_CONFIG_FILE}: runner-synchroniser litestream-config failed (see the error above)"
-    return 1
-  fi
-  printf '%s\n' "${rendered}" >"${LITESTREAM_CONFIG_FILE}" || {
-    error "could not write ${LITESTREAM_CONFIG_FILE}"
-    return 1
-  }
-
-  # Q7's diagnostic, for whoever can read this VM's CloudWatch log: which way
-  # litestream resolved its AWS region, and whether it can even see the
-  # names it would need to (never the VALUES of any OTHER AWS_* variable —
-  # AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN may be present here).
-  local region_empty="yes"
-  if printf '%s\n' "${rendered}" | grep -Eq '^ *region: *[^[:space:]]'; then
-    region_empty="no"
-  fi
-  # Hoisted out of the log line below so it can be timed: this is the FIRST exec
-  # of the litestream binary on the boot, and the pre-warm /run fires (see
-  # prewarm_litestream) is aimed squarely at what this number measures.
-  local version_started_ms litestream_version
-  version_started_ms="$(now_ms)"
-  litestream_version="$(litestream version 2>/dev/null || echo 'unknown')"
-  log_elapsed_since litestream-version "${version_started_ms}" 0
-  log "litestream ${litestream_version}; AWS_REGION=${AWS_REGION:-<unset>} AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION:-<unset>}; rendered litestream.yml region empty: ${region_empty}"
-}
-
-# Writes the marker AND names the reason, in one call, so the marker can never
-# appear silently. Every give-up path in restore_session_db calls this EXCEPT
-# the classifier's 31 (#1106 — see that branch), and no success path ever does.
-# It is what a later `/resume`/`start_litestream` (WI-3) reads to skip
-# replicating this boot: a local DB that is only PARTIALLY restored must never
-# be allowed to overwrite a replica this boot never proved safe to write over.
-# A merely FRESH local DB is not that danger — litestream continues the txid
-# chain — which is precisely why 31 no longer belongs here.
-mark_no_replicate() {
-  : >"${SESSION_DB_NO_REPLICATE_MARKER}"
-  warn "SESSION-DB-NO-REPLICATE: $1"
-}
-
-# Removes local session-DB debris a give-up path leaves behind. Called on
-# EVERY give-up path and NO success path: skipping it on a give-up is a real
-# bug (a truncated file left in place makes opencode fail to open a malformed
-# database, which fails /run outright — worse than the history loss this
-# discards); calling it on a success path would delete a good restore. One
-# `rm -f` per path, not a single command, so a failure removing one does not
-# skip the other two.
-discard_session_db_debris() {
-  rm -f "${OPENCODE_DB_PATH}" "${OPENCODE_DB_PATH}-wal" "${OPENCODE_DB_PATH}-shm"
-}
-
-# How long restore_session_db waits for ONE `litestream restore` before giving
-# up. From M4 (see the plan's §2): ~50 MB/s extrapolated from the x86_64 ECS
-# container's own live replica, so 7s covers roughly 300-350 MB — an
-# EXTRAPOLATION, not a MicroVM measurement (different arch, network path and
-# credential source); the boot line ensure_litestream_config logs, plus the
-# ${SECONDS} stamps in /run, are how it gets measured here for real.
+# Reads the aws CLI v2 install tree into the page cache, in the background, so
+# the CLI's first runner-secret fetch does not pay first-touch I/O. The read
+# overlaps `evident run`'s node startup and auth round trip rather than a hook
+# deadline.
 #
-# 7 rather than the 8 it was: hook-scripts.test.ts's pre-opencode ladder held an
-# allowance of 4s for the rest of this step, which live boots measured at
-# 6.7-7.4s, so the ladder passed while real boots blew the deadline. Correcting
-# that allowance is what takes this second — the remedy the ladder's own failure
-# message prescribes, and the one that leaves the SIGTERM worst case untouched.
-# The cost is real and unmeasured on this platform: ~50 MB less restorable
-# replica before a truncation that silently loses history. A fresh
-# state_prefix starts at zero, so this is generous for a long time, but
-# RoutingStrategy is 'per_user' only (routing-strategy.ts) and every prefix is
-# deterministic and permanent per (pool, routing key) — so a long-lived
-# runner's opencode.db grows monotonically across VM generations, exactly
-# like the ~1 GB ECS one M4 measured, and will eventually hit this ceiling.
-# Past it the restore is truncated (SESSION-DB-RESTORE-TRUNCATED, below) and
-# this boot skips replication — silent, permanent history loss for that
-# runner unless somebody reads the log. Not solved here (WI-0 Task 0.2).
-# The env override is for tests only, so they need not burn 7s of wall clock.
-SESSION_DB_RESTORE_DEADLINE_SECONDS="${EVIDENT_SESSION_DB_RESTORE_DEADLINE_SECONDS:-7}"
-# The SIGKILL backstop `timeout -k` applies after its own SIGTERM: `timeout`
-# alone only SIGTERMs, and a litestream that ignored it would be unbounded
-# again. Hard ceiling on this step: DEADLINE + this = 9s.
-SESSION_DB_RESTORE_KILL_GRACE_SECONDS=2
-
-# The one bounded restore attempt, run before start_opencode (opencode opens
-# the DB the moment it starts, so this is the only place it can happen).
-# Every branch returns 0 — /run calls this bare under `set -euo pipefail`,
-# exactly like restore_credentials, and nothing about the session DB may ever
-# fail /run (Q3): a /run that exits 1 fails the whole lifecycle transition
-# and the user gets NO runner at all, which is worse than losing history.
-restore_session_db() {
-  # Cleanup, not a decision, and unconditionally first: /dev/shm survives
-  # 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
-  # entrypoint.sh's own line does. Unlike ECS's `|| die`, a failure here must
-  # not abort the hook — `x="$(cmd)"` under `set -e` WOULD abort the whole
-  # shell on a failing substitution, which is exactly why it is caught
-  # explicitly rather than left to `set -e`.
-  # Timed OUTSIDE the substitution for the same reason ensure_litestream_config
-  # is: this call's stdout is `eval`'d, so a timing line emitted inside `$(...)`
-  # would be evaluated as configuration.
-  local synchroniser_env env_started_ms env_rc=0
-  env_started_ms="$(now_ms)"
-  synchroniser_env="$(run_synchroniser env)" || env_rc=$?
-  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:
-  # `eval` returns the status of what it ran, so a malformed line from a skewed
-  # bundle would abort /run right here under `set -e` — before start_opencode,
-  # so the user gets NO runner at all. entrypoint.sh:110 leaves the identical
-  # line bare because on ECS the blast radius is a crash-loop-and-replace; here
-  # 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 (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
-  # `${OPENCODE_DB_PATH}` is dereferenced below. entrypoint.sh may `die` on
-  # this (ECS just crash-loops and replaces the task); this hook cannot —
-  # Q3 says nothing about the session DB may ever fail /run — so a missing
-  # OPENCODE_DB_PATH is a give-up, not a silent default (a guessed path would
-  # 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
-
-  # #770's arm, checked FIRST of the decisions and with its OWN message —
-  # never the SESSION-DB-REPLICA-UNUSABLE one below (#764's finding: an
-  # operator grepping that marker must not hit the disabled case).
-  # PERSISTENCE_BUCKET is empty exactly when LITESTREAM_BUCKET or
-  # LITESTREAM_PREFIX is unset (config.ts's persistenceEnabled) — the
-  # IDENTICAL predicate ECS's own litestream-launch gate uses
-  # (entrypoint.sh), so the two images agree on what "disabled" means.
-  if [ -z "${PERSISTENCE_BUCKET:-}" ]; then
-    warn "SESSION-DB-PERSISTENCE-DISABLED: LITESTREAM_BUCKET/LITESTREAM_PREFIX are not both set; opencode starts with a fresh session DB and nothing is replicated."
-    return 0
-  fi
-
-  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
+# A single `cat` of the `aws` entrypoint (litestream's pattern above) is NOT
+# enough here: v2 ships as a real Python distribution (~7,500 files under the
+# resolved binary's own directory), and a cold invocation demand-pages a
+# scattered set of them (botocore's endpoints.json/partitions.json, service
+# model JSON, shared libs) — one boot measured #1997's fetch at 7,243ms cold
+# vs ~400ms warm, an ~18x gap the litestream read-ahead trick alone cannot
+# close. `find -exec cat` walks that whole tree instead of one file.
+prewarm_aws_cli() {
+  local binary tree
+  binary="$(command -v aws 2>/dev/null || true)"
+  if [ -z "${binary}" ]; then
+    warn "aws CLI is not on PATH; skipping the boot pre-warm"
     return 0
   fi
+  tree="$(dirname "$(readlink -f "${binary}")")"
 
-  local restore_rc=0 restore_started_ms
-  restore_started_ms="$(now_ms)"
-  timeout -k "${SESSION_DB_RESTORE_KILL_GRACE_SECONDS}" "${SESSION_DB_RESTORE_DEADLINE_SECONDS}" \
-    litestream restore -config "${LITESTREAM_CONFIG_FILE}" \
-    -if-db-not-exists -if-replica-exists "${OPENCODE_DB_PATH}" || restore_rc=$?
-  log_elapsed_since session-db-restore "${restore_started_ms}" "${restore_rc}"
-
-  # `timeout`'s OWN codes, handled BEFORE classifying: 124/137 are a
-  # TRUNCATED restore, not a corrupt replica — handing them to
-  # session-db-classify would mislabel a slow/large replica as one. 125-127
-  # mean `timeout` (or litestream itself) is broken, not the replica.
-  case "${restore_rc}" in
-    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 --fresh-db-fallback || classify_rc=$?
-  case "${classify_rc}" in
-    0) ;; # restored, or no replica yet — the CLI already logged which
-    31)
-      # The classifier already discarded the local debris (session-db.ts) — and
-      # that is exactly why this is the ONE give-up path that does NOT
-      # mark_no_replicate (#1106). Every other give-up here may be sitting on a
-      # 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 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
-      # again", but this hook has budget for exactly ONE attempt (Q4) — name
-      # the deviation so nobody reads this as a bug.
-      discard_session_db_debris
-      mark_no_replicate "session-db-classify asked for another restore attempt (32), but this hook has budget for only one; treating it as a give-up rather than retrying"
-      ;;
-    30)
-      # The CLI already logged its own FATAL line above; Q3 still says boot
-      # 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
-
-  return 0
+  (
+    local started_ms rc=0
+    started_ms="$(now_ms)"
+    find "${tree}" -type f -exec cat {} + >/dev/null 2>&1 || rc=$?
+    log_elapsed_since aws-cli-prewarm "${started_ms}" "${rc}"
+  ) &
+  log "pre-warming ${tree} in the background"
 }
-# --- Session DB restore (end) -----------------------------------------------
 
 # `kill -0` answers "does this pid exist", which is not the question any caller
 # here is asking. A process that has exited but has not been reaped — a zombie —
 # still exists, so `kill -0` reports a corpse as ALIVE. That condition is the
-# normal case for everything these hooks start: `start_tunnel`/`start_opencode`
+# normal case for everything these hooks start: `start_tunnel` and its CLI child
 # background a process that outlives the hook, the hook shell must return so AWS
 # gets its 200, and PID 1 in this image is a bare node hook server with no init
 # (Dockerfile) — so nothing ever wait()s for the orphan. It stayed a zombie for
@@ -882,24 +339,6 @@ payload_is_complete() {
   ' >/dev/null 2>&1
 }
 
-# `setsid` so opencode outlives this hook: the script must return so AWS gets its
-# 200, while opencode keeps serving. The guard makes /run idempotent — a retry
-# after a killed hook must not put a second instance on the same port.
-start_opencode() {
-  if opencode_is_running; then
-    warn "opencode already running (pid $(cat "${OPENCODE_PID_FILE}")); reusing it"
-    return 0
-  fi
-
-  setsid opencode serve \
-    --hostname 127.0.0.1 \
-    --port "${OPENCODE_PORT}" \
-    --print-logs &
-
-  echo $! >"${OPENCODE_PID_FILE}"
-  log "opencode starting (pid $(cat "${OPENCODE_PID_FILE}"))"
-}
-
 stop_opencode() {
   if ! opencode_is_running; then
     # Clear the file here too, for the same reason stop_tunnel does: opencode
@@ -964,69 +403,11 @@ stop_opencode_and_wait() {
   log "opencode stopped ${outcome}"
 }
 
-# --- litestream replicate (#812 WI-3) ---------------------------------------
-#
-# The write half of session-DB persistence. restore_session_db (above) is the
-# read half only and never starts this. Q8 chose one backgrounded, unsupervised
-# `litestream replicate` over a periodic flush or a `replicate -exec` wrapper
-# around opencode: SIGTERM is `replicate`'s own final-sync trigger, so
-# stop_litestream (below) doubles as the checked flush /suspend and /terminate
-# need, and there is no supervisor in this image to hand the process to (no
-# init, no `wait -n` shell that could stay alive after the hook returns).
-
 # The graceful wait before the SIGKILL backstop in stop_litestream, below.
 # litestream's own sync is normally sub-second, so 10s is generous headroom —
 # chosen the same way TUNNEL_STOP_WAIT_SECONDS was, not a measured worst case.
 LITESTREAM_STOP_WAIT_SECONDS="${EVIDENT_LITESTREAM_STOP_WAIT_SECONDS:-10}"
 
-# Guards, in this exact order and no other — reordering any of them re-arms the
-# invariant it exists to protect:
-#
-#   1. persistence disabled (#770) — bucket AND prefix both non-empty — is its
-#      OWN arm with its OWN message, checked FIRST, and must never log
-#      SESSION-DB-REPLICA-UNUSABLE: an operator grepping that marker must not
-#      hit the disabled case (#764).
-#   2. the no-replicate marker (restore_session_db above) — set when this boot's
-#      local DB may be only PARTIALLY restored, so starting replicate here would
-#      let it overwrite a replica this boot never proved safe to write over.
-#      A classifier 31 no longer sets it (#1106): that DB is guaranteed fresh,
-#      and skipping replicate for it was what made the history loss unbounded.
-#   3. no usable config — ensure_litestream_config (restore_session_db, above)
-#      already logged why it is missing; this is not a place to retry it.
-#   4. already running — idempotence, mirroring start_tunnel's own guard.
-#
-# Only past all four does it actually spawn, backgrounded with `setsid` for the
-# same reason start_opencode/start_tunnel are: the hook must return so AWS gets
-# its 200, while replicate keeps running. litestream's OWN stderr is left to
-# reach CloudWatch — never redirected — because there is no supervisor in this
-# image, so that is the only channel that can say why a replicator died.
-start_litestream() {
-  if [ -z "${PERSISTENCE_BUCKET:-}" ]; then
-    warn "SESSION-DB-PERSISTENCE-DISABLED: LITESTREAM_BUCKET/LITESTREAM_PREFIX are not both set; nothing is replicated."
-    return 0
-  fi
-
-  if [ -e "${SESSION_DB_NO_REPLICATE_MARKER}" ]; then
-    log "skipping litestream replicate: this boot's session DB was not proven safe to replicate (see the SESSION-DB-* warning above)"
-    return 0
-  fi
-
-  if [ ! -s "${LITESTREAM_CONFIG_FILE}" ]; then
-    error "no usable ${LITESTREAM_CONFIG_FILE}; not starting litestream replicate"
-    return 0
-  fi
-
-  if litestream_is_running; then
-    warn "litestream already running (pid $(cat "${LITESTREAM_PID_FILE}")); reusing it"
-    return 0
-  fi
-
-  setsid litestream replicate -config "${LITESTREAM_CONFIG_FILE}" &
-
-  echo $! >"${LITESTREAM_PID_FILE}"
-  log "litestream replicate starting (pid $(cat "${LITESTREAM_PID_FILE}"))"
-}
-
 # The graceful stop: mirrors stop_tunnel exactly, including PROC_DEAD_REASON's
 # one deciding read AFTER the poll loop (never inside it, which polls 10x/s and
 # would bury the log) — gone / zombie / SIGKILLed are the three outcomes an
@@ -1073,7 +454,7 @@ stop_litestream() {
 # stop_tunnel's own comment argues against an argument a future caller can get
 # wrong. litestream_is_running is the same O(1) check stop_litestream's own
 # no-op branch uses, not a poll — /run's cleanup trap fires this before
-# start_litestream is ever reached whenever an earlier step failed, and an
+# the replicator start is ever reached whenever an earlier step failed, and an
 # operator reading that log must not be told a stop signal went to a process
 # that never started.
 kill_litestream() {
@@ -1099,19 +480,16 @@ kill_litestream() {
 # Ceiling for the one-shot `litestream replicate -once` flush below. litestream's
 # own sync is normally sub-second (M5, the plan's grounding); 10s is generous
 # headroom, chosen the same way LITESTREAM_STOP_WAIT_SECONDS was above — not a
-# measured worst case. The SIGKILL backstop below reuses
-# SESSION_DB_RESTORE_KILL_GRACE_SECONDS rather than its own literal: it is the
-# identical concept (bare `timeout` only SIGTERMs, and a litestream that
-# ignored it would be unbounded again), and there is no reason for the restore
-# and flush paths to ever drift on how long a SIGTERM gets to land.
+# measured worst case. The SIGKILL backstop gives the flush its own two-second
+# grace after `timeout` sends SIGTERM.
 SESSION_DB_FLUSH_DEADLINE_SECONDS="${EVIDENT_SESSION_DB_FLUSH_DEADLINE_SECONDS:-10}"
+SESSION_DB_FLUSH_KILL_GRACE_SECONDS=2
 
-# Guards mirror start_litestream's first three exactly (disabled -> marker ->
+# Guards mirror the CLI replicator's first three exactly (disabled -> marker ->
 # config) — a flush must never attempt work those guards would have refused
 # to start in the first place. PERSISTENCE_BUCKET is the SAME variable
-# start_litestream reads, so both agree regardless of which earlier step in
-# THIS process set it (load_state_config, above, or restore_session_db's
-# eval, on /run).
+# the CLI reads, so both agree regardless of which earlier step in
+# THIS process set it (load_state_config above).
 #
 # Then: stop the daemon FIRST — its SIGTERM IS litestream's own final-sync
 # trigger — and only once it is confirmed stopped does the synchronous -once
@@ -1151,7 +529,7 @@ flush_session_db() {
   # Only reached with the daemon confirmed stopped, or never running — never
   # concurrently with it (see above).
   local flush_rc=0
-  timeout -k "${SESSION_DB_RESTORE_KILL_GRACE_SECONDS}" "${SESSION_DB_FLUSH_DEADLINE_SECONDS}" \
+  timeout -k "${SESSION_DB_FLUSH_KILL_GRACE_SECONDS}" "${SESSION_DB_FLUSH_DEADLINE_SECONDS}" \
     litestream replicate -once -config "${LITESTREAM_CONFIG_FILE}" || flush_rc=$?
 
   if [ "${flush_rc}" -eq 0 ]; then
@@ -1168,11 +546,14 @@ flush_session_db() {
 # suspend it (#732). Sized from the measured cost of guessing wrong rather than
 # the saving: suspend reaches SUSPENDED in ~7 s and a resume is RUNNING in
 # ~0.6 s with the tunnel back ~2 s later (README, "Measured, end to end"), so
-# napping a VM whose user comes straight back costs ~10 s — against ~$0.30/h
-# that is cheap enough that the balance sits far nearer the floor than the
-# ceiling. Not AT the floor, though: the CLI's idle detector needs 2 clear poll
-# cycles (`run.ts`'s `idlePolls >= 2`, ≥4 s of real time), so a value near that
-# would spend more time suspending/resuming than idle.
+# napping a VM whose user comes straight back costs ~10 s — against the
+# legacy conservative baseline input of ~$0.30/h, AWS can burst a loaded VM
+# to a 16 GB / 8 vCPU peak (~$1.06/h at sustained full load—a worst-case
+# ceiling, not an expectation); that is cheap enough that the balance
+# sits far nearer the floor than the ceiling. Not AT the floor, though: the
+# CLI's idle detector needs 2 clear poll cycles (`run.ts`'s `idlePolls >= 2`,
+# ≥4 s of real time), so a value near that would spend more time
+# suspending/resuming than idle.
 # ECS's waker uses 900 s instead only because *its* cold start is far slower
 # than this VM's ~2 s resume — not evidence this default should match it.
 #
@@ -1184,7 +565,9 @@ flush_session_db() {
 # 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
+# an always-on VM burning ~$7.17/day at baseline, or up to ~$25.49/day at
+# sustained full peak as load increases (a worst-case ceiling, not an
+# expectation), exactly the bug this closes — so it
 # warns and falls back to the default instead.
 #
 # Deliberately NOT in the /run payload yet: doing so would touch the doorbell
@@ -1206,6 +589,26 @@ fi
 # its 200, while the tunnel keeps serving.
 start_tunnel() {
   local runner_key="$1" api_url="$2" tunnel_url="$3"
+  local restore_runner_credentials="${4:-false}" restore_history="${5:-false}"
+  local -a credential_flags=()
+  local -a session_db_flags=()
+  local -a opencode_config_flags=()
+
+  # The explicit fourth argument is set only by /run; /resume uses the default
+  # so a resumed VM never restores credentials over stores it already has.
+  if [ "${restore_runner_credentials}" = true ]; then
+    credential_flags=(--restore-runner-credentials)
+  fi
+
+  # Only a fresh /run asks the CLI to restore session history. /resume keeps
+  # the database from the snapshot and must not restore over it.
+  if [ "${restore_history}" = true ]; then
+    session_db_flags=(--restore-session-db)
+  fi
+
+  if [ -n "${RUNNER_OPENCODE_CONFIG:-}" ]; then
+    opencode_config_flags=(--opencode-config-overlay "${RUNNER_OPENCODE_CONFIG}")
+  fi
 
   if tunnel_is_running; then
     warn "tunnel already running (pid $(cat "${TUNNEL_PID_FILE}")); not starting a second one"
@@ -1228,6 +631,14 @@ start_tunnel() {
     --port "${OPENCODE_PORT}" \
     --endpoint "${api_url}" \
     --tunnel "${tunnel_url}" \
+    --opencode-pid-file "${OPENCODE_PID_FILE}" \
+    --litestream-config "${LITESTREAM_CONFIG_FILE}" \
+    --litestream-pid-file "${LITESTREAM_PID_FILE}" \
+    --session-db-no-replicate-marker "${SESSION_DB_NO_REPLICATE_MARKER}" \
+    --credential-sync-marker "${CREDENTIAL_FLUSH_MARKER_FILE}" \
+    "${credential_flags[@]}" \
+    "${session_db_flags[@]}" \
+    "${opencode_config_flags[@]}" \
     --idle-timeout "${IDLE_TIMEOUT_SECONDS}" \
     --enable-file-sync-to "${HOME}/.claude" &
 
@@ -1239,19 +650,17 @@ start_tunnel() {
 # whole seconds: 25 s in-flight drain (SHUTDOWN_DRAIN_TIMEOUT_MS,
 # apps/cli/src/commands/run.ts) + 2 s offline POST (notifyAgentDisconnected,
 # apps/cli/src/commands/agent-lookup.ts) + 5 s telemetry flush
-# (TELEMETRY_SHUTDOWN_TIMEOUT_MS, run.ts). Each of the three is bounded there, so
-# this is a ceiling rather than a typical cost — an idle suspend finishes in a
-# couple of seconds. This is the ONE place the budget is written down; the CLI
-# only points back here, because restating it in three places produced #657.
+# (TELEMETRY_SHUTDOWN_TIMEOUT_MS, run.ts) + 8.5 s pre-drain credential flush
+# + 8.5 s post-drain credential flush. Each phase is bounded there, so this is
+# a ceiling rather than a typical cost — an idle suspend finishes in a couple
+# of seconds. This is the ONE place the hand-maintained budget is written down;
+# the CLI points back here when its bounds change.
 #
-# DOCUMENTATION ONLY — nothing is derived from this any more. The wait below
-# used to be pinned above it, which is the reasoning that talked #699 into 40 s;
-# since #718 an exited CLI is noticed on the first poll, so the wait is a
-# backstop chosen on its own merits and the two numbers are unrelated. Nothing
-# cross-checks the 32 against apps/cli either: it is a hand-maintained sum of the
-# three bounds cited above, so if one of them moves, update it here.
+# DOCUMENTATION ONLY — nothing is derived from this value. It is the hand-maintained
+# sum of the five bounded phases above (25 + 2 + 5 + 8.5 + 8.5); update it here if
+# any of those bounds changes.
 # shellcheck disable=SC2034  # documentation; deliberately read by nothing
-CLI_SHUTDOWN_CEILING_SECONDS=32
+CLI_SHUTDOWN_CEILING_SECONDS=49
 
 # How long stop_tunnel waits for that shutdown before the SIGKILL backstop.
 # Since #718 this binds ONLY for a CLI that is still draining: one that has
@@ -1327,6 +736,85 @@ stop_tunnel() {
   log "tunnel stopped ${outcome}"
 }
 
+# The CLI owns the interval loop and its boundary flush. Two seconds of slack
+# over the CLI's 8s flush deadline keeps this marker handshake inside the 55s
+# hook ceiling while leaving the fallback flush and tunnel stop budget intact.
+#
+# This bounds only the CLI's pre-drain flush, which always runs first and
+# unconditionally (run.ts's cleanup(), before the channel-work drain) — not
+# the CLI's post-drain second pass, which can take up to
+# SHUTDOWN_DRAIN_TIMEOUT_MS longer than this wait covers. A drain that
+# consumes the whole window loses the SECOND pass, not the credential
+# guarantee itself: the pre-drain flush already persisted everything on disk
+# at signal time, exactly what the old bash `sync_credentials` guaranteed in
+# one synchronous call — so the worst case here is no worse than before this
+# handshake existed, never a fresh data-loss window. See
+# docs/decisions/0063-microvm-boot-orchestration-in-cli.md's two-phase-flush
+# section for the full reasoning.
+CREDENTIAL_FLUSH_WAIT_SECONDS="${EVIDENT_CREDENTIAL_FLUSH_WAIT_SECONDS:-10}"
+
+# Remove the previous answer, signal the same CLI that stop_tunnel handles, and
+# wait for either its marker or its death. A fallback sync runs only after the
+# CLI is known to be absent, never alongside a live CLI that may still write.
+stop_runner_and_flush_credentials() {
+  rm -f "${CREDENTIAL_FLUSH_MARKER_FILE}"
+
+  if ! tunnel_is_running; then
+    warn "CREDS-FLUSH-NO-RUNNER: no live CLI at handshake entry"
+    stop_tunnel
+    sync_credentials
+    return 0
+  fi
+
+  local pid
+  pid="$(cat "${TUNNEL_PID_FILE}")"
+  kill -TERM "${pid}" 2>/dev/null || true
+
+  local waited_ms=0 marker_found=false runner_exited=false
+  while [ "${waited_ms}" -lt $((CREDENTIAL_FLUSH_WAIT_SECONDS * 1000)) ]; do
+    if [ -s "${CREDENTIAL_FLUSH_MARKER_FILE}" ]; then
+      marker_found=true
+      break
+    fi
+    if ! process_is_alive "${pid}"; then
+      runner_exited=true
+      break
+    fi
+    sleep 0.1
+    waited_ms=$((waited_ms + 100))
+  done
+
+  # The CLI can publish the marker and exit inside one poll tick. A final
+  # marker check after a death break preserves that answer instead of falling
+  # through to the fallback.
+  if [ "${runner_exited}" = true ] && [ -s "${CREDENTIAL_FLUSH_MARKER_FILE}" ]; then
+    marker_found=true
+    runner_exited=false
+  fi
+
+  if [ "${marker_found}" = true ]; then
+    local failures
+    failures="$(grep -Ev '^(claude|opencode)=ok$' "${CREDENTIAL_FLUSH_MARKER_FILE}" || true)"
+    if [ -n "${failures}" ]; then
+      warn "CREDS-FLUSH-HAD-FAILURES: ${failures//$'\n'/ }"
+    else
+      log "CREDS-FLUSH-OK"
+    fi
+    stop_tunnel
+    return 0
+  fi
+
+  if [ "${runner_exited}" = true ]; then
+    warn "CREDS-FLUSH-RUNNER-EXITED: CLI exited without a completion marker"
+    stop_tunnel
+    sync_credentials
+    return 0
+  fi
+
+  warn "CREDS-FLUSH-TIMEOUT: live CLI did not write a completion marker within ${CREDENTIAL_FLUSH_WAIT_SECONDS}s"
+  stop_tunnel
+}
+
 # --- check_runner_key (#1172) ------------------------------------------------
 #
 # Answers exactly one question before opencode/the tunnel start spending this
@@ -1360,10 +848,9 @@ check_runner_key() {
   local runner_key="$1" api_url="$2"
 
   # status.ts's own exit-code contract (its header comment) means this exits
-  # non-zero on EVERY branch except `ok` — guarded exactly like
-  # ensure_litestream_config's `run_synchroniser litestream-config` call,
-  # above, so that expected non-zero does not abort this function under the
-  # caller's `set -e` before the case below ever runs. Only stdout is
+  # non-zero on EVERY branch except `ok`; guard the capture so an expected
+  # non-zero does not abort this function under the caller's `set -e` before
+  # the case below ever runs. Only stdout is
   # captured: status.ts's own contract is one parseable JSON line and nothing
   # else there, and — like litestream's stderr elsewhere in this file — its
   # stderr is left to reach CloudWatch directly rather than being folded in,