thinkwork-cli 0.13.2 → 1.0.0

package/dist/terraform/modules/app/deployment-control-plane/test_runner_bundle.py

@@ -142,6 +142,269 @@ def test_customer_update_accepts_customer_ecr_agentcore_pi_source_image() -> Non
     )
 
 
+SECRET_PEM = "-----BEGIN PUBLIC KEY-----\nMIIFakePemBody\n-----END PUBLIC KEY-----"
+SECRET_API = "fake-api-auth-secret-000"
+PI_RECONCILE_PAYLOAD = {
+    "action": "update",
+    "awsAccountId": "637423202447",
+    "awsRegion": "us-east-1",
+    # The runtime reconcile resolves the arm64 mirror by release version tag
+    # (AgentCore is arm64-only); the amd64 Lambda pin below is NOT used for
+    # the runtime image (tei-e2e canary, 2026-08-04).
+    "releaseVersion": "v0.1.0-canary.434",
+    "agentcorePiSourceImageUri": (
+        "637423202447.dkr.ecr.us-east-1.amazonaws.com/thinkwork-tei-e2e-agentcore:pinned"
+    ),
+}
+PI_DIGEST = "sha256:" + "a" * 64
+
+
+def _pi_reconcile_fixture(runner, tmp_path, monkeypatch, ssm_runtime_id):
+    entry_dir = tmp_path / "control-runtime"
+    entry_dir.mkdir()
+    (entry_dir / "reconcile_pi_runtime.js").write_text("// stub", encoding="utf-8")
+    monkeypatch.setenv("THINKWORK_AGENTCORE_CONTROL_RUNTIME_DIR", str(entry_dir))
+
+    calls = {"output": [], "run": [], "node": []}
+
+    def fake_output(args, **kwargs):
+        calls["output"].append(args)
+        if args[1] == "lambda":
+            return json.dumps(
+                {
+                    "Role": "arn:aws:iam::637423202447:role/thinkwork-tei-e2e-agentcore-pi-role",
+                    "FunctionArn": (
+                        "arn:aws:lambda:us-east-1:637423202447:function:thinkwork-tei-e2e-agentcore-pi"
+                    ),
+                    "Environment": {
+                        "Variables": {
+                            "CAPABILITY_SIGNING_PUBLIC_KEY": SECRET_PEM,
+                            "API_AUTH_SECRET": SECRET_API,
+                        }
+                    },
+                }
+            )
+        if args[1] == "ecr":
+            return PI_DIGEST
+        if args[1] == "ssm":
+            if ssm_runtime_id is None:
+                raise subprocess.CalledProcessError(255, args)
+            return ssm_runtime_id
+        raise AssertionError(f"unexpected output() args: {args}")
+
+    def fake_run(args, **kwargs):
+        calls["run"].append(args)
+        return SimpleNamespace(returncode=0)
+
+    def fake_subprocess_run(args, **kwargs):
+        calls["node"].append({"args": args, "input": kwargs.get("input", "")})
+        return SimpleNamespace(
+            returncode=0,
+            stdout=json.dumps(
+                {
+                    "runtimeId": "rt-pi-123",
+                    "created": ssm_runtime_id is None,
+                    "version": "7",
+                    "status": "READY",
+                    "envCount": 2,
+                }
+            ),
+            stderr="",
+        )
+
+    monkeypatch.setattr(runner, "output", fake_output)
+    monkeypatch.setattr(runner, "run", fake_run)
+    monkeypatch.setattr(runner.subprocess, "run", fake_subprocess_run)
+    return calls
+
+
+def test_pi_runtime_reconcile_creates_when_absent_and_writes_ssm(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture
+) -> None:
+    runner = load_runner()
+    calls = _pi_reconcile_fixture(runner, tmp_path, monkeypatch, ssm_runtime_id=None)
+
+    result = runner.reconcile_agentcore_pi_runtime({"stage": "tei-e2e"}, PI_RECONCILE_PAYLOAD)
+
+    assert result["runtimeId"] == "rt-pi-123"
+    request = json.loads(calls["node"][0]["input"])
+    assert request["runtimeId"] == ""
+    # AgentCore names forbid hyphens ([a-zA-Z][a-zA-Z0-9_]{0,47}) — the
+    # tei-e2e canary proved the unsanitized name 400s (2026-08-04).
+    assert request["runtimeName"] == "thinkwork_tei_e2e_pi"
+    # The runtime image resolves from the versioned arm64 mirror tag, never
+    # from the amd64 Lambda pin.
+    ecr_calls = [args for args in calls["output"] if args[1] == "ecr"]
+    assert any("imageTag=v0.1.0-canary.434-pi-arm64" in " ".join(args) for args in ecr_calls)
+    assert request["imageUri"].endswith(f"@{PI_DIGEST}")
+    assert request["environment"]["API_AUTH_SECRET"] == SECRET_API
+    assert "\\n" in request["environment"]["CAPABILITY_SIGNING_PUBLIC_KEY"]
+    assert "\n" not in request["environment"]["CAPABILITY_SIGNING_PUBLIC_KEY"]
+    ssm_put = [args for args in calls["run"] if args[2] == "put-parameter"]
+    assert len(ssm_put) == 1 and "rt-pi-123" in ssm_put[0]
+    # R19: secret values never reach argv or logs.
+    for args in calls["node"]:
+        assert SECRET_API not in " ".join(args["args"])
+    captured = capsys.readouterr()
+    assert SECRET_API not in captured.out + captured.err
+    assert "MIIFakePemBody" not in captured.out + captured.err
+
+
+def test_pi_runtime_reconcile_updates_when_present(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    calls = _pi_reconcile_fixture(runner, tmp_path, monkeypatch, ssm_runtime_id="rt-pi-123")
+
+    result = runner.reconcile_agentcore_pi_runtime({"stage": "tei-e2e"}, PI_RECONCILE_PAYLOAD)
+
+    assert result["runtimeId"] == "rt-pi-123"
+    request = json.loads(calls["node"][0]["input"])
+    assert request["runtimeId"] == "rt-pi-123"
+    assert [args for args in calls["run"] if args[2] == "put-parameter"]
+
+
+def test_pi_runtime_reconcile_aborts_on_empty_lambda_env(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    calls = _pi_reconcile_fixture(runner, tmp_path, monkeypatch, ssm_runtime_id="rt-pi-123")
+
+    def empty_env_output(args, **kwargs):
+        if args[1] == "lambda":
+            return json.dumps(
+                {
+                    "Role": "arn:aws:iam::637423202447:role/r",
+                    "FunctionArn": "arn:aws:lambda:us-east-1:637423202447:function:f",
+                    "Environment": {"Variables": {}},
+                }
+            )
+        raise AssertionError("must abort before any non-lambda call")
+
+    monkeypatch.setattr(runner, "output", empty_env_output)
+
+    with pytest.raises(RuntimeError, match="EMPTY environment"):
+        runner.reconcile_agentcore_pi_runtime({"stage": "tei-e2e"}, PI_RECONCILE_PAYLOAD)
+    assert not calls["node"]
+
+
+def test_pi_runtime_reconcile_skips_on_legacy_bundle(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture
+) -> None:
+    runner = load_runner()
+    monkeypatch.delenv("THINKWORK_AGENTCORE_CONTROL_RUNTIME_DIR", raising=False)
+
+    assert runner.reconcile_agentcore_pi_runtime({"stage": "tei-e2e"}, PI_RECONCILE_PAYLOAD) is None
+    assert "SKIPPED" in capsys.readouterr().out
+
+
+def test_native_auth_custom_attributes_skip_before_user_pool_exists(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    monkeypatch.setattr(
+        runner,
+        "output",
+        lambda *_args, **_kwargs: pytest.fail("Cognito should not be queried"),
+    )
+
+    assert runner.ensure_native_auth_custom_attributes({}) == {
+        "status": "skipped",
+        "reason": "user-pool-not-created",
+    }
+
+
+def test_native_auth_custom_attributes_are_added_before_route_clients(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    descriptions = iter(
+        [
+            json.dumps(
+                {
+                    "UserPool": {
+                        "SchemaAttributes": [
+                            {"Name": "email"},
+                            {"Name": "custom:tenant_id"},
+                        ]
+                    }
+                }
+            ),
+            json.dumps(
+                {
+                    "UserPool": {
+                        "SchemaAttributes": [
+                            {"Name": "email"},
+                            {"Name": "custom:tenant_id"},
+                            {"Name": "custom:entra_tenant_id"},
+                            {"Name": "custom:entra_object_id"},
+                        ]
+                    }
+                }
+            ),
+        ]
+    )
+    calls = []
+    monkeypatch.setattr(runner, "output", lambda *_args, **_kwargs: next(descriptions))
+    monkeypatch.setattr(
+        runner,
+        "run",
+        lambda args, **kwargs: calls.append((args, kwargs)),
+    )
+
+    result = runner.ensure_native_auth_custom_attributes(
+        {"user_pool_id": {"value": "us-east-1_Example123"}}
+    )
+
+    assert result == {
+        "status": "reconciled",
+        "userPoolId": "us-east-1_Example123",
+        "added": ["entra_tenant_id", "entra_object_id"],
+    }
+    assert len(calls) == 1
+    command, kwargs = calls[0]
+    assert command[:3] == ["aws", "cognito-idp", "add-custom-attributes"]
+    request = json.loads(command[command.index("--cli-input-json") + 1])
+    assert request == {
+        "UserPoolId": "us-east-1_Example123",
+        "CustomAttributes": runner.NATIVE_AUTH_CUSTOM_ATTRIBUTES,
+    }
+    assert kwargs == {"stdout": subprocess.DEVNULL}
+
+
+def test_native_auth_custom_attributes_are_idempotent(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    monkeypatch.setattr(
+        runner,
+        "output",
+        lambda *_args, **_kwargs: json.dumps(
+            {
+                "UserPool": {
+                    "SchemaAttributes": [
+                        {"Name": "custom:entra_tenant_id"},
+                        {"Name": "custom:entra_object_id"},
+                    ]
+                }
+            }
+        ),
+    )
+    monkeypatch.setattr(
+        runner,
+        "run",
+        lambda *_args, **_kwargs: pytest.fail("No mutation should be required"),
+    )
+
+    assert runner.ensure_native_auth_custom_attributes(
+        {"user_pool_id": {"value": "us-east-1_Example123"}}
+    ) == {
+        "status": "current",
+        "userPoolId": "us-east-1_Example123",
+        "added": [],
+    }
+
+
 def test_native_auth_reconciliation_builds_route_specific_secret_free_manifest(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
@@ -226,6 +489,54 @@ def test_native_auth_reconciliation_builds_route_specific_secret_free_manifest(
     assert replay_state == state
 
 
+def _microsoft_reconciliation_scope(tenant: str) -> tuple[dict, dict]:
+    outputs = {
+        "user_pool_id": {"value": "us-east-1_TESTPOOL"},
+        "auth_route_clients": {
+            "value": {
+                "web:microsoft": {
+                    "client_id": "zyxwvutsrqponmlkjihgfedcba",
+                    "route_key": "microsoft",
+                    "client_family": "web",
+                    "provider_names": ["MicrosoftOrganizations"],
+                    "explicit_auth_flows": ["ALLOW_REFRESH_TOKEN_AUTH"],
+                    "callback_urls": ["https://app.example/auth/callback"],
+                    "logout_urls": ["https://app.example"],
+                    "lifecycle_state": "native",
+                },
+            }
+        },
+    }
+    scope = {
+        "stage": "dev",
+        "account_id": "123456789012",
+        "region": "us-east-1",
+        "microsoft_oauth_tenant": tenant,
+    }
+    return outputs, scope
+
+
+@pytest.mark.parametrize("alias", ["common", "organizations", "consumers"])
+def test_native_auth_reconciliation_accepts_cognito_tenant_aliases(alias: str) -> None:
+    runner = load_runner()
+    outputs, scope = _microsoft_reconciliation_scope(alias)
+    payload, _ = runner.native_auth_reconciliation_payload(outputs, scope, {})
+    microsoft_connection = next(
+        item
+        for item in payload["connections"]
+        if item["connectionKey"] == "microsoft:organizations"
+    )
+    assert microsoft_connection["issuerUrl"] == (f"https://login.microsoftonline.com/{alias}/v2.0")
+
+
+@pytest.mark.parametrize("tenant", ["tenant.example", "contoso", "9d65869f", ""])
+def test_native_auth_reconciliation_rejects_arbitrary_tenant_values(tenant: str) -> None:
+    runner = load_runner()
+    outputs, scope = _microsoft_reconciliation_scope(tenant)
+    with pytest.raises(RuntimeError, match="Entra directory GUID or one of"):
+        runner.native_auth_reconciliation_payload(outputs, scope, {})
+
+
 def tenant_entra_operation(action: str, revision: int = 1) -> dict:
     tenant_id = "00000000-0000-4000-8000-000000000123"
     payload = {
@@ -539,6 +850,214 @@ def test_sync_release_artifacts_stages_artifacts_from_platform_bundle(
     assert {artifact["source"] for artifact in runner.RELEASE_EVIDENCE["artifacts"]} == {"bundle"}
 
 
+def test_packaged_agentcore_control_runtime_is_exact_and_runnable(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    repo_root = Path(__file__).resolve().parents[4]
+    release_dir = tmp_path / "release"
+    runner_dir = release_dir / "bundles" / "platform" / "runner"
+    subprocess.run(
+        [
+            "bash",
+            str(repo_root / "scripts/release/package-agentcore-control-runtime.sh"),
+            str(runner_dir),
+        ],
+        cwd=repo_root,
+        check=True,
+        text=True,
+    )
+
+    monkeypatch.setattr(runner, "RELEASE", release_dir)
+    monkeypatch.setattr(runner, "RELEASE_EVIDENCE", {})
+    monkeypatch.delenv("THINKWORK_AGENTCORE_CONTROL_RUNTIME_DIR", raising=False)
+
+    evidence = runner.prepare_agentcore_control_runtime()
+
+    assert evidence["sdkVersion"] == "3.1089.0"
+    assert int(evidence["nodeVersion"].removeprefix("v").split(".", 1)[0]) >= 22
+    assert evidence["bundledRuntimeVerified"] is True
+    assert evidence["bundledEntrypoints"] == [
+        "preflight.js",
+        "reconcile_pi_runtime.js",
+        "reconcile_twenty_provider.js",
+    ]
+    assert json.loads(
+        (runner_dir / "agentcore-control-runtime" / "package.json").read_text(encoding="utf-8")
+    ) == {"type": "module"}
+    assert os.environ["THINKWORK_AGENTCORE_CONTROL_RUNTIME_DIR"] == str(
+        runner_dir / "agentcore-control-runtime"
+    )
+    assert all(item["sdkImportReady"] for item in evidence["entrypointPreflights"])
+
+
+@pytest.mark.parametrize("version", ["v22.14.0", "v24.1.0", "26.5.0"])
+def test_agentcore_control_runtime_accepts_supported_node_versions(version: str) -> None:
+    runner = load_runner()
+
+    assert runner.validate_agentcore_node_runtime(version).startswith("v")
+
+
+@pytest.mark.parametrize("version", ["v20.19.5", "v18.20.8", "unknown", ""])
+def test_agentcore_control_runtime_rejects_unsupported_node_versions(version: str) -> None:
+    runner = load_runner()
+
+    with pytest.raises(RuntimeError, match="Node.js 22|Cannot determine"):
+        runner.validate_agentcore_node_runtime(version)
+
+
+@pytest.mark.parametrize("action", ["deploy", "update", "plan", "apply", "destroy"])
+def test_agentcore_control_runtime_is_required_even_when_proof_is_disabled(
+    action: str,
+) -> None:
+    runner = load_runner()
+
+    assert runner.requires_agentcore_control_runtime(
+        action,
+        {"enableAgentCoreHarness": False},
+        None,
+    )
+
+
+def test_web_only_release_sync_does_not_require_agentcore_control_runtime() -> None:
+    runner = load_runner()
+
+    assert runner.release_sync_request("web", {}, None) == {
+        "artifact_types": {"static-site"},
+        "artifact_names": {"web"},
+    }
+    assert not runner.requires_agentcore_control_runtime("web", {}, None)
+
+
+def _state_document(check_results):
+    return {
+        "version": 4,
+        "terraform_version": "1.9.8",
+        "serial": 820,
+        "lineage": "61f4093e-41da-ac29-852a-267bc853e24f",
+        "resources": [{"type": "aws_s3_bucket", "name": "evidence"}],
+        "check_results": check_results,
+    }
+
+
+def test_state_identity_is_stable_across_check_results_render_order(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    check_a = {"object_kind": "var", "config_addr": "module.a.var.x", "status": "pass"}
+    check_b = {"object_kind": "var", "config_addr": "module.b.var.y", "status": "pass"}
+    pulls = iter(
+        [
+            json.dumps(_state_document([check_a, check_b]), indent=2) + "\n",
+            json.dumps(_state_document([check_b, check_a]), indent=2) + "\n",
+        ]
+    )
+    monkeypatch.setattr(runner, "output", lambda *_args, **_kwargs: next(pulls))
+
+    first = runner.terraform_state_identity()
+    second = runner.terraform_state_identity()
+
+    assert first == second
+    assert first["lineage"] == "61f4093e-41da-ac29-852a-267bc853e24f"
+    assert first["serial"] == 820
+    assert first["terraformVersion"] == "1.9.8"
+
+
+def test_state_identity_changes_when_resources_change(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    base = _state_document([])
+    changed = dict(base, serial=821, resources=[])
+    pulls = iter([json.dumps(base), json.dumps(changed)])
+    monkeypatch.setattr(runner, "output", lambda *_args, **_kwargs: next(pulls))
+
+    first = runner.terraform_state_identity()
+    second = runner.terraform_state_identity()
+
+    assert first["sha256"] != second["sha256"]
+    assert second["serial"] == 821
+
+
+def test_state_identity_still_refuses_missing_lineage(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    document = _state_document([])
+    document.pop("lineage")
+    monkeypatch.setattr(runner, "output", lambda *_args, **_kwargs: json.dumps(document))
+
+    with pytest.raises(RuntimeError, match="no lineage"):
+        runner.terraform_state_identity()
+
+
+def test_deployment_status_pointer_writes_for_saved_plan_apply(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("THINKWORK_EVIDENCE_BUCKET", "evidence-bucket")
+    monkeypatch.setenv("THINKWORK_DEPLOYMENT_ACTION", "apply")
+    monkeypatch.delenv("THINKWORK_MANAGED_APP_OPERATION", raising=False)
+    commands = []
+    monkeypatch.setattr(runner, "read_current_status_pointer", lambda _bucket: {})
+    monkeypatch.setattr(runner, "run", lambda args, **_kwargs: commands.append(args))
+
+    runner.write_deployment_status_pointer(
+        "succeeded", {"stage": "tei-e2e", "account_id": "637423202447"}
+    )
+
+    assert any(
+        arg.endswith("deployment/status/current.json") for command in commands for arg in command
+    )
+
+
+def test_saved_plan_apply_stages_the_approved_release_artifacts() -> None:
+    runner = load_runner()
+
+    assert runner.release_sync_request("apply", {}, None) == {
+        "artifact_types": None,
+        "artifact_names": None,
+    }
+
+
+def test_packaged_agentcore_control_runtime_rebuild_removes_stale_files(
+    tmp_path: Path,
+) -> None:
+    repo_root = Path(__file__).resolve().parents[4]
+    runner_dir = tmp_path / "runner"
+    runtime_dir = runner_dir / "agentcore-control-runtime"
+    runtime_dir.mkdir(parents=True)
+    (runtime_dir / "stale-chunk.js").write_text("stale\n", encoding="utf-8")
+
+    subprocess.run(
+        [
+            "bash",
+            str(repo_root / "scripts/release/package-agentcore-control-runtime.sh"),
+            str(runner_dir),
+        ],
+        cwd=repo_root,
+        check=True,
+        text=True,
+    )
+
+    manifest = json.loads(
+        (runner_dir / "agentcore-control-runtime.json").read_text(encoding="utf-8")
+    )
+    paths = {item["path"] for item in manifest["files"]}
+    generated = {
+        str(path.relative_to(runtime_dir)) for path in runtime_dir.rglob("*") if path.is_file()
+    }
+    assert "stale-chunk.js" not in generated
+    assert paths == generated
+    assert {path for path in paths if "/" not in path} == {
+        "package.json",
+        "preflight.js",
+        "reconcile_pi_runtime.js",
+        "reconcile_twenty_provider.js",
+    }
+
+
 def test_ensure_release_manifest_available_accepts_manifest_file_digest(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
@@ -576,13 +1095,13 @@ def test_sync_release_artifacts_can_materialize_only_web_static_bundle(
     bundle_path = tmp_path / "platform-artifacts.tar.gz"
     lambda_bytes = b"lambda-zip"
     web_bytes = b"web-tarball"
-    docs_bytes = b"docs-tarball"
+    extra_bytes = b"extra-tarball"
     write_tar(
         bundle_path,
         {
             "lambdas/graphql-http.zip": lambda_bytes,
             "static/web.tar.gz": web_bytes,
-            "static/docs.tar.gz": docs_bytes,
+            "static/extra.tar.gz": extra_bytes,
         },
     )
     artifacts = [
@@ -605,13 +1124,13 @@ def test_sync_release_artifacts_can_materialize_only_web_static_bundle(
             "sizeBytes": len(web_bytes),
         },
         {
-            "name": "docs",
+            "name": "extra",
             "type": "static-site",
-            "fileName": "docs.tar.gz",
-            "relativePath": "static/docs.tar.gz",
+            "fileName": "extra.tar.gz",
+            "relativePath": "static/extra.tar.gz",
             "url": None,
-            "sha256": digest(docs_bytes),
-            "sizeBytes": len(docs_bytes),
+            "sha256": digest(extra_bytes),
+            "sizeBytes": len(extra_bytes),
         },
     ]
     manifest_sha = write_manifest(
@@ -629,10 +1148,12 @@ def test_sync_release_artifacts_can_materialize_only_web_static_bundle(
     monkeypatch.setenv("THINKWORK_RELEASE_ARTIFACT_BUCKET", "thinkwork-artifacts")
     monkeypatch.setattr(runner, "run", lambda args, **_kwargs: calls.append(args))
 
-    static_files = runner.sync_release_artifacts(
-        artifact_types={"static-site"},
-        artifact_names={"web"},
-    )
+    release_request = runner.release_sync_request("web", {}, None)
+    assert release_request == {
+        "artifact_types": {"static-site"},
+        "artifact_names": {"web"},
+    }
+    static_files = runner.sync_release_artifacts(**release_request)
 
     assert static_files == {"web": release_dir / "static/web.tar.gz"}
     assert static_files["web"].read_bytes() == web_bytes
@@ -1467,6 +1988,13 @@ def test_write_runner_files_persists_selected_release_to_controller_module(
     assert "deployment_release_manifest_signature_url" in main_tf
     assert "deployment_release_manifest_trusted_keys_json" in main_tf
     assert "deployment_terraform_module_source" in main_tf
+    assert 'required_version = ">= 1.8.5"' in main_tf
+    assert (
+        "from = "
+        "module.thinkwork.module.agentcore_proof_identity."
+        "terraform_data.twenty_identity_lifecycle"
+    ) in main_tf
+    assert "destroy = false" in main_tf
 
 
 def _cognito_email_runner_env(runner, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
@@ -1554,17 +2082,11 @@ def test_write_runner_files_threads_cognito_email_vars_from_payload(
         assert f"= var.{name}" in main_tf
 
 
-def test_write_runner_files_repins_stale_thinkwork_git_module_source_to_release(
+def test_write_runner_files_threads_agentcore_harness_config_from_preserved_payload(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     runner = load_runner()
     tf_dir = _cognito_email_runner_env(runner, tmp_path, monkeypatch)
-    monkeypatch.setenv(
-        "THINKWORK_TERRAFORM_MODULE_SOURCE",
-        "git::https://github.com/thinkwork-ai/thinkwork.git"
-        "//terraform/modules/thinkwork?ref=c66a3aa7f3a5606c66b920b40b39af57a7cc06d0",
-    )
-    monkeypatch.setenv("THINKWORK_TERRAFORM_MODULE_VERSION", "0.1.0-canary.150")
 
     vars_json = runner.write_runner_files(
         {
@@ -1573,25 +2095,69 @@ def test_write_runner_files_repins_stale_thinkwork_git_module_source_to_release(
             "awsAccountId": "637423202447",
             "dbPassword": "db-secret",
             "apiAuthSecret": "api-secret",
+            "preservedConfig": {
+                "enableAgentCoreHarness": True,
+                "agentCoreHarnessTenantSlug": "tei",
+                "agentCoreHarnessOwnerAllowlist": "owner-a,owner-b",
+            },
         },
         {},
     )
 
-    main_tf = (tf_dir / "main.tf").read_text(encoding="utf-8")
+    assert vars_json["enable_agentcore_multiplayer_proof"] is True
+    assert vars_json["agentcore_multiplayer_proof_tenant_slug"] == "tei"
+    assert vars_json["agentcore_multiplayer_proof_owner_allowlist"] == "owner-a,owner-b"
 
-    assert "ref=abc123" in main_tf
-    assert "ref=c66a3aa7f3a5606c66b920b40b39af57a7cc06d0" not in main_tf
-    assert vars_json["deployment_terraform_module_source"].endswith(
-        "//terraform/modules/thinkwork?ref=abc123"
-    )
-    assert vars_json["deployment_terraform_module_version"] == ""
+    tfvars = json.loads((tf_dir / "terraform.auto.tfvars.json").read_text(encoding="utf-8"))
+    assert tfvars["enable_agentcore_multiplayer_proof"] is True
+    main_tf = (tf_dir / "main.tf").read_text(encoding="utf-8")
+    for name in (
+        "enable_agentcore_multiplayer_proof",
+        "agentcore_multiplayer_proof_tenant_slug",
+        "agentcore_multiplayer_proof_owner_allowlist",
+    ):
+        assert f'variable "{name}"' in main_tf
+        assert f"= var.{name}" in main_tf
 
 
-def test_write_runner_files_cognito_email_vars_prefer_runner_secrets_and_default_empty(
+def test_write_runner_files_repins_stale_thinkwork_git_module_source_to_release(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     runner = load_runner()
-    _cognito_email_runner_env(runner, tmp_path, monkeypatch)
+    tf_dir = _cognito_email_runner_env(runner, tmp_path, monkeypatch)
+    monkeypatch.setenv(
+        "THINKWORK_TERRAFORM_MODULE_SOURCE",
+        "git::https://github.com/thinkwork-ai/thinkwork.git"
+        "//terraform/modules/thinkwork?ref=c66a3aa7f3a5606c66b920b40b39af57a7cc06d0",
+    )
+    monkeypatch.setenv("THINKWORK_TERRAFORM_MODULE_VERSION", "0.1.0-canary.150")
+
+    vars_json = runner.write_runner_files(
+        {
+            "stage": "tei-e2e",
+            "awsRegion": "us-east-1",
+            "awsAccountId": "637423202447",
+            "dbPassword": "db-secret",
+            "apiAuthSecret": "api-secret",
+        },
+        {},
+    )
+
+    main_tf = (tf_dir / "main.tf").read_text(encoding="utf-8")
+
+    assert "ref=abc123" in main_tf
+    assert "ref=c66a3aa7f3a5606c66b920b40b39af57a7cc06d0" not in main_tf
+    assert vars_json["deployment_terraform_module_source"].endswith(
+        "//terraform/modules/thinkwork?ref=abc123"
+    )
+    assert vars_json["deployment_terraform_module_version"] == ""
+
+
+def test_write_runner_files_cognito_email_vars_prefer_runner_secrets_and_default_empty(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    _cognito_email_runner_env(runner, tmp_path, monkeypatch)
     secret_arn = "arn:aws:ses:us-east-1:637423202447:identity/secret.example.com"
 
     vars_json = runner.write_runner_files(
@@ -1649,6 +2215,54 @@ def test_write_runner_files_cognito_email_vars_prefer_runner_secrets_and_default
     assert vars_json_retired["finalize_auth_retirement"] is True
 
 
+def test_write_runner_files_threads_additional_admin_callback_urls(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    _cognito_email_runner_env(runner, tmp_path, monkeypatch)
+
+    # runner-secrets carries the customer's hosted console origins; a
+    # comma-separated string and a JSON-array string must both parse, and the
+    # module wiring must be present so the URLs actually reach the web clients.
+    vars_json = runner.write_runner_files(
+        {
+            "stage": "mcpherson",
+            "awsRegion": "us-east-1",
+            "awsAccountId": "024350822488",
+            "dbPassword": "db-secret",
+            "apiAuthSecret": "api-secret",
+        },
+        {
+            "adminCallbackUrls": (
+                "https://console.example.net, https://console.example.net/auth/callback"
+            ),
+            "adminLogoutUrls": '["https://console.example.net"]',
+        },
+    )
+    assert vars_json["additional_admin_callback_urls"] == [
+        "https://console.example.net",
+        "https://console.example.net/auth/callback",
+    ]
+    assert vars_json["additional_admin_logout_urls"] == ["https://console.example.net"]
+    main_tf = (runner.TF / "main.tf").read_text(encoding="utf-8")
+    assert "additional_admin_callback_urls = var.additional_admin_callback_urls" in main_tf
+    assert "additional_admin_logout_urls   = var.additional_admin_logout_urls" in main_tf
+
+    # Default: no runner-secrets keys -> empty lists (no behavior change).
+    vars_json_default = runner.write_runner_files(
+        {
+            "stage": "mcpherson",
+            "awsRegion": "us-east-1",
+            "awsAccountId": "024350822488",
+            "dbPassword": "db-secret",
+            "apiAuthSecret": "api-secret",
+        },
+        {},
+    )
+    assert vars_json_default["additional_admin_callback_urls"] == []
+    assert vars_json_default["additional_admin_logout_urls"] == []
+
+
 def test_write_runner_files_defaults_existing_preauth_stack_to_coexistence(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
@@ -1733,49 +2347,13 @@ def test_main_reconciles_native_auth_before_destructive_schema() -> None:
     source = Path(__file__).with_name("runner.py").read_text(encoding="utf-8")
     post_apply = source[source.index("def main():") :]
     reconciliation = post_apply.index(
-        "CONTROLLER_EVIDENCE[\"authReconciliation\"] = reconcile_native_auth_metadata"
+        'CONTROLLER_EVIDENCE["authReconciliation"] = reconcile_native_auth_metadata'
     )
     schema = post_apply.index("push_database_schema(outputs_path, vars_json)", reconciliation)
 
     assert reconciliation < schema
 
 
-def test_write_runner_files_wires_analyst_lambda_vpc_egress(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-) -> None:
-    """analyst_lambda_vpc_egress needs all three wiring points (vars_json,
-    root variable, module argument) and reads runner-secrets first — the
-    durable per-environment home for the flag — with a payload fallback.
-    Secrets Manager JSON strings ("true") must land as real booleans."""
-    runner = load_runner()
-    tf_dir = _cognito_email_runner_env(runner, tmp_path, monkeypatch)
-    base_payload = {
-        "stage": "tei-e2e",
-        "awsRegion": "us-east-1",
-        "awsAccountId": "637423202447",
-        "dbPassword": "db-secret",
-        "apiAuthSecret": "api-secret",
-    }
-
-    assert runner.write_runner_files(base_payload, {})["analyst_lambda_vpc_egress"] is False
-    assert (
-        runner.write_runner_files(base_payload, {"analystLambdaVpcEgress": "true"})[
-            "analyst_lambda_vpc_egress"
-        ]
-        is True
-    )
-    assert (
-        runner.write_runner_files({**base_payload, "analystLambdaVpcEgress": True}, {})[
-            "analyst_lambda_vpc_egress"
-        ]
-        is True
-    )
-
-    main_tf = (tf_dir / "main.tf").read_text(encoding="utf-8")
-    assert 'variable "analyst_lambda_vpc_egress"' in main_tf
-    assert "= var.analyst_lambda_vpc_egress" in main_tf
-
-
 def test_write_runner_files_threads_customer_domain_vars_from_payload(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
@@ -3492,140 +4070,877 @@ def test_write_controller_release_selection_to_ssm_skips_empty_git_module_versio
     assert "/thinkwork/dev/deployment/terraform-module-version" not in written_names
 
 
-def test_terraform_plan_summary_counts_resource_actions() -> None:
+def _approval_payload(action: str, *, plan: bool, apply: bool) -> dict:
+    return {
+        "contract": "thinkwork.deployment.controller.v1",
+        "action": action,
+        "phase": action,
+        "sessionId": f"session-{action}",
+        "environmentName": "tei-e2e",
+        "awsAccountId": "637423202447",
+        "awsRegion": "us-east-1",
+        "release": {
+            "version": "v0.1.0-canary.381",
+            "manifestUrl": "https://example.test/thinkwork-release.json",
+            "manifestSha256": "a" * 64,
+        },
+        "agentcorePiSourceImageUri": (
+            "637423202447.dkr.ecr.us-east-1.amazonaws.com/"
+            "thinkwork-tei-e2e-agentcore:pinned@sha256:abc"
+        ),
+        "preservedConfig": {
+            "enableAgentCoreHarness": True,
+            "agentCoreHarnessTenantSlug": "tei",
+        },
+        "operation": {
+            "kind": "foundation",
+            "action": action,
+            "targetAction": "update",
+            "plan": plan,
+            "apply": apply,
+            "destroy": False,
+        },
+    }
+
+
+def test_plan_phase_never_implies_apply() -> None:
     runner = load_runner()
+    payload = _approval_payload("plan", plan=True, apply=False)
 
-    summary = runner.terraform_plan_summary(
-        {
-            "format_version": "1.2",
-            "terraform_version": "1.8.0",
-            "resource_changes": [
-                {"change": {"actions": ["create"]}},
-                {"change": {"actions": ["update"]}},
-                {"change": {"actions": ["delete", "create"]}},
-                {"change": {"actions": ["create"]}},
-            ],
-        }
-    )
+    assert runner.validate_terraform_execution_phase(payload, "plan") == "plan"
 
-    assert summary == {
-        "formatVersion": "1.2",
-        "terraformVersion": "1.8.0",
-        "resourceChangeCount": 4,
-        "resourceChangesByAction": {
-            "create": 2,
-            "update": 1,
-            "delete,create": 1,
-        },
+
+def test_existing_managed_application_plan_remains_plan_only() -> None:
+    runner = load_runner()
+    payload = {
+        "action": "plan",
+        "phase": "plan",
+        "appKey": "twenty",
+        "operation": "ENABLE",
     }
 
+    assert runner.validate_terraform_execution_phase(payload, "plan") == "plan"
 
-def test_self_update_runner_script_copies_release_runner_to_s3(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+
+def test_explicit_plan_execution_never_invokes_terraform_apply(
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     runner = load_runner()
-    source_dir = tmp_path / "source"
-    script = source_dir / "terraform/modules/app/deployment-control-plane/runner.py"
-    script.parent.mkdir(parents=True)
-    script.write_text("# release runner\n", encoding="utf-8")
-
-    monkeypatch.setattr(runner, "SOURCE", source_dir)
-    monkeypatch.setenv(
-        "THINKWORK_RUNNER_SCRIPT_S3_URI",
-        "s3://evidence-bucket/runner/thinkwork-runner.py",
-    )
     calls: list[list[str]] = []
-    monkeypatch.setattr(runner, "run", lambda args, **_kw: calls.append(args))
+    monkeypatch.setattr(
+        runner.subprocess,
+        "run",
+        lambda args, **_kwargs: calls.append(args) or SimpleNamespace(returncode=0),
+    )
+    monkeypatch.setattr(
+        runner,
+        "write_terraform_plan_evidence",
+        lambda *_args, **_kwargs: {"status": "awaiting-approval"},
+    )
 
-    runner.self_update_runner_script()
+    result = runner.execute_terraform_plan_phase(
+        _approval_payload("plan", plan=True, apply=False),
+        {"lineage": "lineage", "serial": 1},
+        "update",
+        "plan",
+        [],
+    )
 
-    assert calls == [
-        [
-            "aws",
-            "s3",
-            "cp",
-            str(script),
-            "s3://evidence-bucket/runner/thinkwork-runner.py",
-        ]
-    ]
+    assert result.returncode == 0
+    assert calls == [["terraform", "plan", "-out=tfplan", "-no-color"]]
+    assert runner.TERRAFORM_EVIDENCE["plan"]["status"] == "awaiting-approval"
 
 
-def test_self_update_runner_script_skips_when_source_missing(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+def test_legacy_execution_still_applies_its_successful_plan(
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     runner = load_runner()
-    monkeypatch.setattr(runner, "SOURCE", tmp_path / "missing-source")
-    monkeypatch.setenv(
-        "THINKWORK_RUNNER_SCRIPT_S3_URI",
-        "s3://evidence-bucket/runner/thinkwork-runner.py",
-    )
     calls: list[list[str]] = []
-    monkeypatch.setattr(runner, "run", lambda args, **_kw: calls.append(args))
+    monkeypatch.setattr(
+        runner.subprocess,
+        "run",
+        lambda args, **_kwargs: calls.append(args) or SimpleNamespace(returncode=0),
+    )
+    monkeypatch.setattr(
+        runner,
+        "write_terraform_plan_evidence",
+        lambda *_args, **_kwargs: {"status": "awaiting-approval"},
+    )
 
-    runner.self_update_runner_script()
+    runner.execute_terraform_plan_phase(
+        _approval_payload("update", plan=True, apply=True),
+        {"lineage": "lineage", "serial": 1},
+        "update",
+        "legacy",
+        [],
+    )
 
-    assert calls == []
+    assert calls == [
+        ["terraform", "plan", "-out=tfplan", "-no-color"],
+        ["terraform", "apply", "-auto-approve", "-no-color", "tfplan"],
+    ]
 
 
-# ---------------------------------------------------------------------------
-# First-admin bootstrap (first-run provisioning)
-# ---------------------------------------------------------------------------
+@pytest.mark.parametrize("action", ["deploy", "update", "destroy"])
+def test_legacy_combined_terraform_actions_remain_compatible(action: str) -> None:
+    runner = load_runner()
+    payload = _approval_payload(action, plan=True, apply=True)
 
+    assert runner.validate_terraform_execution_phase(payload, action) == "legacy"
 
-def test_first_admin_tenant_slug_prefers_customer_domain_label() -> None:
+
+def test_legacy_and_approved_apply_reconcile_native_auth_schema() -> None:
     runner = load_runner()
-    slug = runner.first_admin_tenant_slug(
-        {}, {}, {"stage": "acme-prod", "customer_domain": "acme.thinkwork.ai"}
+
+    assert runner.should_reconcile_native_auth_schema("legacy", "deploy", {}) is True
+    assert runner.should_reconcile_native_auth_schema("legacy", "update", {}) is True
+    assert runner.should_reconcile_native_auth_schema("apply", "update", {}) is True
+    assert runner.should_reconcile_native_auth_schema("plan", "update", {}) is False
+    assert runner.should_reconcile_native_auth_schema("legacy", "destroy", {}) is False
+    assert (
+        runner.should_reconcile_native_auth_schema(
+            "legacy",
+            "update",
+            {"appKey": "twenty"},
+        )
+        is False
     )
-    assert slug == "acme"
 
 
-def test_first_admin_tenant_slug_falls_back_to_stage() -> None:
+def test_apply_phase_requires_separate_approved_plan() -> None:
     runner = load_runner()
-    slug = runner.first_admin_tenant_slug({}, {}, {"stage": "acme", "customer_domain": ""})
-    assert slug == "acme"
+    payload = _approval_payload("apply", plan=False, apply=True)
 
+    with pytest.raises(RuntimeError, match="requires approvedPlan"):
+        runner.validate_terraform_execution_phase(payload, "apply")
 
-def test_first_admin_tenant_slug_rejects_domain_mismatch() -> None:
-    runner = load_runner()
-    with pytest.raises(RuntimeError, match="KTD8"):
-        runner.first_admin_tenant_slug(
-            {},
-            {"tenantSlug": "other"},
-            {"stage": "acme", "customer_domain": "acme.thinkwork.ai"},
-        )
+    payload["approvedPlan"] = {
+        "descriptor": {"s3Uri": "s3://evidence/descriptor.json", "sha256": "a" * 64}
+    }
+    assert runner.validate_terraform_execution_phase(payload, "apply") == "apply"
 
 
-def test_first_admin_tenant_slug_rejects_invalid_slug() -> None:
+def test_plan_and_apply_share_only_immutable_deployment_config_digest() -> None:
     runner = load_runner()
-    with pytest.raises(RuntimeError, match="slug pattern"):
-        runner.first_admin_tenant_slug({}, {}, {"stage": "Bad_Stage!", "customer_domain": ""})
+    planned = _approval_payload("plan", plan=True, apply=False)
+    applied = _approval_payload("apply", plan=False, apply=True)
+    applied["approvedPlan"] = {
+        "descriptor": {"s3Uri": "s3://evidence/descriptor.json", "sha256": "a" * 64}
+    }
 
+    assert runner.controller_input_sha256(planned) != runner.controller_input_sha256(applied)
+    assert runner.deployment_config_sha256(planned) == runner.deployment_config_sha256(applied)
 
-def test_first_admin_email_takes_first_valid_entry() -> None:
+    applied["preservedConfig"]["agentCoreHarnessTenantSlug"] = "wrong"
+    assert runner.deployment_config_sha256(planned) != runner.deployment_config_sha256(applied)
+
+
+def test_saved_plan_apply_revalidates_config_release_state_vars_and_rendered_plan(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
     runner = load_runner()
-    assert (
-        runner.first_admin_email({"platform_operator_emails": "ops@acme.com, two@acme.com"})
-        == "ops@acme.com"
+    work = tmp_path / "work"
+    tf = work / "terraform"
+    tf.mkdir(parents=True)
+    monkeypatch.setattr(runner, "WORK", work)
+    monkeypatch.setattr(runner, "TF", tf)
+    payload = _approval_payload("apply", plan=False, apply=True)
+    payload["approvedPlan"] = {
+        "descriptor": {"s3Uri": "s3://evidence/descriptor.json", "sha256": "d" * 64}
+    }
+    state = {
+        "lineage": "lineage",
+        "serial": 7,
+        "sha256": "s" * 64,
+        "terraformVersion": "1.8.5",
+    }
+    tfvars = b'{"stage":"tei-e2e"}\n'
+    (tf / "terraform.auto.tfvars.json").write_bytes(tfvars)
+    saved_plan_bytes = b"opaque-saved-plan"
+    accepted_plan = json.dumps(
+        {
+            "resource_changes": [],
+            "format_version": "1.2",
+            "timestamp": "2026-07-20T18:40:21Z",
+            "configuration": {
+                "expression": {
+                    "references": [
+                        "aws_security_group.twenty.id",
+                        "aws_security_group.twenty",
+                        "var.cache_port",
+                    ]
+                }
+            },
+        }
+    ).encode()
+    rendered_plan = json.dumps(
+        {
+            "format_version": "1.2",
+            "resource_changes": [],
+            "timestamp": "2026-07-20T18:49:12Z",
+            "configuration": {
+                "expression": {
+                    "references": [
+                        "var.cache_port",
+                        "aws_security_group.twenty.id",
+                        "aws_security_group.twenty",
+                    ]
+                }
+            },
+        },
+        indent=2,
+    ).encode()
+    descriptor = {
+        "contract": runner.TERRAFORM_PLAN_APPROVAL_CONTRACT,
+        "deploymentConfigSha256": runner.deployment_config_sha256(payload),
+        "release": runner.release_selection(payload),
+        "state": state,
+        "terraformVariablesSha256": digest(tfvars),
+        "savedPlan": {
+            "s3Uri": "s3://evidence/plan.bin",
+            "sha256": digest(saved_plan_bytes),
+        },
+        "jsonPlan": {
+            "s3Uri": "s3://evidence/plan.json",
+            "sha256": digest(accepted_plan),
+        },
+        "summary": {"resourceChangeCount": 0},
+        "plannedAction": "update",
+        "sessionId": "plan-session",
+    }
+    monkeypatch.setattr(
+        runner,
+        "load_approved_plan_descriptor",
+        lambda _payload: (descriptor, payload["approvedPlan"]["descriptor"]),
     )
-    assert runner.first_admin_email({"platform_operator_emails": ""}) == ""
-    assert runner.first_admin_email({"platform_operator_emails": "not-an-email"}) == ""
-    assert runner.first_admin_email({"platform_operator_emails": "a'b@acme.com"}) == ""
 
+    def fake_download(uri, destination, expected_sha, _label):
+        if uri == "s3://evidence/plan.bin":
+            content = saved_plan_bytes
+        else:
+            assert uri == "s3://evidence/plan.json"
+            content = accepted_plan
+        destination.write_bytes(content)
+        assert digest(content) == expected_sha
+        return expected_sha
 
-def test_ensure_first_admin_skips_without_admin_email(tmp_path: Path) -> None:
+    def fake_run(args, **kwargs):
+        assert args == ["terraform", "show", "-json", "tfplan"]
+        kwargs["stdout"].write(rendered_plan.decode())
+
+    monkeypatch.setattr(runner, "_download_approved_artifact", fake_download)
+    monkeypatch.setattr(runner, "run", fake_run)
+
+    approved = runner.validate_and_materialize_approved_plan(payload, state)
+    assert approved["plannedAction"] == "update"
+    assert approved["sourceSessionId"] == "plan-session"
+    assert (tf / "tfplan").read_bytes() == saved_plan_bytes
+
+    rendered_plan = b'{"format_version":"1.2","resource_changes":[{"address":"changed"}]}\n'
+    with pytest.raises(RuntimeError, match="no longer renders"):
+        runner.validate_and_materialize_approved_plan(payload, state)
+
+    descriptor["state"] = {**state, "serial": 8}
+    with pytest.raises(RuntimeError, match="state changed after plan approval"):
+        runner.validate_and_materialize_approved_plan(payload, state)
+
+
+def test_saved_plan_artifacts_must_use_configured_evidence_bucket(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
     runner = load_runner()
-    outputs = tmp_path / "outputs.json"
-    outputs.write_text("{}", encoding="utf-8")
-    runner.ensure_first_admin(outputs, {"platform_operator_emails": "", "stage": "acme"}, {}, {})
-    assert runner.FIRST_ADMIN_EVIDENCE["status"] == "skipped"
+    monkeypatch.setenv("THINKWORK_EVIDENCE_BUCKET", "expected-evidence")
+
+    assert (
+        runner._validated_evidence_s3_uri(
+            "s3://expected-evidence/sessions/plan.json", "approved plan"
+        )
+        == "s3://expected-evidence/sessions/plan.json"
+    )
+    with pytest.raises(RuntimeError, match="configured deployment evidence bucket"):
+        runner._validated_evidence_s3_uri("s3://attacker-controlled/plan.json", "approved plan")
 
 
-def test_ensure_first_admin_skips_established_env_without_slug(
+def test_tei_v380_saved_plan_apply_refuses_any_delete_action(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     runner = load_runner()
-    outputs = tmp_path / "outputs.json"
+    work = tmp_path / "work"
+    tf = work / "terraform"
+    tf.mkdir(parents=True)
+    monkeypatch.setattr(runner, "WORK", work)
+    monkeypatch.setattr(runner, "TF", tf)
+    payload = _approval_payload("apply", plan=False, apply=True)
+    payload["incidentRecovery"] = {"contract": runner.TEI_V380_RECOVERY_CONTRACT}
+    payload["approvedPlan"] = {
+        "descriptor": {"s3Uri": "s3://evidence/descriptor.json", "sha256": "d" * 64}
+    }
+    state = {
+        "lineage": "lineage",
+        "serial": 7,
+        "sha256": "e" * 64,
+        "terraformVersion": "1.8.5",
+    }
+    tfvars = b'{"stage":"tei-e2e"}\n'
+    (tf / "terraform.auto.tfvars.json").write_bytes(tfvars)
+    saved_plan = b"opaque-saved-plan"
+    rendered_plan = json.dumps(
+        {
+            "format_version": "1.2",
+            "resource_changes": [
+                {
+                    "address": "module.thinkwork.proof_resource",
+                    "change": {"actions": ["delete"]},
+                }
+            ],
+        }
+    ).encode()
+    descriptor = {
+        "contract": runner.TERRAFORM_PLAN_APPROVAL_CONTRACT,
+        "deploymentConfigSha256": runner.deployment_config_sha256(payload),
+        "release": runner.release_selection(payload),
+        "state": state,
+        "terraformVariablesSha256": digest(tfvars),
+        "savedPlan": {
+            "s3Uri": "s3://evidence/plan.bin",
+            "sha256": digest(saved_plan),
+        },
+        "jsonPlan": {
+            "s3Uri": "s3://evidence/plan.json",
+            "sha256": digest(rendered_plan),
+        },
+        "plannedAction": "update",
+    }
+    monkeypatch.setattr(
+        runner,
+        "load_approved_plan_descriptor",
+        lambda _payload: (descriptor, payload["approvedPlan"]["descriptor"]),
+    )
+
+    def fake_download(uri, destination, _sha, _label):
+        destination.write_bytes(saved_plan if uri.endswith("plan.bin") else rendered_plan)
+
+    monkeypatch.setattr(runner, "_download_approved_artifact", fake_download)
+    monkeypatch.setattr(
+        runner,
+        "run",
+        lambda _args, **kwargs: kwargs["stdout"].write(rendered_plan.decode()),
+    )
+
+    with pytest.raises(RuntimeError, match="contains delete actions"):
+        runner.validate_and_materialize_approved_plan(payload, state)
+
+
+def _tei_v380_recovery_payload(runner) -> dict:
+    return {
+        "action": "recover",
+        "environmentName": "tei-e2e",
+        "stage": "tei-e2e",
+        "awsAccountId": "637423202447",
+        "accountId": "637423202447",
+        "awsRegion": "us-east-1",
+        "region": "us-east-1",
+        "operation": {
+            "kind": "incident_recovery",
+            **runner.tei_v380_recovery_scope(),
+        },
+    }
+
+
+def _tei_v380_state(runner) -> dict:
+    return {
+        "bucket": runner.TEI_V380_STATE_BUCKET,
+        "key": runner.TEI_V380_STATE_KEY,
+        "etag": "state-etag",
+        "size": 123,
+        "lastModified": "2026-07-20T13:31:15Z",
+        "serverSideEncryption": "AES256",
+        "versionId": None,
+        "sha256": runner.TEI_V380_STATE_SHA256,
+        "lineage": runner.TEI_V380_STATE_LINEAGE,
+        "serial": runner.TEI_V380_STATE_SERIAL,
+        "terraformVersion": "1.8.5",
+    }
+
+
+def test_tei_v380_recovery_contract_is_exact_and_rejects_alias_drift() -> None:
+    runner = load_runner()
+    payload = _tei_v380_recovery_payload(runner)
+
+    assert runner.validate_tei_v380_recovery_contract(payload) == (runner.tei_v380_recovery_scope())
+
+    payload["stage"] = "dev"
+    with pytest.raises(RuntimeError, match="stage does not match exact incident scope"):
+        runner.validate_tei_v380_recovery_contract(payload)
+
+    payload = _tei_v380_recovery_payload(runner)
+    payload["operation"]["unexpected"] = True
+    with pytest.raises(RuntimeError, match="unexpected fields"):
+        runner.validate_tei_v380_recovery_contract(payload)
+
+
+def test_incident_recovery_exclusivity_ignores_only_current_operation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    execution_arn = "arn:aws:states:us-east-1:637423202447:execution:deploy:current"
+    build_id = "runner:current"
+    monkeypatch.setenv("THINKWORK_DEPLOYMENT_EXECUTION_ARN", execution_arn)
+    monkeypatch.setenv("THINKWORK_DEPLOYMENT_STATE_MACHINE_ARN", "arn:state-machine")
+    monkeypatch.setenv("THINKWORK_DEPLOYMENT_RUNNER_PROJECT_NAME", "runner")
+    monkeypatch.setenv("CODEBUILD_BUILD_ID", build_id)
+
+    include_other = False
+
+    def fake_output(args, **_kwargs):
+        if args[1:3] == ["stepfunctions", "list-executions"]:
+            executions = [{"executionArn": execution_arn}]
+            if include_other:
+                executions.append({"executionArn": "arn:other"})
+            return json.dumps({"executions": executions})
+        if args[1:3] == ["codebuild", "list-builds-for-project"]:
+            assert "--no-paginate" in args
+            return json.dumps({"ids": [build_id]})
+        if args[1:3] == ["codebuild", "batch-get-builds"]:
+            return json.dumps({"builds": [{"id": build_id, "buildStatus": "IN_PROGRESS"}]})
+        raise AssertionError(args)
+
+    monkeypatch.setattr(runner, "output", fake_output)
+    assert runner.assert_incident_recovery_operation_is_exclusive() == {
+        "currentExecutionArn": execution_arn,
+        "currentBuildId": build_id,
+        "otherRunningExecutions": 0,
+        "otherRunningBuilds": 0,
+    }
+
+    include_other = True
+    with pytest.raises(RuntimeError, match="Another deployment execution"):
+        runner.assert_incident_recovery_operation_is_exclusive()
+
+
+def test_incident_recovery_exclusivity_supports_one_managed_transition_execution(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    execution_arn = "arn:aws:states:us-east-1:637423202447:execution:deploy:transition"
+    build_id = "runner:transition"
+    monkeypatch.delenv("THINKWORK_DEPLOYMENT_EXECUTION_ARN", raising=False)
+    monkeypatch.setenv("THINKWORK_DEPLOYMENT_STATE_MACHINE_ARN", "arn:state-machine")
+    monkeypatch.setenv("THINKWORK_DEPLOYMENT_RUNNER_PROJECT_NAME", "runner")
+    monkeypatch.setenv("CODEBUILD_BUILD_ID", build_id)
+
+    def fake_output(args, **_kwargs):
+        if args[1:3] == ["stepfunctions", "list-executions"]:
+            return json.dumps({"executions": [{"executionArn": execution_arn}]})
+        if args[1:3] == ["codebuild", "list-builds-for-project"]:
+            assert "--no-paginate" in args
+            return json.dumps({"ids": [build_id]})
+        if args[1:3] == ["codebuild", "batch-get-builds"]:
+            return json.dumps({"builds": [{"id": build_id, "buildStatus": "IN_PROGRESS"}]})
+        raise AssertionError(args)
+
+    monkeypatch.setattr(runner, "output", fake_output)
+    assert (
+        runner.assert_incident_recovery_operation_is_exclusive()["currentExecutionArn"]
+        == execution_arn
+    )
+
+
+def test_tei_v380_recovery_restores_only_exact_resources_without_secret_read(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    payload = _tei_v380_recovery_payload(runner)
+    state = _tei_v380_state(runner)
+    calls: list[list[str]] = []
+    evidence: list[tuple[str, dict]] = []
+    secret_describes = 0
+    kms_describes = 0
+
+    monkeypatch.setattr(
+        runner,
+        "assert_incident_recovery_operation_is_exclusive",
+        lambda: {
+            "currentExecutionArn": "arn:current",
+            "currentBuildId": "build:current",
+            "otherRunningExecutions": 0,
+            "otherRunningBuilds": 0,
+        },
+    )
+    monkeypatch.setattr(runner, "terraform_state_object_snapshot", lambda _stage: state)
+    monkeypatch.setattr(
+        runner,
+        "force_unlock_tei_v380_state",
+        lambda: {
+            "method": "terraform-force-unlock",
+            "lockId": runner.TEI_V380_LOCK_ID,
+            "directDynamoDbMutation": False,
+        },
+    )
+    monkeypatch.setattr(runner.time, "sleep", lambda _seconds: None)
+
+    def fake_output(args, **_kwargs):
+        nonlocal secret_describes, kms_describes
+        calls.append(args)
+        if args[1:3] == ["sts", "get-caller-identity"]:
+            return "637423202447"
+        if args[1:3] == ["secretsmanager", "describe-secret"]:
+            secret_describes += 1
+            return json.dumps(
+                {
+                    "ARN": runner.TEI_V380_SECRET_ARN,
+                    "Name": runner.TEI_V380_SECRET_NAME,
+                    **({"DeletedDate": "2026-07-20T13:30:54Z"} if secret_describes == 1 else {}),
+                }
+            )
+        if args[1:3] == ["kms", "describe-key"]:
+            kms_describes += 1
+            states = [
+                ("PendingDeletion", False),
+                ("Disabled", False),
+                ("Enabled", True),
+            ]
+            key_state, enabled = states[min(kms_describes - 1, len(states) - 1)]
+            return json.dumps(
+                {
+                    "KeyMetadata": {
+                        "KeyId": runner.TEI_V380_KMS_KEY_ID,
+                        "Arn": runner.TEI_V380_KMS_KEY_ARN,
+                        "KeyState": key_state,
+                        "Enabled": enabled,
+                        "KeyManager": "CUSTOMER",
+                        "Origin": "AWS_KMS",
+                    }
+                }
+            )
+        raise AssertionError(args)
+
+    def fake_run(args, **_kwargs):
+        calls.append(args)
+        return None
+
+    def fake_evidence(name, body):
+        evidence.append((name, json.loads(json.dumps(body))))
+        return {"fileName": name, "sha256": "a" * 64, "s3Uri": f"s3://evidence/{name}"}
+
+    monkeypatch.setattr(runner, "output", fake_output)
+    monkeypatch.setattr(runner, "run", fake_run)
+    monkeypatch.setattr(runner, "write_json_evidence_artifact", fake_evidence)
+
+    recovered = runner.recover_tei_v380_incident(payload)
+
+    assert recovered["proof"]["status"] == "succeeded"
+    assert recovered["proof"]["secretValueRead"] is False
+    assert recovered["proof"]["terraformStateMutation"] is False
+    assert recovered["proof"]["terraformLock"]["directDynamoDbMutation"] is False
+    assert [
+        "aws",
+        "secretsmanager",
+        "restore-secret",
+        "--secret-id",
+        runner.TEI_V380_SECRET_ARN,
+    ] in calls
+    assert ["aws", "kms", "cancel-key-deletion", "--key-id", runner.TEI_V380_KMS_KEY_ID] in calls
+    assert ["aws", "kms", "enable-key", "--key-id", runner.TEI_V380_KMS_KEY_ID] in calls
+    assert not any("get-secret-value" in call for call in calls)
+    assert evidence[-1][0] == "incident-recovery.json"
+    assert all("SecretString" not in json.dumps(body) for _, body in evidence)
+
+
+def test_tei_v380_recovery_refuses_changed_state_before_mutation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    payload = _tei_v380_recovery_payload(runner)
+    changed_state = {**_tei_v380_state(runner), "serial": runner.TEI_V380_STATE_SERIAL + 1}
+    mutation_calls: list[list[str]] = []
+
+    monkeypatch.setattr(runner, "assert_incident_recovery_operation_is_exclusive", lambda: {})
+    monkeypatch.setattr(runner, "terraform_state_object_snapshot", lambda _stage: changed_state)
+    monkeypatch.setattr(
+        runner,
+        "output",
+        lambda args, **_kwargs: (
+            "637423202447"
+            if args[1:3] == ["sts", "get-caller-identity"]
+            else (_ for _ in ()).throw(AssertionError(args))
+        ),
+    )
+    monkeypatch.setattr(runner, "run", lambda args, **_kwargs: mutation_calls.append(args))
+
+    with pytest.raises(RuntimeError, match="state serial changed"):
+        runner.recover_tei_v380_incident(payload)
+    assert mutation_calls == []
+
+
+def test_tei_v380_force_unlock_uses_terraform_and_preserves_digest(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    monkeypatch.setattr(runner, "WORK", tmp_path)
+    calls: list[tuple[list[str], dict]] = []
+    snapshots = iter(
+        [
+            {
+                "table": runner.TEI_V380_LOCK_TABLE,
+                "key": runner.TEI_V380_LOCK_KEY,
+                "present": True,
+                "info": {
+                    "id": runner.TEI_V380_LOCK_ID,
+                    "operation": "OperationTypeApply",
+                    "version": "1.8.5",
+                    "created": "2026-07-20T13:30:42Z",
+                    "path": runner.TEI_V380_LOCK_KEY,
+                },
+                "digestKey": f"{runner.TEI_V380_LOCK_KEY}-md5",
+                "digest": runner.TEI_V380_STATE_DIGEST,
+            },
+            {
+                "table": runner.TEI_V380_LOCK_TABLE,
+                "key": runner.TEI_V380_LOCK_KEY,
+                "present": False,
+                "info": None,
+                "digestKey": f"{runner.TEI_V380_LOCK_KEY}-md5",
+                "digest": runner.TEI_V380_STATE_DIGEST,
+            },
+        ]
+    )
+    monkeypatch.setattr(runner, "tei_v380_lock_snapshot", lambda: next(snapshots))
+    monkeypatch.setattr(runner, "run", lambda args, **kwargs: calls.append((args, kwargs)))
+
+    proof = runner.force_unlock_tei_v380_state()
+
+    assert proof["method"] == "terraform-force-unlock"
+    assert proof["directDynamoDbMutation"] is False
+    assert calls[0][0][:3] == ["terraform", "init", "-reconfigure"]
+    assert calls[1][0] == [
+        "terraform",
+        "force-unlock",
+        "-force",
+        runner.TEI_V380_LOCK_ID,
+    ]
+    assert not any("dynamodb" in arg for call, _kwargs in calls for arg in call)
+    backend = (tmp_path / "tei-v380-force-unlock/backend.hcl").read_text()
+    assert runner.TEI_V380_STATE_BUCKET in backend
+    assert runner.TEI_V380_LOCK_TABLE in backend
+
+
+def test_tei_v380_force_unlock_is_retry_safe_after_exact_unlock(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    calls: list[list[str]] = []
+    unlocked = {
+        "table": runner.TEI_V380_LOCK_TABLE,
+        "key": runner.TEI_V380_LOCK_KEY,
+        "present": False,
+        "info": None,
+        "digestKey": f"{runner.TEI_V380_LOCK_KEY}-md5",
+        "digest": runner.TEI_V380_STATE_DIGEST,
+    }
+    monkeypatch.setattr(runner, "tei_v380_lock_snapshot", lambda: unlocked)
+    monkeypatch.setattr(runner, "run", lambda args, **_kwargs: calls.append(args))
+
+    proof = runner.force_unlock_tei_v380_state()
+
+    assert proof["alreadyUnlocked"] is True
+    assert proof["before"] == proof["after"]
+    assert calls == []
+
+
+def test_tei_v380_recovery_imports_require_exact_evidence_and_current_state(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    monkeypatch.setattr(runner, "WORK", tmp_path)
+    state = _tei_v380_state(runner)
+    scope = runner.tei_v380_recovery_scope()
+    evidence = {
+        "contract": runner.TEI_V380_RECOVERY_CONTRACT,
+        "incidentId": runner.TEI_V380_RECOVERY_INCIDENT_ID,
+        "rejectedPlanSha256": runner.TEI_V380_REJECTED_PLAN_SHA256,
+        "status": "succeeded",
+        "terraformStateMutation": False,
+        "secretValueRead": False,
+        "stateBefore": state,
+        "stateAfter": state,
+    }
+    payload = {
+        "incidentRecovery": {
+            **scope,
+            "evidence": {"s3Uri": "s3://evidence/recovery.json", "sha256": "a" * 64},
+        }
+    }
+    vars_json = {
+        "enable_agentcore_multiplayer_proof": True,
+        "agentcore_multiplayer_proof_tenant_slug": "tei",
+        "agentcore_multiplayer_proof_owner_allowlist": runner.TEI_V380_OWNER_ALLOWLIST,
+        "finalize_auth_retirement": False,
+        "auth_retirement_phase": "coexistence",
+        "microsoft_oauth_tenant": "organizations",
+    }
+
+    def fake_download(_uri, destination, _sha, _label):
+        destination.write_text(json.dumps(evidence), encoding="utf-8")
+        return "a" * 64
+
+    monkeypatch.setattr(runner, "_download_approved_artifact", fake_download)
+    snapshots = [state]
+    monkeypatch.setattr(
+        runner,
+        "terraform_state_object_snapshot",
+        lambda stage: snapshots.pop(0) if stage == "tei-e2e" else {},
+    )
+    blocks = runner.tei_v380_recovery_import_blocks(payload, vars_json)
+    assert f"to = {runner.TEI_V380_SECRET_ADDRESS}" in blocks
+    assert f"id = {runner.hcl_string(runner.TEI_V380_SECRET_ARN)}" in blocks
+    assert f"to = {runner.TEI_V380_KMS_KEY_ADDRESS}" in blocks
+    assert runner.TEI_V380_KMS_ALIAS_ADDRESS not in blocks
+
+    moved_state = {**state, "sha256": "f" * 64}
+    snapshots.append(moved_state)
+    with pytest.raises(RuntimeError, match="state moved"):
+        runner.tei_v380_recovery_import_blocks(payload, vars_json)
+
+    payload["incidentRecovery"]["stage"] = "dev"
+    with pytest.raises(RuntimeError, match="scope does not match"):
+        runner.tei_v380_recovery_import_blocks(payload, vars_json)
+
+
+def test_terraform_plan_summary_counts_resource_actions() -> None:
+    runner = load_runner()
+
+    summary = runner.terraform_plan_summary(
+        {
+            "format_version": "1.2",
+            "terraform_version": "1.8.0",
+            "resource_changes": [
+                {"change": {"actions": ["create"]}},
+                {"change": {"actions": ["update"]}},
+                {"change": {"actions": ["delete", "create"]}},
+                {"change": {"actions": ["create"]}},
+            ],
+        }
+    )
+
+    assert summary == {
+        "formatVersion": "1.2",
+        "terraformVersion": "1.8.0",
+        "resourceChangeCount": 4,
+        "resourceChangesByAction": {
+            "create": 2,
+            "update": 1,
+            "delete,create": 1,
+        },
+    }
+
+
+def test_self_update_runner_script_copies_release_runner_to_s3(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    source_dir = tmp_path / "source"
+    script = source_dir / "terraform/modules/app/deployment-control-plane/runner.py"
+    script.parent.mkdir(parents=True)
+    script.write_text("# release runner\n", encoding="utf-8")
+
+    monkeypatch.setattr(runner, "SOURCE", source_dir)
+    monkeypatch.setenv(
+        "THINKWORK_RUNNER_SCRIPT_S3_URI",
+        "s3://evidence-bucket/runner/thinkwork-runner.py",
+    )
+    calls: list[list[str]] = []
+    monkeypatch.setattr(runner, "run", lambda args, **_kw: calls.append(args))
+
+    runner.self_update_runner_script()
+
+    assert calls == [
+        [
+            "aws",
+            "s3",
+            "cp",
+            str(script),
+            "s3://evidence-bucket/runner/thinkwork-runner.py",
+        ]
+    ]
+
+
+def test_self_update_runner_script_skips_when_source_missing(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    monkeypatch.setattr(runner, "SOURCE", tmp_path / "missing-source")
+    monkeypatch.setenv(
+        "THINKWORK_RUNNER_SCRIPT_S3_URI",
+        "s3://evidence-bucket/runner/thinkwork-runner.py",
+    )
+    calls: list[list[str]] = []
+    monkeypatch.setattr(runner, "run", lambda args, **_kw: calls.append(args))
+
+    runner.self_update_runner_script()
+
+    assert calls == []
+
+
+# ---------------------------------------------------------------------------
+# First-admin bootstrap (first-run provisioning)
+# ---------------------------------------------------------------------------
+
+
+def test_first_admin_tenant_slug_prefers_customer_domain_label() -> None:
+    runner = load_runner()
+    slug = runner.first_admin_tenant_slug(
+        {}, {}, {"stage": "acme-prod", "customer_domain": "acme.thinkwork.ai"}
+    )
+    assert slug == "acme"
+
+
+def test_first_admin_tenant_slug_falls_back_to_stage() -> None:
+    runner = load_runner()
+    slug = runner.first_admin_tenant_slug({}, {}, {"stage": "acme", "customer_domain": ""})
+    assert slug == "acme"
+
+
+def test_first_admin_tenant_slug_rejects_domain_mismatch() -> None:
+    runner = load_runner()
+    with pytest.raises(RuntimeError, match="KTD8"):
+        runner.first_admin_tenant_slug(
+            {},
+            {"tenantSlug": "other"},
+            {"stage": "acme", "customer_domain": "acme.thinkwork.ai"},
+        )
+
+
+def test_first_admin_tenant_slug_rejects_invalid_slug() -> None:
+    runner = load_runner()
+    with pytest.raises(RuntimeError, match="slug pattern"):
+        runner.first_admin_tenant_slug({}, {}, {"stage": "Bad_Stage!", "customer_domain": ""})
+
+
+def test_first_admin_email_takes_first_valid_entry() -> None:
+    runner = load_runner()
+    assert (
+        runner.first_admin_email({"platform_operator_emails": "ops@acme.com, two@acme.com"})
+        == "ops@acme.com"
+    )
+    assert runner.first_admin_email({"platform_operator_emails": ""}) == ""
+    assert runner.first_admin_email({"platform_operator_emails": "not-an-email"}) == ""
+    assert runner.first_admin_email({"platform_operator_emails": "a'b@acme.com"}) == ""
+
+
+def test_ensure_first_admin_skips_without_admin_email(tmp_path: Path) -> None:
+    runner = load_runner()
+    outputs = tmp_path / "outputs.json"
+    outputs.write_text("{}", encoding="utf-8")
+    runner.ensure_first_admin(outputs, {"platform_operator_emails": "", "stage": "acme"}, {}, {})
+    assert runner.FIRST_ADMIN_EVIDENCE["status"] == "skipped"
+
+
+def test_ensure_first_admin_skips_established_env_without_slug(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    runner = load_runner()
+    outputs = tmp_path / "outputs.json"
     outputs.write_text(json.dumps({"user_pool_id": {"value": "us-east-1_POOL"}}), encoding="utf-8")
     monkeypatch.setattr(runner, "database_url_from_outputs", lambda _o: "postgres://x")
 
@@ -3731,3 +5046,568 @@ def test_ensure_first_admin_failure_is_nonfatal(
     )
     assert runner.FIRST_ADMIN_EVIDENCE["status"] == "failed"
     assert "user_pool_id" in runner.FIRST_ADMIN_EVIDENCE["error"]
+
+
+def test_write_runner_files_threads_deployment_runner_in_vpc(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """THINK-1082: the runner-in-VPC flag rides the same three wiring points
+    as every other environment-posture variable — vars_json, the tfvars
+    file, and the generated root's variable + module argument — and is
+    ship-inert (False) unless the runner-secrets document or payload says
+    otherwise."""
+    runner = load_runner()
+    tf_dir = _cognito_email_runner_env(runner, tmp_path, monkeypatch)
+    base_payload = {
+        "stage": "tei-e2e",
+        "awsRegion": "us-east-1",
+        "awsAccountId": "637423202447",
+        "dbPassword": "db-secret",
+        "apiAuthSecret": "api-secret",
+    }
+
+    vars_json_default = runner.write_runner_files(dict(base_payload), {})
+    assert vars_json_default["deployment_runner_in_vpc"] is False
+
+    vars_json_payload = runner.write_runner_files(
+        {**base_payload, "deploymentRunnerInVpc": True}, {}
+    )
+    assert vars_json_payload["deployment_runner_in_vpc"] is True
+    tfvars = json.loads((tf_dir / "terraform.auto.tfvars.json").read_text(encoding="utf-8"))
+    assert tfvars["deployment_runner_in_vpc"] is True
+    main_tf = (tf_dir / "main.tf").read_text(encoding="utf-8")
+    assert 'variable "deployment_runner_in_vpc"' in main_tf
+    assert "deployment_runner_in_vpc           = var.deployment_runner_in_vpc" in main_tf
+
+    # Secrets Manager JSON often carries strings; the runner-secrets document
+    # is the durable home and wins over the payload, emitting a real bool.
+    vars_json_secret = runner.write_runner_files(
+        {**base_payload, "deploymentRunnerInVpc": False},
+        {"deploymentRunnerInVpc": "true"},
+    )
+    assert vars_json_secret["deployment_runner_in_vpc"] is True
+
+
+def test_write_runner_files_threads_api_lambdas_in_vpc_and_db_exposure(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """THINK-1082: the api-Lambdas-in-VPC flag and the two database-exposure
+    inputs ride the same wiring points as deploymentRunnerInVpc (vars_json,
+    tfvars, generated-root variable + module argument) and are ship-inert:
+    Lambdas out of the VPC, public endpoint on, world-open 5432 seeded."""
+    runner = load_runner()
+    tf_dir = _cognito_email_runner_env(runner, tmp_path, monkeypatch)
+    base_payload = {
+        "stage": "tei-e2e",
+        "awsRegion": "us-east-1",
+        "awsAccountId": "637423202447",
+        "dbPassword": "db-secret",
+        "apiAuthSecret": "api-secret",
+    }
+
+    vars_json_default = runner.write_runner_files(dict(base_payload), {})
+    assert vars_json_default["api_lambdas_in_vpc"] is False
+    assert vars_json_default["db_publicly_accessible"] is True
+    assert vars_json_default["db_public_ingress_cidrs"] == ["0.0.0.0/0"]
+    main_tf = (tf_dir / "main.tf").read_text(encoding="utf-8")
+    for name in ("api_lambdas_in_vpc", "db_publicly_accessible", "db_public_ingress_cidrs"):
+        assert f'variable "{name}"' in main_tf
+        assert f"{name:<35}= var.{name}" in main_tf
+
+    # Payload lane: the closed posture. An explicit [] must survive as []
+    # (not fall back to the world-open default) — that IS the port close.
+    vars_json_closed = runner.write_runner_files(
+        {
+            **base_payload,
+            "apiLambdasInVpc": True,
+            "dbPubliclyAccessible": False,
+            "dbPublicIngressCidrs": [],
+        },
+        {},
+    )
+    assert vars_json_closed["api_lambdas_in_vpc"] is True
+    assert vars_json_closed["db_publicly_accessible"] is False
+    assert vars_json_closed["db_public_ingress_cidrs"] == []
+    tfvars = json.loads((tf_dir / "terraform.auto.tfvars.json").read_text(encoding="utf-8"))
+    assert tfvars["api_lambdas_in_vpc"] is True
+    assert tfvars["db_publicly_accessible"] is False
+    assert tfvars["db_public_ingress_cidrs"] == []
+
+    # Secrets Manager JSON often carries strings; the runner-secrets document
+    # is the durable home and wins over the payload, emitting real types.
+    vars_json_secret = runner.write_runner_files(
+        {**base_payload, "apiLambdasInVpc": False, "dbPublicIngressCidrs": ["0.0.0.0/0"]},
+        {
+            "apiLambdasInVpc": "true",
+            "dbPubliclyAccessible": "false",
+            "dbPublicIngressCidrs": "10.0.0.0/8, 192.168.0.0/16",
+        },
+    )
+    assert vars_json_secret["api_lambdas_in_vpc"] is True
+    assert vars_json_secret["db_publicly_accessible"] is False
+    assert vars_json_secret["db_public_ingress_cidrs"] == ["10.0.0.0/8", "192.168.0.0/16"]
+
+    # An explicit empty string in the secret also means "no rule".
+    vars_json_empty = runner.write_runner_files(dict(base_payload), {"dbPublicIngressCidrs": ""})
+    assert vars_json_empty["db_public_ingress_cidrs"] == []
+
+
+def test_psql_failures_redact_the_database_password(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A failed psql surfaces its argv through CalledProcessError, and
+    CodeBuild prints that to CloudWatch. The password must never reach the
+    log; everything else about the failure (type, returncode, output) is
+    preserved for callers that already catch CalledProcessError."""
+    runner = load_runner()
+    password = "s3cr%40t%2Fpw"
+    url = (
+        f"postgresql://thinkwork_admin:{password}"
+        "@db.cluster-abc.us-east-1.rds.amazonaws.com:5432/thinkwork?sslmode=require"
+    )
+
+    def failing_output(args, **_kwargs):
+        raise subprocess.CalledProcessError(2, args, output="", stderr="Connection timed out")
+
+    monkeypatch.setattr(runner, "output", failing_output)
+    with pytest.raises(subprocess.CalledProcessError) as raised:
+        runner.psql_output(url, "SELECT to_regclass('public.tenants')")
+    assert password not in str(raised.value)
+    assert password not in json.dumps(raised.value.cmd)
+    assert "thinkwork_admin:***@db.cluster-abc" in raised.value.cmd[1]
+    assert raised.value.returncode == 2
+    assert raised.value.stderr == "Connection timed out"
+
+    def failing_run(args, **_kwargs):
+        raise subprocess.CalledProcessError(1, args)
+
+    monkeypatch.setattr(runner, "run", failing_run)
+    with pytest.raises(subprocess.CalledProcessError) as raised_file:
+        runner.psql(url, file=Path("0001_init.sql"), variables={"stage": "tei-e2e"})
+    assert password not in str(raised_file.value)
+    assert "-f" in raised_file.value.cmd and "0001_init.sql" in raised_file.value.cmd
+
+    def failing_subprocess_run(args, **_kwargs):
+        raise subprocess.CalledProcessError(3, args)
+
+    monkeypatch.setattr(runner.subprocess, "run", failing_subprocess_run)
+    with pytest.raises(subprocess.CalledProcessError) as raised_sql:
+        runner.psql(url, sql="SELECT 1")
+    assert password not in str(raised_sql.value)
+    assert raised_sql.value.returncode == 3
+
+    assert runner.redact_database_url(url) == (
+        "postgresql://thinkwork_admin:***"
+        "@db.cluster-abc.us-east-1.rds.amazonaws.com:5432/thinkwork?sslmode=require"
+    )
+    assert runner.redact_database_url("no url here") == "no url here"
+    assert runner.redact_database_url(None) is None
+
+
+################################################################################
+# Database access over the RDS Data API (THINK-1082)
+################################################################################
+
+DRIZZLE_DIR = Path(__file__).resolve().parents[4] / "packages/database-pg/drizzle"
+
+
+class FakeRdsDataClient:
+    """boto3-shaped rds-data stand-in: records every call in order, answers
+    scalar probes from a tiny in-memory ledger, and can fail one statement."""
+
+    def __init__(self, fail_on: str | None = None, ledger: set[str] | None = None) -> None:
+        self.calls: list[tuple[str, str | None, str]] = []
+        self.fail_on = fail_on
+        self.ledger = set(ledger or set())
+        self.transactions = 0
+
+    def execute_statement(self, **params):
+        sql = params["sql"]
+        self.calls.append(("execute", params.get("transactionId"), sql))
+        if self.fail_on and self.fail_on in sql:
+            raise RuntimeError(f"ERROR: boom near {self.fail_on}; SQLState: 42601")
+        if "to_regclass('public.tenants')" in sql:
+            return {"records": [[{"stringValue": "tenants"}]]}
+        if "to_regclass('public.platform_schema_migrations')" in sql:
+            return {"records": [[{"stringValue": "platform_schema_migrations"}]]}
+        if "SELECT name FROM public.platform_schema_migrations" in sql:
+            return {"records": [[{"stringValue": name}] for name in sorted(self.ledger)]}
+        if "INSERT INTO public.platform_schema_migrations" in sql:
+            self.ledger.update(re.findall(r"\('([^']+)', '[^']+'\)", sql))
+        return {"records": []}
+
+    def begin_transaction(self, **params):
+        self.transactions += 1
+        transaction_id = f"tx{self.transactions}"
+        self.calls.append(("begin", transaction_id, ""))
+        return {"transactionId": transaction_id}
+
+    def commit_transaction(self, **params):
+        self.calls.append(("commit", params["transactionId"], ""))
+        return {}
+
+    def rollback_transaction(self, **params):
+        self.calls.append(("rollback", params["transactionId"], ""))
+        return {}
+
+    def executed(self) -> list[str]:
+        return [sql for kind, _tx, sql in self.calls if kind == "execute"]
+
+
+def data_api_db(runner, client: FakeRdsDataClient):
+    return runner.DataApiDatabase(
+        "arn:aws:rds:us-east-1:637423202447:cluster:thinkwork-tei-e2e-db",
+        "arn:aws:secretsmanager:us-east-1:637423202447:secret:db-abc",
+        "thinkwork",
+        client=client,
+    )
+
+
+def test_split_sql_script_honours_quotes_dollar_bodies_comments_and_breakpoints() -> None:
+    runner = load_runner()
+    script = """
+-- leading comment; with a semicolon
+CREATE TABLE a (id int);
+--> statement-breakpoint
+CREATE FUNCTION f() RETURNS void AS $$
+BEGIN
+  PERFORM 1; PERFORM 2;
+END;
+$$ LANGUAGE plpgsql
+--> statement-breakpoint
+DO $body$ BEGIN RAISE NOTICE 'x; y'; END $body$;
+INSERT INTO a VALUES ('semi;colon'), (E'esc\\'aped; still'); /* block; comment */
+SELECT "quoted;identifier" FROM a;
+   -- trailing comment only
+"""
+    items = runner.split_sql_script(script)
+    assert [kind for kind, _ in items] == ["sql"] * 5
+    statements = [text for _, text in items]
+    assert statements[0].endswith("CREATE TABLE a (id int)")
+    assert (
+        statements[1].startswith("CREATE FUNCTION f()") and "PERFORM 1; PERFORM 2;" in statements[1]
+    )
+    assert statements[2] == "DO $body$ BEGIN RAISE NOTICE 'x; y'; END $body$"
+    assert statements[3].startswith("INSERT INTO a VALUES ('semi;colon')")
+    assert "E'esc\\'aped; still'" in statements[3]
+    assert statements[4].startswith("/* block; comment */")
+    assert statements[4].endswith('SELECT "quoted;identifier" FROM a')
+    # the drizzle marker alone is a boundary even without a semicolon
+    assert runner.split_sql_script("SELECT 1\n--> statement-breakpoint\nSELECT 2;") == [
+        ("sql", "SELECT 1"),
+        ("sql", "SELECT 2"),
+    ]
+
+
+def test_split_sql_script_lifts_meta_command_lines_in_order() -> None:
+    runner = load_runner()
+    script = "\\set ON_ERROR_STOP on\nSELECT 1;\n\\echo 'done; really'\nSELECT 2;\n"
+    assert runner.split_sql_script(script) == [
+        ("meta", "\\set ON_ERROR_STOP on"),
+        ("sql", "SELECT 1"),
+        ("meta", "\\echo 'done; really'"),
+        ("sql", "SELECT 2"),
+    ]
+    # a backslash inside a dollar-quoted body is not a meta-command
+    body = "DO $$ BEGIN\n\\x := 1;\nEND $$;"
+    assert runner.split_sql_script(body) == [("sql", "DO $$ BEGIN\n\\x := 1;\nEND $$")]
+
+
+def test_substitute_psql_variables_matches_psql_interpolation() -> None:
+    runner = load_runner()
+    variables = {"stage": "tei-e2e", "who": "o'brien"}
+    sql = (
+        "SELECT :'stage', :\"stage\", :stage, :'who', 1::text, ':stage untouched', "
+        "\"also :'stage'\" -- and :'stage' in a comment\n, :'undefined'"
+    )
+    assert runner.substitute_psql_variables(sql, variables) == (
+        "SELECT 'tei-e2e', \"tei-e2e\", tei-e2e, 'o''brien', 1::text, ':stage untouched', "
+        "\"also :'stage'\" -- and :'stage' in a comment\n, :'undefined'"
+    )
+    assert runner.substitute_psql_variables("SELECT :'stage'", None) == "SELECT :'stage'"
+
+
+def test_data_api_plans_the_real_meta_command_migrations() -> None:
+    """0031, 0036 and 0037 are the migration files that use psql
+    meta-commands; every form they use is interpreted, read from disk."""
+    runner = load_runner()
+    db = data_api_db(runner, FakeRdsDataClient())
+
+    # 0036 / 0037: `\set ON_ERROR_STOP on` only.
+    for name in ("0036_user_scoped_memory_wiki.sql", "0037_user_profile_operating_model.sql"):
+        text = (DRIZZLE_DIR / name).read_text(encoding="utf-8")
+        assert "\\set ON_ERROR_STOP on" in text
+        planned = db._plan(text, name, {"stage": "tei-e2e"})
+        assert planned and not any(statement.startswith("\\") for statement in planned)
+
+    # 0031: `\if :{?stage}` / `\else` / `\set stage dev` / `\endif`, then
+    # `:'stage'` inside the S3 snapshot call.
+    text = (DRIZZLE_DIR / "0031_thread_cleanup_drops.sql").read_text(encoding="utf-8")
+    with_stage = db._plan(text, "0031_thread_cleanup_drops.sql", {"stage": "tei-e2e"})
+    assert any("'thinkwork-' || 'tei-e2e' || '-backups'" in statement for statement in with_stage)
+    without_stage = db._plan(text, "0031_thread_cleanup_drops.sql", {})
+    assert any("'thinkwork-' || 'dev' || '-backups'" in statement for statement in without_stage)
+
+    # Anything this lane does not implement is refused by name, before any
+    # statement runs.
+    with pytest.raises(runner.DatabaseCommandError) as refused:
+        db._plan("SELECT 1;\n\\copy a FROM 'x.csv'\n", "0999_bad.sql", {})
+    assert "unsupported psql meta-command in Data API mode: \\copy a FROM 'x.csv'" in str(
+        refused.value
+    )
+    assert "0999_bad.sql" in str(refused.value)
+    with pytest.raises(runner.DatabaseCommandError):
+        db._plan("\\if 1 = 1\nSELECT 1;\n\\endif\n", "0998_bad.sql", {})
+
+
+def test_data_api_quit_ends_the_script_like_psql() -> None:
+    """0076 quits (exit 0 under psql) when computer_id is not passed — the
+    runner's sweep passes only `stage`, so the file is a recorded no-op."""
+    runner = load_runner()
+    client = FakeRdsDataClient()
+    db = data_api_db(runner, client)
+    db.execute(
+        file=DRIZZLE_DIR / "0076_scheduled_jobs_marco_backfill.sql", variables={"stage": "x"}
+    )
+    assert client.calls == []
+
+
+def test_data_api_scalar_renders_like_psql_tA() -> None:
+    runner = load_runner()
+    client = FakeRdsDataClient()
+    db = data_api_db(runner, client)
+    client.execute_statement = lambda **params: {  # type: ignore[method-assign]
+        "records": [
+            [{"longValue": 3}, {"booleanValue": True}, {"isNull": True}, {"stringValue": "a"}],
+            [
+                {"doubleValue": 1.5},
+                {"booleanValue": False},
+                {"stringValue": ""},
+                {"stringValue": "b"},
+            ],
+        ]
+    }
+    assert db.scalar("SELECT ...") == "3|t||a\n1.5|f||b"
+    client.execute_statement = lambda **params: {"records": []}  # type: ignore[method-assign]
+    assert db.scalar("SELECT to_regclass('nothing')::text") == ""
+    assert runner.psql_output(db, "SELECT 1") == ""
+
+
+def test_data_api_stops_at_the_first_error_and_rolls_back() -> None:
+    runner = load_runner()
+    client = FakeRdsDataClient(fail_on="SECOND")
+    db = data_api_db(runner, client)
+    with pytest.raises(subprocess.CalledProcessError) as raised:
+        runner.psql(db, sql="SELECT 'first'; SELECT 'SECOND'; SELECT 'third';")
+    assert isinstance(raised.value, runner.DatabaseCommandError)
+    assert raised.value.returncode == 1
+    assert "statement 2 (SELECT 'SECOND'): ERROR: boom" in str(raised.value)
+    assert "inline sql" in raised.value.cmd
+    assert [kind for kind, _tx, _sql in client.calls] == ["begin", "execute", "execute", "rollback"]
+    assert not any("third" in sql for sql in client.executed())
+
+
+def test_data_api_wraps_scripts_in_one_transaction_and_maps_explicit_ones() -> None:
+    """Every script runs inside a Data API transaction so its statements
+    serialise on one connection (a statement that outlives its 45 s call can
+    never race the next). A script's own BEGIN/COMMIT map onto it, and
+    CREATE INDEX CONCURRENTLY — which refuses a transaction block — commits
+    the open one and runs standalone."""
+    runner = load_runner()
+    client = FakeRdsDataClient()
+    db = data_api_db(runner, client)
+    db.execute(
+        sql=(
+            "BEGIN;\nSET LOCAL lock_timeout = '5s';\nUPDATE a SET b = 1;\nCOMMIT;\n"
+            "CREATE INDEX CONCURRENTLY IF NOT EXISTS i ON a (b);\n"
+            "ALTER TABLE a VALIDATE CONSTRAINT c;\n"
+        )
+    )
+    assert [(kind, tx) for kind, tx, _sql in client.calls] == [
+        ("begin", "tx1"),
+        ("execute", "tx1"),
+        ("execute", "tx1"),
+        ("commit", "tx1"),
+        ("execute", None),
+        ("begin", "tx2"),
+        ("execute", "tx2"),
+        ("commit", "tx2"),
+    ]
+    ddl_call = client.calls[1]
+    assert ddl_call[2].startswith("SET LOCAL")
+
+
+def test_data_api_ships_oversized_statements_through_a_temp_table() -> None:
+    """0230_analyst_rls carries an 85 KB DO block — over the Data API's
+    64 KB per-statement limit. It is delivered in pieces to a temp table on
+    the transaction's connection, reassembled and run there with EXECUTE."""
+    runner = load_runner()
+    client = FakeRdsDataClient()
+    db = data_api_db(runner, client)
+    db.execute(file=DRIZZLE_DIR / "0230_analyst_rls.sql", variables={"stage": "tei-e2e"})
+    executed = client.executed()
+    assert all(len(sql.encode("utf-8")) <= runner.RDS_DATA_API_MAX_SQL_BYTES for sql in executed)
+    inserts = [
+        sql for sql in executed if sql.startswith("INSERT INTO pg_temp.runner_oversized_statement")
+    ]
+    assert len(inserts) == 2
+    assembled = "".join(
+        re.search(r"\$chunk\$(.*)\$chunk\$\)$", sql, re.S).group(1) for sql in inserts
+    )
+    assert assembled.lstrip().startswith("--") and "END $$" in assembled
+    assert any(sql.startswith("DO $runner$ BEGIN EXECUTE") for sql in executed)
+    assert executed[-1] == "DROP TABLE pg_temp.runner_oversized_statement"
+    assert len({tx for kind, tx, _ in client.calls if kind == "execute"}) == 1  # one transaction
+    assert [kind for kind, _tx, _sql in client.calls][-1] == "commit"
+
+
+def test_write_runner_files_threads_db_access_as_a_runner_only_flag(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """THINK-1082: dbAccess rides the runner-secrets / payload precedence
+    like apiLambdasInVpc, defaults to psql, and is runner-only: it never
+    lands in terraform.auto.tfvars.json or the generated root."""
+    runner = load_runner()
+    tf_dir = _cognito_email_runner_env(runner, tmp_path, monkeypatch)
+    base_payload = {
+        "stage": "tei-e2e",
+        "awsRegion": "us-east-1",
+        "awsAccountId": "637423202447",
+        "dbPassword": "db-secret",
+        "apiAuthSecret": "api-secret",
+    }
+    vars_json_default = runner.write_runner_files(dict(base_payload), {})
+    assert vars_json_default["db_access"] == "psql"
+    tfvars = json.loads((tf_dir / "terraform.auto.tfvars.json").read_text(encoding="utf-8"))
+    assert "db_access" not in tfvars
+    main_tf = (tf_dir / "main.tf").read_text(encoding="utf-8")
+    assert "db_access" not in main_tf
+    assert 'output "db_cluster_arn" { value = module.thinkwork.db_cluster_arn }' in main_tf
+
+    vars_json_payload = runner.write_runner_files({**base_payload, "dbAccess": "data-api"}, {})
+    assert vars_json_payload["db_access"] == "data-api"
+    vars_json_secret = runner.write_runner_files(
+        {**base_payload, "dbAccess": "psql"}, {"dbAccess": "Data-API"}
+    )
+    assert vars_json_secret["db_access"] == "data-api"
+    with pytest.raises(RuntimeError, match="dbAccess must be one of psql, data-api"):
+        runner.write_runner_files({**base_payload, "dbAccess": "tunnel"}, {})
+
+    assert runner.set_database_access_mode(vars_json_payload) == "data-api"
+    assert runner.DATABASE_ACCESS_MODE == "data-api"
+    assert runner.set_database_access_mode({}) == "psql"
+
+
+def test_push_database_schema_over_the_data_api_applies_and_records_pending_files(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """With dbAccess=data-api the whole schema step — probes, ledger, the
+    pending files and their ledger rows — runs through the fake rds-data
+    client, in order, with each file recorded only after its statements."""
+    runner = load_runner()
+    client = FakeRdsDataClient(ledger={"0001_init.sql", "0155_tenant_model_catalog.sql"})
+    source_dir = tmp_path / "source"
+    write_drizzle_files(
+        source_dir,
+        ["0001_init.sql", "0002_add_a.sql", "0003_add_b.sql", "0155_tenant_model_catalog.sql"],
+    )
+    drizzle = source_dir / "packages/database-pg/drizzle"
+    (drizzle / "0002_add_a.sql").write_text(
+        "\\set ON_ERROR_STOP on\nBEGIN;\nCREATE TABLE a (id int);\n"
+        "SELECT set_config('thinkwork.stage', :'stage', true);\nCOMMIT;\n",
+        encoding="utf-8",
+    )
+    (drizzle / "0003_add_b.sql").write_text(
+        "CREATE TABLE b (id int);\n--> statement-breakpoint\nCREATE INDEX b_id ON b (id);\n",
+        encoding="utf-8",
+    )
+    outputs_path = tmp_path / "outputs.json"
+    outputs_path.write_text(
+        json.dumps(
+            {
+                "db_cluster_arn": {
+                    "value": "arn:aws:rds:us-east-1:637423202447:cluster:thinkwork-tei-e2e-db"
+                },
+                "db_cluster_endpoint": {
+                    "value": "thinkwork-tei-e2e-db.cluster-x.rds.amazonaws.com"
+                },
+                "db_secret_arn": {"value": "arn:aws:secretsmanager:us-east-1:1:secret:db"},
+                "database_name": {"value": "thinkwork"},
+            }
+        ),
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(runner, "SOURCE", source_dir)
+    monkeypatch.setenv("THINKWORK_TERRAFORM_MODULE_SOURCE", "thinkwork-ai/thinkwork/aws")
+    monkeypatch.setattr(runner, "checkout_source", lambda *_args: None)
+    monkeypatch.setattr(runner, "rds_data_client", lambda _region: client)
+    monkeypatch.setattr(
+        runner,
+        "seed_platform_bootstrap_defaults",
+        lambda _db: client.calls.append(("seed", None, "")),
+    )
+    runner.set_database_access_mode({"db_access": "data-api"})
+
+    runner.push_database_schema(outputs_path, {"stage": "tei-e2e"})
+
+    executed = client.executed()
+    assert executed[0] == "SELECT to_regclass('public.tenants')::text"
+    assert "CREATE TABLE IF NOT EXISTS public.platform_schema_migrations" in executed[2]
+    order = [
+        next(i for i, sql in enumerate(executed) if sql == "CREATE TABLE a (id int)"),
+        next(
+            i for i, sql in enumerate(executed) if "set_config('thinkwork.stage', 'tei-e2e'" in sql
+        ),
+        next(i for i, sql in enumerate(executed) if "('0002_add_a.sql', 'runner')" in sql),
+        next(i for i, sql in enumerate(executed) if sql == "CREATE TABLE b (id int)"),
+        next(i for i, sql in enumerate(executed) if sql == "CREATE INDEX b_id ON b (id)"),
+        next(i for i, sql in enumerate(executed) if "('0003_add_b.sql', 'runner')" in sql),
+    ]
+    assert order == sorted(order)
+    assert not any("('0001_init.sql'" in sql for sql in executed)
+    assert client.ledger == {
+        "0001_init.sql",
+        "0002_add_a.sql",
+        "0003_add_b.sql",
+        "0155_tenant_model_catalog.sql",
+    }
+    kinds = [kind for kind, _tx, _sql in client.calls]
+    assert kinds.count("begin") == kinds.count("commit") and "rollback" not in kinds
+    assert kinds.index("seed") > order[-1]
+
+    # A failing file is never recorded: the error surfaces as the
+    # CalledProcessError callers already handle, after a rollback.
+    failing = FakeRdsDataClient(
+        ledger={"0001_init.sql", "0002_add_a.sql", "0155_tenant_model_catalog.sql"},
+        fail_on="CREATE INDEX b_id",
+    )
+    monkeypatch.setattr(runner, "rds_data_client", lambda _region: failing)
+    with pytest.raises(subprocess.CalledProcessError) as raised:
+        runner.push_database_schema(outputs_path, {"stage": "tei-e2e"})
+    assert "0003_add_b.sql" in raised.value.cmd
+    assert failing.ledger == {"0001_init.sql", "0002_add_a.sql", "0155_tenant_model_catalog.sql"}
+    assert [kind for kind, _tx, _sql in failing.calls][-1] == "rollback"
+
+
+def test_data_api_database_from_outputs_derives_the_cluster_arn_when_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    runner = load_runner()
+    monkeypatch.setattr(runner, "output", lambda _args, **_kw: "637423202447")
+    db = runner.DataApiDatabase.from_outputs(
+        {
+            "db_cluster_endpoint": {
+                "value": "thinkwork-tei-e2e-db.cluster-abc.us-east-1.rds.amazonaws.com"
+            },
+            "db_secret_arn": {"value": "arn:aws:secretsmanager:us-east-1:637423202447:secret:db"},
+        }
+    )
+    assert db.cluster_arn == "arn:aws:rds:us-east-1:637423202447:cluster:thinkwork-tei-e2e-db"
+    assert db.database_name == "thinkwork"
+    assert "secret" not in repr(db).lower() or "arn:aws:secretsmanager" not in repr(db)
+    runner.set_database_access_mode({"db_access": "data-api"})
+    handle = runner.database_url_from_outputs(
+        {
+            "db_cluster_arn": {"value": db.cluster_arn},
+            "db_secret_arn": {"value": db.secret_arn},
+        }
+    )
+    assert isinstance(handle, runner.DataApiDatabase)