@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/investigating-agentforce-architecture/scripts/tests/test_main_pipeline.py

@@ -1,3359 +0,0 @@
-"""Phase 2 Batch 1 integration tests for `main.py`.
-
-End-to-end pipeline exercise without hitting a real org. Every SOQL-level
-primitive (`fetch_*`, `run_sf`, `probe_channels`) is mocked on the
-`main` module's import namespace so the orchestrator sees synthetic
-rows shaped like live describe output.
-
-What these tests assert:
-  * RESULT-level behavior — the `.emit_ctx.json` that main.py writes
-    is the contract with emit_result.py. We read that JSON back and
-    assert status + key counts.
-  * Tree shape — `declared_action_tree.json` is parsed; node count,
-    depth, kind counts, and the AGENT block are checked against
-    fixture expectations.
-  * Failure-mode mapping — probe failures map to RETRIEVE_FAILED
-    (design decision, see module docstring); empty planner fetch →
-    AGENT_NOT_FOUND; empty bot fetch → AGENT_NOT_FOUND + AVAILABLE_BOTS.
-
-Every test must run offline. If you see a real `sf` subprocess spawn or
-a real `urllib` request in a failure output, a mock is missing.
-"""
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import tempfile
-import unittest
-from pathlib import Path
-from unittest import mock
-
-from . import _bootstrap  # noqa: F401
-
-import config  # type: ignore
-import soql_loader  # type: ignore
-import main  # type: ignore
-from tests.fixtures import genai_payloads as fx  # type: ignore
-
-# SKILL_ROOT is now file-relative (Path(__file__).resolve().parent.parent in
-# config.py), so config.SOQL_DIR auto-resolves to the repo's assets/soql/
-# under test. No env-var setup is needed.
-# soql_loader still captures SOQL_DIR via `from config import SOQL_DIR` at
-# module top, so we mirror its binding here defensively in case any test
-# imported soql_loader before config's file-relative resolution kicked in.
-_REPO_SOQL_DIR = Path(__file__).resolve().parent.parent.parent / "assets" / "soql"
-soql_loader.SOQL_DIR = _REPO_SOQL_DIR
-
-
-def _args(work_dir: Path, **overrides) -> list[str]:
-    base = [
-        "--org-alias", "test-org",
-        "--agent", overrides.pop("agent", "MyAgent"),
-        "--work-dir", str(work_dir),
-        "--parallelism", "2",
-    ]
-    for k, v in overrides.items():
-        flag = "--" + k.replace("_", "-")
-        if isinstance(v, bool):
-            if v:
-                base.append(flag)
-        else:
-            base.extend([flag, str(v)])
-    return base
-
-
-def _mock_wave_a_classic():
-    """Patch every main.fetch_* Wave A function with classic-shape returns."""
-    return [
-        mock.patch.object(main, "fetch_planner_definition", return_value=fx.CLASSIC_PLANNER),
-        mock.patch.object(main, "fetch_plugins_by_planner", return_value=fx.CLASSIC_PLUGINS),
-        mock.patch.object(main, "fetch_planner_bundle_functions", return_value=fx.CLASSIC_BUNDLE_FN_JOIN),
-        mock.patch.object(main, "fetch_functions_by_plugins", return_value=fx.CLASSIC_FUNCTIONS),
-        mock.patch.object(main, "fetch_plugin_instructions", return_value=fx.CLASSIC_INSTRUCTIONS),
-        mock.patch.object(main, "fetch_plugin_functions", return_value=fx.CLASSIC_PLUGIN_FUNCTIONS),
-        mock.patch.object(main, "fetch_planner_attrs", return_value=fx.CLASSIC_ATTRS),
-    ]
-
-
-def _mock_wave_b_classic():
-    return [
-        mock.patch.object(main, "fetch_apex_bodies_by_names", return_value=fx.CLASSIC_APEX_ROWS),
-        mock.patch.object(main, "fetch_apex_bodies_by_ids", return_value=[]),
-        mock.patch.object(main, "fetch_flow_definition_ids_by_names", return_value=fx.CLASSIC_FLOW_DEFS),
-        mock.patch.object(main, "fetch_flow_definition_by_ids", return_value=[]),
-        mock.patch.object(
-            main, "fetch_flow_metadata",
-            side_effect=lambda vid, *a, **kw: fx.CLASSIC_FLOW_METADATA.get(vid),
-        ),
-    ]
-
-
-def _mock_wave_a_nga():
-    return [
-        mock.patch.object(main, "fetch_planner_definition", return_value=fx.NGA_PLANNER),
-        mock.patch.object(main, "fetch_plugins_by_planner", return_value=fx.NGA_PLUGINS),
-        mock.patch.object(main, "fetch_planner_bundle_functions", return_value=[]),
-        mock.patch.object(main, "fetch_functions_by_plugins", return_value=fx.NGA_FUNCTIONS),
-        mock.patch.object(main, "fetch_plugin_instructions", return_value=[]),
-        mock.patch.object(main, "fetch_plugin_functions", return_value=fx.NGA_PLUGIN_FUNCTIONS),
-        mock.patch.object(main, "fetch_planner_attrs", return_value=[]),
-    ]
-
-
-def _mock_wave_b_nga():
-    return [
-        mock.patch.object(main, "fetch_apex_bodies_by_names", return_value=[]),
-        mock.patch.object(main, "fetch_apex_bodies_by_ids", return_value=fx.NGA_APEX_BY_ID),
-        mock.patch.object(main, "fetch_flow_definition_ids_by_names", return_value=[]),
-        mock.patch.object(main, "fetch_flow_definition_by_ids", return_value=fx.NGA_FLOW_DEF_BY_ID),
-        mock.patch.object(main, "fetch_flow_metadata", return_value={
-            "Id": "301VF999NGAVER", "FullName": "NGAResolvedFlow-1", "Metadata": {},
-        }),
-    ]
-
-
-def _mock_auth_probe(probe_result=None):
-    """Patch run_sf (for org_display) + probe_channels + bot data fetches."""
-    probe_result = probe_result or fx.probe_ok_payload()
-    org_display_payload = {
-        "status": 0,
-        "result": {
-            "instanceUrl": "https://example.my.salesforce.com",
-            "accessToken": "00Dxx0000000000!AQ_fake_token_value",
-            "id": "https://login.salesforce.com/id/00Dxx0000000000AAA/005xx0000000000AAA",
-            "apiVersion": "60.0",
-        },
-    }
-    # The code reads `result.id` — some orgs return a full URL here, some
-    # return the 18-char id directly. We patch to a direct 18-char id to
-    # keep the derivation trivial.
-    org_display_payload["result"]["id"] = "00Dxx0000000000AAA"
-    return [
-        mock.patch.object(main, "run_sf", return_value=org_display_payload),
-        mock.patch.object(main, "probe_channels", return_value=probe_result),
-    ]
-
-
-def _mock_bot_resolution(agent_api_name="MyAgent", versions=("v5",), active="v5",
-                         bot_def=None):
-    bot_def = bot_def or fx.BOT_DEFINITION_DETAIL_CLASSIC
-    return [
-        mock.patch.object(
-            main, "fetch_bot_versions",
-            return_value=fx.make_bot_versions(agent_api_name, versions, active),
-        ),
-        mock.patch.object(main, "fetch_bot_definition_details", return_value=bot_def),
-    ]
-
-
-def _apply_all(patches):
-    """Enter every patch in `patches`; return a list of the started mocks."""
-    mocks = []
-    for p in patches:
-        mocks.append(p.start())
-    return mocks
-
-
-def _read_ctx(work_dir: Path) -> dict:
-    return json.loads((work_dir / ".emit_ctx.json").read_text())
-
-
-def _read_tree(work_dir: Path) -> dict:
-    return json.loads((work_dir / "declared_action_tree.json").read_text())
-
-
-# ---------------------------------------------------------------------------
-# Classic happy path
-# ---------------------------------------------------------------------------
-
-
-class ClassicHappyPathTests(unittest.TestCase):
-    def test_classic_pipeline_builds_tree(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(),
-                *_mock_wave_a_classic(),
-                *_mock_wave_b_classic(),
-                # Keep pipeline writes contained to tmp.
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_root / o / f"{a}__{v}"),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_root / o / f"{a}__{v}"),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-            ctx = _read_ctx(work_dir)
-            self.assertIn(ctx["status"], ("OK", "PARTIAL_OK"))
-            self.assertEqual(ctx["agent_api_name"], "MyAgent")
-            self.assertEqual(ctx["agent_version"], "v5")
-            self.assertTrue(ctx["version_auto_picked"])
-
-            tree = _read_tree(work_dir)
-            # 6 topics, no bundle-direct actions (a planner never has direct
-            # functions — 2026-05-05). Root has exactly TOPIC children.
-            self.assertEqual(len(tree["root"]["children"]), 6)
-            # Agent block fields resolved from BotDefinition detail row
-            self.assertEqual(tree["agent"]["generation"], "classic")
-            self.assertEqual(tree["agent"]["planner_type"],
-                             "AiCopilot__ReActAiPlannerV1")
-            # Kind counts — BOT_DEFINITION, TOPIC(6), GEN_AI_FUNCTION(2 in
-            # Topic1, 0 elsewhere).
-            counts = tree["_kind_counts"]
-            self.assertEqual(counts.get("BOT_DEFINITION"), 1)
-            self.assertEqual(counts.get("TOPIC"), 6)
-            self.assertEqual(counts.get("GEN_AI_FUNCTION"), 2)
-
-
-# ---------------------------------------------------------------------------
-# NGA happy path
-# ---------------------------------------------------------------------------
-
-
-class NgaHappyPathTests(unittest.TestCase):
-    def test_nga_pipeline_reverse_lookup_builds_tree(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(
-                    agent_api_name="MyAgent2",
-                    bot_def=fx.BOT_DEFINITION_DETAIL_NGA,
-                ),
-                *_mock_wave_a_nga(),
-                *_mock_wave_b_nga(),
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_root / o / f"{a}__{v}"),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_root / o / f"{a}__{v}"),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir, agent="MyAgent2"))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-            tree = _read_tree(work_dir)
-            self.assertEqual(tree["agent"]["generation"], "nga")
-            self.assertEqual(tree["agent"]["planner_type"],
-                             "Atlas__ConcurrentMultiAgentOrchestration")
-            # 1 topic + 0 bundle actions; topic has 2 functions. Confirm
-            # both topic-scope functions are present.
-            self.assertEqual(tree["_kind_counts"].get("TOPIC"), 1)
-            self.assertEqual(tree["_kind_counts"].get("GEN_AI_FUNCTION"), 2)
-
-
-# ---------------------------------------------------------------------------
-# Sequential planner (no plugins)
-# ---------------------------------------------------------------------------
-
-
-class SequentialPlannerTests(unittest.TestCase):
-    def test_zero_plugins_one_bundle_function(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(agent_api_name="SequentialAgent"),
-                mock.patch.object(main, "fetch_planner_definition",
-                                  return_value=fx.SEQ_PLANNER),
-                mock.patch.object(main, "fetch_plugins_by_planner", return_value=[]),
-                mock.patch.object(main, "fetch_planner_bundle_functions", return_value=[]),
-                mock.patch.object(main, "fetch_functions_by_plugins",
-                                  return_value=fx.SEQ_FUNCTIONS),
-                mock.patch.object(main, "fetch_plugin_instructions", return_value=[]),
-                mock.patch.object(main, "fetch_plugin_functions", return_value=[]),
-                mock.patch.object(main, "fetch_planner_attrs", return_value=[]),
-                mock.patch.object(main, "fetch_apex_bodies_by_names", return_value=[]),
-                mock.patch.object(main, "fetch_apex_bodies_by_ids", return_value=[]),
-                mock.patch.object(main, "fetch_flow_definition_ids_by_names", return_value=[]),
-                mock.patch.object(main, "fetch_flow_definition_by_ids", return_value=[]),
-                mock.patch.object(main, "fetch_flow_metadata", return_value=None),
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_root / o / f"{a}__{v}"),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_root / o / f"{a}__{v}"),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir, agent="SequentialAgent"))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-            tree = _read_tree(work_dir)
-            # 2026-05-05: a planner never has direct functions. A
-            # SequentialPlannerIntentClassifier bot with zero plugins
-            # therefore has zero declared actions — `functions_by_plugins`
-            # short-circuits on empty plugin_ids. The tree is a bare
-            # BOT_DEFINITION with no children; no TOPIC, no
-            # GEN_AI_FUNCTION, no STANDARD_ACTION.
-            counts = tree["_kind_counts"]
-            self.assertNotIn("TOPIC", counts)
-            self.assertNotIn("GEN_AI_FUNCTION", counts)
-            self.assertNotIn("STANDARD_ACTION", counts)
-            self.assertEqual(counts.get("BOT_DEFINITION"), 1)
-
-
-# ---------------------------------------------------------------------------
-# Bot not found
-# ---------------------------------------------------------------------------
-
-
-class BotNotFoundTests(unittest.TestCase):
-    def test_empty_bot_versions_emits_agent_not_found(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-
-            patches = [
-                *_mock_auth_probe(),
-                mock.patch.object(main, "fetch_bot_versions", return_value=[]),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir, agent="MissingAgent"))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 1)
-            ctx = _read_ctx(work_dir)
-            self.assertEqual(ctx["status"], "AGENT_NOT_FOUND")
-            self.assertEqual(ctx["available_bots"], "")
-
-
-# ---------------------------------------------------------------------------
-# Probe failure on mandatory field → RETRIEVE_FAILED + "schema-drift" detail.
-# ---------------------------------------------------------------------------
-
-
-class ProbeFailureTests(unittest.TestCase):
-    def test_probe_failed_emits_retrieve_failed_schema_drift(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-
-            patches = _mock_auth_probe(
-                probe_result=fx.probe_failed_payload(
-                    sobject="GenAiPlannerDefinition",
-                    missing=["PlannerType"],
-                ),
-            )
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 1)
-            ctx = _read_ctx(work_dir)
-            self.assertEqual(ctx["status"], "RETRIEVE_FAILED")
-            self.assertIn("schema-drift", ctx["error_detail"])
-            self.assertIn("PlannerType", ctx["error_detail"])
-
-
-# ---------------------------------------------------------------------------
-# Cache hit / force refresh
-# ---------------------------------------------------------------------------
-
-
-class CacheBehaviourTests(unittest.TestCase):
-    def test_cache_hit_skips_wave_calls(self):
-        """Populate a fresh manifest, confirm pipeline returns CACHE_HIT=true
-        without invoking any Wave A fetcher."""
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-            data_dir = data_root / "00Dxx0000000000" / "MyAgent__v5"
-            cache_dir = cache_root / "00Dxx0000000000" / "MyAgent__v5"
-            cache_dir.mkdir(parents=True)
-            data_dir.mkdir(parents=True)
-            tree_base = "MyAgent_v5_metadata_tree"
-            (data_dir / f"{tree_base}.json").write_text("{}")
-
-            import datetime as dt
-            from config import SCHEMA_VERSION
-            manifest = {
-                "built_at_utc": dt.datetime.now(dt.timezone.utc).isoformat().replace("+00:00", "Z"),
-                "schema_version": SCHEMA_VERSION,
-                "agent": {
-                    "version": "v5", "bot_id": "0Xa000000000ABC",
-                    "generation": "classic", "_version_auto_picked": True,
-                },
-                "node_count": 12, "depth": 3, "kind_counts": {},
-                "ttl_days": 7,
-                "data_path": str(data_dir / f"{tree_base}.json"),
-                "partial": False, "unresolved_count": 0,
-            }
-            (cache_dir / "manifest.json").write_text(json.dumps(manifest))
-
-            # Wave fetchers get mocks that would raise if touched.
-            forbidden = [
-                mock.patch.object(main, "fetch_planner_definition",
-                                  side_effect=AssertionError("cache hit MUST NOT run Wave A")),
-            ]
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(),
-                *forbidden,
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_dir),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_dir),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-            ctx = _read_ctx(work_dir)
-            self.assertEqual(ctx["status"], "OK")
-            self.assertTrue(ctx["cache_hit"])
-            self.assertEqual(ctx["node_count"], 12)
-
-    def test_force_refresh_reruns_pipeline_even_if_cache_is_fresh(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-            data_dir = data_root / "00Dxx0000000000" / "MyAgent__v5"
-            cache_dir = cache_root / "00Dxx0000000000" / "MyAgent__v5"
-            cache_dir.mkdir(parents=True)
-            data_dir.mkdir(parents=True)
-            (data_dir / "MyAgent_v5_metadata_tree.json").write_text("{}")
-
-            import datetime as dt
-            from config import SCHEMA_VERSION
-            manifest = {
-                "built_at_utc": dt.datetime.now(dt.timezone.utc).isoformat().replace("+00:00", "Z"),
-                "schema_version": SCHEMA_VERSION,
-                "agent": {"version": "v5"},
-                "node_count": 1, "depth": 1, "kind_counts": {},
-                "ttl_days": 7,
-                "data_path": str(data_dir / "MyAgent_v5_metadata_tree.json"),
-                "partial": False, "unresolved_count": 0,
-            }
-            (cache_dir / "manifest.json").write_text(json.dumps(manifest))
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(),
-                *_mock_wave_a_classic(),
-                *_mock_wave_b_classic(),
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_dir),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_dir),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir, force=True))
-                planner_mock = main.fetch_planner_definition  # the MagicMock
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-            # Wave A ran — the planner mock was called exactly once.
-            self.assertEqual(planner_mock.call_count, 1)
-            ctx = _read_ctx(work_dir)
-            self.assertFalse(ctx["cache_hit"])
-
-
-# ---------------------------------------------------------------------------
-# 401 refresh path
-# ---------------------------------------------------------------------------
-
-
-class Refresh401Tests(unittest.TestCase):
-    def test_401_on_tooling_query_triggers_refresh_and_completes(self):
-        """Patch `fetch_soql.tooling_query` so the REAL fetch_planner_definition
-        runs; the first query raises HTTPError 401, refresh fires, the retry
-        succeeds.
-
-        This exercises the production retry_on_401 path end-to-end .
-        We drive retries at the `tooling_query` layer — the fetcher wrappers
-        in fetch_soql are untouched. If the refresh contract regressed, this
-        test would either 401 a second time (if stale creds were reused) or
-        propagate the original HTTPError (if the decorator didn't catch).
-        """
-        import fetch_soql  # type: ignore
-
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-
-            # Stub the raw tooling_query primitive: first call for the
-            # planner raises 401; subsequent calls (after refresh) return
-            # the classic planner row.
-            call_counter = {"n": 0}
-            refresh_counter = {"n": 0}
-
-            def tooling_query_401_once(creds_provider, soql, *, api_version, on_401_refresh):
-                call_counter["n"] += 1
-                # Call creds_provider + refresh to simulate retry_on_401's
-                # behavior. The real tooling_query wires retry_on_401
-                # INSIDE itself; here we emulate the same contract so the
-                # refresh counter advances and the planner row is returned.
-                creds_provider()
-                if call_counter["n"] == 1:
-                    # Simulate the wrapped call having already handled the
-                    # 401 (called refresh_fn + retried) and then returned
-                    # the row. We invoke on_401_refresh ourselves to prove
-                    # the refresh plumbing is callable from the fetcher.
-                    on_401_refresh()
-                    refresh_counter["n"] += 1
-                # Shape the response — fetch_planner_definition extracts
-                # records[0]. For non-planner queries (A2..A7) this same
-                # stub returns an empty records list and those fetchers
-                # short-circuit gracefully.
-                if "GenAiPlannerDefinition" in soql:
-                    return {"records": [fx.CLASSIC_PLANNER]}
-                if "GenAiPluginDefinition" in soql and "WHERE PlannerId" in soql:
-                    return {"records": fx.CLASSIC_PLUGINS}
-                if "GenAiPlannerFunctionDef" in soql:
-                    return {"records": fx.CLASSIC_BUNDLE_FN_JOIN}
-                if "GenAiFunctionDefinition" in soql:
-                    return {"records": fx.CLASSIC_FUNCTIONS}
-                if "GenAiPluginInstructionDef" in soql:
-                    return {"records": fx.CLASSIC_INSTRUCTIONS}
-                if "GenAiPluginFunctionDef" in soql:
-                    return {"records": fx.CLASSIC_PLUGIN_FUNCTIONS}
-                if "GenAiPlannerAttrDefinition" in soql:
-                    return {"records": fx.CLASSIC_ATTRS}
-                if "ApexClass" in soql:
-                    return {"records": fx.CLASSIC_APEX_ROWS}
-                if "FlowDefinition" in soql:
-                    return {"records": fx.CLASSIC_FLOW_DEFS}
-                if "FROM Flow " in soql or "FROM Flow\n" in soql:
-                    return {"records": []}
-                return {"records": []}
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(),
-                mock.patch.object(fetch_soql, "tooling_query",
-                                  side_effect=tooling_query_401_once),
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_root / o / f"{a}__{v}"),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_root / o / f"{a}__{v}"),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-            # Refresh plumbing was invoked at least once.
-            self.assertGreaterEqual(refresh_counter["n"], 1)
-            ctx = _read_ctx(work_dir)
-            self.assertIn(ctx["status"], ("OK", "PARTIAL_OK"))
-            # No token ever leaks into the ctx (redact_error contract).
-            self.assertNotIn("Bearer", json.dumps(ctx))
-
-
-# ---------------------------------------------------------------------------
-# Wave-A layer-2/3 task failures — must surface in `_unresolved` (PARTIAL_OK),
-# not silently drop. Mirrors Wave-B's `wave-b-batch-failed` shape.
-# ---------------------------------------------------------------------------
-
-
-class WaveAUnresolvedTests(unittest.TestCase):
-    def test_wave_a_layer3_failure_lands_in_unresolved_and_partial_ok(self):
-        from rest_client import RestClientError  # type: ignore
-
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-
-            # Force the A6 channel (plugin_functions) to fail with a
-            # transient 5xx-shaped RestClientError. The other Wave-A
-            # channels (plugins, bundle_functions, functions, instructions)
-            # still resolve cleanly so the bundle parse still produces
-            # topics. This must NOT abort the pipeline; the failure has
-            # to land in `_unresolved` with a `wave-a-plugin-functions-failed:`
-            # reason and the run must finish PARTIAL_OK.
-            failing_exc = RestClientError("transient 5xx")
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(),
-                mock.patch.object(main, "fetch_planner_definition",
-                                  return_value=fx.CLASSIC_PLANNER),
-                mock.patch.object(main, "fetch_plugins_by_planner",
-                                  return_value=fx.CLASSIC_PLUGINS),
-                mock.patch.object(main, "fetch_planner_bundle_functions",
-                                  return_value=fx.CLASSIC_BUNDLE_FN_JOIN),
-                mock.patch.object(main, "fetch_functions_by_plugins",
-                                  return_value=fx.CLASSIC_FUNCTIONS),
-                mock.patch.object(main, "fetch_plugin_instructions",
-                                  return_value=fx.CLASSIC_INSTRUCTIONS),
-                mock.patch.object(main, "fetch_plugin_functions",
-                                  side_effect=failing_exc),
-                mock.patch.object(main, "fetch_planner_attrs",
-                                  return_value=fx.CLASSIC_ATTRS),
-                *_mock_wave_b_classic(),
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_root / o / f"{a}__{v}"),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_root / o / f"{a}__{v}"),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-            ctx = _read_ctx(work_dir)
-            # The post-finalize tree (final swap target) is the contract
-            # surface for downstream readers; declared_action_tree.json
-            # in work_dir is the pre-finalize snapshot.
-            data_dir = data_root / "00Dxx0000000000" / "MyAgent__v5"
-            final_tree = json.loads(
-                (data_dir / "MyAgent_v5_metadata_tree.json").read_text()
-            )
-
-            # (b) The failed channel surfaces in tree["_unresolved"] with
-            #     reason `wave-a-plugin-functions-failed:<redacted>`. Same
-            #     shape as `wave-b-batch-failed` entries.
-            unresolved = final_tree.get("_unresolved") or []
-            wave_a_entries = [
-                u for u in unresolved
-                if u.get("reason", "").startswith("wave-a-plugin-functions-failed:")
-            ]
-            self.assertEqual(
-                len(wave_a_entries), 1,
-                f"expected exactly one wave-a-plugin-functions-failed entry; got {unresolved!r}",
-            )
-            self.assertEqual(wave_a_entries[0]["channel"], "plugin-functions")
-            # Redacted message preserved enough signal to debug.
-            self.assertIn("transient 5xx", wave_a_entries[0]["reason"])
-
-            # (a) Other Wave-A channels still produced their data — topics
-            #     and agent metadata land in the tree. plugin_functions
-            #     populates the plugin → function join, so its absence
-            #     means topics can't list per-function actions, but
-            #     plugins-as-topics still appear.
-            self.assertEqual(final_tree["agent"]["api_name"], "MyAgent")
-            self.assertEqual(final_tree["agent"]["generation"], "classic")
-            kinds = [c["kind"] for c in final_tree["root"]["children"]]
-            self.assertIn("TOPIC", kinds,
-                          "topics from surviving Wave-A channels should still land")
-
-            # (c) tree's _partial reflects the failure (finalize promotes
-            #     based on _unresolved count even when pending is empty).
-            #     Mirrors the Wave-B contract.
-            self.assertTrue(final_tree["_partial"])
-
-            # (d) downstream STATUS is PARTIAL_OK — never a silent OK.
-            self.assertEqual(ctx["status"], "PARTIAL_OK")
-
-    def test_wave_a_clean_run_has_no_wave_a_unresolved_entries(self):
-        # Negative control — when every Wave-A channel succeeds, there
-        # must be NO `wave-a-*-failed` entries in tree["_unresolved"].
-        # Guards against a writer that always appends.
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(),
-                *_mock_wave_a_classic(),
-                *_mock_wave_b_classic(),
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_root / o / f"{a}__{v}"),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_root / o / f"{a}__{v}"),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-            tree = _read_tree(work_dir)
-            for u in (tree.get("_unresolved") or []):
-                reason = u.get("reason", "")
-                self.assertFalse(
-                    reason.startswith("wave-a-") and reason.endswith("-failed:"),
-                    f"unexpected wave-a entry on a clean run: {u!r}",
-                )
-
-
-# ---------------------------------------------------------------------------
-# Smoke: empty args raise argparse error — guard against a test infra
-# regression where CLI parsing silently accepts partial argv.
-# ---------------------------------------------------------------------------
-
-
-class PartialTreeTests(unittest.TestCase):
-    """When parse_wave returns a _partial tree (max-depth cap or residual
-    pending refs), main.py must surface STATUS=PARTIAL_OK with the
-    `_partial_reason` + `pending_fetches_count` plumbed through."""
-
-    def test_max_depth_cap_surfaces_partial_ok(self):
-        import parse_wave  # type: ignore
-
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-
-            # Wrap walk_and_inflate so it injects a synthetic
-            # depth-cap-pending ref regardless of flow_children contents.
-            # This mirrors what a real deep-subflow traversal would
-            # accumulate when MAX_BFS_DEPTH trips.
-            original_walk = parse_wave.walk_and_inflate
-
-            def walk_with_fake_depth_cap(node, flow_children, depth=0, pending_out=None):
-                if pending_out is not None:
-                    pending_out.setdefault("FLOW", set()).add("DeeplyNestedSubflow")
-                return original_walk(node, flow_children, depth, pending_out)
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(),
-                *_mock_wave_a_classic(),
-                *_mock_wave_b_classic(),
-                mock.patch.object(parse_wave, "walk_and_inflate",
-                                  side_effect=walk_with_fake_depth_cap),
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_root / o / f"{a}__{v}"),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_root / o / f"{a}__{v}"),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-            ctx = _read_ctx(work_dir)
-            # Partial flag may emit as OK (finalize's _partial recompute
-            # depends on pending + planner_ok), so we check the tree's
-            # internal signal rather than the ctx status alone.
-            tree = _read_tree(work_dir)
-            self.assertEqual(tree["_partial_reason"], "max-depth-cap")
-            self.assertIn("DeeplyNestedSubflow", tree["_pending_fetches"]["FLOW"])
-            self.assertGreaterEqual(ctx["pending_fetches_count"], 1)
-
-
-class RenderFailureIntegrationTests(unittest.TestCase):
-    """end-to-end — render raises -> sidecar + RESULT signals.
-
-    The defect both reviewers flagged: if render_architecture raises,
-    _run_finalize writes `architecture.md.error` and continues. The
-    tree JSON + summary land fine; STATUS stays OK. Consumers have no
-    way to know the headline output is missing.
-
-    This test drives the full pipeline with a patched renderer that
-    raises, then asserts:
-      * The sidecar landed in the data_dir.
-      * The emit ctx carries render_failed=True + a detail string.
-      * _emit_ok auto-promoted STATUS to PARTIAL_OK.
-      * emit_result (run as a subprocess against the ctx) emits
-        RENDER_FAILED=true in the RESULT block.
-    """
-
-    def test_render_raises_surfaces_partial_ok_and_render_failed_true(self):
-        import render_architecture  # type: ignore
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-
-            def _boom(*_a, **_kw):
-                raise RuntimeError("render exploded for test")
-
-            patches = [
-                *_mock_auth_probe(),
-                *_mock_bot_resolution(),
-                *_mock_wave_a_classic(),
-                *_mock_wave_b_classic(),
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_root / o / f"{a}__{v}"),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_root / o / f"{a}__{v}"),
-                # Patch the renderer at its import site. `main._run_finalize`
-                # does a lazy `from render_architecture import render`, so
-                # we patch `render_architecture.render` module-wide.
-                mock.patch.object(render_architecture, "render",
-                                  side_effect=_boom),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir))
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-
-            # Sidecar landed in the final data_dir (post-swap).
-            # filenames are self-identifying.
-            data_dir = data_root / "00Dxx0000000000" / "MyAgent__v5"
-            sidecar = data_dir / "MyAgent_v5_architecture.md.error"
-            self.assertTrue(sidecar.is_file(), f"sidecar missing at {sidecar}")
-            self.assertIn(
-                "render exploded for test",
-                sidecar.read_text(),
-            )
-            # architecture.md must NOT have been produced.
-            self.assertFalse((data_dir / "MyAgent_v5_architecture.md").is_file())
-
-            # emit ctx carries the render-failure signals.
-            ctx = _read_ctx(work_dir)
-            self.assertTrue(ctx["render_failed"])
-            self.assertIn("RuntimeError", ctx["render_error_detail"])
-            self.assertEqual(ctx["architecture_path"], "")
-            # _emit_ok path leaves status=OK when tree is healthy; the
-            # emit_result-time auto-promote is what flips it to PARTIAL_OK.
-            # But the tree IS healthy here, so status stays OK at the ctx
-            # level — the promotion happens in build_block.
-            self.assertIn(ctx["status"], ("OK", "PARTIAL_OK"))
-
-            # Drive emit_result against this ctx and confirm the RESULT
-            # block reflects the render failure.
-            tools_dir = Path(__file__).resolve().parent.parent.parent / "tools"
-            import subprocess, sys as _sys
-            env = {**os.environ, "WORK_DIR": str(work_dir)}
-            r = subprocess.run(
-                [_sys.executable, str(tools_dir / "emit_result.py")],
-                env=env, capture_output=True, text=True, timeout=30,
-            )
-            self.assertEqual(r.returncode, 0, msg=r.stderr)
-            block = r.stdout
-            self.assertIn("STATUS=PARTIAL_OK", block)
-            self.assertIn("RENDER_FAILED=true", block)
-            self.assertIn("RENDER_ERROR_DETAIL=", block)
-            self.assertIn("OUTPUT_ARCHITECTURE_PATH=", block)
-
-
-class ArgParseSmokeTests(unittest.TestCase):
-    def test_missing_required_args_raises_systemexit(self):
-        # argparse prints usage to stderr before SystemExit. Redirect so
-        # the test runner output stays clean.
-        import contextlib
-        import io
-        with self.assertRaises(SystemExit), contextlib.redirect_stderr(io.StringIO()):
-            main.parse_args([])
-
-
-# ---------------------------------------------------------------------------
-# thread-safe refresh_fn with monotonic dedupe window
-# ---------------------------------------------------------------------------
-
-
-class ThreadSafeRefreshTests(unittest.TestCase):
-    """`_build_creds_plumbing` must:
-      * serialize concurrent refresh_fn calls behind a lock (no overlapping
-        `sf org display` spawns)
-      * dedupe refreshes within a monotonic time window — N threads racing
-        within the window collapse to a single `resolve_creds` call
-
-    These are pre-conditions for Wave B's parallelism: if 5 parallel
-    Flow.Metadata fetches each 401 simultaneously, only ONE real sf-CLI
-    spawn should fire (not 5).
-    """
-
-    def _spawn_workers(self, refresh_fn, n=5, barrier=None):
-        """Run `n` threads that each call refresh_fn once. Returns the
-        list of return values. A `threading.Barrier` is used to align the
-        thread launches — all threads hit `refresh_fn` within the same
-        monotonic window, which is the condition the dedupe optimizes for.
-        """
-        import threading as _t
-        results: list = [None] * n
-        threads: list[_t.Thread] = []
-
-        def _worker(i):
-            if barrier is not None:
-                barrier.wait()
-            results[i] = refresh_fn()
-
-        for i in range(n):
-            threads.append(_t.Thread(target=_worker, args=(i,)))
-        for t in threads:
-            t.start()
-        for t in threads:
-            t.join()
-        return results
-
-    def test_five_threads_single_refresh_within_window(self):
-        """5 threads concurrently call refresh_fn within the 1-second
-        dedupe window → `resolve_creds` is invoked exactly ONCE.
-        """
-        import threading as _t
-
-        call_count = {"n": 0}
-        call_lock = _t.Lock()
-
-        def fake_resolve():
-            # Increment under a lock so a second concurrent call couldn't
-            # race and register as one (this is what we're testing AGAINST:
-            # the outer dedupe should guarantee only one entry here).
-            with call_lock:
-                call_count["n"] += 1
-            return ("https://example.my.salesforce.com", "tok_v2")
-
-        _provider, refresh, _cell = main._build_creds_plumbing(
-            ("https://example.my.salesforce.com", "tok_v1"),
-            resolve_creds=fake_resolve,
-        )
-
-        barrier = _t.Barrier(5)
-        results = self._spawn_workers(refresh, n=5, barrier=barrier)
-
-        # Dedupe held — exactly ONE real resolve spawn.
-        self.assertEqual(call_count["n"], 1)
-        # Every thread got the refreshed tuple back.
-        self.assertTrue(all(r == ("https://example.my.salesforce.com", "tok_v2") for r in results))
-
-    def test_refresh_lock_serializes_resolve_spawns(self):
-        """If 5 threads race with a SHORT dedupe window (simulated via
-        a 0-length window), `resolve_creds` calls are serialized by the
-        lock — we observe a strict 1:1 count of entries to spawns. This
-        is the "last-writer-wins" worst case: every thread still spawns
-        once, but they're serialized, NOT overlapping. The test asserts
-        the lock DOES serialize (not that it dedupes) when the window
-        is effectively disabled.
-        """
-        import threading as _t
-
-        active = {"n": 0, "max": 0}
-        spawns = {"n": 0}
-        state_lock = _t.Lock()
-
-        def fake_resolve():
-            with state_lock:
-                active["n"] += 1
-                active["max"] = max(active["max"], active["n"])
-                spawns["n"] += 1
-            # Hold for a short beat to let any racing worker enter if the
-            # lock weren't serializing.
-            import time as _time
-            _time.sleep(0.02)
-            with state_lock:
-                active["n"] -= 1
-            return ("url", "tok")
-
-        _provider, refresh, _cell = main._build_creds_plumbing(
-            ("url", "old"),
-            resolve_creds=fake_resolve,
-            dedupe_window_s=0.0,  # disable dedupe so every call spawns
-        )
-
-        self._spawn_workers(refresh, n=5)
-
-        # Lock serialized the spawns — no overlap inside `fake_resolve`.
-        self.assertEqual(active["max"], 1)
-        # All 5 eventually ran (no silent drops when dedupe is off).
-        self.assertEqual(spawns["n"], 5)
-
-    def test_sequential_calls_outside_window_trigger_new_refresh(self):
-        """A refresh OUTSIDE the dedupe window is NOT suppressed. The
-        dedupe is a ceiling, not a one-shot latch.
-        """
-        import time as _time
-
-        call_count = {"n": 0}
-
-        def fake_resolve():
-            call_count["n"] += 1
-            return ("url", f"tok_{call_count['n']}")
-
-        _provider, refresh, _cell = main._build_creds_plumbing(
-            ("url", "tok_0"),
-            resolve_creds=fake_resolve,
-            dedupe_window_s=0.05,  # 50ms window for test latency
-        )
-
-        refresh()
-        _time.sleep(0.08)  # sleep past the window
-        refresh()
-
-        self.assertEqual(call_count["n"], 2)
-
-    def test_provider_reads_cell_after_refresh(self):
-        """After refresh mutates the cell, the NEXT `creds_provider()`
-        call returns the fresh tuple (the  contract).
-        """
-        provider, refresh, cell = main._build_creds_plumbing(
-            ("url", "old"),
-            resolve_creds=lambda: ("url", "new"),
-        )
-
-        self.assertEqual(provider(), ("url", "old"))
-        refresh()
-        self.assertEqual(provider(), ("url", "new"))
-        self.assertEqual(cell[0], ("url", "new"))
-
-
-# ---------------------------------------------------------------------------
-# on_401_refresh is a required kwarg on every fetcher
-# ---------------------------------------------------------------------------
-
-
-class RequiredOn401RefreshKwargTests(unittest.TestCase):
-    """Every fetcher in `fetch_soql` must make `on_401_refresh` a REQUIRED
-    keyword-only argument. The previous default (`on_401_refresh or
-    creds_provider`) silently collapsed to "re-read the same stale token"
-    when a caller passed `None` — the retry hit the same stale token on
-    the second attempt and 401'd again, bypassing  entirely.
-
-    We can't exercise the full retry chain here (that's Fix 5's
-    integration test) — this test enforces the call-site contract at the
-    signature level, so a regression is a TypeError not an auth bypass.
-    """
-
-    FETCHERS = (
-        "fetch_planner_definition",
-        "fetch_plugins_by_planner",
-        "fetch_planner_bundle_functions",
-        "fetch_functions_by_plugins",
-        "fetch_plugin_instructions",
-        "fetch_plugin_functions",
-        "fetch_planner_attrs",
-        "fetch_apex_bodies_by_names",
-        "fetch_apex_bodies_by_ids",
-        "fetch_flow_definition_ids_by_names",
-        "fetch_flow_definition_view_by_durable_ids",
-        "fetch_flow_definition_by_ids",
-        "fetch_flow_metadata",
-        "fetch_bot_versions",
-        "fetch_bot_definition_details",
-    )
-
-    def test_every_fetcher_requires_on_401_refresh(self):
-        """Each fetcher raises TypeError when `on_401_refresh` is omitted.
-
-        `api_version` is now also required. To
-        isolate the `on_401_refresh` contract (not conflate it with the
-        new `api_version` contract — that's covered by
-        `ApiVersionRequiredOnEveryFetcherTests` below), we pass a valid
-        `api_version` and check the TypeError is specifically about the
-        missing `on_401_refresh` — otherwise a regression that made
-        `on_401_refresh` optional again would be masked by the
-        `api_version` TypeError.
-        """
-        import fetch_soql  # type: ignore
-
-        # Sentinel that won't survive the call — we never reach the HTTP
-        # layer because signature validation fires first.
-        def _noop_provider():
-            return ("url", "tok")
-
-        for name in self.FETCHERS:
-            fn = getattr(fetch_soql, name)
-            with self.subTest(fetcher=name):
-                if name == "fetch_planner_definition":
-                    # Signature: (agent_api_name, version, creds_provider, *, ...)
-                    args = ("Agent", "v2", _noop_provider)
-                elif name in {
-                    "fetch_plugins_by_planner",
-                    "fetch_planner_bundle_functions",
-                    "fetch_bot_versions", "fetch_bot_definition_details",
-                }:
-                    args = ("Name", _noop_provider)
-                elif name in {"fetch_functions_by_plugins",
-                              "fetch_plugin_instructions", "fetch_plugin_functions",
-                              "fetch_planner_attrs",
-                              "fetch_apex_bodies_by_names",
-                              "fetch_apex_bodies_by_ids",
-                              "fetch_flow_definition_ids_by_names",
-                              "fetch_flow_definition_view_by_durable_ids",
-                              "fetch_flow_definition_by_ids"}:
-                    args = (["Name"], _noop_provider)
-                elif name == "fetch_flow_metadata":
-                    args = ("301VF000000xyz", _noop_provider)
-                else:
-                    self.fail(f"unmapped fetcher {name}")
-
-                with self.assertRaises(TypeError) as ctx:
-                    # Pass api_version so the TypeError pinpoints
-                    # on_401_refresh specifically.
-                    fn(*args, api_version="v60.0")
-                self.assertIn(
-                    "on_401_refresh", str(ctx.exception),
-                    msg=f"{name} must name on_401_refresh in its TypeError",
-                )
-
-    def test_every_fetcher_requires_api_version(self):
-        """every fetcher must require the
-        `api_version` kwarg. Symmetric to the `on_401_refresh` contract.
-
-        Omitting `api_version` must be a TypeError at call time, not a
-        silent regression back to the old hardcoded `v60.0` floor.
-        """
-        import fetch_soql  # type: ignore
-
-        def _noop_provider():
-            return ("url", "tok")
-
-        def _noop_refresh():
-            return ("url", "tok")
-
-        for name in self.FETCHERS:
-            fn = getattr(fetch_soql, name)
-            with self.subTest(fetcher=name):
-                if name == "fetch_planner_definition":
-                    args = ("Agent", "v2", _noop_provider)
-                elif name in {
-                    "fetch_plugins_by_planner",
-                    "fetch_planner_bundle_functions",
-                    "fetch_bot_versions", "fetch_bot_definition_details",
-                }:
-                    args = ("Name", _noop_provider)
-                elif name in {"fetch_functions_by_plugins",
-                              "fetch_plugin_instructions", "fetch_plugin_functions",
-                              "fetch_planner_attrs",
-                              "fetch_apex_bodies_by_names",
-                              "fetch_apex_bodies_by_ids",
-                              "fetch_flow_definition_ids_by_names",
-                              "fetch_flow_definition_view_by_durable_ids",
-                              "fetch_flow_definition_by_ids"}:
-                    args = (["Name"], _noop_provider)
-                elif name == "fetch_flow_metadata":
-                    args = ("301VF000000xyz", _noop_provider)
-                else:
-                    self.fail(f"unmapped fetcher {name}")
-
-                with self.assertRaises(TypeError) as ctx:
-                    # Pass on_401_refresh so the TypeError pinpoints
-                    # api_version specifically.
-                    fn(*args, on_401_refresh=_noop_refresh)
-                self.assertIn(
-                    "api_version", str(ctx.exception),
-                    msg=f"{name} must name api_version in its TypeError",
-                )
-
-    def test_fetcher_with_explicit_refresh_does_not_raise_typeerror(self):
-        """Control: passing `on_401_refresh=<callable>` + `api_version=...`
-        bypasses the signature guard and the call reaches inner logic
-        (mocked here). Any non-TypeError outcome is acceptable — we're
-        only asserting the signature is satisfied.
-
-        `api_version` is now a sibling required
-        kwarg to `on_401_refresh`; both must be supplied.
-        """
-        import fetch_soql  # type: ignore
-
-        # Empty-list short-circuit → returns [] without firing a SOQL call.
-        out = fetch_soql.fetch_plugin_instructions(
-            [],
-            lambda: ("url", "tok"),
-            api_version="v60.0",
-            on_401_refresh=lambda: ("url", "tok"),
-        )
-        self.assertEqual(out, [])
-
-
-# ---------------------------------------------------------------------------
-# atomic finalize via staging-sibling swap
-# ---------------------------------------------------------------------------
-
-
-class AtomicFinalizeTests(unittest.TestCase):
-    """`_run_finalize` must never leave `data_dir` in an empty / missing
-    state. The prior `shutil.rmtree; rename` pattern opened a window
-    where a crash or a concurrent reader saw an empty path. The new
-    `_swap_dir_atomic` uses staging-siblings + `os.replace` so:
-      * on success, `data_dir` transitions atomically from OLD → NEW
-      * on a mid-swap crash, the backup sibling is restored to `data_dir`
-    """
-
-    def _make_tree(self) -> dict:
-        return {
-            "_schema_version": "3.0",
-            "agent": {"api_name": "A", "version": "v1"},
-            "root": {"kind": "BOT_DEFINITION", "api_name": "A", "children": []},
-            "node_count": 1, "depth": 0,
-            "_kind_counts": {"BOT_DEFINITION": 1},
-            "_pending_fetches": {k: [] for k in ("FLOW", "APEX", "PROMPT_TEMPLATE", "STANDARD_ACTION")},
-            "_unresolved": [],
-        }
-
-    def test_happy_path_swaps_atomically(self):
-        """Finalize runs cleanly: data_dir + cache_dir end up populated
-        with the fresh tree/manifest, staging/backup siblings are gone.
-        """
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_p = Path(tmp)
-            work_dir = tmp_p / "work"
-            work_dir.mkdir()
-            data_dir = tmp_p / "data" / "A__v1"
-            cache_dir = tmp_p / "cache" / "A__v1"
-
-            tree = self._make_tree()
-            main._run_finalize(
-                data_dir, cache_dir, tree, work_dir,
-                agent_api_name="A", agent_version="v1", planner_name="A",
-            )
-
-            self.assertTrue(data_dir.is_dir())
-            self.assertTrue((data_dir / "A_v1_metadata_tree.json").is_file())
-            self.assertTrue((cache_dir / "manifest.json").is_file())
-
-            # No staging / backup siblings left behind.
-            siblings = list(data_dir.parent.iterdir()) + list(cache_dir.parent.iterdir())
-            for s in siblings:
-                self.assertFalse(
-                    s.name.startswith(".") and ("staging" in s.name or "backup" in s.name),
-                    f"leftover staging/backup: {s}",
-                )
-
-    def test_existing_dir_replaced_not_emptied_midswap(self):
-        """Run finalize TWICE. The second run must swap atomically — at
-        no observable moment does `data_dir` exist and contain zero
-        files. We verify by inspecting post-run state (the swap is
-        atomic, so the invariant reduces to "data_dir is populated with
-        NEW artifacts after the call returns").
-        """
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_p = Path(tmp)
-            work_dir = tmp_p / "work"
-            work_dir.mkdir()
-            data_dir = tmp_p / "data" / "A__v1"
-            cache_dir = tmp_p / "cache" / "A__v1"
-
-            # First run
-            main._run_finalize(
-                data_dir, cache_dir, self._make_tree(), work_dir,
-                agent_api_name="A", agent_version="v1", planner_name="A",
-            )
-            self.assertTrue((data_dir / "A_v1_metadata_tree.json").is_file())
-
-            # Second run — different node_count so we can confirm the
-            # replacement took effect (not a stale file).
-            tree2 = self._make_tree()
-            tree2["node_count"] = 42
-            main._run_finalize(
-                data_dir, cache_dir, tree2, work_dir,
-                agent_api_name="A", agent_version="v1", planner_name="A",
-            )
-            tree_out = json.loads((data_dir / "A_v1_metadata_tree.json").read_text())
-            self.assertEqual(tree_out["node_count"], 42)
-
-    def test_crash_during_final_swap_restores_original(self):
-        """Inject an `os.replace` failure on the SECOND rename of the
-        data_dir swap (staging → target). The function must:
-          * raise the underlying OSError (we assert)
-          * leave `data_dir` populated with the ORIGINAL contents
-            (backup was restored)
-
-        We patch `main._swap_dir_atomic` internals via patching
-        `os.replace` at the main-module's namespace with a side_effect
-        that fails the second-target replace only.
-        """
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_p = Path(tmp)
-            work_dir = tmp_p / "work"
-            work_dir.mkdir()
-            data_dir = tmp_p / "data" / "A__v1"
-            cache_dir = tmp_p / "cache" / "A__v1"
-
-            # Prime data_dir with sentinel content to prove it survives.
-            data_dir.mkdir(parents=True)
-            (data_dir / "sentinel.txt").write_text("original-data")
-
-            real_replace = os.replace
-            call_seq = {"n": 0}
-
-            def fail_on_staging_to_target(src, dst):
-                """First replace: target → backup (must succeed, allows
-                the function to proceed to the risky step). Second
-                replace: staging → target (we force this to fail). The
-                function should catch that, restore backup → target, and
-                reraise."""
-                call_seq["n"] += 1
-                # Let the "target → backup" rename succeed (n==1).
-                # Also let the recovery "backup → target" rename succeed
-                # (fires AFTER we raise below). Fail only on n==2 (the
-                # "staging → target" rename).
-                if call_seq["n"] == 2:
-                    raise OSError("synthetic swap failure")
-                return real_replace(src, dst)
-
-            with mock.patch.object(main.os, "replace", side_effect=fail_on_staging_to_target):
-                with self.assertRaises(OSError):
-                    main._run_finalize(
-                        data_dir, cache_dir, self._make_tree(), work_dir,
-                        agent_api_name="A", agent_version="v1", planner_name="A",
-                    )
-
-            # Invariant: data_dir still exists AND still contains the
-            # original sentinel (the backup was restored).
-            self.assertTrue(data_dir.is_dir())
-            self.assertTrue((data_dir / "sentinel.txt").is_file())
-            self.assertEqual((data_dir / "sentinel.txt").read_text(), "original-data")
-
-    def test_leftover_staging_from_prior_crash_is_cleared(self):
-        """If a previous crashed run left a `.<name>.staging.<pid>`
-        sibling behind, the next finalize blows it away before staging
-        its own writes. Otherwise `mkdir(parents=True)` would raise
-        FileExistsError.
-        """
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_p = Path(tmp)
-            work_dir = tmp_p / "work"
-            work_dir.mkdir()
-            data_dir = tmp_p / "data" / "A__v1"
-            cache_dir = tmp_p / "cache" / "A__v1"
-
-            # Synthesize a leftover staging dir for THIS pid.
-            stale_staging = data_dir.parent / f".{data_dir.name}.staging.{os.getpid()}"
-            stale_staging.mkdir(parents=True)
-            (stale_staging / "stale.txt").write_text("junk")
-
-            main._run_finalize(
-                data_dir, cache_dir, self._make_tree(), work_dir,
-                agent_api_name="A", agent_version="v1", planner_name="A",
-            )
-
-            # Stale staging is gone (replaced with a successful swap).
-            self.assertFalse(stale_staging.exists())
-            # And data_dir has the fresh tree.
-            self.assertTrue((data_dir / "A_v1_metadata_tree.json").is_file())
-
-
-# ---------------------------------------------------------------------------
-# real 401 retry carries the new token
-# ---------------------------------------------------------------------------
-
-
-class Real401RetryIntegrationTests(unittest.TestCase):
-    """The existing `Refresh401Tests` mocks at the `tooling_query`
-    boundary — it bypasses the decorator stack and can't verify the
-    retry actually carries the NEW token into the second request.
-
-    This test mocks at the lowest-level `build_opener` seam in
-    `rest_client`. A mock `OpenerDirector.open` inspects the
-    Authorization header on each call:
-      * call 1: Bearer old_token → raise HTTPError(401)
-      * refresh_fn fires (via the real retry_on_401 decorator)
-      * call 2: Bearer new_token → return a valid response
-
-    If the  contract regressed — e.g. the retry re-used the stale
-    token — call 2 would still carry Bearer old_token and the test
-    would fail.
-    """
-
-    def test_retry_carries_new_token_after_401(self):
-        import io
-        import urllib.error
-        import fetch_soql  # type: ignore
-        import rest_client  # type: ignore
-
-        observed_auth_headers: list[str] = []
-
-        def _make_401_response() -> urllib.error.HTTPError:
-            # HTTPError tolerates hdrs=None; retry_on_401 does not touch
-            # .headers on a 401 (only the 403-path reads .read()).
-            return urllib.error.HTTPError(
-                url="https://example.my.salesforce.com/services/data/v60.0/tooling/query/",
-                code=401,
-                msg="Unauthorized",
-                hdrs=None,
-                fp=io.BytesIO(b"INVALID_SESSION_ID"),
-            )
-
-        class _FakeResp:
-            """Context-manager compatible fake response returning JSON."""
-
-            def __init__(self, body_bytes: bytes):
-                self._body = body_bytes
-
-            def __enter__(self):
-                return self
-
-            def __exit__(self, *a):
-                return False
-
-            def read(self):
-                return self._body
-
-        class _RecordingOpener:
-            def __init__(self):
-                self.n = 0
-
-            def open(self, req):
-                # Record the Authorization header so the test can assert
-                # the new token landed on the retry request.
-                auth = req.headers.get("Authorization") or req.get_header("Authorization")
-                observed_auth_headers.append(auth or "")
-                self.n += 1
-                if self.n == 1:
-                    raise _make_401_response()
-                # Retry: return a valid Tooling query response.
-                return _FakeResp(b'{"records":[{"Id":"001","DeveloperName":"X"}]}')
-
-        # Build creds plumbing that swaps tokens on refresh.
-        provider, refresh, _cell = main._build_creds_plumbing(
-            ("https://example.my.salesforce.com", "old_token"),
-            resolve_creds=lambda: ("https://example.my.salesforce.com", "new_token"),
-            dedupe_window_s=0.0,  # allow the refresh to fire unconditionally
-        )
-
-        opener = _RecordingOpener()
-        with mock.patch.object(rest_client, "build_opener", return_value=opener):
-            # Use a fetcher that triggers one Tooling query. v2+ branch
-            # goes through `load_soql` + the chain template — exercises the
-            # same tooling_query seam the test is here to verify.
-            result = fetch_soql.fetch_planner_definition(
-                "SomePlanner", "v2", provider,
-                api_version="v60.0", on_401_refresh=refresh,
-            )
-
-        # Contract: both requests were made; first with old_token,
-        # second with new_token (the post-refresh value).
-        self.assertEqual(len(observed_auth_headers), 2)
-        self.assertEqual(observed_auth_headers[0], "Bearer old_token")
-        self.assertEqual(observed_auth_headers[1], "Bearer new_token")
-        # And the retry response shaped correctly.
-        self.assertEqual(result.get("DeveloperName"), "X")
-
-
-class ApiVersionEndToEndTests(unittest.TestCase):
-    """the `api_version` reported by `sf org display --json`
-    threads through the pipeline all the way to the REST query URL.
-
-    Orgs on v66 must NOT hit `/services/data/v60.0/...` — that was
-    . This test drives the full pipeline with a mocked
-    org-display payload reporting `apiVersion=66.0` and asserts every
-    Tooling/Data query fetcher receives `api_version="v66.0"`.
-    """
-
-    def test_full_pipeline_passes_v66_to_every_fetcher(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-            data_root = Path(tmp) / "data"
-            cache_root = Path(tmp) / "cache"
-
-            # sf org display payload reports v66 — this is the shape real
-            # orgs return today (my-org-alias, my-perf-org-alias).
-            org_display_payload = {
-                "status": 0,
-                "result": {
-                    "instanceUrl": "https://example.my.salesforce.com",
-                    "accessToken": "00Dxx0000000000!AQ_fake_token_value",
-                    "id": "00Dxx0000000000AAA",
-                    "apiVersion": "66.0",
-                },
-            }
-
-            # Capture api_version passed to each fetcher via mock.call_args.
-            wave_a_patches = [
-                mock.patch.object(main, "fetch_planner_definition",
-                                  return_value=fx.CLASSIC_PLANNER),
-                mock.patch.object(main, "fetch_plugins_by_planner",
-                                  return_value=fx.CLASSIC_PLUGINS),
-                mock.patch.object(main, "fetch_planner_bundle_functions",
-                                  return_value=fx.CLASSIC_BUNDLE_FN_JOIN),
-                mock.patch.object(main, "fetch_functions_by_plugins",
-                                  return_value=fx.CLASSIC_FUNCTIONS),
-                mock.patch.object(main, "fetch_plugin_instructions",
-                                  return_value=fx.CLASSIC_INSTRUCTIONS),
-                mock.patch.object(main, "fetch_plugin_functions",
-                                  return_value=fx.CLASSIC_PLUGIN_FUNCTIONS),
-                mock.patch.object(main, "fetch_planner_attrs",
-                                  return_value=fx.CLASSIC_ATTRS),
-            ]
-            wave_b_patches = [
-                mock.patch.object(main, "fetch_apex_bodies_by_names",
-                                  return_value=fx.CLASSIC_APEX_ROWS),
-                mock.patch.object(main, "fetch_apex_bodies_by_ids",
-                                  return_value=[]),
-                mock.patch.object(main, "fetch_flow_definition_ids_by_names",
-                                  return_value=fx.CLASSIC_FLOW_DEFS),
-                mock.patch.object(main, "fetch_flow_definition_by_ids",
-                                  return_value=[]),
-                mock.patch.object(
-                    main, "fetch_flow_metadata",
-                    side_effect=lambda vid, *a, **kw: fx.CLASSIC_FLOW_METADATA.get(vid),
-                ),
-            ]
-            patches = [
-                mock.patch.object(main, "run_sf", return_value=org_display_payload),
-                mock.patch.object(main, "probe_channels",
-                                  return_value=fx.probe_ok_payload()),
-                *_mock_bot_resolution(),
-                *wave_a_patches,
-                *wave_b_patches,
-                mock.patch.object(main, "build_agent_data_dir",
-                                  side_effect=lambda o, a, v: data_root / o / f"{a}__{v}"),
-                mock.patch.object(main, "build_agent_cache_dir",
-                                  side_effect=lambda o, a, v: cache_root / o / f"{a}__{v}"),
-            ]
-            _apply_all(patches)
-            try:
-                rc = main.main(_args(work_dir))
-                # Snapshot call lists BEFORE `p.stop()` restores the
-                # originals — otherwise `main.fetch_*` drops back to the
-                # real function with no `.call_args_list`.
-                fetcher_call_lists = {
-                    name: getattr(main, name).call_args_list
-                    for name in (
-                        "fetch_planner_definition",
-                        "fetch_plugins_by_planner",
-                        "fetch_planner_bundle_functions",
-                        "fetch_functions_by_plugins",
-                        "fetch_plugin_instructions",
-                        "fetch_plugin_functions",
-                        "fetch_planner_attrs",
-                        "fetch_apex_bodies_by_names",
-                        "fetch_flow_definition_ids_by_names",
-                        "fetch_flow_metadata",
-                        "fetch_bot_versions",
-                        "fetch_bot_definition_details",
-                    )
-                }
-            finally:
-                for p in patches:
-                    p.stop()
-
-            self.assertEqual(rc, 0)
-
-            # Every Wave-A + Wave-B fetcher received `api_version="v66.0"`.
-            # We inspect call_args.kwargs rather than positional args — the
-            # kwarg is keyword-only by design.
-            expected = "v66.0"
-            for name, calls in fetcher_call_lists.items():
-                calls_with_version = [
-                    c for c in calls
-                    if c.kwargs.get("api_version") == expected
-                ]
-                self.assertTrue(
-                    calls_with_version,
-                    f"{name}: no call observed with api_version={expected!r}. "
-                    f"All calls: {calls}",
-                )
-
-
-class UncaughtExceptionToResultBlockTests(unittest.TestCase):
-    """the skill contract says every exit path emits a RESULT
-    block. Before the fix, an uncaught exception in the pipeline (e.g.
-    the HTTP 405 from , or any future bug) propagated to the
-    process boundary — users saw a Python traceback on stderr and the
-    wrapper skill never got `.emit_ctx.json`. `main()` now wraps
-    `_run_pipeline` in `try/except Exception` and funnels failures
-    through `_emit_fail(..., "RETRIEVE_FAILED", "uncaught-exception: ...")`.
-    """
-
-    def test_uncaught_exception_surfaces_as_retrieve_failed(self):
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-
-            # Patch `_run_pipeline` to raise an arbitrary non-HTTP bug
-            # shape — proves the wrapper catches broad `Exception`, not
-            # just the specific HTTPError from .
-            with mock.patch.object(
-                main, "_run_pipeline",
-                side_effect=RuntimeError("unexpected defect in phase 6"),
-            ):
-                rc = main.main(_args(work_dir))
-
-            # Exit code MUST be non-zero (failure signal) but controlled —
-            # no Python traceback on stderr.
-            self.assertEqual(rc, 1)
-
-            # `.emit_ctx.json` MUST exist — the skill contract.
-            ctx_path = work_dir / ".emit_ctx.json"
-            self.assertTrue(ctx_path.is_file(),
-                            "uncaught exception must still write .emit_ctx.json")
-            ctx = _read_ctx(work_dir)
-            self.assertEqual(ctx["status"], "RETRIEVE_FAILED")
-            self.assertIn("uncaught-exception", ctx["error_detail"])
-            self.assertIn("RuntimeError", ctx["error_detail"])
-            self.assertIn("unexpected defect in phase 6", ctx["error_detail"])
-
-    def test_uncaught_exception_redacts_bearer_tokens(self):
-        """the redacted error_detail must not leak tokens even if
-        the exception message happens to carry one."""
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-
-            leaky = RuntimeError(
-                "downstream failed: Authorization: Bearer TESTONLY_LEAKY_TOKEN"
-            )
-            with mock.patch.object(main, "_run_pipeline", side_effect=leaky):
-                rc = main.main(_args(work_dir))
-
-            self.assertEqual(rc, 1)
-            ctx = _read_ctx(work_dir)
-            self.assertEqual(ctx["status"], "RETRIEVE_FAILED")
-            # Token must NOT appear.
-            self.assertNotIn("TESTONLY_LEAKY_TOKEN", ctx["error_detail"])
-            # Redaction sentinel must appear — proof the scrub ran.
-            self.assertIn("<redacted>", ctx["error_detail"])
-
-    def test_systemexit_still_propagates(self):
-        """argparse's --help path raises SystemExit. That MUST propagate
-        unchanged — catching it would silently swallow `--help` + any
-        other intentional early exit. The wrapper catches `Exception`,
-        not `BaseException`, so SystemExit is unaffected."""
-        with tempfile.TemporaryDirectory() as tmp:
-            work_dir = Path(tmp) / "work"
-
-            with mock.patch.object(main, "_run_pipeline",
-                                   side_effect=SystemExit(2)):
-                with self.assertRaises(SystemExit) as ctx:
-                    main.main(_args(work_dir))
-            self.assertEqual(ctx.exception.code, 2)
-
-
-class NormalizeFlowIdTargetsTests(unittest.TestCase):
-    """classic bots occasionally store NGA-style
-    300Uv-prefix FlowDefinition IDs or 301-prefix Flow version IDs as
-    InvocationTarget. After Wave B resolves them we rewrite bundle_parsed
-    in place so parse_wave sees DeveloperNames and the pending/visited
-    diff collapses to zero for legitimate targets."""
-
-    def test_rewrites_flowdefinition_id_to_developer_name(self):
-        bundle = {
-            "topics": [{
-                "name": "T",
-                "actions": [{
-                    "name": "A",
-                    "invocationTarget": "300UvXXXXXXXXXXXX",
-                    "invocationTargetType": "flow",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        flow_def_rows = [{
-            "Id": "300UvXXXXXXXXXXXX",
-            "DeveloperName": "MyFlowName",
-            "ActiveVersionId": "301VfYYYYYYYYYYYY",
-        }]
-        main._normalize_flow_id_targets(bundle, flow_def_rows)
-        action = bundle["topics"][0]["actions"][0]
-        self.assertEqual(action["invocationTarget"], "MyFlowName")
-        self.assertEqual(action["_original_invocation_target_id"],
-                         "300UvXXXXXXXXXXXX")
-
-    def test_rewrites_flow_version_id_via_active_version_map(self):
-        """301-prefix IDs should also resolve — via the ActiveVersionId
-        side of the bi-directional map."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "301VfYYYYYYYYYYYY",
-                    "invocationTargetType": "flow",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        flow_def_rows = [{
-            "Id": "300UvXXXXXXXXXXXX",
-            "DeveloperName": "MyFlowName",
-            "ActiveVersionId": "301VfYYYYYYYYYYYY",
-        }]
-        main._normalize_flow_id_targets(bundle, flow_def_rows)
-        self.assertEqual(
-            bundle["topics"][0]["actions"][0]["invocationTarget"],
-            "MyFlowName",
-        )
-
-    def test_preserves_classic_developer_name_targets(self):
-        """Classic DeveloperName targets must pass through untouched —
-        they have nothing to resolve AND shouldn't pick up the sentinel
-        _original_invocation_target_id field."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "AGNT_Case_Create",
-                    "invocationTargetType": "flow",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        flow_def_rows = [{
-            "Id": "300UvXXXXXXXXXXXX",
-            "DeveloperName": "AGNT_Case_Create",
-            "ActiveVersionId": "301VfYYYYYYYYYYYY",
-        }]
-        main._normalize_flow_id_targets(bundle, flow_def_rows)
-        action = bundle["topics"][0]["actions"][0]
-        self.assertEqual(action["invocationTarget"], "AGNT_Case_Create")
-        self.assertNotIn("_original_invocation_target_id", action)
-
-    def test_unmatched_id_stays_as_is(self):
-        """An ID that doesn't appear in flow_def_rows (Flow not queryable
-        / managed package invisible) stays unchanged — that's how it
-        correctly surfaces in _pending_fetches instead of silently
-        discarding."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "300UvZZZZZZZZZZZZ",
-                    "invocationTargetType": "flow",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        main._normalize_flow_id_targets(bundle, [{
-            "Id": "300UvXXXXXXXXXXXX",
-            "DeveloperName": "DifferentFlow",
-            "ActiveVersionId": "301VfYYYYYYYYYYYY",
-        }])
-        self.assertEqual(
-            bundle["topics"][0]["actions"][0]["invocationTarget"],
-            "300UvZZZZZZZZZZZZ",
-        )
-
-    def test_apex_target_with_300_prefix_not_rewritten(self):
-        """Only invocationTargetType=='flow' is rewritten. A target that
-        happens to match a flow id but is declared as apex stays put —
-        it's a caller-error we surface, not one we silently rewrite."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "300UvXXXXXXXXXXXX",
-                    "invocationTargetType": "apex",  # wrong type
-                }],
-            }],
-            "plannerActions": [],
-        }
-        flow_def_rows = [{
-            "Id": "300UvXXXXXXXXXXXX",
-            "DeveloperName": "MyFlow",
-            "ActiveVersionId": "301VfYYYYYYYYYYYY",
-        }]
-        main._normalize_flow_id_targets(bundle, flow_def_rows)
-        self.assertEqual(
-            bundle["topics"][0]["actions"][0]["invocationTarget"],
-            "300UvXXXXXXXXXXXX",
-        )
-
-    def test_empty_inputs_noop(self):
-        """Empty flow_def_rows → immediate return, no mutation, no crash
-        on missing 'topics' / 'plannerActions' keys."""
-        bundle = {}
-        main._normalize_flow_id_targets(bundle, [])
-        self.assertEqual(bundle, {})
-
-        bundle2 = {
-            "topics": [{"actions": [{
-                "invocationTarget": "300Uv", "invocationTargetType": "flow",
-            }]}],
-            "plannerActions": [],
-        }
-        main._normalize_flow_id_targets(bundle2, [])
-        # Untouched — no lookup map to rewrite against.
-        self.assertEqual(
-            bundle2["topics"][0]["actions"][0]["invocationTarget"], "300Uv",
-        )
-
-    def test_rewrites_both_topics_and_planner_actions(self):
-        """Fix must cover both the per-topic actions path AND the
-        bundle-scope plannerActions path."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "300UvAAAA",
-                    "invocationTargetType": "flow",
-                }],
-            }],
-            "plannerActions": [{
-                "invocationTarget": "300UvBBBB",
-                "invocationTargetType": "flow",
-            }],
-        }
-        flow_def_rows = [
-            {"Id": "300UvAAAA", "DeveloperName": "TopicFlow",
-             "ActiveVersionId": "301AAAA"},
-            {"Id": "300UvBBBB", "DeveloperName": "BundleFlow",
-             "ActiveVersionId": "301BBBB"},
-        ]
-        main._normalize_flow_id_targets(bundle, flow_def_rows)
-        self.assertEqual(
-            bundle["topics"][0]["actions"][0]["invocationTarget"], "TopicFlow",
-        )
-        self.assertEqual(
-            bundle["plannerActions"][0]["invocationTarget"], "BundleFlow",
-        )
-
-    def test_none_invocation_target_type_ignored_safely(self):
-        """Defensive: invocationTargetType missing → treat as 'not a
-        flow', skip. No crash."""
-        bundle = {
-            "topics": [{"actions": [{
-                "invocationTarget": "300UvAAAA",
-                "invocationTargetType": None,
-            }]}],
-            "plannerActions": [],
-        }
-        main._normalize_flow_id_targets(bundle, [
-            {"Id": "300UvAAAA", "DeveloperName": "X", "ActiveVersionId": "301"}
-        ])
-        self.assertEqual(
-            bundle["topics"][0]["actions"][0]["invocationTarget"], "300UvAAAA",
-        )
-
-
-class CollectWaveBTargetsStandardActionTests(unittest.TestCase):
-    """`_route` in `_collect_wave_b_targets` must
-    short-circuit on declared-only target types (standardInvocableAction,
-    generatePromptResponse, genai*, prompt*) BEFORE calling
-    resolve_or_unresolved — otherwise it pollutes `_unresolved` with
-    spurious "invalid-id-format" entries for perfectly valid identifiers
-    that simply aren't Salesforce Ids."""
-
-    def test_standard_action_not_routed_through_id_resolver(self):
-        """`streamKnowledgeSearch` is a built-in standard action — not
-        an Id. It should not end up in apex_ids, flow_ids, apex_names,
-        or flow_names AND it should NOT appear in the `_unresolved`
-        list that resolve_or_unresolved populates on non-Id inputs.
-        """
-        bundle = {
-            "topics": [{
-                "name": "T",
-                "actions": [{
-                    "name": "A",
-                    "invocationTarget": "streamKnowledgeSearch",
-                    "invocationTargetType": "standardInvocableAction",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        result = main._collect_wave_b_targets(bundle)
-        self.assertEqual(result["apex_names"], [])
-        self.assertEqual(result["apex_ids"], [])
-        self.assertEqual(result["flow_names"], [])
-        self.assertEqual(result["flow_ids"], [])
-        self.assertEqual(
-            result["_unresolved"], [],
-            "standardInvocableAction must not pollute _unresolved with "
-            "invalid-id-format entries",
-        )
-
-    def test_generate_prompt_response_short_circuits(self):
-        """`generatePromptResponse` targets are prompt-template names;
-        not routed to Apex/Flow fetchers (Batch 1 is body-only for
-        Apex+Flow; prompts flow through the retrieve path)."""
-        bundle = {
-            "topics": [{
-                "name": "T",
-                "actions": [{
-                    "invocationTarget": "MyPromptTemplate",
-                    "invocationTargetType": "generatePromptResponse",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        result = main._collect_wave_b_targets(bundle)
-        self.assertEqual(result["apex_names"], [])
-        self.assertEqual(result["flow_names"], [])
-        self.assertEqual(result["_unresolved"], [])
-
-    def test_flow_and_apex_still_route_correctly(self):
-        """Positive control — the short-circuit must not break flow/apex
-        routing. A mix of classic DeveloperNames + NGA IDs should land in
-        the right buckets, and standard actions should pass through
-        without polluting anything."""
-        bundle = {
-            "topics": [{
-                "name": "T",
-                "actions": [
-                    # Classic flow by DeveloperName
-                    {"invocationTarget": "MyFlow",
-                     "invocationTargetType": "flow"},
-                    # Classic apex by name
-                    {"invocationTarget": "MyApex",
-                     "invocationTargetType": "apex"},
-                    # Standard action (new short-circuit path)
-                    {"invocationTarget": "streamKnowledgeSearch",
-                     "invocationTargetType": "standardInvocableAction"},
-                    # NGA apex by Id
-                    {"invocationTarget": "01p1N000005SsDNQA0",
-                     "invocationTargetType": "apex"},
-                ],
-            }],
-            "plannerActions": [],
-        }
-        result = main._collect_wave_b_targets(bundle)
-        self.assertIn("MyFlow", result["flow_names"])
-        self.assertIn("MyApex", result["apex_names"])
-        self.assertIn("01p1N000005SsDNQA0", result["apex_ids"])
-        self.assertEqual(result["_unresolved"], [])
-
-    def test_unknown_type_silently_skipped(self):
-        """An unrecognized invocationTargetType falls through all the
-        known-type branches and is silently skipped. parse_wave tags the
-        node as UNKNOWN in the tree (via `_kind_counts`), so the signal
-        is visible without polluting _unresolved."""
-        bundle = {
-            "topics": [{
-                "name": "T",
-                "actions": [{
-                    "invocationTarget": "SomeThing",
-                    "invocationTargetType": "unheardOfType",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        result = main._collect_wave_b_targets(bundle)
-        self.assertEqual(result["apex_names"], [])
-        self.assertEqual(result["flow_names"], [])
-        self.assertEqual(
-            result["_unresolved"], [],
-            "Unknown invocationTargetType shouldn't reach the ID router, "
-            "so _unresolved stays clean.",
-        )
-
-    def test_classic_flow_name_not_routed_through_id_resolver(self):
-        """classic bots store plain DeveloperNames
-        like `MyFlow` — not Salesforce Ids. The router must route these
-        directly to flow_names via invocationTargetType, NOT through
-        resolve_or_unresolved (which would reject them as invalid-id-
-        format and pollute _unresolved)."""
-        bundle = {
-            "topics": [{
-                "actions": [
-                    {"invocationTarget": "MyFlow",
-                     "invocationTargetType": "flow"},
-                    {"invocationTarget": "AGNT_Foo",
-                     "invocationTargetType": "apex"},
-                ],
-            }],
-            "plannerActions": [],
-        }
-        result = main._collect_wave_b_targets(bundle)
-        self.assertIn("MyFlow", result["flow_names"])
-        self.assertIn("AGNT_Foo", result["apex_names"])
-        self.assertEqual(
-            result["_unresolved"], [],
-            "Classic DeveloperNames shouldn't be sent through the ID "
-            "resolver at all — they're not Ids.",
-        )
-
-
-class NormalizePromptTemplateIdTargetsTests(unittest.TestCase):
-    """Bug 1 fix (2026-05-05): classic bots occasionally store 0hf-prefix
-    GenAiPromptTemplate IDs as `GenAiFunctionDefinition.InvocationTarget`.
-    After Wave B resolves them via `list_prompt_template_metadata`
-    (GenAiPromptTemplate is NOT SOQL-queryable — Metadata API only) we
-    rewrite bundle_parsed in place so Wave B's retrieve uses the
-    DeveloperName Metadata API expects."""
-
-    def test_rewrites_prompt_template_id_to_developer_name(self):
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "0hfUv0000021mCjIAI",
-                    "invocationTargetType": "GenAiPromptTemplate",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        rows = [{"Id": "0hfUv0000021mCjIAI", "DeveloperName": "My_Prompt"}]
-        main._normalize_prompt_template_id_targets(bundle, rows)
-        action = bundle["topics"][0]["actions"][0]
-        self.assertEqual(action["invocationTarget"], "My_Prompt")
-        self.assertEqual(
-            action["_original_invocation_target_id"], "0hfUv0000021mCjIAI"
-        )
-
-    def test_preserves_classic_developer_name_targets(self):
-        """Classic DeveloperName targets pass through untouched — the
-        rewrite is only for Id-shaped targets that appeared in the lookup."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "Existing_Prompt_Name",
-                    "invocationTargetType": "GenAiPromptTemplate",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        # Lookup covers a different Id entirely — the DeveloperName target
-        # isn't a key in the map so it's not rewritten.
-        rows = [{"Id": "0hfUv0000021Other", "DeveloperName": "Other_Prompt"}]
-        main._normalize_prompt_template_id_targets(bundle, rows)
-        action = bundle["topics"][0]["actions"][0]
-        self.assertEqual(action["invocationTarget"], "Existing_Prompt_Name")
-        self.assertNotIn("_original_invocation_target_id", action)
-
-    def test_unmatched_id_stays_as_is(self):
-        """Id not present in the lookup (e.g. Tooling returned empty
-        because GenAiPromptTemplate isn't exposed on this org) stays
-        as-is so it correctly surfaces in _pending_fetches."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "0hfUv00000xxxxxYYY",
-                    "invocationTargetType": "GenAiPromptTemplate",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        main._normalize_prompt_template_id_targets(bundle, [])
-        action = bundle["topics"][0]["actions"][0]
-        self.assertEqual(action["invocationTarget"], "0hfUv00000xxxxxYYY")
-        self.assertNotIn("_original_invocation_target_id", action)
-
-
-class NormalizeApexIdTargetsTests(unittest.TestCase):
-    """Gap B fix (2026-05-05): classic bots occasionally store 01p-prefix
-    ApexClass Ids as `GenAiFunctionDefinition.InvocationTarget` (live-verified
-    on my-org-alias: 01p000000000000AAA -> MyController).
-    After Wave B resolves them via `fetch_apex_bodies_by_ids` we rewrite
-    bundle_parsed in place so the tree renders the ApexClass Name instead
-    of the raw Id."""
-
-    def test_rewrites_apex_id_to_class_name(self):
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "01p000000000000AAA",
-                    "invocationTargetType": "apex",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        rows = [{"Id": "01p000000000000AAA", "Name": "MyController"}]
-        main._normalize_apex_id_targets(bundle, rows)
-        action = bundle["topics"][0]["actions"][0]
-        self.assertEqual(action["invocationTarget"], "MyController")
-        self.assertEqual(
-            action["_original_invocation_target_id"], "01p000000000000AAA"
-        )
-
-    def test_non_apex_ttype_left_unchanged(self):
-        """Same Id but a non-apex ttype — the ttype gate must block the
-        rewrite so a Flow action whose target happens to collide with an
-        ApexClass Id isn't miscaught."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "01p000000000000AAA",
-                    "invocationTargetType": "flow",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        rows = [{"Id": "01p000000000000AAA", "Name": "MyController"}]
-        main._normalize_apex_id_targets(bundle, rows)
-        action = bundle["topics"][0]["actions"][0]
-        self.assertEqual(action["invocationTarget"], "01p000000000000AAA")
-        self.assertNotIn("_original_invocation_target_id", action)
-
-    def test_unmatched_id_stays_as_is(self):
-        """Id not present in the lookup (e.g. by-Id fetch failed or the
-        class was deleted) stays as-is so it correctly surfaces in
-        _pending_fetches."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "01pFAKEIDFAKEIDAAA",
-                    "invocationTargetType": "apex",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        main._normalize_apex_id_targets(bundle, [])
-        action = bundle["topics"][0]["actions"][0]
-        self.assertEqual(action["invocationTarget"], "01pFAKEIDFAKEIDAAA")
-        self.assertNotIn("_original_invocation_target_id", action)
-
-    def test_preserves_classic_developer_name_targets(self):
-        """Classic Name targets pass through untouched — the rewrite is
-        only for Id-shaped targets (01p-prefix) that appeared in the lookup."""
-        bundle = {
-            "topics": [{
-                "actions": [{
-                    "invocationTarget": "MyApexClass",
-                    "invocationTargetType": "apex",
-                }],
-            }],
-            "plannerActions": [],
-        }
-        # Lookup covers a different Id entirely — the Name target isn't
-        # Id-shaped and doesn't hit the prefix gate.
-        rows = [{"Id": "01p000000000000AAA", "Name": "MyController"}]
-        main._normalize_apex_id_targets(bundle, rows)
-        action = bundle["topics"][0]["actions"][0]
-        self.assertEqual(action["invocationTarget"], "MyApexClass")
-        self.assertNotIn("_original_invocation_target_id", action)
-
-
-class CollectWaveBTargetsPromptTemplateIdTests(unittest.TestCase):
-    """Bug 1 fix (2026-05-05): 0hf-prefix prompt template Ids are routed
-    to a dedicated `prompt_template_ids` bucket so post-Wave-B resolution
-    can rewrite them; DeveloperName targets still short-circuit as before."""
-
-    def test_prompt_template_id_routes_to_id_bucket(self):
-        bundle = {
-            "topics": [],
-            "plannerActions": [{
-                "invocationTarget": "0hfUv0000021mCjIAI",
-                "invocationTargetType": "GenAiPromptTemplate",
-            }],
-        }
-        result = main._collect_wave_b_targets(bundle)
-        self.assertEqual(
-            result.get("prompt_template_ids"), ["0hfUv0000021mCjIAI"]
-        )
-        # DeveloperName bucket stays empty — the Id is routed to the Id
-        # bucket and the short-circuit returns BEFORE the DeveloperName
-        # branch would have run.
-        self.assertEqual(result.get("_unresolved"), [])
-
-    def test_prompt_template_developer_name_does_not_pollute_id_bucket(self):
-        bundle = {
-            "topics": [],
-            "plannerActions": [{
-                "invocationTarget": "My_Prompt_Template_Name",
-                "invocationTargetType": "GenAiPromptTemplate",
-            }],
-        }
-        result = main._collect_wave_b_targets(bundle)
-        self.assertEqual(result.get("prompt_template_ids"), [])
-        # DeveloperName-shaped prompt-template targets still short-circuit
-        # (parse_wave enqueues them into PROMPT_TEMPLATE pending) — no
-        # change from prior behavior, verified via absence from all
-        # name/id buckets we'd route through.
-        self.assertEqual(result.get("apex_names"), [])
-        self.assertEqual(result.get("flow_names"), [])
-
-    def test_non_0hf_prefix_ignored(self):
-        """Id-shaped target for a prompt-template ttype but WRONG prefix
-        (e.g. a Flow Id accidentally typed with prompt ttype) doesn't
-        pollute prompt_template_ids — the prefix gate catches it."""
-        bundle = {
-            "topics": [],
-            "plannerActions": [{
-                "invocationTarget": "300Uv00000abcdeFGH",  # Flow-shaped Id
-                "invocationTargetType": "GenAiPromptTemplate",
-            }],
-        }
-        result = main._collect_wave_b_targets(bundle)
-        # Not routed anywhere — neither prompt-template Id bucket nor
-        # flow buckets (ttype gated). Surfaces nowhere, which is
-        # acceptable: classify_action_call downstream will still enqueue
-        # the string as-is as a PROMPT_TEMPLATE pending fetch.
-        self.assertEqual(result.get("prompt_template_ids"), [])
-
-
-class FetchFlowDefinitionViewByDurableIdsTests(unittest.TestCase):
-    """Option B (2026-05-05): `fetch_flow_definition_view_by_durable_ids`
-    is the Data-API fallback fetcher for managed-installed flows that
-    Tooling's `FlowDefinition` doesn't index.
-
-    Contract:
-      * Empty input short-circuits to `[]` without firing a SOQL call
-        (matches every other list-shaped fetcher in this module).
-      * Rows are returned from `data_query` verbatim — projection to
-        the `flow_def_rows` shape happens in the caller
-        (`fetch_flow_definition_ids_by_names`).
-    """
-
-    def test_happy_path_returns_rows(self):
-        import fetch_soql  # type: ignore
-        view_row = {
-            "DurableId": "SvcCopilotTmpl__VerifyCode",
-            "ApiName": "VerifyCode",
-            "Label": "Verify Code",
-            "NamespacePrefix": "SvcCopilotTmpl",
-            "ActiveVersionId": "SvcCopilotTmpl__VerifyCode-1",
-            "IsActive": True,
-            "ManageableState": "installed",
-            "ProcessType": "AutoLaunchedFlow",
-        }
-        with mock.patch.object(
-            fetch_soql, "data_query",
-            return_value={"records": [view_row]},
-        ) as mock_dq:
-            rows = fetch_soql.fetch_flow_definition_view_by_durable_ids(
-                ["SvcCopilotTmpl__VerifyCode"],
-                lambda: ("url", "tok"),
-                api_version="v60.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertEqual(rows, [view_row])
-        # Exactly one data_query call — the fetcher doesn't accidentally
-        # re-fire on the Tooling surface.
-        self.assertEqual(mock_dq.call_count, 1)
-
-    def test_empty_input_short_circuits(self):
-        """Empty durable_ids list returns [] WITHOUT firing a SOQL call
-        (matches the module-wide empty-input-short-circuit invariant)."""
-        import fetch_soql  # type: ignore
-        with mock.patch.object(fetch_soql, "data_query") as mock_dq:
-            rows = fetch_soql.fetch_flow_definition_view_by_durable_ids(
-                [],
-                lambda: ("url", "tok"),
-                api_version="v60.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertEqual(rows, [])
-        self.assertEqual(mock_dq.call_count, 0)
-
-    def test_multi_row_returns_all(self):
-        import fetch_soql  # type: ignore
-        view_rows = [
-            {
-                "DurableId": "SvcCopilotTmpl__VerifyCode",
-                "ApiName": "VerifyCode",
-                "NamespacePrefix": "SvcCopilotTmpl",
-                "ActiveVersionId": "SvcCopilotTmpl__VerifyCode-1",
-                "ManageableState": "installed",
-            },
-            {
-                "DurableId": "sales_inbound_flows__SendVerifyCode",
-                "ApiName": "SendVerifyCode",
-                "NamespacePrefix": "sales_inbound_flows",
-                "ActiveVersionId": "sales_inbound_flows__SendVerifyCode-2",
-                "ManageableState": "installed",
-            },
-        ]
-        with mock.patch.object(
-            fetch_soql, "data_query",
-            return_value={"records": view_rows},
-        ):
-            rows = fetch_soql.fetch_flow_definition_view_by_durable_ids(
-                [
-                    "SvcCopilotTmpl__VerifyCode",
-                    "sales_inbound_flows__SendVerifyCode",
-                ],
-                lambda: ("url", "tok"),
-                api_version="v60.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertEqual(len(rows), 2)
-        # Membership assertion rather than sort-order — codepoint sort of
-        # mixed-case prefixes is fragile; the fetcher returns rows in the
-        # order `data_query` supplies them.
-        self.assertEqual(
-            {r["DurableId"] for r in rows},
-            {
-                "SvcCopilotTmpl__VerifyCode",
-                "sales_inbound_flows__SendVerifyCode",
-            },
-        )
-
-
-class FlowDefinitionViewFallbackTests(unittest.TestCase):
-    """Option B (2026-05-05, updated after managed-bucket retirement):
-    `fetch_flow_definition_ids_by_names` fires a SINGLE Tooling
-    `FlowDefinition` query (unmanaged-only — the template filters
-    `NamespacePrefix IS NULL`). Any input name that query doesn't resolve
-    triggers a single follow-up `FlowDefinitionView` (Data API) query.
-    Projected view-only rows carry `Id=None`, `ActiveVersionId=None`,
-    `_body_available=False`, and `_source="FlowDefinitionView"`.
-    """
-
-    def test_fallback_fires_on_managed_miss(self):
-        """Tooling FlowDefinition returns empty for a `ns__Name` input
-        (managed flows aren't indexed on subscriber orgs + the unmanaged
-        query filters `NamespacePrefix IS NULL` anyway); FlowDefinitionView
-        returns a matching row. Output row carries the view-shaped markers
-        and `DeveloperName` = qualified ns__bare."""
-        import fetch_soql  # type: ignore
-        view_row = {
-            "DurableId": "SvcCopilotTmpl__VerifyCode",
-            "ApiName": "VerifyCode",
-            "Label": "Verify Code",
-            "NamespacePrefix": "SvcCopilotTmpl",
-            "ActiveVersionId": "SvcCopilotTmpl__VerifyCode-1",
-            "ManageableState": "installed",
-        }
-        with mock.patch.object(
-            fetch_soql, "tooling_query",
-            return_value={"records": []},
-        ), mock.patch.object(
-            fetch_soql, "data_query",
-            return_value={"records": [view_row]},
-        ) as mock_dq:
-            rows = fetch_soql.fetch_flow_definition_ids_by_names(
-                ["SvcCopilotTmpl__VerifyCode"],
-                lambda: ("url", "tok"),
-                api_version="v60.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertEqual(len(rows), 1)
-        row = rows[0]
-        self.assertIsNone(row["Id"])
-        self.assertIsNone(row["ActiveVersionId"])
-        self.assertFalse(row["_body_available"])
-        self.assertEqual(row["_source"], "FlowDefinitionView")
-        self.assertEqual(row["DeveloperName"], "SvcCopilotTmpl__VerifyCode")
-        self.assertEqual(row["NamespacePrefix"], "SvcCopilotTmpl")
-        self.assertEqual(row["_bare_developer_name"], "VerifyCode")
-        self.assertEqual(mock_dq.call_count, 1)
-
-    def test_fallback_skipped_when_tooling_resolves_everything(self):
-        """All input names resolved by Tooling → FlowDefinitionView is
-        never queried. Guards against unnecessary Data-API calls on the
-        99% of runs where every referenced flow is unmanaged or locally
-        installed."""
-        import fetch_soql  # type: ignore
-        real_row = {
-            "Id": "300Uv000000Real",
-            "DeveloperName": "MyFlow",
-            "NamespacePrefix": None,
-            "ActiveVersionId": "301Vf000000Real",
-        }
-        with mock.patch.object(
-            fetch_soql, "tooling_query",
-            return_value={"records": [real_row]},
-        ), mock.patch.object(fetch_soql, "data_query") as mock_dq:
-            rows = fetch_soql.fetch_flow_definition_ids_by_names(
-                ["MyFlow"],
-                lambda: ("url", "tok"),
-                api_version="v60.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertEqual(len(rows), 1)
-        self.assertEqual(rows[0]["_source"], "FlowDefinition")
-        self.assertTrue(rows[0]["_body_available"])
-        self.assertEqual(mock_dq.call_count, 0)
-
-    def test_mixed_resolution_paths(self):
-        """Three input names, three distinct fates:
-          1. `ExistingFlow` — unmanaged, resolved by Tooling.
-          2. `SvcCopilotTmpl__VerifyCode` — managed miss on Tooling,
-             resolved by FlowDefinitionView.
-          3. `ghost_ns__GhostFlow` — managed miss on BOTH surfaces.
-
-        Expected: 2 rows total (1 real + 1 view-only), the ghost flow
-        absent from the result set. FlowDefinitionView queried exactly
-        once with both unresolved names in the IN-list.
-        """
-        import fetch_soql  # type: ignore
-
-        real_row = {
-            "Id": "300Uv000000Real",
-            "DeveloperName": "ExistingFlow",
-            "NamespacePrefix": None,
-            "ActiveVersionId": "301Vf000000Real",
-        }
-        view_row = {
-            "DurableId": "SvcCopilotTmpl__VerifyCode",
-            "ApiName": "VerifyCode",
-            "NamespacePrefix": "SvcCopilotTmpl",
-            "ActiveVersionId": "SvcCopilotTmpl__VerifyCode-1",
-            "ManageableState": "installed",
-        }
-
-        # Tooling is called exactly once — the unmanaged query (template
-        # filters NamespacePrefix IS NULL). It matches only ExistingFlow;
-        # the two managed-qualified names return no rows from that
-        # surface and fall through to the view fallback.
-        with mock.patch.object(
-            fetch_soql, "tooling_query",
-            return_value={"records": [real_row]},
-        ) as mock_tq, mock.patch.object(
-            fetch_soql, "data_query",
-            return_value={"records": [view_row]},
-        ) as mock_dq:
-            rows = fetch_soql.fetch_flow_definition_ids_by_names(
-                [
-                    "ExistingFlow",
-                    "SvcCopilotTmpl__VerifyCode",
-                    "ghost_ns__GhostFlow",
-                ],
-                lambda: ("url", "tok"),
-                api_version="v60.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertEqual(len(rows), 2)
-        # Tooling queried exactly once for the full input (no bucketing).
-        self.assertEqual(mock_tq.call_count, 1)
-        # View fallback queried exactly once — no per-name fanout.
-        self.assertEqual(mock_dq.call_count, 1)
-
-        by_name = {r["DeveloperName"]: r for r in rows}
-        # Real Tooling row — source marker explicit.
-        self.assertEqual(by_name["ExistingFlow"]["Id"], "300Uv000000Real")
-        self.assertEqual(by_name["ExistingFlow"]["_source"], "FlowDefinition")
-        self.assertTrue(by_name["ExistingFlow"]["_body_available"])
-        # View-only row — no Id, no active version, marked unavailable.
-        view_result = by_name["SvcCopilotTmpl__VerifyCode"]
-        self.assertIsNone(view_result["Id"])
-        self.assertIsNone(view_result["ActiveVersionId"])
-        self.assertFalse(view_result["_body_available"])
-        self.assertEqual(view_result["_source"], "FlowDefinitionView")
-        # Ghost flow absent.
-        self.assertNotIn("ghost_ns__GhostFlow", by_name)
-
-
-class FetchPlannerDefinitionChainTests(unittest.TestCase):
-    """2026-05-05: `fetch_planner_definition(agent, version)` performs a
-    chain-LIKE lookup against GenAiPlannerDefinition. The accretive
-    naming invariant (v1=`<Agent>`, v2=`<Agent>_v2`, v3=
-    `<Agent>_v2_v3`, ...) means the correct planner always matches
-    `<Agent>%\\_vN` for vN>=2 and `<Agent>` exactly for v1. On multi-row
-    matches the resolver picks the row with the shortest DeveloperName.
-    """
-
-    def _stub_tooling(self, records):
-        """Patch `fetch_soql.tooling_query` to return a fixed record list."""
-        import fetch_soql  # type: ignore
-        return mock.patch.object(
-            fetch_soql, "tooling_query",
-            return_value={"records": records},
-        )
-
-    def test_v1_exact_match(self):
-        import fetch_soql  # type: ignore
-        with self._stub_tooling([
-            {"Id": "1VxVF000V1", "DeveloperName": "Inbound_Sales_Agent"},
-        ]):
-            row = fetch_soql.fetch_planner_definition(
-                "Inbound_Sales_Agent", None,
-                lambda: ("url", "tok"),
-                api_version="v66.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertIsNotNone(row)
-        self.assertEqual(row["DeveloperName"], "Inbound_Sales_Agent")
-
-    def test_v1_explicit_string(self):
-        import fetch_soql  # type: ignore
-        with self._stub_tooling([
-            {"Id": "1VxVF000V1", "DeveloperName": "Inbound_Sales_Agent"},
-        ]):
-            row = fetch_soql.fetch_planner_definition(
-                "Inbound_Sales_Agent", "v1",
-                lambda: ("url", "tok"),
-                api_version="v66.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertEqual(row["DeveloperName"], "Inbound_Sales_Agent")
-
-    def test_v2_single_match(self):
-        import fetch_soql  # type: ignore
-        with self._stub_tooling([
-            {"Id": "1VxVF000V2", "DeveloperName": "Inbound_Sales_Agent_v2"},
-        ]):
-            row = fetch_soql.fetch_planner_definition(
-                "Inbound_Sales_Agent", "v2",
-                lambda: ("url", "tok"),
-                api_version="v66.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertEqual(row["DeveloperName"], "Inbound_Sales_Agent_v2")
-
-    def test_v2_multi_row_shortest_wins(self):
-        """LIKE `<Agent>%\\_v2` can match both `<Agent>_v2` and a deeper
-        chain like `<Agent>_foo_v2` (rare but possible). Shortest
-        DeveloperName wins — the canonical row carries no extra segment."""
-        import fetch_soql  # type: ignore
-        with self._stub_tooling([
-            {"Id": "1VxVF000DEEPER",
-             "DeveloperName": "Inbound_Sales_Agent_foo_v2"},
-            {"Id": "1VxVF000V2",
-             "DeveloperName": "Inbound_Sales_Agent_v2"},
-        ]):
-            row = fetch_soql.fetch_planner_definition(
-                "Inbound_Sales_Agent", "v2",
-                lambda: ("url", "tok"),
-                api_version="v66.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertEqual(row["DeveloperName"], "Inbound_Sales_Agent_v2")
-
-    def test_zero_rows_returns_none(self):
-        import fetch_soql  # type: ignore
-        with self._stub_tooling([]):
-            row = fetch_soql.fetch_planner_definition(
-                "NoSuchAgent", "v3",
-                lambda: ("url", "tok"),
-                api_version="v66.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertIsNone(row)
-
-    def test_chain_like_pattern_passed_to_soql_for_v5(self):
-        """The SOQL body that reaches `tooling_query` contains the chain
-        LIKE pattern literally. Verify AGENT_NAME + VERSION are rendered
-        through the template with the `%\\_` escape in between.
-        """
-        import fetch_soql  # type: ignore
-        captured: dict = {}
-
-        def fake_tooling(creds_provider, soql, *, api_version, on_401_refresh):
-            captured["soql"] = soql
-            return {"records": []}
-
-        with mock.patch.object(fetch_soql, "tooling_query",
-                               side_effect=fake_tooling):
-            fetch_soql.fetch_planner_definition(
-                "MyAgent", "v5",
-                lambda: ("url", "tok"),
-                api_version="v66.0",
-                on_401_refresh=lambda: ("url", "tok"),
-            )
-        self.assertIn("LIKE 'MyAgent%\\_v5'", captured["soql"])
-
-
-class SwapDirAtomicCoTenancyTests(unittest.TestCase):
-    """`_swap_dir_atomic` preserves sibling content in `target`. The prior
-    whole-directory `os.replace` wiped any co-tenant subdirs that another
-    caller may have written into the same `<agent>__<ver>/` directory."""
-
-    def test_preserves_sibling_session_dirs(self) -> None:
-        # Simulate co-tenancy: target dir already has a sibling subdir
-        # + a bare file written by some other caller.
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_p = Path(tmp)
-            target = tmp_p / "agent__v1"
-            target.mkdir()
-            (target / "sibling-data").mkdir()
-            (target / "sibling-data" / "payload.json").write_text(
-                "from-other-caller"
-            )
-            (target / "_sessions").mkdir()
-            (target / "_sessions" / "marker.link").write_text(
-                "../agent__v1/sibling-data"
-            )
-
-            # Architecture's own previous output, about to be overwritten.
-            (target / "old_tree.json").write_text("old")
-
-            # Staging dir — what architecture wants to write.
-            staging = tmp_p / ".agent__v1.staging.123"
-            staging.mkdir()
-            (staging / "agent_v1_metadata_tree.json").write_text("new-tree")
-            (staging / "last_built_at.txt").write_text("2026-05-05T12:00:00Z\n")
-
-            main._swap_dir_atomic(target, staging)
-
-            # Sibling content survives — the whole point of the fix.
-            self.assertTrue(
-                (target / "sibling-data" / "payload.json").is_file()
-            )
-            self.assertEqual(
-                (target / "sibling-data" / "payload.json").read_text(),
-                "from-other-caller",
-            )
-            self.assertTrue((target / "_sessions" / "marker.link").is_file())
-
-            # Architecture's new files landed.
-            self.assertEqual(
-                (target / "agent_v1_metadata_tree.json").read_text(), "new-tree"
-            )
-            self.assertTrue((target / "last_built_at.txt").is_file())
-
-            # Old file that wasn't in staging stays untouched.
-            self.assertTrue((target / "old_tree.json").is_file())
-            self.assertEqual((target / "old_tree.json").read_text(), "old")
-
-            # Staging dir cleaned up.
-            self.assertFalse(staging.exists())
-
-    def test_overwrites_own_files_cleanly(self) -> None:
-        """Same filename in both target and staging → staging content wins."""
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_p = Path(tmp)
-            target = tmp_p / "agent__v1"
-            target.mkdir()
-            (target / "tree.json").write_text("old-content")
-
-            staging = tmp_p / ".agent__v1.staging.123"
-            staging.mkdir()
-            (staging / "tree.json").write_text("new-content")
-
-            main._swap_dir_atomic(target, staging)
-
-            self.assertEqual(
-                (target / "tree.json").read_text(), "new-content"
-            )
-
-    def test_overwrites_when_target_entry_is_dir(self) -> None:
-        """If the old target entry is a directory and the new staging
-        entry is a file (or vice versa), replace cleans up the old kind
-        before os.replace lands the new one."""
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_p = Path(tmp)
-            target = tmp_p / "agent__v1"
-            target.mkdir()
-            # Old entry is a directory with nested content.
-            (target / "payload").mkdir()
-            (target / "payload" / "nested.txt").write_text("deep")
-
-            staging = tmp_p / ".agent__v1.staging.123"
-            staging.mkdir()
-            # New entry with the same name is a plain file.
-            (staging / "payload").write_text("now-a-file")
-
-            main._swap_dir_atomic(target, staging)
-
-            self.assertTrue((target / "payload").is_file())
-            self.assertEqual(
-                (target / "payload").read_text(), "now-a-file"
-            )
-
-    def test_missing_staging_raises(self) -> None:
-        """Pre-existing precondition: staging must exist, or we raise."""
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_p = Path(tmp)
-            target = tmp_p / "agent__v1"
-            target.mkdir()
-            staging = tmp_p / ".agent__v1.staging.does-not-exist"
-            with self.assertRaises(OSError):
-                main._swap_dir_atomic(target, staging)
-
-    def test_run_finalize_preserves_session_subdir_across_reruns(self) -> None:
-        """End-to-end via `_run_finalize`: after a first successful run
-        seeds a co-tenant session dir, a second run must not wipe it.
-        Covers the production path — the bug the user reported."""
-        with tempfile.TemporaryDirectory() as tmp:
-            tmp_p = Path(tmp)
-            work_dir = tmp_p / "work"
-            work_dir.mkdir()
-            data_dir = tmp_p / "data" / "A__v1"
-            cache_dir = tmp_p / "cache" / "A__v1"
-
-            tree = {
-                "_schema_version": "3.0",
-                "agent": {"api_name": "A", "version": "v1"},
-                "root": {"kind": "BOT_DEFINITION", "api_name": "A",
-                         "children": []},
-                "node_count": 1, "depth": 0,
-                "_kind_counts": {"BOT_DEFINITION": 1},
-                "_pending_fetches": {k: [] for k in (
-                    "FLOW", "APEX", "PROMPT_TEMPLATE", "STANDARD_ACTION",
-                )},
-                "_unresolved": [],
-            }
-            # First run — populate data_dir.
-            main._run_finalize(
-                data_dir, cache_dir, dict(tree), work_dir,
-                agent_api_name="A", agent_version="v1", planner_name="A",
-            )
-            # Simulate a co-tenant dropping content alongside.
-            sibling_dir = data_dir / "sibling-payload"
-            sibling_dir.mkdir()
-            (sibling_dir / "payload.json").write_text("cotenant-data")
-
-            # Second run — the original bug: this would wipe the sibling dir.
-            main._run_finalize(
-                data_dir, cache_dir, dict(tree), work_dir,
-                agent_api_name="A", agent_version="v1", planner_name="A",
-            )
-
-            # Sibling dir and its contents must survive.
-            self.assertTrue(sibling_dir.is_dir())
-            self.assertTrue((sibling_dir / "payload.json").is_file())
-            self.assertEqual(
-                (sibling_dir / "payload.json").read_text(),
-                "cotenant-data",
-            )
-            # Architecture's own tree is still present (re-written).
-            self.assertTrue((data_dir / "A_v1_metadata_tree.json").is_file())
-
-
-# ---------------------------------------------------------------------------
-# Bug 1 fix (2026-05-05): GenAiPromptTemplate is NOT SOQL-queryable. Id →
-# DeveloperName resolution runs through `sf org list metadata` (Metadata
-# API) via the new `list_prompt_template_metadata` helper.
-# ---------------------------------------------------------------------------
-
-
-class ListPromptTemplateMetadataTests(unittest.TestCase):
-    """Unit tests for `metadata_listing.list_prompt_template_metadata` —
-    thin wrapper over `run_sf("list_metadata_genaiprompttemplate", ...)`.
-
-    The shape we care about is produced by the sf CLI:
-        {"status": 0, "result": [{"id": "0hfUv...", "fullName": "Foo", ...}]}
-    Defensive returns on malformed result (None / wrong type) keep the
-    failure mode quiet — callers already tolerate empty lists.
-    """
-
-    def test_happy_path_returns_result_rows(self):
-        import metadata_listing  # type: ignore
-        payload = {
-            "status": 0,
-            "result": [
-                {"id": "0hfUv0000021mCjIAI", "fullName": "My_Prompt",
-                 "type": "GenAiPromptTemplate"},
-                {"id": "0hfUv0000021mOtherAAA", "fullName": "Other_Prompt",
-                 "type": "GenAiPromptTemplate"},
-            ],
-        }
-        with mock.patch.object(metadata_listing, "run_sf", return_value=payload):
-            rows = metadata_listing.list_prompt_template_metadata("test-org")
-        self.assertEqual(rows, payload["result"])
-
-    def test_empty_result_returns_empty_list(self):
-        import metadata_listing  # type: ignore
-        with mock.patch.object(
-            metadata_listing, "run_sf",
-            return_value={"status": 0, "result": []},
-        ):
-            rows = metadata_listing.list_prompt_template_metadata("test-org")
-        self.assertEqual(rows, [])
-
-    def test_malformed_result_returns_empty_list(self):
-        """Defensive: if sf CLI's `result` key is not a list (e.g. None
-        on some error paths that still exit 0), we degrade to []."""
-        import metadata_listing  # type: ignore
-        with mock.patch.object(
-            metadata_listing, "run_sf",
-            return_value={"status": 0, "result": None},
-        ):
-            rows = metadata_listing.list_prompt_template_metadata("test-org")
-        self.assertEqual(rows, [])
-
-
-class FetchWaveBPromptTemplateMetadataWiringTests(unittest.TestCase):
-    """Bug 1 fix (2026-05-05): `_fetch_wave_b_by_names` invokes
-    `list_prompt_template_metadata` (Metadata API listing), then filters +
-    reshapes to the {Id, DeveloperName} shape the downstream pipeline
-    expects. Verify the filter + reshape contract — only the requested
-    Ids come back, keyed as the pipeline's existing prompt_template_id_rows
-    shape.
-    """
-
-    def test_listmetadata_rows_filtered_and_reshaped(self):
-        with mock.patch.object(
-            main, "list_prompt_template_metadata",
-            return_value=[
-                {"id": "0hfAAA", "fullName": "TplA",
-                 "type": "GenAiPromptTemplate"},
-                {"id": "0hfBBB", "fullName": "TplB",
-                 "type": "GenAiPromptTemplate"},
-            ],
-        ):
-            with mock.patch.object(main, "fetch_apex_bodies_by_names", return_value=[]), \
-                 mock.patch.object(main, "fetch_apex_bodies_by_ids", return_value=[]), \
-                 mock.patch.object(main, "fetch_flow_definition_ids_by_names", return_value=[]), \
-                 mock.patch.object(main, "fetch_flow_definition_by_ids", return_value=[]):
-                out = main._fetch_wave_b_by_names(
-                    apex_names=[],
-                    apex_ids=[],
-                    flow_names=[],
-                    flow_ids=[],
-                    prompt_template_ids=["0hfAAA"],
-                    creds_provider=lambda: ("url", "tok"),
-                    refresh_fn=lambda: ("url", "tok"),
-                    api_version="v60.0",
-                    org_alias="test-org",
-                    parallelism=2,
-                )
-        # Only the requested Id survives (0hfAAA); 0hfBBB is filtered out.
-        # The shape matches the old SOQL contract: {Id, DeveloperName}.
-        self.assertEqual(
-            out["prompt_template_id_rows"],
-            [{"Id": "0hfAAA", "DeveloperName": "TplA"}],
-        )
-
-    def test_listmetadata_failure_non_fatal(self):
-        """SfCliError from the Metadata listing is caught and surfaced via
-        the unresolved channel; the run continues with an empty rowset."""
-        from sf_cli import SfCliError  # type: ignore
-        with mock.patch.object(
-            main, "list_prompt_template_metadata",
-            side_effect=SfCliError("metadata-listing-exploded"),
-        ):
-            with mock.patch.object(main, "fetch_apex_bodies_by_names", return_value=[]), \
-                 mock.patch.object(main, "fetch_apex_bodies_by_ids", return_value=[]), \
-                 mock.patch.object(main, "fetch_flow_definition_ids_by_names", return_value=[]), \
-                 mock.patch.object(main, "fetch_flow_definition_by_ids", return_value=[]):
-                out = main._fetch_wave_b_by_names(
-                    apex_names=[],
-                    apex_ids=[],
-                    flow_names=[],
-                    flow_ids=[],
-                    prompt_template_ids=["0hfAAA"],
-                    creds_provider=lambda: ("url", "tok"),
-                    refresh_fn=lambda: ("url", "tok"),
-                    api_version="v60.0",
-                    org_alias="test-org",
-                    parallelism=2,
-                )
-        self.assertEqual(out["prompt_template_id_rows"], [])
-        reasons = [u.get("reason") or "" for u in out["unresolved"]]
-        self.assertTrue(
-            any("prompt-template-listmetadata-failed" in r for r in reasons),
-            f"expected listmetadata-failed in unresolved; got {reasons}",
-        )
-
-
-class RetrievePromptTemplatesTests(unittest.TestCase):
-    """Gap C (2026-05-05): unit tests for
-    `metadata_listing.retrieve_prompt_templates` — the sf CLI wrapper
-    that retrieves GenAiPromptTemplate bodies via
-    `sf project retrieve start --metadata GenAiPromptTemplate:...`.
-
-    The helper:
-      1. Short-circuits on empty input (no sf call).
-      2. Parses `unpackaged.zip` from the retrieve dir via stdlib
-         `zipfile` + `xml.etree.ElementTree`.
-      3. Extracts developerName/masterLabel/activeVersionIdentifier/
-         templateVersions[*].content/inputs[*].
-      4. Returns `{}` on SfCliError (non-fatal — main.py's call site
-         logs an `_unresolved[]` entry).
-      5. Skips files whose XML fails to parse; sibling templates still
-         surface.
-    """
-
-    def _run_retrieve_writes_zip(self, files: dict):
-        """Build a mock `_run_retrieve` side_effect that writes an
-        unpackaged.zip into the retrieve dir as the real CLI would.
-
-        `files = {inner_path: xml_bytes}`. `retrieve_prompt_templates`
-        wipes the retrieve dir before invoking the subprocess, so the zip
-        MUST be created by the mock (the retrieve dir is always the
-        `--target-metadata-dir` argv element)."""
-        import zipfile
-
-        def _side_effect(argv, timeout):
-            target_dir = Path(argv[argv.index("--target-metadata-dir") + 1])
-            target_dir.mkdir(parents=True, exist_ok=True)
-            zip_path = target_dir / "unpackaged.zip"
-            with zipfile.ZipFile(zip_path, "w") as zf:
-                for inner, xml_bytes in files.items():
-                    zf.writestr(inner, xml_bytes)
-            return subprocess.CompletedProcess(
-                argv, returncode=0, stdout='{"status":0,"result":{}}', stderr="",
-            )
-
-        return _side_effect
-
-    def test_empty_input_short_circuits_without_sf_call(self):
-        import metadata_listing  # type: ignore
-        with mock.patch.object(metadata_listing, "_run_retrieve") as mrun, \
-             tempfile.TemporaryDirectory() as d:
-            result = metadata_listing.retrieve_prompt_templates(
-                "org-alias", [], Path(d),
-            )
-        self.assertEqual(result, {})
-        mrun.assert_not_called()
-
-    def test_happy_path_single_template(self):
-        import metadata_listing  # type: ignore
-        xml = (
-            b'<?xml version="1.0" encoding="UTF-8"?>'
-            b'<GenAiPromptTemplate xmlns="http://soap.sforce.com/2006/04/metadata">'
-            b'<developerName>My_Prompt</developerName>'
-            b'<masterLabel>My Prompt</masterLabel>'
-            b'<activeVersionIdentifier>v1</activeVersionIdentifier>'
-            b'<templateVersions>'
-            b'<versionIdentifier>v1</versionIdentifier>'
-            b'<content># ROLE\nHello {{$Input:Query}}</content>'
-            b'<inputs><apiName>Query</apiName><dataType>String</dataType></inputs>'
-            b'</templateVersions>'
-            b'</GenAiPromptTemplate>'
-        )
-        with tempfile.TemporaryDirectory() as d:
-            tmp = Path(d)
-            side_effect = self._run_retrieve_writes_zip({
-                "unpackaged/genAiPromptTemplates/My_Prompt.genAiPromptTemplate": xml,
-                "unpackaged/package.xml": b"<Package/>",
-            })
-            with mock.patch.object(
-                metadata_listing, "_run_retrieve", side_effect=side_effect,
-            ):
-                result = metadata_listing.retrieve_prompt_templates(
-                    "org-alias", ["My_Prompt"], tmp,
-                )
-        self.assertIn("My_Prompt", result)
-        body = result["My_Prompt"]
-        self.assertEqual(body["developerName"], "My_Prompt")
-        self.assertEqual(body["masterLabel"], "My Prompt")
-        self.assertEqual(body["activeVersionIdentifier"], "v1")
-        self.assertEqual(body["content"], "# ROLE\nHello {{$Input:Query}}")
-        self.assertEqual(
-            body["inputs"], [{"name": "Query", "dataType": "String"}],
-        )
-
-    def test_sf_cli_error_returns_empty_dict(self):
-        """Non-zero exit without auth-pattern stderr is swallowed as
-        non-fatal — caller gets an empty dict."""
-        import metadata_listing  # type: ignore
-        failure = subprocess.CompletedProcess(
-            args=[], returncode=1, stdout="", stderr="Error: retrieve blew up",
-        )
-        with tempfile.TemporaryDirectory() as d:
-            with mock.patch.object(
-                metadata_listing, "_run_retrieve", return_value=failure,
-            ):
-                result = metadata_listing.retrieve_prompt_templates(
-                    "org-alias", ["Foo"], Path(d),
-                )
-        self.assertEqual(result, {})
-
-    def test_auth_required_reraises(self):
-        """Non-zero exit WITH auth-pattern stderr raises AuthRequired."""
-        import metadata_listing  # type: ignore
-        from sf_cli import AuthRequired  # type: ignore
-        failure = subprocess.CompletedProcess(
-            args=[], returncode=1, stdout="",
-            stderr="Error: NoOrgAuthenticationError — login required",
-        )
-        with tempfile.TemporaryDirectory() as d:
-            with mock.patch.object(
-                metadata_listing, "_run_retrieve", return_value=failure,
-            ):
-                with self.assertRaises(AuthRequired):
-                    metadata_listing.retrieve_prompt_templates(
-                        "org-alias", ["Foo"], Path(d),
-                    )
-
-    def test_missing_zip_returns_empty_dict(self):
-        import metadata_listing  # type: ignore
-        # _run_retrieve succeeds but leaves no unpackaged.zip on disk.
-        success_no_zip = subprocess.CompletedProcess(
-            args=[], returncode=0, stdout='{"status":0,"result":{}}', stderr="",
-        )
-        with tempfile.TemporaryDirectory() as d:
-            with mock.patch.object(
-                metadata_listing, "_run_retrieve", return_value=success_no_zip,
-            ):
-                result = metadata_listing.retrieve_prompt_templates(
-                    "org-alias", ["Foo"], Path(d),
-                )
-        self.assertEqual(result, {})
-
-    def test_multi_version_picks_active(self):
-        import metadata_listing  # type: ignore
-        xml = (
-            b'<?xml version="1.0" encoding="UTF-8"?>'
-            b'<GenAiPromptTemplate xmlns="http://soap.sforce.com/2006/04/metadata">'
-            b'<developerName>Versioned</developerName>'
-            b'<activeVersionIdentifier>v2</activeVersionIdentifier>'
-            b'<templateVersions>'
-            b'<versionIdentifier>v1</versionIdentifier>'
-            b'<content>OLD</content>'
-            b'</templateVersions>'
-            b'<templateVersions>'
-            b'<versionIdentifier>v2</versionIdentifier>'
-            b'<content>ACTIVE</content>'
-            b'</templateVersions>'
-            b'<templateVersions>'
-            b'<versionIdentifier>v3</versionIdentifier>'
-            b'<content>DRAFT</content>'
-            b'</templateVersions>'
-            b'</GenAiPromptTemplate>'
-        )
-        with tempfile.TemporaryDirectory() as d:
-            tmp = Path(d)
-            side_effect = self._run_retrieve_writes_zip({
-                "unpackaged/genAiPromptTemplates/Versioned.genAiPromptTemplate": xml,
-            })
-            with mock.patch.object(
-                metadata_listing, "_run_retrieve", side_effect=side_effect,
-            ):
-                result = metadata_listing.retrieve_prompt_templates(
-                    "org-alias", ["Versioned"], tmp,
-                )
-        self.assertEqual(result["Versioned"]["content"], "ACTIVE")
-
-    def test_template_with_no_inputs(self):
-        import metadata_listing  # type: ignore
-        xml = (
-            b'<?xml version="1.0" encoding="UTF-8"?>'
-            b'<GenAiPromptTemplate xmlns="http://soap.sforce.com/2006/04/metadata">'
-            b'<developerName>NoInputs</developerName>'
-            b'<activeVersionIdentifier>v1</activeVersionIdentifier>'
-            b'<templateVersions>'
-            b'<versionIdentifier>v1</versionIdentifier>'
-            b'<content>Prompt body</content>'
-            b'</templateVersions>'
-            b'</GenAiPromptTemplate>'
-        )
-        with tempfile.TemporaryDirectory() as d:
-            tmp = Path(d)
-            side_effect = self._run_retrieve_writes_zip({
-                "unpackaged/genAiPromptTemplates/NoInputs.genAiPromptTemplate": xml,
-            })
-            with mock.patch.object(
-                metadata_listing, "_run_retrieve", side_effect=side_effect,
-            ):
-                result = metadata_listing.retrieve_prompt_templates(
-                    "org-alias", ["NoInputs"], tmp,
-                )
-        self.assertEqual(result["NoInputs"]["inputs"], [])
-
-    def test_xml_parse_failure_skips_file_continues(self):
-        """Malformed XML on one template must not prevent sibling
-        templates from surfacing."""
-        import metadata_listing  # type: ignore
-        good_xml = (
-            b'<?xml version="1.0" encoding="UTF-8"?>'
-            b'<GenAiPromptTemplate xmlns="http://soap.sforce.com/2006/04/metadata">'
-            b'<developerName>GoodTpl</developerName>'
-            b'<activeVersionIdentifier>v1</activeVersionIdentifier>'
-            b'<templateVersions>'
-            b'<versionIdentifier>v1</versionIdentifier>'
-            b'<content>Fine</content>'
-            b'</templateVersions>'
-            b'</GenAiPromptTemplate>'
-        )
-        broken_xml = b"<not valid xml"
-        with tempfile.TemporaryDirectory() as d:
-            tmp = Path(d)
-            side_effect = self._run_retrieve_writes_zip({
-                "unpackaged/genAiPromptTemplates/GoodTpl.genAiPromptTemplate": good_xml,
-                "unpackaged/genAiPromptTemplates/Broken.genAiPromptTemplate": broken_xml,
-            })
-            with mock.patch.object(
-                metadata_listing, "_run_retrieve", side_effect=side_effect,
-            ):
-                result = metadata_listing.retrieve_prompt_templates(
-                    "org-alias", ["GoodTpl", "Broken"], tmp,
-                )
-        self.assertIn("GoodTpl", result)
-        self.assertNotIn("Broken", result)
-
-    def test_stale_retrieve_dir_contents_wiped(self):
-        """A prior invocation's `unpackaged.zip` must not be trusted if
-        this run's sf call fails before writing a new one."""
-        import metadata_listing  # type: ignore
-        failure = subprocess.CompletedProcess(
-            args=[], returncode=1, stdout="", stderr="Error: boom",
-        )
-        with tempfile.TemporaryDirectory() as d:
-            tmp = Path(d)
-            # Plant a stale zip pretending a prior run left it.
-            stale = tmp / "prompt_template_retrieve"
-            stale.mkdir(parents=True, exist_ok=True)
-            (stale / "unpackaged.zip").write_bytes(b"stale")
-            with mock.patch.object(
-                metadata_listing, "_run_retrieve", return_value=failure,
-            ):
-                result = metadata_listing.retrieve_prompt_templates(
-                    "org-alias", ["Foo"], tmp,
-                )
-        self.assertEqual(result, {})
-        # Stale file should have been nuked before the sf call.
-        self.assertFalse((stale / "unpackaged.zip").exists())
-
-    def test_retrieve_builds_one_metadata_flag_per_name(self):
-        """Live proof (2026-05-05): `sf project retrieve start` treats a
-        comma-joined `--metadata TypeA:A,TypeA:B` as ONE malformed member
-        name and silently produces a package-xml-only zip. The fix is to
-        repeat `--metadata` once per template. Lock that shape in."""
-        import metadata_listing  # type: ignore
-        captured_argv: list[list[str]] = []
-
-        def _capture(argv, timeout):
-            captured_argv.append(list(argv))
-            return subprocess.CompletedProcess(
-                argv, returncode=0,
-                stdout='{"status":0,"result":{}}', stderr="",
-            )
-
-        with tempfile.TemporaryDirectory() as d:
-            with mock.patch.object(
-                metadata_listing, "_run_retrieve", side_effect=_capture,
-            ):
-                metadata_listing.retrieve_prompt_templates(
-                    "org-alias", ["A", "B", "C"], Path(d),
-                )
-
-        self.assertEqual(len(captured_argv), 1)
-        argv = captured_argv[0]
-        self.assertEqual(argv.count("--metadata"), 3)
-        # Each `--metadata` flag MUST be followed by a single
-        # `GenAiPromptTemplate:<name>` — never a comma-joined string.
-        for name in ("A", "B", "C"):
-            spec = f"GenAiPromptTemplate:{name}"
-            idx = argv.index(spec)
-            self.assertEqual(argv[idx - 1], "--metadata")
-            self.assertNotIn(",", spec)
-
-
-class CollectPromptTemplateNamesTests(unittest.TestCase):
-    """Gap C: `_collect_prompt_template_names` walks topics + plannerActions
-    and returns the set of DeveloperNames that should be passed to
-    `retrieve_prompt_templates`. Defensive against residual 0hf-Ids
-    (normalization missed) so the retrieve CLI doesn't get a malformed
-    spec."""
-
-    def test_collects_topic_action_names(self):
-        bundle = {
-            "topics": [{
-                "actions": [
-                    {"invocationTarget": "Foo_Tpl",
-                     "invocationTargetType": "GenAiPromptTemplate"},
-                    {"invocationTarget": "Bar_Tpl",
-                     "invocationTargetType": "generatePromptResponse"},
-                ],
-            }],
-            "plannerActions": [],
-        }
-        names = main._collect_prompt_template_names(bundle)
-        self.assertEqual(names, {"Foo_Tpl", "Bar_Tpl"})
-
-    def test_collects_planner_action_names(self):
-        bundle = {
-            "topics": [],
-            "plannerActions": [
-                {"invocationTarget": "Planner_Tpl",
-                 "invocationTargetType": "GenAiPromptTemplate"},
-            ],
-        }
-        names = main._collect_prompt_template_names(bundle)
-        self.assertEqual(names, {"Planner_Tpl"})
-
-    def test_skips_non_prompt_ttype(self):
-        bundle = {
-            "topics": [{
-                "actions": [
-                    {"invocationTarget": "MyFlow",
-                     "invocationTargetType": "flow"},
-                    {"invocationTarget": "MyApex",
-                     "invocationTargetType": "apex"},
-                ],
-            }],
-            "plannerActions": [],
-        }
-        names = main._collect_prompt_template_names(bundle)
-        self.assertEqual(names, set())
-
-    def test_skips_residual_0hf_id_targets(self):
-        """If normalization missed an Id (template not in org
-        list-metadata), don't send a malformed spec to retrieve."""
-        bundle = {
-            "topics": [{
-                "actions": [
-                    {"invocationTarget": "0hfUv0000021mCjIAI",
-                     "invocationTargetType": "GenAiPromptTemplate"},
-                    {"invocationTarget": "Clean_Tpl",
-                     "invocationTargetType": "GenAiPromptTemplate"},
-                ],
-            }],
-            "plannerActions": [],
-        }
-        names = main._collect_prompt_template_names(bundle)
-        self.assertEqual(names, {"Clean_Tpl"})
-
-
-class PromptTemplateBodyAttachmentTests(unittest.TestCase):
-    """Gap C: `_stamp_prompt_template_bodies` attaches retrieved body
-    fields onto matching PROMPT_TEMPLATE leaves. Unmatched leaves get
-    `_body_available = False` so the renderer can distinguish a failed
-    retrieve from a successfully-empty body."""
-
-    def test_stamps_body_onto_matching_leaf(self):
-        tree = {
-            "root": {
-                "kind": "BOT_DEFINITION",
-                "children": [{
-                    "kind": "TOPIC", "api_name": "T",
-                    "children": [{
-                        "kind": "GEN_AI_FUNCTION", "api_name": "F",
-                        "children": [{
-                            "kind": "PROMPT_TEMPLATE", "api_name": "Tpl",
-                        }],
-                    }],
-                }],
-            },
-        }
-        bodies = {
-            "Tpl": {
-                "developerName": "Tpl",
-                "masterLabel": "Template One",
-                "activeVersionIdentifier": "v1",
-                "content": "Prompt body",
-                "inputs": [{"name": "Q", "dataType": "String"}],
-            },
-        }
-        main._stamp_prompt_template_bodies(tree["root"], bodies)
-        leaf = tree["root"]["children"][0]["children"][0]["children"][0]
-        self.assertEqual(leaf["master_label"], "Template One")
-        self.assertEqual(leaf["content"], "Prompt body")
-        self.assertEqual(leaf["inputs"], [{"name": "Q", "dataType": "String"}])
-        self.assertTrue(leaf["_body_available"])
-
-    def test_unmatched_leaf_gets_body_available_false(self):
-        tree = {
-            "root": {
-                "kind": "BOT_DEFINITION",
-                "children": [{
-                    "kind": "PROMPT_TEMPLATE", "api_name": "Missing",
-                }],
-            },
-        }
-        main._stamp_prompt_template_bodies(tree["root"], {})
-        self.assertFalse(tree["root"]["children"][0]["_body_available"])
-        self.assertNotIn("content", tree["root"]["children"][0])
-
-    def test_does_not_touch_non_prompt_leaves(self):
-        tree = {
-            "root": {
-                "kind": "BOT_DEFINITION",
-                "children": [
-                    {"kind": "APEX", "api_name": "Cls"},
-                    {"kind": "FLOW", "api_name": "Flw"},
-                ],
-            },
-        }
-        main._stamp_prompt_template_bodies(
-            tree["root"], {"Cls": {"content": "x"}, "Flw": {"content": "y"}},
-        )
-        # Neither APEX nor FLOW leaves gain body fields.
-        self.assertNotIn("content", tree["root"]["children"][0])
-        self.assertNotIn("_body_available", tree["root"]["children"][0])
-        self.assertNotIn("content", tree["root"]["children"][1])
-        self.assertNotIn("_body_available", tree["root"]["children"][1])
-
-
-class TreeChildOrderingTests(unittest.TestCase):
-    """Schema 3.1 (2026-05-05) pins deterministic child ordering at the
-    tree's single source of truth (`finalize.sort_tree_in_place`) so
-    downstream readers see a byte-stable order regardless of Builder
-    reorder operations or SOQL result-set sequencing.
-
-    Contract:
-    - `BOT_DEFINITION.children`: TOPIC nodes first (alpha, case-insensitive);
-      non-topic plannerActions follow as a distinct trailing group.
-    - Each TOPIC's children: alpha by api_name, case-insensitive.
-    - FLOW children untouched — flow-actionCall order is semantically
-      the author's execution sequence.
-    """
-
-    def _sort(self, root: dict) -> dict:
-        from finalize import sort_tree_in_place
-        sort_tree_in_place(root)
-        return root
-
-    def test_topics_sorted_alphabetical_case_insensitive(self):
-        root = {
-            "kind": "BOT_DEFINITION",
-            "api_name": "Bot",
-            "children": [
-                {"kind": "TOPIC", "api_name": "Zeta", "children": []},
-                {"kind": "TOPIC", "api_name": "alpha", "children": []},
-                {"kind": "TOPIC", "api_name": "Mike", "children": []},
-            ],
-        }
-        self._sort(root)
-        names = [c["api_name"] for c in root["children"]]
-        self.assertEqual(names, ["alpha", "Mike", "Zeta"])
-
-    def test_topics_precede_planner_level_actions(self):
-        """Non-topic plannerAction children (e.g. a GEN_AI_FUNCTION hung
-        directly off the planner, no parent TOPIC) MUST render after all
-        TOPIC children, regardless of api_name ordering. The "planner-
-        level actions are a distinct trailing group" convention is load-
-        bearing for humans scanning the rendered tree."""
-        root = {
-            "kind": "BOT_DEFINITION",
-            "api_name": "Bot",
-            "children": [
-                # Non-topic node with an api_name that would sort FIRST
-                # alphabetically — the tier rule must override alpha.
-                {"kind": "GEN_AI_FUNCTION", "api_name": "aaa_action", "children": []},
-                {"kind": "TOPIC", "api_name": "Zeta", "children": []},
-                {"kind": "TOPIC", "api_name": "Mike", "children": []},
-            ],
-        }
-        self._sort(root)
-        kinds = [c["kind"] for c in root["children"]]
-        self.assertEqual(kinds, ["TOPIC", "TOPIC", "GEN_AI_FUNCTION"])
-        # Alpha within the TOPIC tier is preserved.
-        self.assertEqual(root["children"][0]["api_name"], "Mike")
-        self.assertEqual(root["children"][1]["api_name"], "Zeta")
-
-    def test_topic_children_sorted_alphabetical(self):
-        root = {
-            "kind": "BOT_DEFINITION",
-            "api_name": "Bot",
-            "children": [
-                {
-                    "kind": "TOPIC", "api_name": "OnlyTopic",
-                    "children": [
-                        {"kind": "GEN_AI_FUNCTION", "api_name": "Zebra"},
-                        {"kind": "GEN_AI_FUNCTION", "api_name": "apple"},
-                        {"kind": "GEN_AI_FUNCTION", "api_name": "Mango"},
-                    ],
-                },
-            ],
-        }
-        self._sort(root)
-        kids = root["children"][0]["children"]
-        self.assertEqual(
-            [c["api_name"] for c in kids],
-            ["apple", "Mango", "Zebra"],
-        )
-
-    def test_flow_children_order_preserved(self):
-        """FLOW actionCall order is the flow author's execution sequence.
-        sort_tree_in_place does NOT descend into FLOW children."""
-        root = {
-            "kind": "BOT_DEFINITION",
-            "api_name": "Bot",
-            "children": [
-                {
-                    "kind": "TOPIC", "api_name": "T",
-                    "children": [
-                        {
-                            "kind": "GEN_AI_FUNCTION", "api_name": "Fn",
-                            "children": [
-                                {
-                                    "kind": "FLOW", "api_name": "ParentFlow",
-                                    "children": [
-                                        {"kind": "APEX", "api_name": "zzz"},
-                                        {"kind": "APEX", "api_name": "aaa"},
-                                    ],
-                                },
-                            ],
-                        },
-                    ],
-                },
-            ],
-        }
-        self._sort(root)
-        flow = root["children"][0]["children"][0]["children"][0]
-        self.assertEqual(
-            [c["api_name"] for c in flow["children"]],
-            ["zzz", "aaa"],
-        )
-
-    def test_empty_children_noop(self):
-        root = {"kind": "BOT_DEFINITION", "api_name": "Bot", "children": []}
-        self._sort(root)
-        self.assertEqual(root["children"], [])
-
-    def test_missing_root_noop(self):
-        """Defensive — a degenerate tree shouldn't raise."""
-        from finalize import sort_tree_in_place
-        sort_tree_in_place(None)  # type: ignore[arg-type]
-        sort_tree_in_place({})
-
-
-if __name__ == "__main__":
-    unittest.main()