thinkwork-cli 0.13.2 → 1.0.0

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

@@ -7,6 +7,7 @@ import re
 import secrets
 import subprocess
 import tarfile
+import time
 import urllib.error
 import urllib.parse
 import urllib.request
@@ -51,6 +52,59 @@ MIGRATION_MARKER_KINDS = [
     ("-- creates-constraint:", "constraint"),
     ("-- creates:", "object"),
 ]
+NATIVE_AUTH_CUSTOM_ATTRIBUTES = [
+    {
+        "AttributeDataType": "String",
+        "DeveloperOnlyAttribute": False,
+        "Mutable": True,
+        "Name": "entra_tenant_id",
+        "Required": False,
+        "StringAttributeConstraints": {"MinLength": "0", "MaxLength": "36"},
+    },
+    {
+        "AttributeDataType": "String",
+        "DeveloperOnlyAttribute": False,
+        "Mutable": True,
+        "Name": "entra_object_id",
+        "Required": False,
+        "StringAttributeConstraints": {"MinLength": "0", "MaxLength": "36"},
+    },
+]
+AGENTCORE_CONTROL_SDK_VERSION = "3.1089.0"
+TERRAFORM_PLAN_APPROVAL_CONTRACT = "thinkwork.terraform.saved-plan-approval.v1"
+TERRAFORM_PLAN_DESCRIPTOR_NAME = "terraform-plan-approval.json"
+TERRAFORM_SAVED_PLAN_NAME = "terraform-plan.bin"
+TEI_V380_RECOVERY_CONTRACT = "thinkwork.incident.tei-v380-proof-plane-recovery.v1"
+TEI_V380_RECOVERY_INCIDENT_ID = "tei-v380-proof-plane-partial-apply"
+TEI_V380_REJECTED_PLAN_SHA256 = "ba7b0ffa099f725b4f32e394446ee43693fe3dd4b7a9eb639d47eb833d40db84"
+TEI_V380_STATE_LINEAGE = "61f4093e-41da-ac29-852a-267bc853e24f"
+TEI_V380_STATE_SERIAL = 819
+TEI_V380_STATE_SHA256 = "cc99973e7b80e1a0c6e1097d889e006e5e2610e236ed730a02ca5f3457b99d7f"
+TEI_V380_STATE_BUCKET = "tei-thinkwork-terraform-state"
+TEI_V380_STATE_KEY = "env:/tei-e2e/thinkwork/tei-e2e/terraform.tfstate"
+TEI_V380_LOCK_TABLE = "tei-thinkwork-terraform-locks"
+TEI_V380_LOCK_KEY = f"{TEI_V380_STATE_BUCKET}/{TEI_V380_STATE_KEY}"
+TEI_V380_LOCK_ID = "04b3e9a1-3de6-c668-87e7-43d94280605e"
+TEI_V380_STATE_DIGEST = "7fe214eeaae491f5c1d8d792bddbbb19"
+TEI_V380_SECRET_ARN = (
+    "arn:aws:secretsmanager:us-east-1:637423202447:secret:"
+    "thinkwork/tei-e2e/agentcore-identity/twenty-crm-oauth-client-7OeAlG"
+)
+TEI_V380_SECRET_NAME = "thinkwork/tei-e2e/agentcore-identity/twenty-crm-oauth-client"
+TEI_V380_SECRET_ADDRESS = (
+    "module.thinkwork.module.agentcore_proof_identity."
+    "aws_secretsmanager_secret.twenty_oauth_client[0]"
+)
+TEI_V380_KMS_KEY_ID = "8798ab48-cd60-477d-a96e-c2d56bae7b40"
+TEI_V380_KMS_KEY_ARN = "arn:aws:kms:us-east-1:637423202447:key/8798ab48-cd60-477d-a96e-c2d56bae7b40"
+TEI_V380_KMS_KEY_ADDRESS = 'module.thinkwork.module.api.aws_kms_key.agentcore_turn_assertion["v1"]'
+TEI_V380_KMS_ALIAS = "alias/thinkwork-tei-e2e-agentcore-turn-assertion-v1"
+TEI_V380_KMS_ALIAS_ADDRESS = (
+    'module.thinkwork.module.api.aws_kms_alias.agentcore_turn_assertion["v1"]'
+)
+TEI_V380_OWNER_ALLOWLIST = (
+    "0ea2f626-8b40-43ca-b7f1-3601b2a6bef8,f498f488-70a1-709b-24d7-f895f2164301"
+)
 
 
 def run(args, **kwargs):
@@ -69,6 +123,10 @@ def sha256_file(path):
     return digest.hexdigest()
 
 
+def sha256_bytes(value):
+    return hashlib.sha256(value).hexdigest()
+
+
 def read_json_env(name, default):
     value = os.environ.get(name)
     if not value:
@@ -385,6 +443,118 @@ def safe_extract_tar_file(archive_path, destination):
         tar.extractall(destination, members=members)
 
 
+def validate_agentcore_node_runtime(version):
+    normalized = str(version or "").strip().removeprefix("v")
+    try:
+        major = int(normalized.split(".", 1)[0])
+    except (TypeError, ValueError):
+        raise RuntimeError(
+            f"Cannot determine Node.js version for AgentCore runtime: {version}"
+        ) from None
+    if major < 22:
+        raise RuntimeError(
+            "AgentCore control runtime requires Node.js 22 or newer; "
+            f"deployment runner is using {version}"
+        )
+    return f"v{normalized}"
+
+
+def prepare_agentcore_control_runtime():
+    global RELEASE_EVIDENCE
+    node_version = validate_agentcore_node_runtime(output(["node", "--version"]))
+    runner_bundle = bundle_extract_dir({"name": "platform"}) / "runner"
+    manifest_path = runner_bundle / "agentcore-control-runtime.json"
+    if not manifest_path.is_file():
+        raise RuntimeError("Release bundle is missing the AgentCore control runtime manifest")
+
+    runtime_manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    expected_sdk = runtime_manifest.get("sdk") or {}
+    if (
+        expected_sdk.get("package") != "@aws-sdk/client-bedrock-agentcore-control"
+        or expected_sdk.get("version") != AGENTCORE_CONTROL_SDK_VERSION
+    ):
+        raise RuntimeError("Release does not pin the required AgentCore control SDK version")
+
+    runtime_dir = safe_join(
+        runner_bundle,
+        str(runtime_manifest.get("directory") or "agentcore-control-runtime"),
+    )
+    if not runtime_dir.is_dir():
+        raise RuntimeError("Release bundle has no AgentCore control runtime directory")
+    runtime_files = runtime_manifest.get("files") or []
+    if not runtime_files:
+        raise RuntimeError("AgentCore control runtime manifest has no files")
+    runtime_paths = [str(item.get("path") or "") for item in runtime_files]
+    # THINK-324: the managed harness is retired — harness-lifecycle.js is
+    # absent from new releases but tolerated in legacy bundles.
+    required_entrypoints = {
+        "preflight.js",
+        "reconcile_twenty_provider.js",
+    }
+    required_files = required_entrypoints | {"package.json"}
+    if len(runtime_paths) != len(set(runtime_paths)) or not required_files.issubset(runtime_paths):
+        raise RuntimeError("AgentCore control runtime manifest has an invalid file set")
+    for runtime_file in runtime_files:
+        file_path = safe_join(runtime_dir, str(runtime_file.get("path") or ""))
+        if not file_path.is_file() or sha256_file(file_path) != runtime_file.get("sha256"):
+            raise RuntimeError(
+                f"AgentCore control runtime file digest mismatch: {runtime_file.get('path')}"
+            )
+    actual_runtime_paths = {
+        str(path.relative_to(runtime_dir)) for path in runtime_dir.rglob("*") if path.is_file()
+    }
+    if actual_runtime_paths != set(runtime_paths):
+        raise RuntimeError("AgentCore control runtime contains unmanifested or missing files")
+
+    module_boundary = json.loads((runtime_dir / "package.json").read_text(encoding="utf-8"))
+    if module_boundary != {"type": "module"}:
+        raise RuntimeError("AgentCore control runtime has an invalid ESM module boundary")
+
+    preflight = json.loads(output(["node", str(runtime_dir / "preflight.js")]))
+    if preflight != expected_sdk:
+        raise RuntimeError("AgentCore control runtime preflight differs from its manifest")
+    # reconcile_pi_runtime.js (THINK-584 U5) is preflighted only when present:
+    # a newer seeded runner.py may run against a pre-U5 release bundle (the
+    # runner-py-bootstrap-skew trap), and the Pi runtime reconcile step skips
+    # loudly in that case rather than failing bundle validation here.
+    optional_entrypoints = ("reconcile_pi_runtime.js",)
+    entrypoint_preflights = [
+        json.loads(
+            output(
+                [
+                    "node",
+                    str(runtime_dir / entrypoint),
+                    "--runtime-preflight",
+                ]
+            )
+        )
+        for entrypoint in ("reconcile_twenty_provider.js", *optional_entrypoints)
+        if entrypoint not in optional_entrypoints or (runtime_dir / entrypoint).is_file()
+    ]
+    if any(not item.get("sdkImportReady") for item in entrypoint_preflights):
+        raise RuntimeError("An AgentCore control runtime entrypoint cannot import its SDK")
+    os.environ["THINKWORK_AGENTCORE_CONTROL_RUNTIME_DIR"] = str(runtime_dir)
+    evidence = {
+        "manifestSha256": sha256_file(manifest_path),
+        "sdkPackage": preflight["package"],
+        "sdkVersion": preflight["version"],
+        "nodeVersion": node_version,
+        "bundledEntrypoints": sorted(
+            item["path"]
+            for item in runtime_files
+            if item.get("path") in required_entrypoints or item.get("path") in optional_entrypoints
+        ),
+        "bundledRuntimeVerified": True,
+        "entrypointPreflights": entrypoint_preflights,
+    }
+    RELEASE_EVIDENCE["agentCoreControlRuntime"] = evidence
+    print(
+        "[runner] AgentCore control runtime ready: "
+        f"sdk={evidence['sdkVersion']} manifest={evidence['manifestSha256']}"
+    )
+    return evidence
+
+
 def release_artifacts_by_name(manifest):
     return {
         artifact.get("name"): artifact
@@ -504,6 +674,11 @@ def write_json_evidence_artifact(name, payload):
     }
 
 
+# vars_json keys the runner consumes itself; they are not variables of the
+# generated Terraform root and are left out of terraform.auto.tfvars.json.
+RUNNER_ONLY_VARS = frozenset({"db_access"})
+
+
 def redacted_tfvars(vars_json):
     redacted = dict(vars_json)
     for key in [
@@ -653,6 +828,259 @@ def terraform_plan_summary(plan_json):
     }
 
 
+def terraform_plan_delete_addresses(plan_json):
+    return [
+        change.get("address")
+        for change in plan_json.get("resource_changes", [])
+        if "delete" in (change.get("change", {}).get("actions") or [])
+    ]
+
+
+def deployment_config_for_approval(payload):
+    """Return the immutable deployment intent shared by plan and apply phases.
+
+    Controller/session routing fields necessarily change between executions.
+    Everything that can influence the generated Terraform configuration stays
+    in this projection, including release pins and preserved configuration.
+    """
+    reviewed = json.loads(json.dumps(payload))
+    for key in [
+        "action",
+        "phase",
+        "sessionId",
+        "session",
+        "evidence",
+        "approvedPlan",
+    ]:
+        reviewed.pop(key, None)
+    operation = reviewed.get("operation")
+    if isinstance(operation, dict):
+        for key in ["action", "plan", "apply", "approvedPlan"]:
+            operation.pop(key, None)
+    return reviewed
+
+
+def deployment_config_sha256(payload):
+    return sha256_bytes(stable_json_bytes(deployment_config_for_approval(payload)))
+
+
+def controller_input_sha256(payload):
+    return sha256_bytes(stable_json_bytes(payload))
+
+
+def raw_controller_input_sha256(payload):
+    raw = os.environ.get("THINKWORK_DEPLOYMENT_INPUT")
+    if raw:
+        return sha256_bytes(raw.encode("utf-8"))
+    return controller_input_sha256(payload)
+
+
+def requested_plan_action(payload, action):
+    if action in {"deploy", "update", "destroy"}:
+        return action
+    operation = payload.get("operation")
+    if isinstance(operation, dict):
+        candidate = operation.get("targetAction") or operation.get("requestedAction")
+        if candidate in {"deploy", "update", "destroy"}:
+            return candidate
+    if action == "plan":
+        return "update"
+    return action
+
+
+def validate_terraform_execution_phase(payload, action):
+    """Select the explicit saved-plan protocol or the compatible legacy path.
+
+    The incident recovery always uses separate ``plan`` and ``apply``
+    executions. Existing callers still send ``deploy``/``update``/``destroy``
+    while their API and CLI approval surfaces are migrated, so those actions
+    retain their established combined behavior instead of becoming an
+    accidental platform-wide outage.
+    """
+    operation_value = payload.get("operation")
+    operation_is_structured = isinstance(operation_value, dict)
+    operation = operation_value
+    if not operation_is_structured:
+        operation = {}
+    requested_apply = operation.get("apply")
+    requested_plan = operation.get("plan")
+
+    if action == "apply":
+        if requested_apply is not True or requested_plan is not False:
+            raise RuntimeError(
+                "Saved-plan apply requires operation.apply=true and operation.plan=false"
+            )
+        approved = payload.get("approvedPlan")
+        if not isinstance(approved, dict):
+            raise RuntimeError("Saved-plan apply requires approvedPlan")
+        return "apply"
+
+    if action in {"deploy", "update", "destroy"}:
+        return "legacy"
+
+    if action == "plan":
+        if not operation_is_structured:
+            # Managed-application jobs predate the structured foundation
+            # operation object and already use action=plan as a strict
+            # plan-only phase. Preserve that safe contract.
+            return "plan"
+        if requested_apply is not False:
+            raise RuntimeError(
+                "Terraform planning never implies approval: operation.apply must be false; "
+                "apply the accepted saved plan in a separate action=apply execution"
+            )
+        if requested_plan is not True:
+            raise RuntimeError("Terraform plan phase requires operation.plan=true")
+        return "plan"
+
+    return "none"
+
+
+def canonical_state_identity_bytes(state):
+    """`terraform state pull` re-renders the state document on every run and
+    serializes the render-only check_results block in nondeterministic map
+    order, so identical remote state produces different raw bytes across
+    runs. Hash a canonical JSON form without check_results; lineage/serial
+    stay the authoritative change signal for the infrastructure content."""
+    comparable = {key: value for key, value in state.items() if key != "check_results"}
+    return json.dumps(comparable, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def terraform_state_identity():
+    raw = output(["terraform", "state", "pull"], cwd=TF)
+    state = json.loads(raw or "{}")
+    lineage = state.get("lineage")
+    serial = state.get("serial")
+    if not isinstance(lineage, str) or not lineage:
+        raise RuntimeError("Terraform state has no lineage; refusing saved-plan operation")
+    if not isinstance(serial, int) or serial < 0:
+        raise RuntimeError("Terraform state has no valid serial; refusing saved-plan operation")
+    return {
+        "lineage": lineage,
+        "serial": serial,
+        "sha256": sha256_bytes(canonical_state_identity_bytes(state)),
+        "terraformVersion": state.get("terraform_version"),
+    }
+
+
+def _validated_evidence_s3_uri(uri, label):
+    parsed = urllib.parse.urlparse(require_string(uri, label))
+    expected_bucket = os.environ.get("THINKWORK_EVIDENCE_BUCKET")
+    if parsed.scheme != "s3" or not parsed.netloc or not parsed.path.lstrip("/"):
+        raise RuntimeError(f"{label} must be an s3:// evidence URI")
+    if expected_bucket and parsed.netloc != expected_bucket:
+        raise RuntimeError(f"{label} must use the configured deployment evidence bucket")
+    return uri
+
+
+def _download_approved_artifact(uri, destination, expected_sha256, label):
+    _validated_evidence_s3_uri(uri, label)
+    expected = require_string(expected_sha256, f"{label}.sha256").lower()
+    if not re.fullmatch(r"[0-9a-f]{64}", expected):
+        raise RuntimeError(f"{label}.sha256 must be a lowercase SHA-256 digest")
+    run(["aws", "s3", "cp", uri, str(destination)])
+    actual = sha256_file(destination)
+    if actual != expected:
+        raise RuntimeError(f"{label} digest mismatch: expected {expected}, got {actual}")
+    return actual
+
+
+def load_approved_plan_descriptor(payload):
+    approved = payload.get("approvedPlan")
+    if not isinstance(approved, dict):
+        raise RuntimeError("Saved-plan apply requires approvedPlan")
+    descriptor_ref = approved.get("descriptor")
+    if not isinstance(descriptor_ref, dict):
+        raise RuntimeError("approvedPlan.descriptor is required")
+    descriptor_path = WORK / TERRAFORM_PLAN_DESCRIPTOR_NAME
+    _download_approved_artifact(
+        descriptor_ref.get("s3Uri"),
+        descriptor_path,
+        descriptor_ref.get("sha256"),
+        "approvedPlan.descriptor",
+    )
+    descriptor = json.loads(descriptor_path.read_text(encoding="utf-8"))
+    if descriptor.get("contract") != TERRAFORM_PLAN_APPROVAL_CONTRACT:
+        raise RuntimeError("Approved plan descriptor contract is unsupported")
+    return descriptor, descriptor_ref
+
+
+def comparable_terraform_plan(value, *, _top_level=True, _parent_key=None):
+    """Normalize render-only Terraform JSON variance without changing plan decisions."""
+    if isinstance(value, dict):
+        return {
+            key: comparable_terraform_plan(item, _top_level=False, _parent_key=key)
+            for key, item in value.items()
+            if not (_top_level and key == "timestamp")
+        }
+    if isinstance(value, list):
+        normalized = [comparable_terraform_plan(item, _top_level=False) for item in value]
+        if _parent_key == "references" and all(isinstance(item, str) for item in normalized):
+            return sorted(normalized)
+        return normalized
+    return value
+
+
+def validate_and_materialize_approved_plan(payload, state_identity):
+    descriptor, descriptor_ref = load_approved_plan_descriptor(payload)
+    if descriptor.get("deploymentConfigSha256") != deployment_config_sha256(payload):
+        raise RuntimeError("Approved plan deployment configuration does not match apply input")
+    if descriptor.get("release") != release_selection(payload):
+        raise RuntimeError("Approved plan release pin does not match apply input")
+    if descriptor.get("state") != state_identity:
+        raise RuntimeError("Terraform state changed after plan approval; refusing apply")
+
+    tfvars_sha256 = sha256_file(TF / "terraform.auto.tfvars.json")
+    if descriptor.get("terraformVariablesSha256") != tfvars_sha256:
+        raise RuntimeError("Approved plan Terraform variables do not match apply execution")
+
+    saved_plan = descriptor.get("savedPlan")
+    plan_json = descriptor.get("jsonPlan")
+    if not isinstance(saved_plan, dict) or not isinstance(plan_json, dict):
+        raise RuntimeError("Approved plan descriptor is missing saved plan artifacts")
+    destination = TF / "tfplan"
+    _download_approved_artifact(
+        saved_plan.get("s3Uri"),
+        destination,
+        saved_plan.get("sha256"),
+        "approvedPlan.savedPlan",
+    )
+    accepted_json = WORK / "accepted-terraform-plan.json"
+    _download_approved_artifact(
+        plan_json.get("s3Uri"),
+        accepted_json,
+        plan_json.get("sha256"),
+        "approvedPlan.jsonPlan",
+    )
+    rendered = WORK / "approved-terraform-plan.json"
+    with rendered.open("w", encoding="utf-8") as handle:
+        run(["terraform", "show", "-json", "tfplan"], cwd=TF, stdout=handle)
+    accepted_plan = json.loads(accepted_json.read_text(encoding="utf-8"))
+    rendered_plan = json.loads(rendered.read_text(encoding="utf-8"))
+    if comparable_terraform_plan(rendered_plan) != comparable_terraform_plan(accepted_plan):
+        raise RuntimeError("Approved saved plan no longer renders to the accepted JSON plan")
+    if payload.get("incidentRecovery") is not None:
+        delete_addresses = terraform_plan_delete_addresses(rendered_plan)
+        if delete_addresses:
+            raise RuntimeError(
+                "TEI v380 recovery approved plan contains delete actions; refusing apply"
+            )
+
+    return {
+        "descriptor": {
+            "fileName": TERRAFORM_PLAN_DESCRIPTOR_NAME,
+            "sha256": descriptor_ref.get("sha256"),
+            "s3Uri": descriptor_ref.get("s3Uri"),
+        },
+        "savedPlan": saved_plan,
+        "jsonPlan": plan_json,
+        "summary": descriptor.get("summary"),
+        "plannedAction": descriptor.get("plannedAction"),
+        "sourceSessionId": descriptor.get("sessionId"),
+        "state": state_identity,
+    }
+
+
 def managed_app_terraform_target_args(payload):
     app_key = payload.get("appKey")
     if app_key == "n8n":
@@ -667,6 +1095,43 @@ def managed_app_terraform_target_args(payload):
     return []
 
 
+def execute_terraform_plan_phase(
+    payload,
+    state_identity,
+    planned_action,
+    terraform_phase,
+    target_args,
+):
+    """Create plan evidence and apply only for the compatible legacy phase."""
+    plan_args = ["terraform", "plan"]
+    if planned_action == "destroy":
+        plan_args.append("-destroy")
+    plan_args.extend([*target_args, "-out=tfplan", "-no-color"])
+    plan = subprocess.run(plan_args, cwd=TF, text=True)
+    if plan.returncode != 0:
+        return plan
+    TERRAFORM_EVIDENCE["plan"] = write_terraform_plan_evidence(
+        payload,
+        state_identity,
+        planned_action,
+    )
+    if terraform_phase != "legacy":
+        return plan
+    return subprocess.run(
+        ["terraform", "apply", "-auto-approve", "-no-color", "tfplan"],
+        cwd=TF,
+        text=True,
+    )
+
+
+def should_reconcile_native_auth_schema(terraform_phase, planned_action, payload):
+    return (
+        terraform_phase in {"apply", "legacy"}
+        and planned_action in {"deploy", "update"}
+        and not is_managed_app_operation(payload)
+    )
+
+
 def truthy(value):
     if isinstance(value, bool):
         return value
@@ -797,6 +1262,28 @@ def is_web_only_operation(payload, action=None):
     return component == "web" or truthy(payload.get("webOnly"))
 
 
+def release_sync_request(action, payload, identity_operation):
+    if (
+        action not in {"deploy", "update", "apply", "web"}
+        or is_managed_app_operation(payload)
+        or identity_operation is not None
+    ):
+        return None
+    web_only = is_web_only_operation(payload, action)
+    return {
+        "artifact_types": {"static-site"} if web_only else None,
+        "artifact_names": {"web"} if web_only else None,
+    }
+
+
+def requires_agentcore_control_runtime(action, payload, identity_operation):
+    return (
+        action in {"deploy", "update", "plan", "apply", "destroy"}
+        and not is_managed_app_operation(payload)
+        and identity_operation is None
+    )
+
+
 def configure_managed_app_evidence_prefix(payload):
     if not is_managed_app_operation(payload):
         return
@@ -912,21 +1399,54 @@ def cloudfront_alias_items(value):
     return []
 
 
-def write_terraform_plan_evidence(payload=None):
+def write_terraform_plan_evidence(payload=None, state_identity=None, planned_action="update"):
+    payload = payload or {}
+    state_identity = state_identity or terraform_state_identity()
     plan_path = Path("terraform-plan.json")
     with plan_path.open("w", encoding="utf-8") as handle:
         run(["terraform", "show", "-json", "tfplan"], cwd=TF, stdout=handle)
     plan_json = json.loads(plan_path.read_text(encoding="utf-8"))
-    validate_managed_app_plan_scope(payload or {}, plan_json)
-    validate_environment_plan_scope(payload or {}, plan_json)
+    validate_managed_app_plan_scope(payload, plan_json)
+    validate_environment_plan_scope(payload, plan_json)
     artifact = {
         "fileName": plan_path.name,
         "sha256": sha256_file(plan_path),
         "s3Uri": upload_evidence_artifact(plan_path),
     }
+    saved_plan_path = TF / "tfplan"
+    saved_plan = {
+        "fileName": TERRAFORM_SAVED_PLAN_NAME,
+        "sha256": sha256_file(saved_plan_path),
+        "s3Uri": upload_evidence_artifact(saved_plan_path, TERRAFORM_SAVED_PLAN_NAME),
+    }
+    descriptor = {
+        "schemaVersion": 1,
+        "contract": TERRAFORM_PLAN_APPROVAL_CONTRACT,
+        "createdAt": datetime.now(UTC).isoformat(),
+        "status": "awaiting-approval",
+        "sessionId": payload.get("sessionId") or os.environ.get("THINKWORK_DEPLOYMENT_SESSION_ID"),
+        "plannedAction": planned_action,
+        "controllerInputSha256": controller_input_sha256(payload),
+        "rawControllerInputSha256": raw_controller_input_sha256(payload),
+        "deploymentConfigSha256": deployment_config_sha256(payload),
+        "terraformVariablesSha256": sha256_file(TF / "terraform.auto.tfvars.json"),
+        "release": release_selection(payload),
+        "state": state_identity,
+        "jsonPlan": artifact,
+        "savedPlan": saved_plan,
+        "summary": terraform_plan_summary(plan_json),
+    }
+    descriptor_artifact = write_json_evidence_artifact(
+        TERRAFORM_PLAN_DESCRIPTOR_NAME,
+        descriptor,
+    )
     return {
         "artifact": artifact,
-        "summary": terraform_plan_summary(plan_json),
+        "savedPlan": saved_plan,
+        "approvalDescriptor": descriptor_artifact,
+        "summary": descriptor["summary"],
+        "state": state_identity,
+        "status": "awaiting-approval",
     }
 
 
@@ -974,6 +1494,38 @@ def safe_get_bool(runner_secrets, payload, name, default=False):
     return default
 
 
+def safe_get_list(runner_secrets, payload, name, default=None):
+    """List analogue of safe_get_bool's precedence. Generated-root
+    variables typed list(string) reject bare strings, so string values
+    (comma-separated, common in Secrets Manager JSON) are split here and
+    the wiring point always emits a real list of non-empty strings."""
+    for source in (runner_secrets, payload):
+        value = source.get(name)
+        if isinstance(value, list):
+            return [str(item).strip() for item in value if str(item).strip()]
+        if isinstance(value, str) and value.strip():
+            return [part.strip() for part in value.split(",") if part.strip()]
+    return list(default or [])
+
+
+def safe_get_ingress_cidrs(runner_secrets, payload, name, default=None):
+    """safe_get_list precedence, but an explicitly PRESENT empty value ([] or
+    "") wins as "no ingress" instead of falling through to the default —
+    closing the database port (THINK-1082) is spelled dbPublicIngressCidrs: []
+    and must not silently re-seed the world-open default."""
+    for source in (runner_secrets, payload):
+        if name not in source:
+            continue
+        value = source.get(name)
+        if isinstance(value, list):
+            return [str(item).strip() for item in value if str(item).strip()]
+        if isinstance(value, str):
+            return [part.strip() for part in value.split(",") if part.strip()]
+        if value is None:
+            continue
+    return list(default or [])
+
+
 def current_terraform_state(stage):
     bucket = os.environ.get("THINKWORK_TERRAFORM_STATE_BUCKET")
     if not bucket:
@@ -993,6 +1545,670 @@ def current_terraform_state(stage):
     return {}
 
 
+def _terraform_state_object_keys(stage):
+    return [
+        f"env:/{stage}/thinkwork/{stage}/terraform.tfstate",
+        f"thinkwork/{stage}/terraform.tfstate",
+    ]
+
+
+def terraform_state_object_snapshot(stage):
+    bucket = require_string(
+        os.environ.get("THINKWORK_TERRAFORM_STATE_BUCKET"),
+        "THINKWORK_TERRAFORM_STATE_BUCKET",
+    )
+    for key in _terraform_state_object_keys(stage):
+        try:
+            head = json.loads(
+                output(
+                    [
+                        "aws",
+                        "s3api",
+                        "head-object",
+                        "--bucket",
+                        bucket,
+                        "--key",
+                        key,
+                        "--output",
+                        "json",
+                    ]
+                )
+            )
+            body = subprocess.check_output(
+                ["aws", "s3", "cp", f"s3://{bucket}/{key}", "-"],
+            )
+        except (subprocess.CalledProcessError, json.JSONDecodeError):
+            continue
+        state = json.loads(body)
+        return {
+            "bucket": bucket,
+            "key": key,
+            "etag": str(head.get("ETag") or "").strip('"'),
+            "size": int(head.get("ContentLength") or len(body)),
+            "lastModified": head.get("LastModified"),
+            "serverSideEncryption": head.get("ServerSideEncryption"),
+            "versionId": head.get("VersionId"),
+            "sha256": sha256_bytes(body),
+            "lineage": state.get("lineage"),
+            "serial": state.get("serial"),
+            "terraformVersion": state.get("terraform_version"),
+        }
+    raise RuntimeError(f"Terraform state object for stage {stage} was not found")
+
+
+def _incident_operation(payload):
+    operation = payload.get("operation")
+    if not isinstance(operation, dict) or operation.get("kind") != "incident_recovery":
+        raise RuntimeError("Incident recovery requires operation.kind=incident_recovery")
+    return operation
+
+
+def _require_exact_incident_payload_aliases(payload, aliases, expected, label):
+    present = {name: payload.get(name) for name in aliases if name in payload}
+    if not present or any(value != expected for value in present.values()):
+        raise RuntimeError(f"TEI v380 recovery {label} does not match exact incident scope")
+
+
+def tei_v380_recovery_scope():
+    return {
+        "contract": TEI_V380_RECOVERY_CONTRACT,
+        "incidentId": TEI_V380_RECOVERY_INCIDENT_ID,
+        "rejectedPlanSha256": TEI_V380_REJECTED_PLAN_SHA256,
+        "stage": "tei-e2e",
+        "accountId": "637423202447",
+        "region": "us-east-1",
+        "state": {
+            "bucket": TEI_V380_STATE_BUCKET,
+            "key": TEI_V380_STATE_KEY,
+            "lineage": TEI_V380_STATE_LINEAGE,
+            "serial": TEI_V380_STATE_SERIAL,
+            "sha256": TEI_V380_STATE_SHA256,
+        },
+        "lock": {
+            "table": TEI_V380_LOCK_TABLE,
+            "key": TEI_V380_LOCK_KEY,
+            "id": TEI_V380_LOCK_ID,
+            "operation": "OperationTypeApply",
+            "terraformVersion": "1.8.5",
+            "digest": TEI_V380_STATE_DIGEST,
+        },
+        "secret": {
+            "address": TEI_V380_SECRET_ADDRESS,
+            "arn": TEI_V380_SECRET_ARN,
+            "name": TEI_V380_SECRET_NAME,
+        },
+        "kmsKey": {
+            "address": TEI_V380_KMS_KEY_ADDRESS,
+            "id": TEI_V380_KMS_KEY_ID,
+            "arn": TEI_V380_KMS_KEY_ARN,
+            "aliasAddress": TEI_V380_KMS_ALIAS_ADDRESS,
+            "alias": TEI_V380_KMS_ALIAS,
+        },
+    }
+
+
+def validate_tei_v380_recovery_contract(payload):
+    operation = _incident_operation(payload)
+    expected = tei_v380_recovery_scope()
+    actual = {
+        key: operation.get(key)
+        for key in [
+            "contract",
+            "incidentId",
+            "rejectedPlanSha256",
+            "stage",
+            "accountId",
+            "region",
+            "state",
+            "lock",
+            "secret",
+            "kmsKey",
+        ]
+    }
+    if actual != expected:
+        raise RuntimeError("TEI v380 recovery contract does not match the exact incident scope")
+    expected_operation_keys = {"kind", *expected.keys()}
+    if set(operation) != expected_operation_keys:
+        raise RuntimeError("TEI v380 recovery operation contains unexpected fields")
+    _require_exact_incident_payload_aliases(
+        payload, ("environmentName", "stage"), "tei-e2e", "stage"
+    )
+    _require_exact_incident_payload_aliases(
+        payload, ("awsAccountId", "accountId"), "637423202447", "account"
+    )
+    _require_exact_incident_payload_aliases(payload, ("awsRegion", "region"), "us-east-1", "region")
+    return expected
+
+
+def assert_incident_recovery_operation_is_exclusive():
+    current_execution = os.environ.get("THINKWORK_DEPLOYMENT_EXECUTION_ARN")
+    state_machine_arn = require_string(
+        os.environ.get("THINKWORK_DEPLOYMENT_STATE_MACHINE_ARN"),
+        "THINKWORK_DEPLOYMENT_STATE_MACHINE_ARN",
+    )
+    executions = json.loads(
+        output(
+            [
+                "aws",
+                "stepfunctions",
+                "list-executions",
+                "--state-machine-arn",
+                state_machine_arn,
+                "--status-filter",
+                "RUNNING",
+                "--output",
+                "json",
+            ]
+        )
+        or "{}"
+    ).get("executions", [])
+    if current_execution:
+        other_executions = [
+            item.get("executionArn")
+            for item in executions
+            if item.get("executionArn") != current_execution
+        ]
+    else:
+        # Established control planes do not receive Execution.Id until this
+        # release updates their state-machine definition. Permit exactly the
+        # sole running controller execution during that bounded transition.
+        # Zero executions would mean the recovery was launched outside the
+        # managed controller; more than one is ambiguous and unsafe.
+        if len(executions) != 1:
+            raise RuntimeError(
+                "Incident recovery without execution identity requires exactly one "
+                "running deployment execution"
+            )
+        current_execution = executions[0].get("executionArn")
+        other_executions = []
+    if other_executions:
+        raise RuntimeError("Another deployment execution is running; recovery refused")
+
+    project = require_string(
+        os.environ.get("THINKWORK_DEPLOYMENT_RUNNER_PROJECT_NAME"),
+        "THINKWORK_DEPLOYMENT_RUNNER_PROJECT_NAME",
+    )
+    current_build = os.environ.get("CODEBUILD_BUILD_ID")
+    if not current_build:
+        raise RuntimeError("Incident recovery must run inside the deployment CodeBuild")
+    build_ids = json.loads(
+        output(
+            [
+                "aws",
+                "codebuild",
+                "list-builds-for-project",
+                "--project-name",
+                project,
+                "--sort-order",
+                "DESCENDING",
+                "--no-paginate",
+                "--output",
+                "json",
+            ]
+        )
+        or "{}"
+    ).get("ids", [])[:100]
+    if build_ids:
+        builds = json.loads(
+            output(
+                [
+                    "aws",
+                    "codebuild",
+                    "batch-get-builds",
+                    "--ids",
+                    *build_ids,
+                    "--output",
+                    "json",
+                ]
+            )
+            or "{}"
+        ).get("builds", [])
+        other_builds = [
+            item.get("id")
+            for item in builds
+            if item.get("buildStatus") == "IN_PROGRESS" and item.get("id") != current_build
+        ]
+        if other_builds:
+            raise RuntimeError("Another deployment CodeBuild is running; recovery refused")
+    return {
+        "currentExecutionArn": current_execution,
+        "currentBuildId": current_build,
+        "otherRunningExecutions": 0,
+        "otherRunningBuilds": 0,
+    }
+
+
+def _redacted_secret_description(description):
+    return {
+        "arn": description.get("ARN"),
+        "name": description.get("Name"),
+        "deletedDate": description.get("DeletedDate"),
+        "kmsKeyId": description.get("KmsKeyId"),
+        "rotationEnabled": bool(description.get("RotationEnabled", False)),
+    }
+
+
+def _redacted_kms_description(description):
+    metadata = description.get("KeyMetadata") or {}
+    return {
+        "keyId": metadata.get("KeyId"),
+        "arn": metadata.get("Arn"),
+        "keyState": metadata.get("KeyState"),
+        "deletionDate": metadata.get("DeletionDate"),
+        "enabled": metadata.get("Enabled"),
+        "keyManager": metadata.get("KeyManager"),
+        "origin": metadata.get("Origin"),
+    }
+
+
+def _wait_for_json_description(fetch, accept, description, attempts=20, delay_seconds=1):
+    """Bound eventual-consistency waits without ever reading secret values."""
+    latest = None
+    for attempt in range(attempts):
+        latest = fetch()
+        if accept(latest):
+            return latest
+        if attempt + 1 < attempts:
+            time.sleep(delay_seconds)
+    raise RuntimeError(f"Timed out waiting for {description}")
+
+
+def _dynamodb_string(item, name):
+    value = (item.get(name) or {}).get("S")
+    return value if isinstance(value, str) else None
+
+
+def tei_v380_lock_snapshot():
+    def get_item(lock_key):
+        raw = output(
+            [
+                "aws",
+                "dynamodb",
+                "get-item",
+                "--table-name",
+                TEI_V380_LOCK_TABLE,
+                "--key",
+                json.dumps({"LockID": {"S": lock_key}}, separators=(",", ":")),
+                "--consistent-read",
+                "--output",
+                "json",
+            ]
+        )
+        return json.loads(raw or "{}").get("Item") or {}
+
+    lock_item = get_item(TEI_V380_LOCK_KEY)
+    digest_item = get_item(f"{TEI_V380_LOCK_KEY}-md5")
+    info_raw = _dynamodb_string(lock_item, "Info")
+    info = json.loads(info_raw) if info_raw else None
+    if info is not None and not isinstance(info, dict):
+        raise RuntimeError("TEI v380 Terraform lock Info is malformed")
+    return {
+        "table": TEI_V380_LOCK_TABLE,
+        "key": TEI_V380_LOCK_KEY,
+        "present": bool(lock_item),
+        "info": {
+            "id": (info or {}).get("ID"),
+            "operation": (info or {}).get("Operation"),
+            "version": (info or {}).get("Version"),
+            "created": (info or {}).get("Created"),
+            "path": (info or {}).get("Path"),
+        }
+        if info
+        else None,
+        "digestKey": f"{TEI_V380_LOCK_KEY}-md5",
+        "digest": _dynamodb_string(digest_item, "Digest"),
+    }
+
+
+def force_unlock_tei_v380_state():
+    """Use Terraform's backend-aware unlock path; never delete DynamoDB rows directly."""
+    before = tei_v380_lock_snapshot()
+    expected_info = {
+        "id": TEI_V380_LOCK_ID,
+        "operation": "OperationTypeApply",
+        "version": "1.8.5",
+        "path": TEI_V380_LOCK_KEY,
+    }
+    actual_info = before.get("info") or {}
+    if before.get("digest") != TEI_V380_STATE_DIGEST:
+        raise RuntimeError("TEI v380 Terraform state digest changed; unlock refused")
+    if before.get("present") is not True:
+        return {
+            "method": "terraform-force-unlock",
+            "lockId": TEI_V380_LOCK_ID,
+            "before": before,
+            "after": before,
+            "alreadyUnlocked": True,
+            "directDynamoDbMutation": False,
+        }
+    if any(actual_info.get(key) != value for key, value in expected_info.items()):
+        raise RuntimeError("TEI v380 stale Terraform lock identity does not match")
+
+    unlock_dir = WORK / "tei-v380-force-unlock"
+    unlock_dir.mkdir(parents=True, exist_ok=True)
+    (unlock_dir / "main.tf").write_text(
+        'terraform {\n  required_version = ">= 1.8.5"\n  backend "s3" {}\n}\n',
+        encoding="utf-8",
+    )
+    (unlock_dir / "backend.hcl").write_text(
+        "\n".join(
+            [
+                f"bucket = {hcl_string(TEI_V380_STATE_BUCKET)}",
+                f"key = {hcl_string(TEI_V380_STATE_KEY)}",
+                'region = "us-east-1"',
+                f"dynamodb_table = {hcl_string(TEI_V380_LOCK_TABLE)}",
+                "encrypt = true",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    run(
+        [
+            "terraform",
+            "init",
+            "-reconfigure",
+            "-backend-config=backend.hcl",
+            "-input=false",
+            "-no-color",
+        ],
+        cwd=unlock_dir,
+    )
+    run(
+        ["terraform", "force-unlock", "-force", TEI_V380_LOCK_ID],
+        cwd=unlock_dir,
+    )
+    after = tei_v380_lock_snapshot()
+    if after.get("present") is not False:
+        raise RuntimeError("TEI v380 stale Terraform lock remains after force-unlock")
+    if after.get("digest") != before.get("digest"):
+        raise RuntimeError("Terraform state digest changed during force-unlock")
+    return {
+        "method": "terraform-force-unlock",
+        "lockId": TEI_V380_LOCK_ID,
+        "before": before,
+        "after": after,
+        "alreadyUnlocked": False,
+        "directDynamoDbMutation": False,
+    }
+
+
+def recover_tei_v380_incident(payload):
+    validate_tei_v380_recovery_contract(payload)
+    exclusivity = assert_incident_recovery_operation_is_exclusive()
+    caller_account = output(
+        ["aws", "sts", "get-caller-identity", "--query", "Account", "--output", "text"]
+    )
+    if caller_account != "637423202447":
+        raise RuntimeError("TEI v380 recovery caller is in the wrong AWS account")
+
+    before_state = terraform_state_object_snapshot("tei-e2e")
+    for key, expected in [
+        ("bucket", TEI_V380_STATE_BUCKET),
+        ("key", TEI_V380_STATE_KEY),
+        ("lineage", TEI_V380_STATE_LINEAGE),
+        ("serial", TEI_V380_STATE_SERIAL),
+        ("sha256", TEI_V380_STATE_SHA256),
+    ]:
+        if before_state.get(key) != expected:
+            raise RuntimeError(f"TEI v380 recovery state {key} changed; recovery refused")
+
+    progress = {
+        "schemaVersion": 1,
+        "contract": TEI_V380_RECOVERY_CONTRACT,
+        "incidentId": TEI_V380_RECOVERY_INCIDENT_ID,
+        "rejectedPlanSha256": TEI_V380_REJECTED_PLAN_SHA256,
+        "status": "preflight-passed",
+        "startedAt": datetime.now(UTC).isoformat(),
+        "exclusiveOperation": exclusivity,
+        "stateBefore": before_state,
+        "terraformStateMutation": False,
+        "secretValueRead": False,
+    }
+    write_json_evidence_artifact("incident-recovery-progress.json", progress)
+
+    secret_before_raw = json.loads(
+        output(
+            [
+                "aws",
+                "secretsmanager",
+                "describe-secret",
+                "--secret-id",
+                TEI_V380_SECRET_ARN,
+                "--output",
+                "json",
+            ]
+        )
+    )
+    if (
+        secret_before_raw.get("ARN") != TEI_V380_SECRET_ARN
+        or secret_before_raw.get("Name") != TEI_V380_SECRET_NAME
+    ):
+        raise RuntimeError("TEI v380 recovery secret identity does not match")
+    if secret_before_raw.get("DeletedDate"):
+        run(
+            [
+                "aws",
+                "secretsmanager",
+                "restore-secret",
+                "--secret-id",
+                TEI_V380_SECRET_ARN,
+            ],
+            stdout=subprocess.DEVNULL,
+        )
+
+    def describe_secret():
+        return json.loads(
+            output(
+                [
+                    "aws",
+                    "secretsmanager",
+                    "describe-secret",
+                    "--secret-id",
+                    TEI_V380_SECRET_ARN,
+                    "--output",
+                    "json",
+                ]
+            )
+        )
+
+    secret_after_raw = _wait_for_json_description(
+        describe_secret,
+        lambda value: not value.get("DeletedDate"),
+        "restored TEI Twenty OAuth client secret",
+    )
+    if (
+        secret_after_raw.get("ARN") != TEI_V380_SECRET_ARN
+        or secret_after_raw.get("Name") != TEI_V380_SECRET_NAME
+    ):
+        raise RuntimeError("Restored TEI v380 recovery secret identity does not match")
+    progress["secret"] = {
+        "address": TEI_V380_SECRET_ADDRESS,
+        "before": _redacted_secret_description(secret_before_raw),
+        "after": _redacted_secret_description(secret_after_raw),
+        "status": "restored",
+    }
+    progress["status"] = "secret-restored"
+    write_json_evidence_artifact("incident-recovery-progress.json", progress)
+
+    kms_before_raw = json.loads(
+        output(
+            [
+                "aws",
+                "kms",
+                "describe-key",
+                "--key-id",
+                TEI_V380_KMS_KEY_ID,
+                "--output",
+                "json",
+            ]
+        )
+    )
+    kms_before = _redacted_kms_description(kms_before_raw)
+    if (
+        kms_before.get("keyId") != TEI_V380_KMS_KEY_ID
+        or kms_before.get("arn") != TEI_V380_KMS_KEY_ARN
+    ):
+        raise RuntimeError("TEI v380 recovery KMS key identity does not match")
+    if kms_before.get("keyState") == "PendingDeletion":
+        run(
+            ["aws", "kms", "cancel-key-deletion", "--key-id", TEI_V380_KMS_KEY_ID],
+            stdout=subprocess.DEVNULL,
+        )
+
+    def describe_kms_key():
+        return json.loads(
+            output(
+                [
+                    "aws",
+                    "kms",
+                    "describe-key",
+                    "--key-id",
+                    TEI_V380_KMS_KEY_ID,
+                    "--output",
+                    "json",
+                ]
+            )
+        )
+
+    kms_mid_raw = _wait_for_json_description(
+        describe_kms_key,
+        lambda value: _redacted_kms_description(value).get("keyState") in {"Disabled", "Enabled"},
+        "cancelled TEI turn-assertion KMS deletion",
+    )
+    if _redacted_kms_description(kms_mid_raw).get("keyState") == "Disabled":
+        run(
+            ["aws", "kms", "enable-key", "--key-id", TEI_V380_KMS_KEY_ID],
+            stdout=subprocess.DEVNULL,
+        )
+    kms_after_raw = _wait_for_json_description(
+        describe_kms_key,
+        lambda value: (
+            _redacted_kms_description(value).get("keyState") == "Enabled"
+            and _redacted_kms_description(value).get("enabled") is True
+        ),
+        "enabled TEI turn-assertion KMS key",
+    )
+    kms_after = _redacted_kms_description(kms_after_raw)
+    if (
+        kms_after.get("keyId") != TEI_V380_KMS_KEY_ID
+        or kms_after.get("arn") != TEI_V380_KMS_KEY_ARN
+    ):
+        raise RuntimeError("Recovered TEI v380 KMS key identity does not match")
+    progress["kmsKey"] = {
+        "address": TEI_V380_KMS_KEY_ADDRESS,
+        "aliasAddress": TEI_V380_KMS_ALIAS_ADDRESS,
+        "alias": TEI_V380_KMS_ALIAS,
+        "before": kms_before,
+        "after": kms_after,
+        "status": "enabled",
+    }
+    progress["status"] = "resources-recovered"
+    write_json_evidence_artifact("incident-recovery-progress.json", progress)
+
+    progress["terraformLock"] = force_unlock_tei_v380_state()
+    progress["status"] = "resources-recovered-and-state-unlocked"
+    write_json_evidence_artifact("incident-recovery-progress.json", progress)
+
+    after_state = terraform_state_object_snapshot("tei-e2e")
+    if after_state != before_state:
+        raise RuntimeError("Terraform state object changed during incident recovery")
+    progress.update(
+        {
+            "status": "succeeded",
+            "completedAt": datetime.now(UTC).isoformat(),
+            "stateAfter": after_state,
+            "terraformStateMutation": False,
+            "secretValueRead": False,
+            "nextStep": "proof-enabled-plan-with-imports",
+        }
+    )
+    artifact = write_json_evidence_artifact("incident-recovery.json", progress)
+    return {"proof": progress, "artifact": artifact}
+
+
+def tei_v380_recovery_import_blocks(payload, vars_json):
+    recovery = payload.get("incidentRecovery")
+    if recovery is None:
+        return ""
+    if not isinstance(recovery, dict):
+        raise RuntimeError("incidentRecovery must be an object")
+    evidence_ref = recovery.get("evidence")
+    actual_scope = {key: recovery.get(key) for key in tei_v380_recovery_scope()}
+    if actual_scope != tei_v380_recovery_scope():
+        raise RuntimeError("Incident recovery import scope does not match TEI v380 incident")
+    if not isinstance(evidence_ref, dict):
+        raise RuntimeError("incidentRecovery.evidence is required")
+
+    # The decoded Terraform state is used elsewhere to preserve outputs and
+    # guardrails, but it does not carry an object digest. Recovery approval is
+    # explicitly bound to the S3 state object's SHA/lineage/serial, so compare
+    # against the authoritative object snapshot instead of the decoded state.
+    current_state = terraform_state_object_snapshot(
+        vars_json.get("stage") or recovery.get("stage") or ""
+    )
+
+    evidence_path = WORK / "accepted-incident-recovery.json"
+    _download_approved_artifact(
+        evidence_ref.get("s3Uri"),
+        evidence_path,
+        evidence_ref.get("sha256"),
+        "incidentRecovery.evidence",
+    )
+    evidence = json.loads(evidence_path.read_text(encoding="utf-8"))
+    if (
+        evidence.get("contract") != TEI_V380_RECOVERY_CONTRACT
+        or evidence.get("incidentId") != TEI_V380_RECOVERY_INCIDENT_ID
+        or evidence.get("rejectedPlanSha256") != TEI_V380_REJECTED_PLAN_SHA256
+        or evidence.get("status") != "succeeded"
+        or evidence.get("terraformStateMutation") is not False
+        or evidence.get("secretValueRead") is not False
+        or evidence.get("stateBefore") != evidence.get("stateAfter")
+    ):
+        raise RuntimeError("Incident recovery evidence is incomplete or unsafe")
+    evidence_state = evidence.get("stateAfter") or {}
+    if (
+        evidence_state.get("lineage") != TEI_V380_STATE_LINEAGE
+        or evidence_state.get("serial") != TEI_V380_STATE_SERIAL
+        or evidence_state.get("sha256") != TEI_V380_STATE_SHA256
+    ):
+        raise RuntimeError("Incident recovery evidence state identity does not match")
+    if (
+        current_state.get("lineage") != TEI_V380_STATE_LINEAGE
+        or current_state.get("serial") != TEI_V380_STATE_SERIAL
+        or current_state.get("sha256") != TEI_V380_STATE_SHA256
+    ):
+        raise RuntimeError("Current Terraform state moved after incident recovery")
+
+    if vars_json.get("enable_agentcore_multiplayer_proof") is not True:
+        raise RuntimeError("Incident recovery import requires AgentCore proof enabled")
+    if vars_json.get("agentcore_multiplayer_proof_tenant_slug") != "tei":
+        raise RuntimeError("Incident recovery import requires the exact TEI tenant slug")
+    if vars_json.get("agentcore_multiplayer_proof_owner_allowlist") != TEI_V380_OWNER_ALLOWLIST:
+        raise RuntimeError("Incident recovery import requires the exact owner allowlist")
+    if vars_json.get("finalize_auth_retirement") is not False:
+        raise RuntimeError("Incident recovery import cannot finalize auth retirement")
+    if vars_json.get("auth_retirement_phase") != "coexistence":
+        raise RuntimeError("Incident recovery import requires auth coexistence")
+    if vars_json.get("microsoft_oauth_tenant") != "organizations":
+        raise RuntimeError("Incident recovery import requires Microsoft organizations tenant")
+
+    return f"""
+# TEI v380 incident recovery imports. These addresses and IDs are bound to the
+# independently accepted recovery evidence above. They recover ownership of
+# the original secret and KMS key without reading or replacing either value.
+import {{
+  to = {TEI_V380_SECRET_ADDRESS}
+  id = {hcl_string(TEI_V380_SECRET_ARN)}
+}}
+
+import {{
+  to = {TEI_V380_KMS_KEY_ADDRESS}
+  id = {hcl_string(TEI_V380_KMS_KEY_ID)}
+}}
+"""
+
+
 def current_terraform_outputs(stage):
     outputs = current_terraform_state(stage).get("outputs")
     return outputs if isinstance(outputs, dict) else {}
@@ -1238,6 +2454,42 @@ def config_string_list(desired_config, key, env_name, default=None):
     return list(default or [])
 
 
+def coerce_string_list(value):
+    """Normalize a runner-secrets / payload value into a list[str].
+
+    Accepts a native list, a JSON-array string (``["a","b"]``), or a
+    comma-separated string. Blank entries are dropped. Anything else yields
+    an empty list. Order and duplicates are preserved for the caller; the
+    Terraform side applies distinct().
+    """
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return []
+        if text.startswith("["):
+            try:
+                parsed = json.loads(text)
+            except ValueError:
+                parsed = None
+            if isinstance(parsed, list):
+                return [str(item).strip() for item in parsed if str(item).strip()]
+        return [item.strip() for item in text.split(",") if item.strip()]
+    return []
+
+
+def runner_secret_string_list(runner_secrets, payload, *keys):
+    """First non-empty list found across runner_secrets then payload for keys."""
+    for source in (runner_secrets or {}, payload or {}):
+        for key in keys:
+            if key in source:
+                result = coerce_string_list(source.get(key))
+                if result:
+                    return result
+    return []
+
+
 def required_config_value(
     desired_config,
     manifest_images,
@@ -2105,6 +3357,184 @@ def resolve_agentcore_pi_source_image_uri(payload):
     return release_runtime_image("agentcore-pi-amd64")
 
 
+def escape_env_control_chars(value):
+    # AgentCore rejects env values with raw control characters (the PEM's
+    # newlines); mirror them as literal escapes exactly like the dev-pipeline
+    # env mirror does (scripts/update-agentcore-runtime-image.sh). Consumers
+    # un-escape (the Pi container's publicKeyPemFromEnv normalizes \n).
+    return value.replace("\r", "\\r").replace("\n", "\\n").replace("\t", "\\t")
+
+
+def reconcile_agentcore_pi_runtime(vars_json, payload):
+    """Create/update the Pi Bedrock AgentCore Runtime after a successful apply
+    (THINK-584 U5). Pins the runtime to the immutable digest of the customer's
+    mirrored Pi image, mirrors the Pi Lambda env atomically (abort on empty),
+    and records the runtime id in SSM. Secret env values never appear in logs
+    or argv — the request travels to the node entrypoint on stdin."""
+    stage = vars_json["stage"]
+    region = os.environ.get("AWS_REGION") or safe_get(payload, "awsRegion", default="us-east-1")
+    runtime_bundle_dir = os.environ.get("THINKWORK_AGENTCORE_CONTROL_RUNTIME_DIR", "")
+    entrypoint = (
+        Path(runtime_bundle_dir) / "reconcile_pi_runtime.js" if runtime_bundle_dir else None
+    )
+    if entrypoint is None or not entrypoint.is_file():
+        print(
+            "[runner] AgentCore Pi runtime reconcile SKIPPED: release bundle predates "
+            "reconcile_pi_runtime.js (THINK-584 U5). Re-seed the runner bundle to enable "
+            "the customer runtime-update path."
+        )
+        return None
+
+    lambda_name = f"thinkwork-{stage}-agentcore-pi"
+    fn = json.loads(
+        output(
+            [
+                "aws",
+                "lambda",
+                "get-function-configuration",
+                "--function-name",
+                lambda_name,
+                "--region",
+                region,
+            ]
+        )
+    )
+    environment = {
+        key: escape_env_control_chars(value) if isinstance(value, str) else value
+        for key, value in ((fn.get("Environment") or {}).get("Variables") or {}).items()
+    }
+    if not environment:
+        raise RuntimeError(
+            f"AgentCore Pi runtime reconcile: {lambda_name} reported an EMPTY environment; "
+            "mirroring it would strand the runtime (atomic-or-abort)."
+        )
+    # THINK-586 U7 (KTD6): runtime-only overlay — the warm-session cache
+    # factory gates on this var; it must never enter the Lambda terraform env.
+    environment["AGENTCORE_RUNTIME_SESSION_CACHE"] = "1"
+    role_arn = fn.get("Role") or ""
+    account_id = (fn.get("FunctionArn") or "").split(":")[4] if fn.get("FunctionArn") else ""
+    if not role_arn or not account_id:
+        raise RuntimeError("AgentCore Pi runtime reconcile: Lambda did not report Role/ARN")
+
+    # AgentCore runtimes are arm64-only ("Supported platforms: [arm64]" —
+    # first tei-e2e canary, 2026-08-04). The Lambda's amd64 pin
+    # (agentcorePiSourceImageUri) is the WRONG architecture for the runtime;
+    # the runtime image is mirrored into the customer ECR under the release
+    # version tag by the release workflow's `mirror-customer-images` job
+    # (THINK-616; targets listed in .github/release-mirror-targets.json).
+    release_version = os.environ.get("THINKWORK_RELEASE_VERSION", "") or str(
+        safe_get(payload, "releaseVersion", default="")
+    )
+    if not release_version:
+        raise RuntimeError(
+            "AgentCore Pi runtime reconcile: no release version available to "
+            "resolve the arm64 runtime image tag."
+        )
+    image_tag = f"{release_version}-pi-arm64"
+    repository = f"thinkwork-{stage}-agentcore"
+    digest = output(
+        [
+            "aws",
+            "ecr",
+            "describe-images",
+            "--repository-name",
+            repository,
+            "--region",
+            region,
+            "--image-ids",
+            f"imageTag={image_tag}",
+            "--query",
+            "imageDetails[0].imageDigest",
+            "--output",
+            "text",
+        ]
+    )
+    if not re.fullmatch(r"sha256:[0-9a-f]{64}", digest):
+        raise RuntimeError(
+            f"AgentCore Pi runtime reconcile: could not resolve an immutable digest for "
+            f"{repository}:{image_tag} (got '{digest}'). Mirror the release's "
+            "arm64 Pi runtime image into this customer's ECR under that tag "
+            "before retrying."
+        )
+    image_uri = f"{account_id}.dkr.ecr.{region}.amazonaws.com/{repository}@{digest}"
+
+    ssm_name = f"/thinkwork/{stage}/agentcore/runtime-id-pi"
+    runtime_id = ""
+    try:
+        runtime_id = output(
+            [
+                "aws",
+                "ssm",
+                "get-parameter",
+                "--name",
+                ssm_name,
+                "--region",
+                region,
+                "--query",
+                "Parameter.Value",
+                "--output",
+                "text",
+            ],
+            stderr=subprocess.DEVNULL,
+        )
+    except subprocess.CalledProcessError:
+        runtime_id = ""
+    if runtime_id == "None":
+        runtime_id = ""
+
+    # AgentCore runtime names must match [a-zA-Z][a-zA-Z0-9_]{0,47} — no
+    # hyphens. Customer stages like "tei-e2e" broke the create with a
+    # ValidationException (first live canary of this step, 2026-08-04).
+    runtime_stage = re.sub(r"[^a-zA-Z0-9_]", "_", stage)
+    request = {
+        "region": region,
+        "runtimeName": f"thinkwork_{runtime_stage}_pi",
+        "runtimeId": runtime_id,
+        "roleArn": role_arn,
+        "imageUri": image_uri,
+        "environment": environment,
+        "waitSeconds": 900,
+    }
+    print(
+        f"[runner] Reconciling AgentCore Pi runtime to {image_uri} "
+        f"({len(environment)} env vars mirrored; values not logged)"
+    )
+    reconciled = subprocess.run(
+        ["node", str(entrypoint)],
+        input=json.dumps(request),
+        capture_output=True,
+        text=True,
+    )
+    if reconciled.returncode != 0:
+        raise RuntimeError(
+            "AgentCore Pi runtime reconcile failed: "
+            f"{(reconciled.stderr or '').strip() or f'exit {reconciled.returncode}'}"
+        )
+    result = json.loads(reconciled.stdout)
+    run(
+        [
+            "aws",
+            "ssm",
+            "put-parameter",
+            "--name",
+            ssm_name,
+            "--value",
+            str(result["runtimeId"]),
+            "--type",
+            "String",
+            "--overwrite",
+            "--region",
+            region,
+        ],
+        stdout=subprocess.DEVNULL,
+    )
+    print(
+        f"[runner] AgentCore Pi runtime ready: {result['runtimeId']} "
+        f"v{result.get('version')} ({'created' if result.get('created') else 'updated'})"
+    )
+    return result
+
+
 def release_git_sha():
     if not MANIFEST.exists():
         return ""
@@ -2204,6 +3634,10 @@ def checkout_source(module_source, release_version):
 
 
 def database_url_from_outputs(outputs):
+    """The database handle every schema step uses: a `postgresql://` URL for
+    psql, or a DataApiDatabase when this run's dbAccess is `data-api`."""
+    if DATABASE_ACCESS_MODE == "data-api":
+        return DataApiDatabase.from_outputs(outputs)
     endpoint = outputs.get("db_cluster_endpoint", {}).get("value")
     secret_arn = outputs.get("db_secret_arn", {}).get("value")
     database_name = outputs.get("database_name", {}).get("value") or "thinkwork"
@@ -2235,24 +3669,704 @@ def database_url_from_outputs(outputs):
     )
 
 
-def psql_env(database_url):
-    env = os.environ.copy()
-    env["DATABASE_URL"] = database_url
-    return env
+def psql_env(database_url):
+    env = os.environ.copy()
+    env["DATABASE_URL"] = database_url
+    return env
+
+
+DATABASE_URL_PASSWORD_RE = re.compile(r"(://[^/:@\s]*:)[^@\s]*(@)")
+
+
+def redact_database_url(value):
+    """Replace the password segment of any `scheme://user:password@host` URL
+    in `value` with `***`. Applied to everything a database URL can reach in a
+    log or exception message: a failed psql surfaces its argv (URL included)
+    through CalledProcessError, which CodeBuild prints to CloudWatch."""
+    if isinstance(value, (list, tuple)):
+        return [redact_database_url(item) for item in value]
+    if not isinstance(value, str):
+        return value
+    return DATABASE_URL_PASSWORD_RE.sub(r"\1***\2", value)
+
+
+def _redacted_psql_error(error):
+    """Re-raise a psql CalledProcessError with the connection password
+    redacted from its command. Same exception type, same returncode, same
+    captured output — only the secret is gone."""
+    return subprocess.CalledProcessError(
+        error.returncode,
+        redact_database_url(error.cmd),
+        output=redact_database_url(error.output),
+        stderr=redact_database_url(error.stderr),
+    )
+
+
+def psql(database_url, sql=None, file=None, variables=None):
+    if isinstance(database_url, DataApiDatabase):
+        return database_url.execute(sql=sql, file=file, variables=variables)
+    args = ["psql", database_url, "-v", "ON_ERROR_STOP=1"]
+    for key, value in (variables or {}).items():
+        args.extend(["-v", f"{key}={value}"])
+    try:
+        if file:
+            args.extend(["-f", str(file)])
+            return run(args)
+        return subprocess.run(args, input=sql, check=True, text=True)
+    except subprocess.CalledProcessError as error:
+        raise _redacted_psql_error(error) from None
+
+
+def psql_output(database_url, sql):
+    if isinstance(database_url, DataApiDatabase):
+        return database_url.scalar(sql)
+    try:
+        return output(["psql", database_url, "-tAc", sql])
+    except subprocess.CalledProcessError as error:
+        raise _redacted_psql_error(error) from None
+
+
+################################################################################
+# Database access over the RDS Data API (THINK-1082)
+#
+# The runner is the last client of the Aurora cluster's public endpoint. With
+# every API Lambda inside the VPC, `psql` from this out-of-VPC CodeBuild is
+# the only reason the world-open 0.0.0.0/0 -> 5432 rule still exists. Setting
+# `dbAccess: "data-api"` (runner-secrets document, or the controller payload)
+# routes every psql / psql_output call below through the RDS Data API instead:
+# HTTPS, IAM-authorised, no network path — the lane the Brain already uses for
+# its own migrations against these clusters. The call sites do not change;
+# `database_url_from_outputs` hands back a DataApiDatabase handle instead of a
+# URL and `psql` / `psql_output` dispatch on it.
+#
+# What the Data API does not give us and how it is bridged here:
+#   - one statement per ExecuteStatement -> scripts are split into statements
+#     (dollar-quote / quote / comment aware; drizzle `--> statement-breakpoint`
+#     markers are honoured as boundaries too);
+#   - no psql variables -> `:'name'`, `:"name"` and `:name` are substituted for
+#     the variables the runner passes (`stage`, the compliance passwords) — in
+#     code only, never inside quotes, never touching `::casts`;
+#   - no psql meta-commands -> `\set`, `\echo`/`\qecho`, `\if :{?name}` /
+#     `\else` / `\endif` and `\quit` (the forms the migration files use) are
+#     interpreted; anything else is refused by name;
+#   - 45 s per call -> DDL runs with continueAfterTimeout so a slow statement
+#     is never aborted server-side, and every script runs inside ONE Data API
+#     transaction (BeginTransaction ... CommitTransaction) so its statements
+#     serialise on one connection and a statement that outlived its call can
+#     never race the next one. A script's own top-level BEGIN/COMMIT map onto
+#     that transaction; `CREATE INDEX CONCURRENTLY` (which refuses to run in a
+#     transaction block) commits the open one and runs standalone.
+#   - ON_ERROR_STOP -> the first failing statement stops the script, rolls the
+#     transaction back and raises DatabaseCommandError, a CalledProcessError
+#     subclass, so every existing `except subprocess.CalledProcessError`
+#     keeps working and the migration ledger is recorded only after success.
+################################################################################
+
+DATABASE_ACCESS_MODES = ("psql", "data-api")
+DATABASE_ACCESS_MODE = "psql"
+RDS_DATA_API_MAX_SQL_BYTES = 65536
+STATEMENT_BREAKPOINT = "--> statement-breakpoint"
+
+
+def set_database_access_mode(vars_json):
+    """Select psql (today) or the RDS Data API for every database step of
+    this run; logged once so the build log proves which lane ran."""
+    global DATABASE_ACCESS_MODE
+    mode = str((vars_json or {}).get("db_access") or "psql")
+    if mode not in DATABASE_ACCESS_MODES:
+        raise RuntimeError(
+            f"dbAccess must be one of {', '.join(DATABASE_ACCESS_MODES)}; got {mode!r}"
+        )
+    DATABASE_ACCESS_MODE = mode
+    print(f"[runner] database access: {mode}")
+    return mode
+
+
+def safe_get_db_access(runner_secrets, payload):
+    """`dbAccess` rides the same precedence as apiLambdasInVpc: the
+    runner-secrets document is the durable home, the controller payload can
+    override per deploy. Runner-only — it never reaches the Terraform root."""
+    value = safe_get(runner_secrets, "dbAccess", default=safe_get(payload, "dbAccess", default=""))
+    value = value.strip().lower() or "psql"
+    if value not in DATABASE_ACCESS_MODES:
+        raise RuntimeError(
+            f"dbAccess must be one of {', '.join(DATABASE_ACCESS_MODES)}; got {value!r}"
+        )
+    return value
+
+
+class DatabaseCommandError(subprocess.CalledProcessError):
+    """A failed Data API statement. Subclasses CalledProcessError so every
+    caller that catches psql failures handles it identically; `cmd` names the
+    lane and the script, never a connection string or a secret."""
+
+    def __init__(self, message, label):
+        super().__init__(1, ["rds-data", "execute-statement", label], output="", stderr=message)
+        self.message = message
+
+    def __str__(self):
+        return f"rds-data failed for {self.cmd[2]}: {self.message}"
+
+
+def _sql_segments(text):
+    """Split SQL text into (kind, chunk) segments: 'code', 'squote',
+    'dquote', 'dollar', 'line_comment', 'block_comment' and 'meta' (a psql
+    meta-command: an unquoted backslash starting a line, through the end of
+    that line). Concatenating the chunks reproduces the input byte for byte."""
+    segments = []
+    i = 0
+    n = len(text)
+    code_start = 0
+
+    def flush_code(end):
+        if end > code_start:
+            segments.append(("code", text[code_start:end]))
+
+    while i < n:
+        ch = text[i]
+        if ch == "\\" and not text[text.rfind("\n", 0, i) + 1 : i].strip():
+            flush_code(i)
+            end = text.find("\n", i)
+            end = n if end == -1 else end
+            segments.append(("meta", text[i:end]))
+            i = code_start = end
+            continue
+        if ch == "-" and text.startswith("--", i):
+            flush_code(i)
+            end = text.find("\n", i)
+            end = n if end == -1 else end
+            segments.append(("line_comment", text[i:end]))
+            i = code_start = end
+            continue
+        if ch == "/" and text.startswith("/*", i):
+            flush_code(i)
+            depth = 0
+            j = i
+            while j < n:
+                if text.startswith("/*", j):
+                    depth += 1
+                    j += 2
+                elif text.startswith("*/", j):
+                    depth -= 1
+                    j += 2
+                    if depth == 0:
+                        break
+                else:
+                    j += 1
+            segments.append(("block_comment", text[i:j]))
+            i = code_start = j
+            continue
+        if ch in "'\"" and PSQL_QUOTED_VARIABLE_RE.match(text, i) and _is_variable_colon(text, i):
+            # psql's :'name' / :"name" — interpolation syntax, not a literal
+            i = PSQL_QUOTED_VARIABLE_RE.match(text, i).end()
+            continue
+        if ch == "'":
+            flush_code(i)
+            escaped = (
+                i > 0
+                and text[i - 1] in "eE"
+                and (i < 2 or not (text[i - 2].isalnum() or text[i - 2] == "_"))
+            )
+            j = i + 1
+            while j < n:
+                if escaped and text[j] == "\\":
+                    j += 2
+                    continue
+                if text[j] == "'":
+                    if j + 1 < n and text[j + 1] == "'":
+                        j += 2
+                        continue
+                    j += 1
+                    break
+                j += 1
+            segments.append(("squote", text[i:j]))
+            i = code_start = j
+            continue
+        if ch == '"':
+            flush_code(i)
+            j = i + 1
+            while j < n:
+                if text[j] == '"':
+                    if j + 1 < n and text[j + 1] == '"':
+                        j += 2
+                        continue
+                    j += 1
+                    break
+                j += 1
+            segments.append(("dquote", text[i:j]))
+            i = code_start = j
+            continue
+        if ch == "$":
+            match = DOLLAR_QUOTE_RE.match(text, i)
+            if match and not (i > 0 and (text[i - 1].isalnum() or text[i - 1] == "_")):
+                tag = match.group(0)
+                flush_code(i)
+                end = text.find(tag, i + len(tag))
+                end = n if end == -1 else end + len(tag)
+                segments.append(("dollar", text[i:end]))
+                i = code_start = end
+                continue
+        i += 1
+    flush_code(n)
+    return segments
+
+
+DOLLAR_QUOTE_RE = re.compile(r"\$[A-Za-z_][A-Za-z0-9_]*\$|\$\$")
+PSQL_QUOTED_VARIABLE_RE = re.compile(r"'\w+'|\"\w+\"")
+
+
+def _is_variable_colon(text, i):
+    """True when the quote at `i` follows a psql variable colon: a `:` that
+    is not part of a `::` cast or of an identifier."""
+    return (
+        i > 0
+        and text[i - 1] == ":"
+        and (i < 2 or not (text[i - 2] == ":" or text[i - 2].isalnum() or text[i - 2] == "_"))
+    )
+
+
+PSQL_META_RE = re.compile(r"^\s*\\(\w+)\s*(.*?)\s*$")
+PSQL_VARIABLE_RE = re.compile(r"(?<![:\w]):(?:'(\w+)'|\"(\w+)\"|(\w+))")
+
+
+def split_sql_script(text):
+    """Split a psql script into ordered items: ('sql', statement) for each
+    top-level `;`-terminated statement (drizzle `--> statement-breakpoint`
+    markers are boundaries too) and ('meta', line) for each psql meta-command
+    line (an unquoted backslash at the start of a line). Comment-only and
+    blank chunks are dropped; comments inside a statement travel with it."""
+    items = []
+    buffer = []
+    has_code = [False]
+
+    def emit():
+        statement = "".join(buffer).strip()
+        if has_code[0] and statement:
+            items.append(("sql", statement))
+        buffer.clear()
+        has_code[0] = False
+
+    for kind, chunk in _sql_segments(text):
+        if kind == "meta":
+            items.append(("meta", chunk.strip()))
+            continue
+        if kind == "line_comment":
+            if chunk.strip() == STATEMENT_BREAKPOINT:
+                emit()
+            else:
+                buffer.append(chunk)
+            continue
+        if kind != "code":
+            buffer.append(chunk)
+            has_code[0] = True
+            continue
+        start = 0
+        for i, ch in enumerate(chunk):
+            if ch == ";":
+                buffer.append(chunk[start:i])
+                emit()
+                start = i + 1
+            elif not ch.isspace():
+                has_code[0] = True
+        buffer.append(chunk[start:])
+    emit()
+    return items
+
+
+def substitute_psql_variables(sql, variables):
+    """psql `-v` interpolation for the variables given: `:'name'` becomes a
+    SQL string literal, `:"name"` an identifier, bare `:name` the raw value.
+    Only code is touched — never quoted text, comments or `::type` casts —
+    and only names that were actually passed (psql leaves the rest alone)."""
+    if not variables:
+        return sql
+
+    def replace(match):
+        literal, identifier, raw = match.groups()
+        name = literal or identifier or raw
+        if name not in variables:
+            return match.group(0)
+        value = str(variables[name])
+        if literal:
+            return "'" + value.replace("'", "''") + "'"
+        if identifier:
+            return '"' + value.replace('"', '""') + '"'
+        return value
+
+    return "".join(
+        PSQL_VARIABLE_RE.sub(replace, chunk) if kind == "code" else chunk
+        for kind, chunk in _sql_segments(sql)
+    )
+
+
+def _leading_keywords(statement, count=2):
+    words = []
+    for kind, chunk in _sql_segments(statement):
+        if kind in ("line_comment", "block_comment"):
+            continue
+        if kind != "code":
+            break
+        words.extend(chunk.split())
+        if len(words) >= count:
+            break
+    return tuple(word.upper().rstrip(";") for word in words[:count])
+
+
+def _statement_runs_outside_transaction(statement):
+    """Postgres refuses these inside a transaction block; psql (autocommit)
+    runs them standalone, so the Data API lane does too."""
+    keywords = _leading_keywords(statement, 4)
+    return "CONCURRENTLY" in keywords or keywords[:1] == ("VACUUM",)
+
+
+def _rds_data_cell_text(cell):
+    """psql -tA rendering of one Data API field: NULL is empty, booleans are
+    t/f, numbers print plainly, everything else is its string form."""
+    if not isinstance(cell, dict) or cell.get("isNull"):
+        return ""
+    if "booleanValue" in cell:
+        return "t" if cell["booleanValue"] else "f"
+    for key in ("stringValue", "longValue", "doubleValue"):
+        if key in cell:
+            return str(cell[key])
+    if "arrayValue" in cell:
+        values = next(iter(cell["arrayValue"].values()), [])
+        return "{" + ",".join(str(value) for value in values) + "}"
+    if "blobValue" in cell:
+        value = cell["blobValue"]
+        return value.decode("utf-8", "replace") if isinstance(value, bytes) else str(value)
+    return ""
+
+
+class AwsCliRdsDataClient:
+    """boto3-shaped rds-data client backed by the AWS CLI, for a build image
+    without boto3 (the runner already shells out to `aws` everywhere)."""
+
+    def __init__(self, region):
+        self.region = region
+
+    def _call(self, operation, params):
+        args = ["aws", "rds-data", operation, "--cli-input-json", json.dumps(params)]
+        if self.region:
+            args.extend(["--region", self.region])
+        try:
+            body = subprocess.check_output(args, text=True, stderr=subprocess.PIPE)
+        except subprocess.CalledProcessError as error:
+            message = (error.stderr or "").strip() or f"aws rds-data {operation} failed"
+            raise RuntimeError(message) from None
+        return json.loads(body or "{}")
+
+    def execute_statement(self, **params):
+        return self._call("execute-statement", params)
+
+    def begin_transaction(self, **params):
+        return self._call("begin-transaction", params)
+
+    def commit_transaction(self, **params):
+        return self._call("commit-transaction", params)
+
+    def rollback_transaction(self, **params):
+        return self._call("rollback-transaction", params)
+
+
+def rds_data_client(region):
+    try:
+        import boto3  # noqa: PLC0415 — optional on the build image
+    except ImportError:
+        return AwsCliRdsDataClient(region)
+    return boto3.client("rds-data", region_name=region) if region else boto3.client("rds-data")
+
+
+def _cluster_arn_from_outputs(outputs):
+    arn = (outputs.get("db_cluster_arn") or {}).get("value")
+    if arn:
+        return str(arn)
+    endpoint = str((outputs.get("db_cluster_endpoint") or {}).get("value") or "")
+    labels = endpoint.split(".")
+    if len(labels) < 5 or labels[-2] != "amazonaws" or labels[-3] != "rds":
+        raise RuntimeError(
+            "Terraform outputs carry no db_cluster_arn and the endpoint "
+            f"{endpoint!r} is not an RDS hostname; cannot address the RDS Data API"
+        )
+    region = labels[-4]
+    account = output(
+        ["aws", "sts", "get-caller-identity", "--query", "Account", "--output", "text"]
+    )
+    return f"arn:aws:rds:{region}:{account}:cluster:{labels[0]}"
+
+
+class DataApiDatabase:
+    """The database handle in data-api mode: what `database_url_from_outputs`
+    returns instead of a URL, and what `psql` / `psql_output` dispatch on."""
+
+    def __init__(self, cluster_arn, secret_arn, database_name, client=None, region=None):
+        self.cluster_arn = cluster_arn
+        self.secret_arn = secret_arn
+        self.database_name = database_name
+        self.region = region or os.environ.get("AWS_REGION") or cluster_arn.split(":")[3]
+        self._client = client
+
+    @classmethod
+    def from_outputs(cls, outputs, client=None):
+        secret_arn = (outputs.get("db_secret_arn") or {}).get("value")
+        if not secret_arn:
+            raise RuntimeError("Terraform outputs missing database secret ARN")
+        database_name = (outputs.get("database_name") or {}).get("value") or "thinkwork"
+        return cls(_cluster_arn_from_outputs(outputs), str(secret_arn), str(database_name), client)
+
+    def __repr__(self):
+        return f"DataApiDatabase({self.cluster_arn}, database={self.database_name})"
+
+    __str__ = __repr__
+
+    @property
+    def client(self):
+        if self._client is None:
+            self._client = rds_data_client(self.region)
+        return self._client
+
+    def _params(self, sql, transaction_id=None, continue_after_timeout=False):
+        params = {
+            "resourceArn": self.cluster_arn,
+            "secretArn": self.secret_arn,
+            "database": self.database_name,
+            "sql": sql,
+        }
+        if transaction_id:
+            params["transactionId"] = transaction_id
+        if continue_after_timeout:
+            params["continueAfterTimeout"] = True
+        return params
+
+    def scalar(self, sql):
+        """`psql -tAc`: every row on its own line, columns `|`-joined, NULL
+        empty, booleans t/f, whole result stripped."""
+        try:
+            response = self.client.execute_statement(**self._params(sql))
+        except Exception as error:  # noqa: BLE001 — every SDK/CLI failure lands here
+            raise DatabaseCommandError(str(error), "query") from None
+        rows = [
+            "|".join(_rds_data_cell_text(cell) for cell in row)
+            for row in response.get("records") or []
+        ]
+        return "\n".join(rows).strip()
+
+    def execute(self, sql=None, file=None, variables=None):
+        """`psql -v ON_ERROR_STOP=1 [-v k=v] -f file | -c sql`."""
+        if file is not None:
+            label = Path(file).name
+            text = Path(file).read_text(encoding="utf-8")
+        else:
+            label = "inline sql"
+            text = sql or ""
+        variables = {str(key): str(value) for key, value in (variables or {}).items()}
+        statements = self._plan(text, label, variables)
+        self._run(statements, label, variables)
+
+    def _plan(self, text, label, variables):
+        """Interpret meta-commands in order and resolve the statements that
+        will run; refuses the script before anything runs when it needs a
+        meta-command this lane does not implement or a statement the Data
+        API cannot carry."""
+        planned = []
+        conditions = []
+        for kind, item in split_sql_script(text):
+            active = all(conditions)
+            if kind == "meta":
+                match = PSQL_META_RE.match(item)
+                command, argument = (match.group(1), match.group(2)) if match else (item, "")
+                if command == "if":
+                    defined = re.fullmatch(r":\{\?(\w+)\}", argument)
+                    if not defined:
+                        raise DatabaseCommandError(
+                            f"unsupported psql meta-command in Data API mode: {item}", label
+                        )
+                    conditions.append(defined.group(1) in variables)
+                elif command == "else":
+                    if not conditions:
+                        raise DatabaseCommandError(f"\\else without \\if in {label}", label)
+                    conditions[-1] = not conditions[-1]
+                elif command == "endif":
+                    if not conditions:
+                        raise DatabaseCommandError(f"\\endif without \\if in {label}", label)
+                    conditions.pop()
+                elif not active:
+                    continue
+                elif command == "set":
+                    parts = argument.split(None, 1)
+                    if parts:
+                        value = parts[1].strip() if len(parts) > 1 else ""
+                        if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+                            value = value[1:-1]
+                        variables[parts[0]] = value
+                elif command in ("echo", "qecho"):
+                    message = argument.strip("'")
+                    print(f"[psql:{label}] {message}")
+                elif command in ("quit", "q"):
+                    # psql: \quit in a script ends that script, exit status 0
+                    # (it takes no argument; `\quit 1` still exits 0).
+                    print(f"[psql:{label}] \\quit — remaining statements skipped")
+                    conditions.clear()
+                    break
+                else:
+                    raise DatabaseCommandError(
+                        f"unsupported psql meta-command in Data API mode: {item}", label
+                    )
+                continue
+            if not active:
+                continue
+            statement = substitute_psql_variables(item, variables)
+            if len(
+                statement.encode("utf-8")
+            ) > RDS_DATA_API_MAX_SQL_BYTES and _statement_runs_outside_transaction(statement):
+                raise DatabaseCommandError(
+                    f"statement {len(planned) + 1} exceeds the RDS Data API's "
+                    f"{RDS_DATA_API_MAX_SQL_BYTES}-byte limit and cannot run inside a "
+                    "transaction; split it at `;` boundaries",
+                    label,
+                )
+            planned.append(statement)
+        if conditions:
+            raise DatabaseCommandError(f"\\if without \\endif in {label}", label)
+        return planned
+
+    def _run(self, statements, label, variables):
+        transaction_id = None
+        secrets_to_redact = [value for value in variables.values() if len(value) >= 8]
 
+        def redact(message):
+            for secret in secrets_to_redact:
+                message = message.replace(secret, "***")
+            return message
 
-def psql(database_url, sql=None, file=None, variables=None):
-    args = ["psql", database_url, "-v", "ON_ERROR_STOP=1"]
-    for key, value in (variables or {}).items():
-        args.extend(["-v", f"{key}={value}"])
-    if file:
-        args.extend(["-f", str(file)])
-        return run(args)
-    return subprocess.run(args, input=sql, check=True, text=True)
+        def begin():
+            return self.client.begin_transaction(
+                resourceArn=self.cluster_arn, secretArn=self.secret_arn, database=self.database_name
+            )["transactionId"]
 
+        try:
+            for index, statement in enumerate(statements, start=1):
+                head = _leading_keywords(statement)
+                if head[:1] in {("BEGIN",), ("START",)}:
+                    if transaction_id is None:
+                        transaction_id = begin()
+                    continue
+                if head[:1] in {("COMMIT",), ("END",)}:
+                    if transaction_id is not None:
+                        self.client.commit_transaction(
+                            resourceArn=self.cluster_arn,
+                            secretArn=self.secret_arn,
+                            transactionId=transaction_id,
+                        )
+                        transaction_id = None
+                    continue
+                if head[:1] == ("ROLLBACK",):
+                    if transaction_id is not None:
+                        self.client.rollback_transaction(
+                            resourceArn=self.cluster_arn,
+                            secretArn=self.secret_arn,
+                            transactionId=transaction_id,
+                        )
+                        transaction_id = None
+                    continue
+                if _statement_runs_outside_transaction(statement):
+                    if transaction_id is not None:
+                        self.client.commit_transaction(
+                            resourceArn=self.cluster_arn,
+                            secretArn=self.secret_arn,
+                            transactionId=transaction_id,
+                        )
+                        transaction_id = None
+                    self._execute_one(statement, None, index, label, redact)
+                    continue
+                if transaction_id is None:
+                    transaction_id = begin()
+                self._execute_one(statement, transaction_id, index, label, redact)
+            if transaction_id is not None:
+                self.client.commit_transaction(
+                    resourceArn=self.cluster_arn,
+                    secretArn=self.secret_arn,
+                    transactionId=transaction_id,
+                )
+        except BaseException:
+            if transaction_id is not None:
+                try:
+                    self.client.rollback_transaction(
+                        resourceArn=self.cluster_arn,
+                        secretArn=self.secret_arn,
+                        transactionId=transaction_id,
+                    )
+                except Exception:  # noqa: BLE001 — rollback is best-effort
+                    pass
+            raise
 
-def psql_output(database_url, sql):
-    return output(["psql", database_url, "-tAc", sql])
+    def _execute_one(self, statement, transaction_id, index, label, redact):
+        if len(statement.encode("utf-8")) > RDS_DATA_API_MAX_SQL_BYTES:
+            self._execute_oversized(statement, transaction_id, index, label, redact)
+            return
+        try:
+            self.client.execute_statement(
+                **self._params(statement, transaction_id, continue_after_timeout=True)
+            )
+        except Exception as error:  # noqa: BLE001 — every SDK/CLI failure lands here
+            first_line = statement.strip().splitlines()[0][:120]
+            raise DatabaseCommandError(
+                redact(f"statement {index} ({first_line}): {error}"), label
+            ) from None
+
+    def _execute_oversized(self, statement, transaction_id, index, label, redact):
+        """A statement over the Data API's per-call limit (0230_analyst_rls
+        carries an 85 KB DO block) is shipped in pieces into a temp table on
+        the transaction's connection, reassembled and run there with EXECUTE,
+        then the temp table is dropped. Same statement, same transaction."""
+        if transaction_id is None:
+            raise DatabaseCommandError(
+                f"statement {index} exceeds {RDS_DATA_API_MAX_SQL_BYTES} bytes and "
+                "cannot run inside a transaction",
+                label,
+            )
+        tag = "$chunk$"
+        suffix = 0
+        while tag in statement:
+            suffix += 1
+            tag = f"$chunk{suffix}$"
+        table = "pg_temp.runner_oversized_statement"
+        pieces = []
+        current = []
+        size = 0
+        for char in statement:
+            width = len(char.encode("utf-8"))
+            if size + width > RDS_DATA_API_MAX_SQL_BYTES - 4096:
+                pieces.append("".join(current))
+                current, size = [], 0
+            current.append(char)
+            size += width
+        if current:
+            pieces.append("".join(current))
+        steps = [f"CREATE TEMP TABLE {table.split('.')[1]} (n integer PRIMARY KEY, chunk text)"]
+        steps.extend(
+            f"INSERT INTO {table} (n, chunk) VALUES ({number}, {tag}{piece}{tag})"
+            for number, piece in enumerate(pieces)
+        )
+        steps.append(
+            "DO $runner$ BEGIN EXECUTE (SELECT string_agg(chunk, '' ORDER BY n) "
+            f"FROM {table}); END $runner$"
+        )
+        steps.append(f"DROP TABLE {table}")
+        print(
+            f"[psql:{label}] statement {index} is {len(statement.encode('utf-8'))} bytes; "
+            f"shipping it to the server in {len(pieces)} pieces"
+        )
+        for step in steps:
+            try:
+                self.client.execute_statement(
+                    **self._params(step, transaction_id, continue_after_timeout=True)
+                )
+            except Exception as error:  # noqa: BLE001 — every SDK/CLI failure lands here
+                first_line = statement.strip().splitlines()[0][:120]
+                raise DatabaseCommandError(
+                    redact(f"statement {index} ({first_line}): {error}"), label
+                ) from None
 
 
 def put_secret_value(secret_id, payload):
@@ -2957,31 +5071,6 @@ def pg_literal(value):
     return "'" + value.replace("'", "''") + "'"
 
 
-def ensure_hindsight_database(database_url, vars_json):
-    """THINK-220: the dedicated Hindsight database is bootstrap SQL — Terraform
-    cannot CREATE DATABASE inside the cluster. Runs post-apply; the Hindsight
-    service may crash-loop briefly on a first enablement until this creates
-    the database, then ECS stabilizes on its own. Vanilla boot migrations
-    (RUN_MIGRATIONS_ON_STARTUP) build the schema, including the maintenance
-    discovery functions the repair migration installs on base-schema runs."""
-    db_name = (vars_json.get("hindsight_database_name") or "").strip()
-    if not db_name:
-        return
-    if not re.fullmatch(r"[a-z][a-z0-9_]*", db_name):
-        raise RuntimeError(f"invalid hindsight_database_name: {db_name!r}")
-    admin_url = re.sub(r"/[^/?]+(\?|$)", r"/postgres\1", database_url, count=1)
-    exists = psql_output(
-        admin_url,
-        f"SELECT 1 FROM pg_database WHERE datname = '{db_name}'",
-    ).strip()
-    if not exists:
-        print(f"[hindsight] creating database {db_name}")
-        psql(admin_url, sql=f'CREATE DATABASE "{db_name}"')
-    hindsight_url = re.sub(r"/[^/?]+(\?|$)", f"/{db_name}\\1", database_url, count=1)
-    psql(hindsight_url, sql="CREATE EXTENSION IF NOT EXISTS vector;")
-    print(f"[hindsight] database {db_name} ready (pgvector ensured)")
-
-
 def push_database_schema(outputs_path, vars_json):
     outputs = json.loads(outputs_path.read_text(encoding="utf-8"))
     checkout_source(
@@ -2990,10 +5079,11 @@ def push_database_schema(outputs_path, vars_json):
         os.environ.get("THINKWORK_RELEASE_VERSION", "main"),
     )
     database_url = database_url_from_outputs(outputs)
-    ensure_hindsight_database(database_url, vars_json)
-    fresh = not psql_output(database_url, "SELECT to_regclass('public.tenants')").strip()
+    fresh = not psql_output(database_url, "SELECT to_regclass('public.tenants')::text").strip()
     ledger_present = bool(
-        psql_output(database_url, "SELECT to_regclass('public.platform_schema_migrations')").strip()
+        psql_output(
+            database_url, "SELECT to_regclass('public.platform_schema_migrations')::text"
+        ).strip()
     )
     if fresh:
         initialize_greenfield_database(database_url, outputs, vars_json)
@@ -3158,11 +5248,7 @@ def write_runner_files(payload, runner_secrets):
         current_outputs=current_outputs,
     )
     prior_phase_output = current_outputs.get("auth_retirement_phase")
-    prior_phase = (
-        prior_phase_output.get("value")
-        if isinstance(prior_phase_output, dict)
-        else None
-    )
+    prior_phase = prior_phase_output.get("value") if isinstance(prior_phase_output, dict) else None
     if prior_phase not in {"coexistence", "cutover", "retired"}:
         # An existing pre-native-auth stack must enter through coexistence.
         # A truly empty state is greenfield and has no WorkOS runtime to keep.
@@ -3217,32 +5303,115 @@ def write_runner_files(payload, runner_secrets):
             "databaseEngine",
             default="aurora-serverless",
         ),
-        "enable_hindsight": safe_get_bool(
-            {},
+        # External S3 KB source R20: customer-owned buckets granted to the
+        # KB service role for s3-connect sources. Per-environment infra
+        # posture — durable home is the runner-secrets document; a payload
+        # list can override per-deploy. Accepts a JSON list or a
+        # comma-separated string (Secrets Manager values often arrive as
+        # strings).
+        "external_kb_source_arns": safe_get_list(
+            runner_secrets,
+            reviewed_payload,
+            "externalKbSourceArns",
+        ),
+        # VPC endpoint diet (cost review 2026-08-28): which AWS services get
+        # a private interface endpoint, and one ENI or one per AZ. The
+        # private subnets are NAT-routed, so this is network posture, not
+        # reachability. Environment-level — durable home is the
+        # runner-secrets document; the payload can override per-deploy.
+        # Absent = the module's legacy full set across every AZ; the literal
+        # "none" = no interface endpoints at all.
+        "vpc_interface_endpoint_services": safe_get_list(
+            runner_secrets,
+            reviewed_payload,
+            "vpcInterfaceEndpointServices",
+        ),
+        "vpc_interface_endpoint_single_az": safe_get_bool(
+            runner_secrets,
+            reviewed_payload,
+            "vpcInterfaceEndpointSingleAz",
+            default=False,
+        ),
+        # AgentCore Harness is an environment-level deployment choice. The
+        # controller carries these reviewed, non-secret values forward so a
+        # release update cannot silently remove the managed runtime plane.
+        # The registry module retains its rollout-era multiplayer-proof input
+        # names for compatibility; all provisioning still happens in the
+        # normal Terraform apply owned by this controller.
+        # THINK-1082: run the deployment runner inside the VPC so the psql
+        # schema step reaches Aurora by security group instead of the
+        # world-open 0.0.0.0/0 -> 5432 rule (turns on the VPC NAT gateway).
+        # Environment-level network posture — durable home is the
+        # runner-secrets document (deploymentRunnerInVpc); the controller
+        # payload can override per-deploy. Ship-inert default.
+        "deployment_runner_in_vpc": safe_get_bool(
+            runner_secrets,
+            reviewed_payload,
+            "deploymentRunnerInVpc",
+            default=False,
+        ),
+        # THINK-1082: every database-connected Lambda (api handlers,
+        # agentcore-admin, Pi, broker) inside the VPC behind the api-lambda
+        # security group, granted 5432 on the DB group — so the world-open
+        # 0.0.0.0/0 -> 5432 rule can close without taking the app down.
+        # Same homes as deploymentRunnerInVpc: runner-secrets document is
+        # durable, payload overrides per-deploy. Ship-inert default.
+        "api_lambdas_in_vpc": safe_get_bool(
+            runner_secrets,
             reviewed_payload,
-            "enableHindsight",
+            "apiLambdasInVpc",
             default=False,
         ),
-        # Analyst data-path Lambda VPC egress (stable NAT EIP for external
-        # database IP allowlists). Per-environment infra posture, so the
-        # durable home is the runner-secrets document; a payload boolean
-        # can override per-deploy.
-        "analyst_lambda_vpc_egress": safe_get_bool(
+        # THINK-1082: database exposure. Defaults reproduce today's posture
+        # (public endpoint + world-open 5432 seeded on a new DB security
+        # group). Closed per stage only after both *InVpc flags are live.
+        # dbPublicIngressCidrs accepts a JSON list or a comma-separated
+        # string; an explicit empty string / [] means "seed no rule".
+        "db_publicly_accessible": safe_get_bool(
+            runner_secrets,
+            reviewed_payload,
+            "dbPubliclyAccessible",
+            default=True,
+        ),
+        "db_public_ingress_cidrs": safe_get_ingress_cidrs(
             runner_secrets,
             reviewed_payload,
-            "analystLambdaVpcEgress",
+            "dbPublicIngressCidrs",
+            default=["0.0.0.0/0"],
+        ),
+        # THINK-1082: how this runner reaches the database for its schema
+        # steps — `psql` (public endpoint, today) or `data-api` (RDS Data API:
+        # HTTPS + IAM, no network path, so the runner can stay outside the
+        # VPC while the public 5432 rule closes). Runner-only: it never
+        # reaches the generated Terraform root (see RUNNER_ONLY_VARS).
+        "db_access": safe_get_db_access(runner_secrets, reviewed_payload),
+        "enable_agentcore_multiplayer_proof": safe_get_bool(
+            {},
+            reviewed_payload,
+            "enableAgentCoreHarness",
             default=False,
         ),
-        # THINK-220: dedicated Hindsight database on the stage cluster.
-        # Empty keeps the legacy hindsight-schema layout; set (e.g.
-        # "thinkwork_hindsight") points the Hindsight service and platform
-        # readers at that database's public schema, where upstream's
-        # maintenance discovery actually runs.
-        "hindsight_database_name": safe_get(
+        "agentcore_multiplayer_proof_tenant_slug": safe_get(
+            reviewed_payload,
+            "agentCoreHarnessTenantSlug",
+            default="",
+        ),
+        "agentcore_multiplayer_proof_owner_allowlist": safe_get(
             reviewed_payload,
-            "hindsightDatabaseName",
+            "agentCoreHarnessOwnerAllowlist",
             default="",
         ),
+        # THINK-585/587 — stage kill-switch for AgentCore Runtime chat
+        # dispatch. Environment posture: durable home is the runner-secrets
+        # document (agentcoreRuntimeDispatchEnabled); a reviewed payload can
+        # override per-deploy. Dark by default — flipping a customer stage is
+        # an explicit operator action.
+        "agentcore_runtime_dispatch_enabled": safe_get_bool(
+            runner_secrets,
+            reviewed_payload,
+            "agentcoreRuntimeDispatchEnabled",
+            default=False,
+        ),
         "platform_operator_emails": safe_get(
             runner_secrets,
             "adminEmail",
@@ -3358,6 +5527,20 @@ def write_runner_files(payload, runner_secrets):
             "customerDomainLegacyRetired",
             default=False,
         ),
+        # Extra web-family OAuth callback/logout origins (e.g. the customer's
+        # Company Brain console CloudFront domain, hosted in their own account).
+        # Persisted in runner-secrets so they survive every controller apply
+        # instead of being stripped back to the computed defaults.
+        "additional_admin_callback_urls": runner_secret_string_list(
+            runner_secrets,
+            reviewed_payload,
+            "adminCallbackUrls",
+        ),
+        "additional_admin_logout_urls": runner_secret_string_list(
+            runner_secrets,
+            reviewed_payload,
+            "adminLogoutUrls",
+        ),
         "lambda_artifact_bucket": os.environ["THINKWORK_RELEASE_ARTIFACT_BUCKET"],
         "lambda_artifact_prefix": f"releases/{release_version}/lambdas",
         "deployment_release_version": release_version,
@@ -3374,6 +5557,75 @@ def write_runner_files(payload, runner_secrets):
         "deployment_terraform_module_source": terraform_module_source,
         "deployment_terraform_module_version": terraform_module_version,
         "agentcore_pi_source_image_uri": resolve_agentcore_pi_source_image_uri(payload),
+        # Account-level Lambda memory ceiling. Legacy AWS accounts cap
+        # function memory at 3008 MB (raised only via support case); set the
+        # runner-secrets key lambdaMaxMemoryMb on such accounts so handlers
+        # that request more are clamped instead of failing mid-apply.
+        "lambda_max_memory_mb": safe_get(
+            runner_secrets,
+            "lambdaMaxMemoryMb",
+            default=safe_get(reviewed_payload, "lambdaMaxMemoryMb", default=10240),
+        ),
+        # Digital Twin Neptune wiring (THINK-334): values come from the
+        # etl-platform neptune stack outputs, written into the runner-secrets
+        # document by `thinkwork twin install`. Empty = twin disabled.
+        "neptune_endpoint": safe_get(
+            runner_secrets,
+            "neptuneEndpoint",
+            default=safe_get(reviewed_payload, "neptuneEndpoint", default=""),
+        ),
+        "neptune_cluster_resource_id": safe_get(
+            runner_secrets,
+            "neptuneClusterResourceId",
+            default=safe_get(reviewed_payload, "neptuneClusterResourceId", default=""),
+        ),
+        "neptune_client_security_group_id": safe_get(
+            runner_secrets,
+            "neptuneClientSecurityGroupId",
+            default=safe_get(reviewed_payload, "neptuneClientSecurityGroupId", default=""),
+        ),
+        "neptune_load_bucket": safe_get(
+            runner_secrets,
+            "neptuneLoadBucket",
+            default=safe_get(reviewed_payload, "neptuneLoadBucket", default=""),
+        ),
+        "neptune_loader_role_arn": safe_get(
+            runner_secrets,
+            "neptuneLoaderRoleArn",
+            default=safe_get(reviewed_payload, "neptuneLoaderRoleArn", default=""),
+        ),
+        # Platform Brain MCP endpoint (consolidation U14). Without this
+        # mapping, customer stages never set BRAIN_MCP_URL and twin-connector
+        # provisioning falls back to the retired product /mcp/twin route.
+        "brain_mcp_url": safe_get(
+            runner_secrets,
+            "brainMcpUrl",
+            default=safe_get(reviewed_payload, "brainMcpUrl", default=""),
+        ),
+        # Company Brain platform-agent machine lane (THINK-628/THINK-710).
+        # Secrets Manager ARN of etl-platform/brain-mcp/m2m/platform-agent in
+        # this account; grants the shared API Lambda role read so MCP config
+        # build can mint Cognito bearers for the Brain connector. Environment
+        # posture: durable home is the runner-secrets document. Empty leaves
+        # the tkt_ lane untouched.
+        "brain_m2m_platform_agent_secret_arn": safe_get(
+            runner_secrets,
+            "brainM2mPlatformAgentSecretArn",
+            default=safe_get(reviewed_payload, "brainM2mPlatformAgentSecretArn", default=""),
+        ),
+        # Brain ops-api flag intake (THINK-781): base URL + agent-identity
+        # m2m secret ARN for flagThreadToBrain's POST /flags. Empty leaves
+        # the Send-to-the-Brain action reporting "not configured".
+        "brain_ops_api_url": safe_get(
+            runner_secrets,
+            "brainOpsApiUrl",
+            default=safe_get(reviewed_payload, "brainOpsApiUrl", default=""),
+        ),
+        "brain_ops_m2m_secret_arn": safe_get(
+            runner_secrets,
+            "brainOpsM2mSecretArn",
+            default=safe_get(reviewed_payload, "brainOpsM2mSecretArn", default=""),
+        ),
     }
     enforce_customer_domain_preservation(
         current_outputs,
@@ -3384,6 +5636,7 @@ def write_runner_files(payload, runner_secrets):
     vars_json.update(
         managed_app_terraform_overrides(payload, stage, account_id, current_outputs, current_state)
     )
+    incident_import_blocks = tei_v380_recovery_import_blocks(payload, vars_json)
 
     TF.mkdir(parents=True, exist_ok=True)
     (TF / "backend.hcl").write_text(
@@ -3400,13 +5653,20 @@ def write_runner_files(payload, runner_secrets):
         encoding="utf-8",
     )
     (TF / "terraform.auto.tfvars.json").write_text(
-        json.dumps(vars_json, indent=2, sort_keys=True),
+        json.dumps(
+            {key: value for key, value in vars_json.items() if key not in RUNNER_ONLY_VARS},
+            indent=2,
+            sort_keys=True,
+        ),
         encoding="utf-8",
     )
     (TF / "main.tf").write_text(
         f"""
 terraform {{
-  required_version = ">= 1.5"
+  # The managed deployment runtime is pinned to this floor. Terraform 1.8.5
+  # adds declarative state-only removal, used below to forget the original
+  # non-owning AgentCore reconciliation marker without a destroy action.
+  required_version = ">= 1.8.5"
 
   backend "s3" {{}}
 
@@ -3440,6 +5700,21 @@ provider "aws" {{
 # even though they do not change those records.
 provider "cloudflare" {{}}
 
+# The original AgentCore Twenty reconciliation marker never owned external
+# cleanup, but an interrupted local-exec may have left it tainted. Forget every
+# counted instance from managed-deployment state without refresh, provider RPC,
+# or destroy provisioners. The child module owns the replacement idempotent
+# reconciliation marker under a new address.
+removed {{
+  from = module.thinkwork.module.agentcore_proof_identity.terraform_data.twenty_identity_lifecycle
+
+  lifecycle {{
+    destroy = false
+  }}
+}}
+
+{incident_import_blocks}
+
 variable "stage" {{
   type = string
 }}
@@ -3476,20 +5751,91 @@ variable "database_engine" {{
   type = string
 }}
 
-variable "enable_hindsight" {{
-  type = bool
+variable "external_kb_source_arns" {{
+  type    = list(string)
+  default = []
+}}
+
+variable "vpc_interface_endpoint_services" {{
+  type    = list(string)
+  default = []
+}}
+
+variable "vpc_interface_endpoint_single_az" {{
+  type    = bool
+  default = false
+}}
+
+variable "lambda_max_memory_mb" {{
+  type    = number
+  default = 10240
+}}
+
+variable "neptune_endpoint" {{
+  type    = string
+  default = ""
+}}
+
+variable "neptune_cluster_resource_id" {{
+  type    = string
+  default = ""
+}}
+
+variable "neptune_client_security_group_id" {{
+  type    = string
+  default = ""
+}}
+
+variable "neptune_load_bucket" {{
+  type    = string
+  default = ""
+}}
+
+variable "neptune_loader_role_arn" {{
+  type    = string
+  default = ""
+}}
+
+variable "brain_mcp_url" {{
+  type    = string
+  default = ""
+}}
+
+variable "brain_m2m_platform_agent_secret_arn" {{
+  type    = string
+  default = ""
+}}
+
+variable "brain_ops_api_url" {{
+  type    = string
+  default = ""
+}}
+
+variable "brain_ops_m2m_secret_arn" {{
+  type    = string
+  default = ""
 }}
 
-variable "analyst_lambda_vpc_egress" {{
+variable "enable_agentcore_multiplayer_proof" {{
   type    = bool
   default = false
 }}
 
-variable "hindsight_database_name" {{
+variable "agentcore_multiplayer_proof_tenant_slug" {{
+  type    = string
+  default = ""
+}}
+
+variable "agentcore_multiplayer_proof_owner_allowlist" {{
   type    = string
   default = ""
 }}
 
+variable "agentcore_runtime_dispatch_enabled" {{
+  type    = bool
+  default = false
+}}
+
 variable "platform_operator_emails" {{
   type = string
 }}
@@ -3526,6 +5872,16 @@ variable "customer_domain_legacy_retired" {{
   type = bool
 }}
 
+variable "additional_admin_callback_urls" {{
+  type    = list(string)
+  default = []
+}}
+
+variable "additional_admin_logout_urls" {{
+  type    = list(string)
+  default = []
+}}
+
 variable "google_oauth_client_id" {{
   type = string
 }}
@@ -3624,6 +5980,26 @@ variable "enable_deployment_control_plane" {{
   type = bool
 }}
 
+variable "deployment_runner_in_vpc" {{
+  type    = bool
+  default = false
+}}
+
+variable "api_lambdas_in_vpc" {{
+  type    = bool
+  default = false
+}}
+
+variable "db_publicly_accessible" {{
+  type    = bool
+  default = true
+}}
+
+variable "db_public_ingress_cidrs" {{
+  type    = list(string)
+  default = ["0.0.0.0/0"]
+}}
+
 variable "twenty_provisioned" {{
   type = bool
 }}
@@ -3907,15 +6283,36 @@ module "thinkwork" {{
   customer_domain_delegated      = var.customer_domain_delegated
   customer_domain_legacy_retired = var.customer_domain_legacy_retired
 
+  additional_admin_callback_urls = var.additional_admin_callback_urls
+  additional_admin_logout_urls   = var.additional_admin_logout_urls
+
   lambda_artifact_bucket   = var.lambda_artifact_bucket
   lambda_artifact_prefix   = var.lambda_artifact_prefix
   require_lambda_artifacts = true
   agentcore_pi_source_image_uri = var.agentcore_pi_source_image_uri
 
-  enable_hindsight               = var.enable_hindsight
-  analyst_lambda_vpc_egress      = var.analyst_lambda_vpc_egress
-  hindsight_database_name        = var.hindsight_database_name
+  external_kb_source_arns        = var.external_kb_source_arns
+  vpc_interface_endpoint_services = (
+    length(var.vpc_interface_endpoint_services) == 0
+    ? null
+    : (contains(var.vpc_interface_endpoint_services, "none") ? [] : var.vpc_interface_endpoint_services)
+  )
+  vpc_interface_endpoint_single_az = var.vpc_interface_endpoint_single_az
+  lambda_max_memory_mb             = var.lambda_max_memory_mb
+  neptune_endpoint                 = var.neptune_endpoint
+  neptune_cluster_resource_id      = var.neptune_cluster_resource_id
+  neptune_client_security_group_id = var.neptune_client_security_group_id
+  neptune_load_bucket              = var.neptune_load_bucket
+  neptune_loader_role_arn          = var.neptune_loader_role_arn
+  brain_mcp_url                    = var.brain_mcp_url
+  brain_m2m_platform_agent_secret_arn = var.brain_m2m_platform_agent_secret_arn
+  brain_ops_api_url                = var.brain_ops_api_url
+  brain_ops_m2m_secret_arn         = var.brain_ops_m2m_secret_arn
   enable_workspace_orchestration = true
+  enable_agentcore_multiplayer_proof          = var.enable_agentcore_multiplayer_proof
+  agentcore_multiplayer_proof_tenant_slug     = var.agentcore_multiplayer_proof_tenant_slug
+  agentcore_multiplayer_proof_owner_allowlist = var.agentcore_multiplayer_proof_owner_allowlist
+  agentcore_runtime_dispatch_enabled          = var.agentcore_runtime_dispatch_enabled
 
   twenty_provisioned     = var.twenty_provisioned
   twenty_runtime_enabled = var.twenty_runtime_enabled
@@ -3965,6 +6362,10 @@ module "thinkwork" {{
   enable_slack_workspace_app = false
 
   enable_deployment_control_plane    = var.enable_deployment_control_plane
+  deployment_runner_in_vpc           = var.deployment_runner_in_vpc
+  api_lambdas_in_vpc                 = var.api_lambdas_in_vpc
+  db_publicly_accessible             = var.db_publicly_accessible
+  db_public_ingress_cidrs            = var.db_public_ingress_cidrs
   deployment_control_plane_create_secret_placeholders = var.deployment_control_plane_create_secret_placeholders
   deployment_state_machine_arn        = var.deployment_state_machine_arn
   deployment_evidence_bucket          = var.deployment_evidence_bucket
@@ -3999,6 +6400,7 @@ output "appsync_realtime_url" {{ value = module.thinkwork.appsync_realtime_url }
 output "auth_domain" {{ value = module.thinkwork.auth_domain }}
 output "customer_domain" {{ value = module.thinkwork.customer_domain }}
 output "customer_domain_name_servers" {{ value = module.thinkwork.customer_domain_name_servers }}
+output "db_cluster_arn" {{ value = module.thinkwork.db_cluster_arn }}
 output "db_cluster_endpoint" {{ value = module.thinkwork.db_cluster_endpoint }}
 output "db_secret_arn" {{ value = module.thinkwork.db_secret_arn }}
 output "database_name" {{ value = module.thinkwork.database_name }}
@@ -4007,9 +6409,6 @@ output "admin_client_id" {{ value = module.thinkwork.admin_client_id }}
 output "web_local_client_id" {{ value = module.thinkwork.web_local_client_id }}
 output "auth_route_clients" {{ value = module.thinkwork.auth_route_clients }}
 output "auth_retirement_phase" {{ value = module.thinkwork.auth_retirement_phase }}
-  output "docs_bucket_name" {{ value = module.thinkwork.docs_bucket_name }}
-  output "docs_distribution_id" {{ value = module.thinkwork.docs_distribution_id }}
-  output "docs_distribution_domain" {{ value = module.thinkwork.docs_distribution_domain }}
 output "twenty_provisioned" {{ value = module.thinkwork.twenty_provisioned }}
 output "twenty_runtime_enabled" {{ value = module.thinkwork.twenty_runtime_enabled }}
 output "twenty_url" {{ value = module.thinkwork.twenty_url }}
@@ -4050,7 +6449,7 @@ output "deployment_appconfig_configuration_profile_id" {{ value = module.thinkwo
 
 def sync_release_artifacts(artifact_types=None, artifact_names=None):
     global RELEASE_EVIDENCE
-    artifact_types = set(artifact_types or {"lambda", "static-site"})
+    artifact_types = {"lambda", "static-site"} if artifact_types is None else set(artifact_types)
     artifact_names = set(artifact_names or [])
     manifest_url = os.environ.get("THINKWORK_RELEASE_MANIFEST_URL")
     expected = os.environ.get("THINKWORK_RELEASE_MANIFEST_SHA256", "").lower()
@@ -4221,6 +6620,69 @@ def write_current_outputs_from_state(stage, outputs_path):
     return outputs
 
 
+def ensure_native_auth_custom_attributes(current_outputs):
+    """Add the native Entra claims to an existing pool before app clients use them."""
+    user_pool_id = str(_current_output_value(current_outputs, "user_pool_id") or "").strip()
+    if not user_pool_id:
+        return {"status": "skipped", "reason": "user-pool-not-created"}
+
+    def describe_attribute_names():
+        raw = output(
+            [
+                "aws",
+                "cognito-idp",
+                "describe-user-pool",
+                "--user-pool-id",
+                user_pool_id,
+                "--output",
+                "json",
+            ]
+        )
+        described = json.loads(raw or "{}")
+        attributes = described.get("UserPool", {}).get("SchemaAttributes", [])
+        return {
+            str(attribute.get("Name") or "")
+            for attribute in attributes
+            if isinstance(attribute, dict)
+        }
+
+    existing_names = describe_attribute_names()
+    missing = [
+        attribute
+        for attribute in NATIVE_AUTH_CUSTOM_ATTRIBUTES
+        if f"custom:{attribute['Name']}" not in existing_names
+    ]
+    if not missing:
+        return {"status": "current", "userPoolId": user_pool_id, "added": []}
+
+    request = {"UserPoolId": user_pool_id, "CustomAttributes": missing}
+    run(
+        [
+            "aws",
+            "cognito-idp",
+            "add-custom-attributes",
+            "--cli-input-json",
+            json.dumps(request, separators=(",", ":"), sort_keys=True),
+        ],
+        stdout=subprocess.DEVNULL,
+    )
+    reconciled_names = describe_attribute_names()
+    unresolved = [
+        attribute["Name"]
+        for attribute in missing
+        if f"custom:{attribute['Name']}" not in reconciled_names
+    ]
+    if unresolved:
+        raise RuntimeError(
+            "Cognito native-auth custom attributes were not added: " + ", ".join(unresolved)
+        )
+    return {
+        "status": "reconciled",
+        "userPoolId": user_pool_id,
+        "added": [attribute["Name"] for attribute in missing],
+    }
+
+
 def write_outputs_to_ssm(outputs_path, vars_json):
     outputs = json.loads(outputs_path.read_text(encoding="utf-8"))
     profile, web_env = runtime_profile(outputs, vars_json)
@@ -4676,9 +7138,13 @@ def native_auth_reconciliation_payload(outputs, vars_json, previous_state=None):
         )
     if provider_client_ids.get("MicrosoftOrganizations"):
         microsoft_tenant = str(vars_json.get("microsoft_oauth_tenant") or "").lower()
-        if not microsoft_tenant:
+        if microsoft_tenant not in {"common", "organizations", "consumers"} and not re.fullmatch(
+            r"[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}",
+            microsoft_tenant,
+        ):
             raise RuntimeError(
-                "Microsoft native auth reconciliation requires microsoft_oauth_tenant"
+                "Microsoft native auth reconciliation requires microsoft_oauth_tenant to be"
+                " an Entra directory GUID or one of: common, organizations, consumers"
             )
         connections.append(
             {
@@ -5124,7 +7590,6 @@ def sync_static(outputs_path, static_files, vars_json, artifact_names=None):
     artifact_names = set(artifact_names or [])
     syncs = [
         ("web", "app_bucket_name", "app_distribution_id"),
-        ("docs", "docs_bucket_name", "docs_distribution_id"),
     ]
     for artifact_name, bucket_output, distribution_output in syncs:
         if artifact_names and artifact_name not in artifact_names:
@@ -5254,7 +7719,7 @@ def write_deployment_status_pointer(status, vars_json=None, terraform_exit_code=
     action = os.environ.get("THINKWORK_DEPLOYMENT_ACTION")
     if os.environ.get("THINKWORK_MANAGED_APP_OPERATION") == "true":
         return
-    if not bucket or action not in {"deploy", "update", "web"}:
+    if not bucket or action not in {"deploy", "update", "apply", "web"}:
         return
     vars_json = vars_json or {}
     previous = read_current_status_pointer(bucket)
@@ -5394,7 +7859,16 @@ def main():
     action = os.environ.get("THINKWORK_DEPLOYMENT_ACTION") or payload.get("action") or "deploy"
     if action == "teardown":
         action = "destroy"
-    if action not in {"deploy", "update", "destroy", "plan", "status", "web"}:
+    if action not in {
+        "deploy",
+        "update",
+        "destroy",
+        "plan",
+        "apply",
+        "recover",
+        "status",
+        "web",
+    }:
         raise RuntimeError(f"Unsupported deployment action: {action}")
     os.environ["THINKWORK_DEPLOYMENT_ACTION"] = action
     configure_managed_app_evidence_prefix(payload)
@@ -5414,21 +7888,45 @@ def main():
         )
         return 0
 
+    if action == "recover":
+        CONTROLLER_EVIDENCE = {
+            "incidentRecovery": recover_tei_v380_incident(payload),
+        }
+        write_evidence(
+            "succeeded",
+            {
+                "stage": "tei-e2e",
+                "account_id": "637423202447",
+                "region": "us-east-1",
+            },
+            0,
+        )
+        return 0
+
+    terraform_phase = validate_terraform_execution_phase(payload, action)
+    planned_action = requested_plan_action(payload, action)
+    execution_effect_action = planned_action if terraform_phase == "apply" else action
     runner_secrets = secret_payload(payload)
     web_only = is_web_only_operation(payload, action)
     identity_operation = identity_provider_operation(payload)
     static_files = {}
-    if (
-        action in {"deploy", "update", "web"}
-        and not is_managed_app_operation(payload)
-        and identity_operation is None
-    ):
-        static_files = sync_release_artifacts(
-            artifact_types={"static-site"} if web_only else None,
-            artifact_names={"web"} if web_only else None,
-        )
+    release_request = release_sync_request(execution_effect_action, payload, identity_operation)
+    control_runtime_operation = requires_agentcore_control_runtime(
+        execution_effect_action, payload, identity_operation
+    )
+    if release_request is not None:
+        static_files = sync_release_artifacts(**release_request)
+    elif control_runtime_operation:
+        # Plan and destroy still execute AgentCore local-exec wrappers for
+        # existing resources. Download the content-addressed platform bundle
+        # without publishing application artifacts so those paths never depend
+        # on an ambient CodeBuild SDK.
+        sync_release_artifacts(artifact_types=set())
     managed_app_artifacts = stage_managed_app_release_artifacts(action, payload)
     vars_json = write_runner_files(payload, runner_secrets)
+    set_database_access_mode(vars_json)
+    if control_runtime_operation:
+        prepare_agentcore_control_runtime()
     controller_summary = controller_input_summary(payload)
     CONTROLLER_EVIDENCE = {
         "inputSummary": controller_summary,
@@ -5482,44 +7980,56 @@ def main():
         )
         if selected.returncode != 0:
             run(["terraform", "workspace", "new", workspace, "-no-color"], cwd=TF)
+    state_identity = terraform_state_identity()
     target_args = managed_app_terraform_target_args(payload)
-    pre_app_schema = prepare_additive_schema_before_app(payload, vars_json)
-    if pre_app_schema is not None and pre_app_schema.returncode != 0:
-        result = pre_app_schema
-    elif action == "destroy":
-        plan = subprocess.run(
-            ["terraform", "plan", "-destroy", *target_args, "-out=tfplan", "-no-color"],
-            cwd=TF,
-            text=True,
+    pre_app_schema = (
+        prepare_additive_schema_before_app(payload, vars_json)
+        if terraform_phase in {"plan", "legacy"}
+        else None
+    )
+    if terraform_phase == "legacy" and should_reconcile_native_auth_schema(
+        terraform_phase, planned_action, payload
+    ):
+        CONTROLLER_EVIDENCE["cognitoSchema"] = ensure_native_auth_custom_attributes(
+            current_terraform_outputs(vars_json["stage"])
         )
-        if plan.returncode == 0:
-            TERRAFORM_EVIDENCE["plan"] = write_terraform_plan_evidence(payload)
-            result = subprocess.run(
-                ["terraform", "apply", "-auto-approve", "-no-color", "tfplan"],
-                cwd=TF,
-                text=True,
+    applied_plan = None
+    if terraform_phase == "apply":
+        applied_plan = validate_and_materialize_approved_plan(payload, state_identity)
+        planned_action = applied_plan.get("plannedAction")
+        if planned_action not in {"deploy", "update", "destroy"}:
+            raise RuntimeError("Approved plan has an invalid plannedAction")
+        TERRAFORM_EVIDENCE["approvedPlan"] = applied_plan
+        if should_reconcile_native_auth_schema(terraform_phase, planned_action, payload):
+            CONTROLLER_EVIDENCE["cognitoSchema"] = ensure_native_auth_custom_attributes(
+                current_terraform_outputs(vars_json["stage"])
             )
-        else:
-            result = plan
-    else:
-        plan = subprocess.run(
-            ["terraform", "plan", *target_args, "-out=tfplan", "-no-color"],
+        result = subprocess.run(
+            ["terraform", "apply", "-no-color", "tfplan"],
             cwd=TF,
             text=True,
         )
-        if plan.returncode == 0:
-            TERRAFORM_EVIDENCE["plan"] = write_terraform_plan_evidence(payload)
-        if action == "plan" or plan.returncode != 0:
-            result = plan
-        else:
-            result = subprocess.run(
-                ["terraform", "apply", "-auto-approve", "-no-color", "tfplan"],
-                cwd=TF,
-                text=True,
-            )
+    elif pre_app_schema is not None and pre_app_schema.returncode != 0:
+        result = pre_app_schema
+    else:
+        result = execute_terraform_plan_phase(
+            payload,
+            state_identity,
+            planned_action,
+            terraform_phase,
+            target_args,
+        )
 
     outputs_path = TF / "outputs.json"
-    if result.returncode == 0 and action in {"deploy", "update"}:
+    if (
+        result.returncode == 0
+        and terraform_phase in {"apply", "legacy"}
+        and planned_action
+        in {
+            "deploy",
+            "update",
+        }
+    ):
         if identity_operation is not None:
             finalized = finalize_disabled_identity_provider(payload, vars_json)
             if finalized is not None:
@@ -5558,6 +8068,13 @@ def main():
                     selected_controller_release,
                 )
             sync_static(outputs_path, static_files, vars_json)
+            if control_runtime_operation:
+                pi_runtime_evidence = reconcile_agentcore_pi_runtime(vars_json, payload)
+                if pi_runtime_evidence is not None:
+                    CONTROLLER_EVIDENCE["agentcorePiRuntime"] = write_json_evidence_artifact(
+                        "agentcore-pi-runtime.json",
+                        pi_runtime_evidence,
+                    )
             try:
                 self_update_runner_script()
             except Exception as self_update_error: