@evident-ai/runner-cdk 3.4.1-dev.3adba63 → 3.4.1-dev.59c7df3

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

@@ -24,6 +24,8 @@ CONTEXT_FILE="/dev/shm/evident-run-context"
 TUNNEL_PID_FILE="/dev/shm/evident-tunnel.pid"
 OPENCODE_PID_FILE="/dev/shm/evident-opencode.pid"
 LITESTREAM_PID_FILE="/dev/shm/evident-litestream.pid"
+CREDS_SYNC_PID_FILE="/dev/shm/evident-creds-sync.pid"
+CREDS_SYNC_LAST_ERROR_FILE="/dev/shm/evident-creds-sync.last-error"
 
 # Where the runner's credential store lives inside the durable-state bucket.
 # The BUCKET is the same for every VM from an image version, so the stack bakes
@@ -37,57 +39,33 @@ 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"
 
-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; }
 
 # 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 `runner/synchroniser/src/cli.ts`'s own
+# unusable)/32 (retry), extended by `session-db-verify`'s 33 (integrity
+# exhausted, replica separated and local disposed) / 34 (could not prove
+# separation or disposal) — 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.
+# 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) ;;
+    *) error "synchroniser '$*' exited ${rc}; the '${SYNCHRONISER}' command is missing from PATH, corrupt, or it threw" ;;
   esac
   return "${rc}"
 }
@@ -110,8 +88,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
@@ -122,16 +100,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
@@ -150,26 +122,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
@@ -191,271 +143,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.
 #
@@ -482,246 +195,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}"
-
-  # 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)"
-    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"
-    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"
-    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)"
+# 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"
-      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"
-      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"
-      ;;
-    *)
-      # 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"
-      ;;
-  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
@@ -810,6 +317,7 @@ regenerate_machine_id() {
 tunnel_is_running() { is_running "${TUNNEL_PID_FILE}"; }
 opencode_is_running() { is_running "${OPENCODE_PID_FILE}"; }
 litestream_is_running() { is_running "${LITESTREAM_PID_FILE}"; }
+creds_sync_is_running() { is_running "${CREDS_SYNC_PID_FILE}"; }
 
 # `jq -e` alone is not enough: its exit status reflects the LAST OUTPUT VALUE,
 # and an interpolation of a missing field is still a non-empty string, so a
@@ -823,24 +331,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
@@ -905,69 +395,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
@@ -1014,7 +446,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() {
@@ -1030,6 +462,149 @@ kill_litestream() {
 }
 # --- litestream replicate (end) ----------------------------------------------
 
+# --- credential sync loop (#1868 WI-3, ECS parity) ---------------------------
+#
+# sync_credentials (above) covers the three boundary flushes /run's restore,
+# /suspend and /terminate already call. What it does NOT cover is a VM that
+# runs for a long time between those boundaries: a provider re-authenticated
+# through the proxied UI hours into a run would sit unflushed until the next
+# suspend/terminate, and a VM that dies without one (a crash, an OOM kill)
+# loses everything since boot. runner/docker-images/fargate/entrypoint.sh's
+# own sync_credentials_loop is the ECS side of the identical gap; this is the
+# same fix, backgrounded like the other long-lived services so it
+# outlives this hook process, `( … ) &` rather than `setsid`: a plain
+# backgrounded subshell is reparented to init and keeps running once its
+# parent hook script exits (verified: PPID=1, still alive, with no controlling
+# terminal in this image to send it a stray SIGHUP), and it inherits every
+# function this file defines, so it can call run_synchroniser directly with no
+# re-exec.
+
+# Bounded confirmation window `stop_credential_sync` polls after signalling the
+# loop. The loop's current child is one fast `run_synchroniser sync-once` call,
+# so this stays a short backstop rather than a graceful drain.
+CREDS_SYNC_STOP_WAIT_SECONDS=2
+
+# Best-effort per tick, exactly like sync_credentials above: a failed tick
+# must never end the loop, or a single transient S3 error would silently
+# disable sync for the rest of the VM's life.
+start_credential_sync() {
+  if [ -z "${PERSISTENCE_BUCKET:-}" ]; then
+    warn "CREDS-SYNC-DISABLED: LITESTREAM_BUCKET/LITESTREAM_PREFIX are not both set; no interval credential sync this boot."
+    return 0
+  fi
+
+  if creds_sync_is_running; then
+    warn "credential sync loop already running (pid $(cat "${CREDS_SYNC_PID_FILE}")); reusing it"
+    return 0
+  fi
+
+  # This is the same environment input runner-synchroniser validates. The
+  # variable is normally absent, so that ordinary case uses the documented
+  # default without a warning; a present invalid value is named and rejected.
+  local interval="${CREDS_SYNC_INTERVAL:-60}"
+  if [ -n "${CREDS_SYNC_INTERVAL+x}" ] && [[ ! "${CREDS_SYNC_INTERVAL}" =~ ^[1-9][0-9]*$ ]]; then
+    warn "CREDS-SYNC-INTERVAL-INVALID: CREDS_SYNC_INTERVAL='${CREDS_SYNC_INTERVAL}' is not a positive integer; using 60s"
+    interval=60
+  fi
+
+  rm -f "${CREDS_SYNC_LAST_ERROR_FILE}"
+
+  (
+    # Releases the fds this subshell inherited from the hook process before
+    # settling in for the VM's whole remaining life: nothing here writes to
+    # them (every synchroniser call already redirects its own), so there is
+    # no reason to keep holding the hook's original stdout/stderr open. A
+    # long-lived process that instead inherited a pipe's write end (a test
+    # harness reading the hook's own output, for one) would keep that pipe
+    # from ever reporting EOF — testing-guide.mdc's own lesson, and the same
+    # reason the long-lived services never inherit stdio either. That
+    # redirect also means `warn`/`log`/`error` calls in here go nowhere, so a
+    # failed sync-once is instead recorded to CREDS_SYNC_LAST_ERROR_FILE and
+    # surfaced by stop_credential_sync, which DOES have live stdio.
+    exec >/dev/null 2>&1 </dev/null
+
+    # A TERM this subshell receives (from stop_credential_sync, below) only
+    # kills THIS wrapper by default — its currently-running child (`sleep`,
+    # or a `run_synchroniser sync-once` call) is a separate process that
+    # would otherwise be orphaned and keep running, free to upload STALE
+    # credentials to S3 after the boundary flush that /suspend and
+    # /terminate perform immediately following the stop. Tracking the
+    # current child explicitly and forwarding the signal closes that race.
+    creds_sync_child_pid=""
+    trap 'trap - TERM; [ -n "${creds_sync_child_pid}" ] && kill -TERM "${creds_sync_child_pid}" 2>/dev/null; exit 0' TERM
+
+    while true; do
+      sleep "${interval}" &
+      creds_sync_child_pid=$!
+      wait "${creds_sync_child_pid}" 2>/dev/null
+      creds_sync_child_pid=""
+
+      run_synchroniser sync-once claude &
+      creds_sync_child_pid=$!
+      wait "${creds_sync_child_pid}" 2>/dev/null || echo "claude" >"${CREDS_SYNC_LAST_ERROR_FILE}"
+      creds_sync_child_pid=""
+
+      run_synchroniser sync-once opencode &
+      creds_sync_child_pid=$!
+      wait "${creds_sync_child_pid}" 2>/dev/null || echo "opencode" >"${CREDS_SYNC_LAST_ERROR_FILE}"
+      creds_sync_child_pid=""
+    done
+  ) &
+
+  echo $! >"${CREDS_SYNC_PID_FILE}"
+  log "CREDS-SYNC-STARTED: pid=$! interval=${interval}s"
+}
+
+# Signals the loop, then confirms (bounded — see CREDS_SYNC_STOP_WAIT_SECONDS)
+# that it and its current child are actually gone before returning: /suspend
+# and /terminate start their own boundary flush immediately after this call,
+# and an orphaned in-flight sync-once surviving past that point can overwrite
+# fresher credentials with stale ones. The TERM trap inside the loop (above)
+# forwards the signal to its current child almost instantly — this poll is a
+# defensive confirmation, not the primary mechanism, so it stays short; a
+# SIGKILL backstop covers a child that ignores TERM entirely.
+#
+# The DIED branch is a liveness report, not a no-op: every recovery/no-op path
+# must say what it found (development-workflow.mdc) — a stopped-before-called
+# loop and a died-on-its-own loop are different facts an operator needs told
+# apart, not the same "nothing to stop" line.
+stop_credential_sync() {
+  if [ ! -s "${CREDS_SYNC_PID_FILE}" ]; then
+    log "CREDS-SYNC-NOT-RUNNING: no credential sync loop to stop"
+    return 0
+  fi
+
+  local pid
+  pid="$(cat "${CREDS_SYNC_PID_FILE}")"
+  if ! process_is_alive "${pid}"; then
+    rm -f "${CREDS_SYNC_PID_FILE}"
+    warn "CREDS-SYNC-DIED: credential sync loop (pid=${pid}) had already exited before this stop"
+    return 0
+  fi
+
+  kill -TERM "${pid}" 2>/dev/null || true
+  rm -f "${CREDS_SYNC_PID_FILE}"
+
+  local waited_ms=0
+  while process_is_alive "${pid}" && [ "${waited_ms}" -lt $((CREDS_SYNC_STOP_WAIT_SECONDS * 1000)) ]; do
+    sleep 0.1
+    waited_ms=$((waited_ms + 100))
+  done
+
+  if process_is_alive "${pid}"; then
+    kill -KILL "${pid}" 2>/dev/null || true
+    warn "CREDS-SYNC-STOP-TIMEOUT: pid=${pid} still alive after ${CREDS_SYNC_STOP_WAIT_SECONDS}s; sent SIGKILL"
+  fi
+
+  if [ -s "${CREDS_SYNC_LAST_ERROR_FILE}" ]; then
+    warn "CREDS-SYNC-HAD-FAILURES: sync-once failed at least once for: $(tr '\n' ' ' <"${CREDS_SYNC_LAST_ERROR_FILE}")"
+    rm -f "${CREDS_SYNC_LAST_ERROR_FILE}"
+  fi
+
+  log "CREDS-SYNC-STOPPED: pid=${pid}"
+}
+# --- credential sync loop (end) -----------------------------------------------
+
 # --- flush_session_db (#812 WI-4) -------------------------------------------
 #
 # The checked, synchronous flush /suspend and /terminate need before they
@@ -1040,19 +615,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
@@ -1092,7 +664,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
@@ -1147,6 +719,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"
@@ -1169,6 +761,13 @@ 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_flags[@]}" \
+    "${session_db_flags[@]}" \
+    "${opencode_config_flags[@]}" \
     --idle-timeout "${IDLE_TIMEOUT_SECONDS}" \
     --enable-file-sync-to "${HOME}/.claude" &
 
@@ -1301,10 +900,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,