@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/investigating-agentforce-architecture/scripts/main.py

@@ -1,2835 +0,0 @@
-"""Phase 2 Batch 1: pipeline orchestrator for investigating-agentforce-architecture.
-
-Composes Phase 1 primitives (config, rest_client, sf_cli, soql_loader,
-probe_channels, fetch_soql, parallel_retrieve, parse_wave, finalize) into
-the 13-phase flow defined in the plan.
-
-NOT a credential holder. Credentials live in a single mutable cell
-(`_creds_cell`) that both `creds_provider()` and `refresh_fn()` close over.
-Every SOQL call uses `creds_provider` so `retry_on_401`'s refresh path
- can deliver fresh creds into the retry — storing the URL/token
-in function args would defeat the refresh entirely.
-
-Phase ordering:
-  1  parse args                    (Bash harness does phases 1-3 today;
-  2  resolve creds (sf org display)   P2 Batch 1 runs them in-process too)
-  3  probe channels
-  4  resolve bot + version
-  5  cache check
-  6  Wave A (7 parallel Tooling queries, DAG-ordered)
-  7  join Wave A → _bundle_parsed.json-shaped dict
-  8  Wave B (Flow + Apex bodies, parallel)
-  9  parse_wave -> declared_action_tree.json
-  10 render architecture.md (Batch 2 — stubbed)
-  11 finalize (atomic writes + manifest)
-  12 emit RESULT
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-import threading
-import time
-from functools import partial
-from pathlib import Path
-from typing import Callable, Tuple
-
-# Phase 2 Batch 1: all cross-module wiring routes through config so a future
-# relocation of DATA_ROOT / CACHE_ROOT only touches one file.
-from config import (
-    CACHE_TTL_DAYS,
-    DATA_ROOT,
-    SCHEMA_VERSION,
-    build_agent_cache_dir,
-    build_agent_data_dir,
-)
-from rest_client import RestClientError, redact_error
-from sf_cli import AuthRequired, SfCliError, run_sf
-from soql_loader import SoqlParamError
-
-# Phase 2 Batch 1 imports — functional pipeline primitives.
-from fetch_soql import (
-    fetch_apex_bodies_by_ids,
-    fetch_apex_bodies_by_names,
-    fetch_bot_definition_details,
-    fetch_bot_versions,
-    fetch_flow_definition_by_ids,
-    fetch_flow_definition_ids_by_names,
-    fetch_flow_metadata,
-    fetch_functions_by_plugins,
-    fetch_planner_attrs,
-    fetch_planner_bundle_functions,
-    fetch_planner_definition,
-    fetch_plugin_functions,
-    fetch_plugin_instructions,
-    fetch_plugins_by_planner,
-)
-from metadata_listing import (
-    list_prompt_template_metadata,
-    retrieve_prompt_templates,
-)
-from parallel_retrieve import fetch_bodies_parallel
-from parse_bundle import classify_generation
-from probe_channels import probe_channels
-from resolve_invocation_target import looks_like_sf_id, resolve_or_unresolved
-
-
-# ---------------------------------------------------------------------------
-# CLI
-# ---------------------------------------------------------------------------
-
-
-def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
-    p = argparse.ArgumentParser(prog="architecture")
-    p.add_argument("--org-alias", required=True)
-    p.add_argument("--agent", required=True, dest="agent_api_name")
-    p.add_argument("--version", dest="agent_version")
-    p.add_argument("--force", action="store_true", dest="force_refresh")
-    # --reprobe forces a fresh channel-probe run on pipeline start.
-    p.add_argument("--reprobe", action="store_true")
-    p.add_argument("--parallelism", type=int, default=5)
-    p.add_argument("--max-mermaid-nodes", type=int, default=80)
-    p.add_argument("--work-dir", required=True)
-    # Runtime-agnostic path overrides. Defaults are
-    # ~/.vibe/{data,cache}/investigating-agentforce-architecture/.
-    # Other runtimes (AFV OOTB, Codex, Cursor, OpenCode) pass these to land
-    # artifacts under their own distribution layout.
-    p.add_argument(
-        "--data-dir",
-        type=Path,
-        default=None,
-        help="Override data root (default: ~/.vibe/data/investigating-agentforce-architecture).",
-    )
-    p.add_argument(
-        "--cache-dir",
-        type=Path,
-        default=None,
-        help="Override cache root (default: ~/.vibe/cache/investigating-agentforce-architecture).",
-    )
-    return p.parse_args(argv)
-
-
-# ---------------------------------------------------------------------------
-# Three-level rebind for --data-dir / --cache-dir overrides.
-#
-# Python's `from X import Y` snapshots Y into the importer's local namespace.
-# Mutating X.Y later does NOT update the importer's local binding. main.py
-# does `from config import DATA_ROOT, ...` at module top, so without a
-# global rebind, line 2221's `str(DATA_ROOT)` would write the default path
-# even when --data-dir was passed.
-#
-# Levels rebound:
-#   1. paths.DATA_ROOT (the source of truth)
-#   2. config.DATA_ROOT (the re-export)
-#   3. main.DATA_ROOT (THIS module's local snapshot — via global)
-#
-# Plus: config.PROBE_CACHE_ROOT (derived from CACHE_ROOT at import time).
-# ---------------------------------------------------------------------------
-
-
-def _apply_path_overrides(args: argparse.Namespace) -> None:
-    """Apply --data-dir / --cache-dir overrides across all 3 namespace levels.
-
-    Must be called BEFORE any pipeline code reads DATA_ROOT or CACHE_ROOT.
-    """
-    if not (args.data_dir or args.cache_dir):
-        return
-    global DATA_ROOT  # rebind level 1: this module
-    from _shared import runtime, paths
-    import config
-
-    skill_name = "investigating-agentforce-architecture"
-    if args.data_dir:
-        runtime.set_data_root_override(args.data_dir)
-        new_data = runtime.resolve_data_root(skill_name)
-        paths.DATA_ROOT = new_data       # level 2: paths module
-        config.DATA_ROOT = new_data      # level 3: config module re-export
-        DATA_ROOT = new_data              # level 1: main.py local
-    if args.cache_dir:
-        runtime.set_cache_root_override(args.cache_dir)
-        new_cache = runtime.resolve_cache_root(skill_name)
-        paths.CACHE_ROOT = new_cache
-        config.CACHE_ROOT = new_cache
-        config.PROBE_CACHE_ROOT = new_cache / "_channel_probe"
-
-
-# ---------------------------------------------------------------------------
-# Phase 2 Batch 1: credentials
-# ---------------------------------------------------------------------------
-# Single mutable cell read by `creds_provider`. `refresh_fn` rewrites the
-# cell. `retry_on_401` in rest_client invokes refresh_fn for side effect;
-# the next invocation of creds_provider picks up the new tuple. See
-# rest_client 
-
-
-def _build_creds_plumbing(
-    initial_creds: Tuple[str, str],
-    resolve_creds: Callable[[], Tuple[str, str]],
-    *,
-    dedupe_window_s: float = 1.0,
-) -> Tuple[
-    Callable[[], Tuple[str, str]],
-    Callable[[], Tuple[str, str]],
-    "list[Tuple[str, str]]",
-]:
-    """Build the (creds_provider, refresh_fn, creds_cell) triple.
-
-     + `creds_provider` re-reads `creds_cell`
-    on every call so a refresh actually lands in the NEXT SOQL attempt.
-    `refresh_fn` is serialized by an internal `threading.Lock` + a
-    `time.monotonic()` dedupe window — N concurrent 401s against the same
-    stale token collapse to ONE `resolve_creds()` spawn per window. That
-    caps real `sf org display` spawns at roughly 1/second regardless of
-    pool size.
-
-    Extracted from `main()` so the closure is testable without threading
-    a whole pipeline run through argparse + mocks.
-
-    Returns (creds_provider, refresh_fn, creds_cell). The cell is
-    returned so callers/tests can inspect the current tuple directly
-    (it's the single source of truth the provider reads from).
-    """
-    creds_cell: list[Tuple[str, str]] = [initial_creds]
-    lock = threading.Lock()
-    last_refresh_mono = [0.0]
-
-    def creds_provider() -> Tuple[str, str]:
-        return creds_cell[0]
-
-    def refresh_fn() -> Tuple[str, str]:
-        with lock:
-            now = time.monotonic()
-            if now - last_refresh_mono[0] < dedupe_window_s:
-                # Another thread refreshed within the dedupe window — reuse.
-                return creds_cell[0]
-            creds_cell[0] = resolve_creds()
-            last_refresh_mono[0] = now
-            return creds_cell[0]
-
-    return creds_provider, refresh_fn, creds_cell
-
-
-_REDACTION_MARKER_FRAGMENT = "show-access-token"
-"""Substring that uniquely identifies the sf CLI v2 redaction placeholder
-(`"[REDACTED] Use 'sf org auth show-access-token' to view"`). We match on
-this fragment rather than the full literal because the upstream wording
-has shifted between sf CLI builds, but the embedded subcommand name has
-been stable since cli#3560 landed."""
-
-
-def _resolve_creds(org_alias: str) -> Tuple[str, str]:
-    """Resolve (instance_url, access_token) for ``org_alias``.
-
-    Two-path strategy per forcedotcom/cli#3560 (effective 2026-05-27):
-
-      1. **Primary** — call ``sf org display`` for instanceUrl, then
-         ``sf org auth show-access-token`` for the access token. This is
-         the upstream long-term path; ``SF_TEMP_SHOW_SECRETS`` is
-         decommissioned in summer 2026.
-      2. **Fallback** — if the dedicated command isn't shipped in the
-         installed sf CLI version (older releases), fall back to the
-         legacy ``sf org display --verbose`` with the
-         ``SF_TEMP_SHOW_SECRETS=true`` env var that ``run_sf`` injects
-         unconditionally. The fallback is detected by the redaction
-         placeholder appearing in the ``accessToken`` field — exact match
-         on the substring ``show-access-token`` (see
-         ``_REDACTION_MARKER_FRAGMENT``).
-
-    sf_cli.run_sf already redacts stderr on failure paths. Any
-    exception surfaces as `AuthRequired` / `SfCliError`; caller routes
-    through `_emit_fail`.
-    """
-    display_data = run_sf("org_display", ORG_ALIAS=org_alias)
-    display_result = display_data.get("result") or {}
-    instance_url = display_result.get("instanceUrl") or ""
-    if not instance_url:
-        raise AuthRequired(
-            "sf org display returned an incomplete payload (missing instanceUrl)"
-        )
-
-    # Primary path: dedicated command. Catches both the unknown-command
-    # case (older sf CLI) and any AuthRequired surfaced from the recipe.
-    try:
-        token_data = run_sf("show_access_token", ORG_ALIAS=org_alias)
-    except SfCliError:
-        # Older sf CLI versions emit "is not a sf command" on stderr; the
-        # recipe surfaces that as SfCliError. Fall back to the
-        # SF_TEMP_SHOW_SECRETS path via the org_display payload we
-        # already have.
-        access_token = display_result.get("accessToken") or ""
-    else:
-        token_result = token_data.get("result") or {}
-        access_token = token_result.get("accessToken") or ""
-
-    # Defensive fallback: if the dedicated command silently returned an
-    # empty token OR sf CLI redacted the org_display token to the
-    # placeholder, try the org_display payload directly. SF_TEMP_SHOW_SECRETS
-    # is set unconditionally by run_sf so this works as long as the env
-    # var is still honoured by the installed sf CLI.
-    if not access_token or _REDACTION_MARKER_FRAGMENT in access_token:
-        legacy_token = display_result.get("accessToken") or ""
-        if legacy_token and _REDACTION_MARKER_FRAGMENT not in legacy_token:
-            access_token = legacy_token
-
-    if not access_token or _REDACTION_MARKER_FRAGMENT in access_token:
-        raise AuthRequired(
-            "could not retrieve a usable access token via sf org auth "
-            "show-access-token (primary) or sf org display (fallback); "
-            "ensure sf CLI is logged in for this org and either the "
-            "dedicated command is available or SF_TEMP_SHOW_SECRETS is "
-            "still honoured."
-        )
-
-    return instance_url, access_token
-
-
-def _derive_org_ids(org_alias: str) -> Tuple[str, str, str]:
-    """Run `sf org display --json` once more for org_id_15 + org_id_18 +
-    api_version.
-
-    Reused call: the second `sf org display` is cheap and keeps the
-    creds-resolve + org-ids functions uncoupled. When a run passes both
-    through together, the overhead is two spawn()s not one — fine given
-    the whole pipeline is O(seconds).
-
-    Returns (org_id_15, org_id_18, api_version) — all strings. api_version
-    matches `vNN.N` (validated by probe_channels' path builder downstream).
-
-    Gap 3 fix (2026-05-05): returns the 18-char id as well so downstream
-    emit helpers can populate the RESULT-block `ORG_ID_18` field. The
-    18-char value comes straight from `sf org display`; we do NOT compute
-    it from the 15-char prefix.
-    """
-    data = run_sf("org_display", ORG_ALIAS=org_alias)
-    result = data.get("result") or {}
-    org_id_18 = result.get("id") or ""
-    # SF org id is 18 chars; the 15-char slice is the stable prefix used
-    # everywhere in this skill. Fail fast if shorter.
-    if len(org_id_18) < 15:
-        raise SfCliError(f"sf org display returned malformed id (len={len(org_id_18)})")
-    org_id_15 = org_id_18[:15]
-    api_version_raw = str(result.get("apiVersion") or "")
-    # apiVersion from sf CLI is "60.0" shape; our validator requires "v60.0".
-    api_version = api_version_raw if api_version_raw.startswith("v") else f"v{api_version_raw}"
-    return org_id_15, org_id_18, api_version
-
-
-# ---------------------------------------------------------------------------
-# Phase 4: bot resolution (in-process; Data API via fetch_soql)
-# ---------------------------------------------------------------------------
-
-
-def _resolve_bot(
-    agent_api_name: str,
-    explicit_version: str | None,
-    creds_provider: Callable[[], Tuple[str, str]],
-    refresh_fn: Callable[[], Tuple[str, str]],
-    *,
-    api_version: str,
-) -> dict | None:
-    """Resolve (bot_id, version, master_label, planner_name, bot_def_details).
-
-    Returns a dict with:
-        bot_id, version, master_label, version_auto_picked (bool),
-        bot_definition (dict row from BotDefinition details query),
-        all_versions (list of {version, status}) — retained for error ctx.
-
-    Returns None on AGENT_NOT_FOUND. Caller distinguishes by checking the
-    absence — not by catching an exception — to keep the error-emit path
-    a flat if-chain.
-
-    `api_version` is threaded in from
-    `_derive_org_ids`. The Data-API helpers require it — see
-    `rest_client.data_query` for why the old hardcoded `v60.0` was
-    wrong (real orgs run v66 and expose fields v60 does not).
-    """
-    versions = fetch_bot_versions(
-        agent_api_name, creds_provider,
-        api_version=api_version, on_401_refresh=refresh_fn,
-    )
-    if not versions:
-        return None
-
-    # Natural-key sort: v10 > v9 > v2 > v1. Copy the scheme from
-    # resolve_bot.py so multi-version bots rank consistently across the
-    # in-process + shell-out entry points.
-    def _natural_key(v: dict) -> list:
-        import re
-        dn = v.get("DeveloperName") or ""
-        return [int(p) if p.isdigit() else p for p in re.split(r"(\d+)", dn)]
-
-    versions.sort(key=_natural_key, reverse=True)
-
-    picked = None
-    if explicit_version:
-        for v in versions:
-            if v.get("DeveloperName") == explicit_version:
-                picked = v
-                break
-        version_auto_picked = False
-    else:
-        for v in versions:
-            if v.get("Status") == "Active":
-                picked = v
-                break
-        version_auto_picked = True
-
-    if not picked:
-        # Signal "version miss" distinctly from "bot miss". Caller emits
-        # STATUS=AGENT_VERSION_NOT_FOUND with AVAILABLE_VERSIONS.
-        return {
-            "bot_id": "",
-            "version": explicit_version or "",
-            "master_label": "",
-            "version_auto_picked": False,
-            "all_versions": [
-                {
-                    "version": v.get("DeveloperName") or "",
-                    "status": v.get("Status") or "",
-                }
-                for v in versions
-            ],
-            "_version_not_found": True,
-        }
-
-    bot_id = picked.get("BotDefinitionId") or ""
-    bd_node = picked.get("BotDefinition") or {}
-    master_label = bd_node.get("MasterLabel") or ""
-    chosen_version = picked.get("DeveloperName") or ""
-
-    # Phase 2 Batch 1: pull BotDefinition metadata once for the tree's
-    # `agent` block. Non-fatal if the second query fails — tree falls
-    # back to defaults.
-    try:
-        bot_def = fetch_bot_definition_details(
-            agent_api_name, creds_provider,
-            api_version=api_version, on_401_refresh=refresh_fn,
-        )
-    except (RestClientError, SoqlParamError):
-        bot_def = None
-
-    # Planner-name resolution moved to Wave A — `fetch_planner_definition`
-    # now takes (agent_api_name, chosen_version) and performs a chain-LIKE
-    # lookup (`<agent>%\_<vN>`). The canonical planner DeveloperName comes
-    # back on the row and propagates downstream via the bundle join.
-    return {
-        "bot_id": bot_id,
-        "version": chosen_version,
-        "master_label": master_label,
-        "version_auto_picked": version_auto_picked,
-        "bot_definition": bot_def or {},
-    }
-
-
-# ---------------------------------------------------------------------------
-# Phase 5: cache check
-# ---------------------------------------------------------------------------
-
-
-def _cache_is_fresh(cache_dir: Path) -> dict | None:
-    """Return the manifest dict if the cache is hot + fresh, else None.
-
-    Checks: manifest exists, schema_version matches, TTL not expired,
-    data_path is a real file. Any failure degrades to `None` so the
-    caller falls through to the pipeline-run path.
-
-    Mirrors cache_check.py's shell-level logic; duplicated in-process so
-    main.py can branch without shelling out.
-    """
-    import datetime as dt
-
-    manifest_path = cache_dir / "manifest.json"
-    if not manifest_path.is_file():
-        return None
-    try:
-        manifest = json.loads(manifest_path.read_text())
-    except (OSError, json.JSONDecodeError):
-        return None
-
-    if str(manifest.get("schema_version") or "0") != SCHEMA_VERSION:
-        return None
-
-    data_path_s = manifest.get("data_path") or ""
-    if not data_path_s or not Path(data_path_s).is_file():
-        return None
-
-    try:
-        built = dt.datetime.fromisoformat(
-            (manifest.get("built_at_utc") or "").replace("Z", "+00:00")
-        )
-    except ValueError:
-        return None
-
-    age_days = (dt.datetime.now(dt.timezone.utc) - built).days
-    ttl = int(manifest.get("ttl_days") or CACHE_TTL_DAYS)
-    if age_days > ttl:
-        return None
-
-    return manifest
-
-
-# ---------------------------------------------------------------------------
-# Phase 6: Wave A
-# ---------------------------------------------------------------------------
-
-
-def _run_wave_a(
-    agent_api_name: str,
-    version: str | None,
-    creds_provider: Callable[[], Tuple[str, str]],
-    refresh_fn: Callable[[], Tuple[str, str]],
-    *,
-    api_version: str,
-    parallelism: int = 5,
-) -> dict | None:
-    """Run the 7-query GenAi normalized DAG in layered parallel steps.
-
-    A1 resolves the live `GenAiPlannerDefinition` from (agent_api_name,
-    version) via a chain-LIKE lookup — Agentforce's accretive planner
-    naming (v1=`<Agent>`, v2=`<Agent>_v2`, v3=`<Agent>_v2_v3`, ...) means
-    (agent, version) alone is the only reliable key. The resolved row's
-    `DeveloperName` is the canonical planner_name that propagates
-    downstream via the bundle join in `_join_wave_a_to_bundle`.
-
-    Returns a dict:
-        {
-            "planner": {...},
-            "plugins": [...],                  # A2
-            "bundle_functions_join": [...],    # A3
-            "functions": [...],                # A4
-            "instructions": [...],             # A5
-            "plugin_functions_join": [...],    # A6
-            "attrs": [...],                    # A7
-            "unresolved": [...],               # per-channel A2..A6 failures
-        }
-    Returns None if A1 yields no planner row — caller emits a clean
-    error instead of failing later in the join.
-
-    Failures:
-      * RestClientError / HTTPError on A1 → propagates. No graceful path
-        when the planner itself is unreachable.
-      * A2..A6 failures: one failure in a parallel layer doesn't abort
-        the layer (fetch_bodies_parallel's contract). The failed channel
-        yields an empty data list AND an entry in `unresolved` keyed by
-        channel with reason `wave-a-<channel>-failed:<redacted>`. The
-        caller folds these into `tree["_unresolved"]` so STATUS flips
-        to PARTIAL_OK.
-    """
-    # A1 — scalar, no parallelism. api_version threads through
-    # every fetcher; see module docstring + fetch_soql.py.
-    planner = fetch_planner_definition(
-        agent_api_name, version, creds_provider,
-        api_version=api_version, on_401_refresh=refresh_fn,
-    )
-    if not planner:
-        return None
-
-    planner_id = planner.get("Id")
-    if not planner_id:
-        # Planner row missing Id — malformed response. Treat as miss.
-        return None
-
-    unresolved: list[dict] = []
-
-    # Layer 2: A2 + A3 in parallel
-    layer2 = fetch_bodies_parallel(
-        [
-            partial(
-                fetch_plugins_by_planner,
-                planner_id, creds_provider,
-                api_version=api_version, on_401_refresh=refresh_fn,
-            ),
-            partial(
-                fetch_planner_bundle_functions,
-                planner_id, creds_provider,
-                api_version=api_version, on_401_refresh=refresh_fn,
-            ),
-        ],
-        max_workers=parallelism,
-    )
-    plugins = layer2[0][1] if layer2[0][0] else []
-    bundle_functions_join = layer2[1][1] if layer2[1][0] else []
-    for channel, (ok, r) in zip(("plugins", "bundle-functions"), layer2):
-        if not ok:
-            entry = {
-                "kind": "WAVE_A",
-                "channel": channel,
-                "reason": f"wave-a-{channel}-failed:{redact_error(r)}",
-            }
-            preview = getattr(r, "_response_body_preview", None)
-            if preview:
-                entry["response_body_preview"] = preview
-            unresolved.append(entry)
-
-    plugin_ids = [p.get("Id") for p in plugins if p.get("Id")]
-
-    # Layer 3: A4 + A5 + A6 in parallel
-    layer3 = fetch_bodies_parallel(
-        [
-            partial(
-                fetch_functions_by_plugins,
-                plugin_ids, creds_provider,
-                api_version=api_version, on_401_refresh=refresh_fn,
-            ),
-            partial(
-                fetch_plugin_instructions,
-                plugin_ids, creds_provider,
-                api_version=api_version, on_401_refresh=refresh_fn,
-            ),
-            partial(
-                fetch_plugin_functions,
-                plugin_ids, creds_provider,
-                api_version=api_version, on_401_refresh=refresh_fn,
-            ),
-        ],
-        max_workers=parallelism,
-    )
-    functions = layer3[0][1] if layer3[0][0] else []
-    instructions = layer3[1][1] if layer3[1][0] else []
-    plugin_functions_join = layer3[2][1] if layer3[2][0] else []
-    for channel, (ok, r) in zip(
-        ("functions", "instructions", "plugin-functions"), layer3,
-    ):
-        if not ok:
-            entry = {
-                "kind": "WAVE_A",
-                "channel": channel,
-                "reason": f"wave-a-{channel}-failed:{redact_error(r)}",
-            }
-            preview = getattr(r, "_response_body_preview", None)
-            if preview:
-                entry["response_body_preview"] = preview
-            unresolved.append(entry)
-
-    # Layer 4: A7 alone, parent_ids = function_ids. Planner-level attrs
-    # returned 0 rows live (a planner never carries direct attrs) so the
-    # prior `function_ids ∪ {planner_id}` widened the IN-list for no
-    # payoff. Keep the list minimal; dedupe defensively in case a
-    # function Id repeats across bundles.
-    parent_ids = list(dict.fromkeys(
-        f.get("Id") for f in functions if f.get("Id")
-    ))
-    try:
-        attrs = fetch_planner_attrs(
-            parent_ids, creds_provider,
-            api_version=api_version, on_401_refresh=refresh_fn,
-        )
-    except (RestClientError, SoqlParamError):
-        attrs = []
-
-    return {
-        "planner": planner,
-        "plugins": plugins,
-        "bundle_functions_join": bundle_functions_join,
-        "functions": functions,
-        "instructions": instructions,
-        "plugin_functions_join": plugin_functions_join,
-        "attrs": attrs,
-        "unresolved": unresolved,
-    }
-
-
-# ---------------------------------------------------------------------------
-# Phase 7: join Wave A → _bundle_parsed.json shape
-# ---------------------------------------------------------------------------
-
-
-def _join_wave_a_to_bundle(
-    bot_info: dict,
-    wave_a: dict,
-) -> dict:
-    """Reshape normalized Wave-A rows into the bundle dict parse_wave expects.
-
-    `parse_bundle.py` wrote XML-shaped bundles keyed by:
-      plannerType, plannerName, generation, description, masterLabel,
-      topics[{name, actions[{name, invocationTarget, invocationTargetType, ...}]}],
-      plannerActions[{...}]
-
-    We reconstruct that shape from the Tooling rows so parse_wave's
-    `init_tree` + `build_root_children` accept the dict unchanged.
-    """
-    planner = wave_a["planner"]
-    planner_type = planner.get("PlannerType") or ""
-    generation = classify_generation(planner_type)
-
-    functions_by_id = {f.get("Id"): f for f in wave_a["functions"] if f.get("Id")}
-    # Plugin join: map plugin_id → ordered function_ids
-    plugin_fn_map: dict[str, list[str]] = {}
-    for row in wave_a["plugin_functions_join"]:
-        pid = row.get("PluginId")
-        fn_id = row.get("Function")
-        if pid and fn_id:
-            plugin_fn_map.setdefault(pid, []).append(fn_id)
-
-    def _action_dict(fn: dict) -> dict:
-        """Shape a GenAiFunctionDefinition row as a bundle-action dict."""
-        return {
-            "name": fn.get("DeveloperName") or fn.get("Id") or "",
-            "localDeveloperName": fn.get("LocalDeveloperName"),
-            "masterLabel": fn.get("MasterLabel"),
-            "description": fn.get("Description"),
-            "invocationTarget": fn.get("InvocationTarget"),
-            "invocationTargetType": (fn.get("InvocationTargetType") or "").strip(),
-            "source": fn.get("Source"),
-        }
-
-    topics = []
-    for plugin in wave_a["plugins"]:
-        pid = plugin.get("Id")
-        fn_ids = plugin_fn_map.get(pid, [])
-        actions = [
-            _action_dict(functions_by_id[fid])
-            for fid in fn_ids if fid in functions_by_id
-        ]
-        topics.append({
-            "name": plugin.get("DeveloperName") or "",
-            "localDeveloperName": plugin.get("LocalDeveloperName"),
-            "masterLabel": plugin.get("MasterLabel"),
-            "description": plugin.get("Description"),
-            "canEscalate": bool(plugin.get("CanEscalate")),
-            "pluginType": plugin.get("PluginType"),
-            "actions": actions,
-        })
-
-    # A planner never has direct functions (user invariant, verified
-    # against my-org-alias). The previous `PlannerId`-leg query leaked
-    # orphan rows (e.g. `AnswerQuestionsWithKnowledge_*`) as root-level
-    # children. Key retained for downstream compatibility with callers
-    # that read `bundle.get("plannerActions", [])` (parse_wave, a few
-    # _route / _normalize paths); always emits an empty list now.
-    return {
-        "plannerType": planner_type,
-        "plannerName": planner.get("DeveloperName"),
-        "generation": generation,
-        "description": planner.get("Description"),
-        "masterLabel": planner.get("MasterLabel"),
-        "topics": topics,
-        "plannerActions": [],
-    }
-
-
-# ---------------------------------------------------------------------------
-# Phase 8: Wave B (Flow + Apex body fetches)
-# ---------------------------------------------------------------------------
-
-
-def _collect_wave_b_targets(bundle_parsed: dict) -> dict[str, list[str]]:
-    """Walk topics + plannerActions. Return {kind: [invocation_target, ...]}.
-
-    Deduplicates per-kind. Caller routes each kind through the appropriate
-    fetch_soql helper.
-    """
-    apex_names: set[str] = set()
-    apex_ids: set[str] = set()
-    flow_names: set[str] = set()
-    flow_ids: set[str] = set()
-    # Bug 1 fix (2026-05-05): prompt-template targets can arrive as either
-    # DeveloperNames (classic) OR 0hf-prefix Ids (observed in live orgs —
-    # GenAiFunctionDefinition.InvocationTarget sometimes stores the Id).
-    # Route to separate buckets so the Id bucket can be resolved → DevName
-    # by _normalize_prompt_template_id_targets before Wave B retrieve.
-    prompt_template_ids: set[str] = set()
-    unresolved: list[dict] = []
-
-    def _route(target: str, ttype: str) -> None:
-        t = (ttype or "").lower()
-        if not target:
-            return
-        # Bug 1 fix: prompt-template targets can arrive as either
-        # DeveloperNames (classic) OR 0hf-prefix Ids. The Metadata API
-        # retrieve expects DeveloperName; an Id sent verbatim returns
-        # zero members and the target stays in _pending_fetches forever.
-        # Route 0hf Ids into a separate bucket for post-lookup rewrite
-        # via _normalize_prompt_template_id_targets (parallel to the
-        # existing _normalize_flow_id_targets pattern).
-        if t in ("prompttemplate", "generatepromptresponse") or t.startswith("prompt") or t.startswith("genai"):
-            if looks_like_sf_id(target) and target[:3].lower() == "0hf":
-                prompt_template_ids.add(target)
-            return
-        # bundle-declared kinds that never carry an Id.
-        # Standard actions store their identifier (not an SF Id) directly
-        # in InvocationTarget. Skip the ID router entirely — routing them
-        # through resolve_or_unresolved would pollute `_unresolved` with
-        # misleading "invalid-id-format" entries.
-        if t == "standardinvocableaction":
-            return
-        # for flow/apex, only consult the ID router
-        # when the target actually looks like a Salesforce Id. Classic
-        # DeveloperNames (e.g. `MyFlow`, `AGNT_Foo`) don't
-        # match the Id shape and used to land in _unresolved with reason
-        # `invalid-id-format` — noise. Short-circuit: if it's not an Id
-        # shape, skip the router and trust the invocationTargetType.
-        if t in ("flow", "apex") and looks_like_sf_id(target):
-            kind, _channel = resolve_or_unresolved(target, unresolved)
-            if kind == "apex":
-                apex_ids.add(target)
-                return
-            if kind in ("flow_definition", "flow_version"):
-                flow_ids.add(target)
-                return
-            # Unknown Id prefix: resolve_or_unresolved already appended
-            # to `unresolved` with reason "unknown-id-prefix:..." — fall
-            # through; the target stays unrouted and surfaces there.
-            return
-        # Classic path: InvocationTarget is a DeveloperName.
-        if t == "apex":
-            apex_names.add(target)
-        elif t == "flow":
-            flow_names.add(target)
-        # Any other unrecognized type: silently skip. parse_wave will
-        # classify the node as UNKNOWN and it surfaces via _kind_counts.
-
-    for topic in bundle_parsed.get("topics", []) or []:
-        for a in topic.get("actions", []) or []:
-            _route(a.get("invocationTarget") or "",
-                   a.get("invocationTargetType") or "")
-    for a in bundle_parsed.get("plannerActions", []) or []:
-        _route(a.get("invocationTarget") or "",
-               a.get("invocationTargetType") or "")
-
-    return {
-        "apex_names": sorted(apex_names),
-        "apex_ids": sorted(apex_ids),
-        "flow_names": sorted(flow_names),
-        "flow_ids": sorted(flow_ids),
-        "prompt_template_ids": sorted(prompt_template_ids),
-        "_unresolved": unresolved,
-    }
-
-
-def _fetch_wave_b_by_names(
-    *,
-    apex_names: list[str],
-    apex_ids: list[str],
-    flow_names: list[str],
-    flow_ids: list[str],
-    prompt_template_ids: list[str] | None = None,
-    creds_provider: Callable[[], Tuple[str, str]],
-    refresh_fn: Callable[[], Tuple[str, str]],
-    api_version: str,
-    org_alias: str,
-    parallelism: int = 5,
-) -> dict:
-    """Fire body fetches for an explicit set of Apex/Flow identifiers.
-
-    Factored out of `_run_wave_b` so the iterative Wave B caller
-    (`_iterate_wave_b`) can reuse the same shape on subflow rounds —
-    every round's fetch concurrency + error handling semantics must
-    match the initial round exactly (same parallel layer, same
-    unresolved bookkeeping).
-
-    Returns a dict with:
-        apex_rows: list of ApexClass records (Name keyed)
-        flow_def_rows: list of FlowDefinition records (DeveloperName keyed)
-        flow_metadata: dict {version_id: Flow record}
-        unresolved: list of {id, reason} from fetch failures
-
-    Any empty input list short-circuits that branch — callers can pass
-    subsets safely (e.g. subflow rounds typically pass only flow_names).
-    """
-    unresolved: list[dict] = []
-
-    # First hop: resolve IDs back to names where applicable. The results
-    # merge into the same rowsets the name-keyed path produces.
-    # api_version threads into every fetch call.
-    if apex_ids:
-        try:
-            apex_by_id_rows = fetch_apex_bodies_by_ids(
-                apex_ids, creds_provider,
-                api_version=api_version, on_401_refresh=refresh_fn,
-            )
-        except (RestClientError, SoqlParamError) as e:
-            unresolved.append({"kind": "APEX", "reason": f"apex-by-id-failed:{redact_error(e)}"})
-            apex_by_id_rows = []
-    else:
-        apex_by_id_rows = []
-
-    if flow_ids:
-        try:
-            flow_def_by_id_rows = fetch_flow_definition_by_ids(
-                flow_ids, creds_provider,
-                api_version=api_version, on_401_refresh=refresh_fn,
-            )
-        except (RestClientError, SoqlParamError) as e:
-            unresolved.append({"kind": "FLOW", "reason": f"flow-def-by-id-failed:{redact_error(e)}"})
-            flow_def_by_id_rows = []
-    else:
-        flow_def_by_id_rows = []
-
-    # Bug 1 fix: GenAiPromptTemplate is NOT SOQL-queryable (not on Tooling,
-    # not on Data API). The only way to resolve Id → DeveloperName is
-    # `sf org list metadata -m GenAiPromptTemplate`. We list every prompt
-    # template in the org, build an Id → fullName map, filter to the Ids
-    # we care about, and project to the same {Id, DeveloperName} shape the
-    # rest of the pipeline expects.
-    #
-    # Failure is non-fatal — the Ids stay in the bucket and surface in
-    # `_pending_fetches` rather than masking the real issue.
-    if prompt_template_ids:
-        try:
-            rows = list_prompt_template_metadata(org_alias)
-        except (SfCliError, AuthRequired) as e:
-            unresolved.append({
-                "kind": "PROMPT_TEMPLATE",
-                "reason": f"prompt-template-listmetadata-failed:{redact_error(e)}",
-            })
-            rows = []
-        wanted = set(prompt_template_ids)
-        prompt_template_id_rows = [
-            {"Id": r["id"], "DeveloperName": r["fullName"]}
-            for r in rows
-            if isinstance(r, dict) and r.get("id") in wanted and r.get("fullName")
-        ]
-    else:
-        prompt_template_id_rows = []
-
-    # Parallel layer: apex-by-name + flow-def-by-name. Empty name lists
-    # still produce a task, but the downstream fetcher short-circuits on
-    # empty input — the overhead is a single worker dispatch which is
-    # cheaper than conditionally building the task list.
-    name_layer = fetch_bodies_parallel(
-        [
-            partial(
-                fetch_apex_bodies_by_names,
-                apex_names, creds_provider,
-                api_version=api_version, on_401_refresh=refresh_fn,
-            ),
-            partial(
-                fetch_flow_definition_ids_by_names,
-                flow_names, creds_provider,
-                api_version=api_version, on_401_refresh=refresh_fn,
-            ),
-        ],
-        max_workers=parallelism,
-    )
-    apex_name_rows = name_layer[0][1] if name_layer[0][0] else []
-    flow_def_name_rows = name_layer[1][1] if name_layer[1][0] else []
-    # Bug D.1 fix: include the response body preview captured by
-    # rest_client._query_once when the failure was an HTTPError. Without
-    # it, all wave-B 400s collapse to "HTTP Error 400: Bad Request" with
-    # no signal about which name caused the malformed query. Falls back
-    # to None (existing shape) for non-HTTPError failures.
-    for ok, r in (name_layer[0], name_layer[1]):
-        if not ok:
-            entry = {"kind": "APEX_OR_FLOW", "reason": f"wave-b-batch-failed:{redact_error(r)}"}
-            preview = getattr(r, "_response_body_preview", None)
-            if preview:
-                entry["response_body_preview"] = preview
-            unresolved.append(entry)
-
-    apex_rows = [*apex_name_rows, *apex_by_id_rows]
-    flow_def_rows = [*flow_def_name_rows, *flow_def_by_id_rows]
-
-    # Second hop: one Flow.Metadata single-row call per ActiveVersionId.
-    # Parallelized via fetch_bodies_parallel.
-    version_ids = [
-        r.get("ActiveVersionId") for r in flow_def_rows
-        if r.get("ActiveVersionId")
-    ]
-    metadata_tasks = [
-        partial(
-            fetch_flow_metadata,
-            vid, creds_provider,
-            api_version=api_version, on_401_refresh=refresh_fn,
-        )
-        for vid in version_ids
-    ]
-    metadata_results = fetch_bodies_parallel(
-        metadata_tasks, max_workers=parallelism,
-    )
-    flow_metadata: dict[str, dict] = {}
-    for vid, (ok, result_or_exc) in zip(version_ids, metadata_results):
-        if ok and isinstance(result_or_exc, dict):
-            flow_metadata[vid] = result_or_exc
-        elif not ok:
-            unresolved.append({
-                "kind": "FLOW",
-                "version_id": vid,
-                "reason": f"flow-metadata-failed:{redact_error(result_or_exc)}",
-            })
-
-    return {
-        "apex_rows": apex_rows,
-        "flow_def_rows": flow_def_rows,
-        "flow_metadata": flow_metadata,
-        "prompt_template_id_rows": prompt_template_id_rows,
-        "unresolved": unresolved,
-    }
-
-
-def _run_wave_b(
-    bundle_parsed: dict,
-    creds_provider: Callable[[], Tuple[str, str]],
-    refresh_fn: Callable[[], Tuple[str, str]],
-    *,
-    api_version: str,
-    org_alias: str,
-    parallelism: int = 5,
-) -> dict:
-    """Fire body fetches for every Apex/Flow target in the bundle.
-
-    Returns a dict with:
-        apex_rows: list of ApexClass records (Name keyed)
-        flow_def_rows: list of FlowDefinition records (DeveloperName keyed)
-        flow_metadata: dict {version_id: Flow record}
-        unresolved: list of {id, reason} from NGA ID routing
-
-    Only covers the top-level identifiers enumerated directly in
-    `bundle_parsed`. Subflows referenced inside fetched Flow.Metadata
-    bodies (e.g. shared utility flows like `handleFlowFault`) are
-    discovered AFTER this function returns and need a second round of
-    fetching — see `_iterate_wave_b`.
-    """
-    targets = _collect_wave_b_targets(bundle_parsed)
-
-    fetched = _fetch_wave_b_by_names(
-        apex_names=targets["apex_names"],
-        apex_ids=targets["apex_ids"],
-        flow_names=targets["flow_names"],
-        flow_ids=targets["flow_ids"],
-        prompt_template_ids=targets.get("prompt_template_ids") or [],
-        creds_provider=creds_provider,
-        refresh_fn=refresh_fn,
-        api_version=api_version,
-        org_alias=org_alias,
-        parallelism=parallelism,
-    )
-
-    # Merge the routing-layer unresolved entries (unknown-id-prefix, etc.)
-    # with the fetch-layer ones. Order: routing first, fetch second — it's
-    # the order they're discovered in the pipeline.
-    fetched["unresolved"] = [*targets["_unresolved"], *fetched["unresolved"]]
-    return fetched
-
-
-# ---------------------------------------------------------------------------
-# iterative Wave B for nested-subflow discovery
-# ---------------------------------------------------------------------------
-
-
-def _extract_refs_from_flow_metadata(
-    flow_metadata: dict[str, dict],
-) -> Tuple[set[str], set[str]]:
-    """Scan fetched Flow.Metadata dicts for downstream subflow + apex refs.
-
-    Returns `(subflow_names, apex_names)` — both DeveloperName sets.
-    Subsets of the data that `_build_flow_children` walks, narrowed to
-    just the name-extraction we need before we have enough information
-    to build the full child list.
-
-    The extractor is intentionally permissive: missing keys / non-dict
-    entries / blank names all drop silently. Parsing shape mirrors the
-    `Metadata.actionCalls[]` + `Metadata.subflows[]` layout documented
-    in the fetch_flow_metadata docstring and exercised by the
-    CLASSIC_FLOW_METADATA fixture.
-
-    Apex discovery from actionCalls is deliberate — a subflow body CAN
-    reference a new Apex class the parent tree didn't see (actionType
-    == "apex" && actionName == <new class>). Missing those means the
-    iterated tree has unexpanded APEX leaves even after flows resolve.
-    """
-    subflow_names: set[str] = set()
-    apex_names: set[str] = set()
-    for record in (flow_metadata or {}).values():
-        if not isinstance(record, dict):
-            continue
-        md = record.get("Metadata")
-        if not isinstance(md, dict):
-            continue
-        for ac in md.get("actionCalls") or []:
-            if not isinstance(ac, dict):
-                continue
-            if (ac.get("actionType") or "") == "apex":
-                nm = ac.get("actionName") or ""
-                if nm:
-                    apex_names.add(nm)
-        for sub in md.get("subflows") or []:
-            if not isinstance(sub, dict):
-                continue
-            nm = sub.get("flowName") or ""
-            if nm:
-                subflow_names.add(nm)
-    return subflow_names, apex_names
-
-
-def _iterate_wave_b(
-    initial_wave_b: dict,
-    creds_provider: Callable[[], Tuple[str, str]],
-    refresh_fn: Callable[[], Tuple[str, str]],
-    *,
-    api_version: str,
-    org_alias: str,
-    parallelism: int = 5,
-    max_iterations: int = 5,
-) -> dict:
-    """Drive Wave B to fixed-point for nested subflow / apex discovery.
-
-    The initial `_run_wave_b` call only enumerates top-level flow refs
-    from `bundle_parsed`. When those flow bodies reference subflows
-    (via `Metadata.subflows[].flowName`) or new Apex classes (via
-    `Metadata.actionCalls[]`), their bodies were never fetched — so
-    `_build_flow_children` would shape them as leaf nodes with no
-    children even though the real subtree has content.
-
-    Per round:
-      1. Extract subflow + apex refs from the current flow_metadata.
-      2. Diff against already-fetched DeveloperNames.
-      3. If diff empty → converged, return.
-      4. Fetch the diff via `_fetch_wave_b_by_names`.
-      5. Merge into the running wave_b dict.
-      6. Repeat.
-
-    Safety:
-      * `max_iterations=5` — empirically 2-3 is enough on real bots
-        (handleFlowFault etc.). Hit the cap → remaining unfetched names
-        surface via parse_wave's `_pending_fetches.FLOW` (their names
-        are never added to `visited_by_kind["FLOW"]` since they're
-        absent from `flow_def_rows`) and a marker lands in `unresolved`
-        for triage.
-      * Fetch failures in a round are tolerated by `_fetch_wave_b_by_names`
-        — the affected names simply don't make it into `flow_def_rows`
-        and naturally surface as pending.
-
-    Returns the (possibly enlarged) wave_b dict; caller mutates nothing.
-    """
-    if max_iterations <= 0:
-        return initial_wave_b
-
-    # Running state: copy so callers see their original dict untouched.
-    merged_apex_rows = list(initial_wave_b.get("apex_rows") or [])
-    merged_flow_def_rows = list(initial_wave_b.get("flow_def_rows") or [])
-    merged_flow_metadata: dict[str, dict] = dict(
-        initial_wave_b.get("flow_metadata") or {}
-    )
-    merged_unresolved = list(initial_wave_b.get("unresolved") or [])
-
-    fetched_flow_names: set[str] = {
-        r.get("DeveloperName") for r in merged_flow_def_rows
-        if r.get("DeveloperName")
-    }
-    fetched_apex_names: set[str] = {
-        r.get("Name") for r in merged_apex_rows if r.get("Name")
-    }
-
-    for _round in range(max_iterations):
-        subflow_names, apex_names = _extract_refs_from_flow_metadata(
-            merged_flow_metadata
-        )
-        new_flow_names = sorted(subflow_names - fetched_flow_names)
-        new_apex_names = sorted(apex_names - fetched_apex_names)
-        if not new_flow_names and not new_apex_names:
-            # Fixed-point reached.
-            return {
-                "apex_rows": merged_apex_rows,
-                "flow_def_rows": merged_flow_def_rows,
-                "flow_metadata": merged_flow_metadata,
-                "prompt_template_id_rows": initial_wave_b.get(
-                    "prompt_template_id_rows"
-                ) or [],
-                "unresolved": merged_unresolved,
-            }
-
-        round_result = _fetch_wave_b_by_names(
-            apex_names=new_apex_names,
-            apex_ids=[],
-            flow_names=new_flow_names,
-            flow_ids=[],
-            creds_provider=creds_provider,
-            refresh_fn=refresh_fn,
-            api_version=api_version,
-            org_alias=org_alias,
-            parallelism=parallelism,
-        )
-        merged_apex_rows.extend(round_result["apex_rows"])
-        merged_flow_def_rows.extend(round_result["flow_def_rows"])
-        merged_flow_metadata.update(round_result["flow_metadata"])
-        merged_unresolved.extend(round_result["unresolved"])
-
-        # Update fetched-name bookkeeping — we only track rows we
-        # actually received (fetch failure ⇒ not fetched ⇒ will be
-        # retried next round, bounded by the iteration cap).
-        for r in round_result["flow_def_rows"]:
-            nm = r.get("DeveloperName")
-            if nm:
-                fetched_flow_names.add(nm)
-        for r in round_result["apex_rows"]:
-            nm = r.get("Name")
-            if nm:
-                fetched_apex_names.add(nm)
-
-    # Iteration cap hit. Scan one more time to see what's still pending
-    # so we can surface it clearly in `unresolved`. These names will also
-    # land in `_pending_fetches.FLOW` via parse_wave's visited-vs-pending
-    # diff (they're absent from flow_def_rows ⇒ absent from
-    # visited_by_kind["FLOW"]).
-    subflow_names, apex_names = _extract_refs_from_flow_metadata(
-        merged_flow_metadata
-    )
-    still_pending_flows = sorted(subflow_names - fetched_flow_names)
-    still_pending_apex = sorted(apex_names - fetched_apex_names)
-    for nm in still_pending_flows:
-        merged_unresolved.append({
-            "kind": "FLOW",
-            "api_name": nm,
-            "reason": f"wave-b-iteration-cap:{max_iterations}-rounds-exhausted",
-        })
-    for nm in still_pending_apex:
-        merged_unresolved.append({
-            "kind": "APEX",
-            "api_name": nm,
-            "reason": f"wave-b-iteration-cap:{max_iterations}-rounds-exhausted",
-        })
-
-    return {
-        "apex_rows": merged_apex_rows,
-        "flow_def_rows": merged_flow_def_rows,
-        "flow_metadata": merged_flow_metadata,
-        "prompt_template_id_rows": initial_wave_b.get(
-            "prompt_template_id_rows"
-        ) or [],
-        "unresolved": merged_unresolved,
-    }
-
-
-# ---------------------------------------------------------------------------
-# build flow_children from in-memory Wave B metadata
-# ---------------------------------------------------------------------------
-
-
-def _build_flow_children(
-    flow_metadata: dict[str, dict],
-    flow_def_rows: list[dict],
-) -> dict[str, list[dict]]:
-    """Produce `{flow_developer_name: [child_ref, ...]}` from Wave B data.
-
-    Mirrors the shape `parse_wave.harvest_waves` produces from on-disk
-    flow XML, but sourced from the in-memory `Flow.Metadata` JSON that
-    Wave B already fetched via the Tooling REST API (the `Metadata`
-    complexvalue field decodes to a plain dict — see
-    `fetch_flow_metadata` + test fixture `CLASSIC_FLOW_METADATA`). The
-    shape parse_wave expects per child:
-
-        {"kind": "APEX",            "api_name": <name>, "element_name": <elem>}
-        {"kind": "PROMPT_TEMPLATE", "api_name": <name>, "element_name": <elem>}
-        {"kind": "STANDARD_ACTION", "api_name": <name>, "element_name": <elem>,
-         "invocation_type": <actionType>}
-        {"kind": "FLOW",            "api_name": <target_flow_name>,
-         "element_name": <elem>}
-        {"kind": "UNKNOWN",         "api_name": <name>, "element_name": <elem>,
-         "invocation_type": <actionType>}
-
-    Keying is by FlowDefinition.DeveloperName (not ActiveVersionId) —
-    `walk_and_inflate` looks up by `leaf["api_name"]`, which the bundle
-    populates with the Flow's DeveloperName.
-
-    Flows whose ActiveVersionId is missing (inactive / draft-only) or
-    whose fetched metadata was None are silently skipped — they never
-    had a body to walk. actionCall entries missing required fields
-    (`actionType`, `actionName`, or `name`) degrade to UNKNOWN via
-    `classify_action_call`, which already tolerates blanks. Subflow
-    entries missing `flowName` are dropped entirely (no api_name to
-    descend into).
-    """
-    import parse_wave
-
-    # Build ActiveVersionId → DeveloperName lookup. FlowDefinition rows with
-    # no ActiveVersionId (inactive flows, or flows only materializing a
-    # Latest version) skip this map — `flow_metadata` is keyed on
-    # ActiveVersionId too, so they drop out symmetrically.
-    version_to_name: dict[str, str] = {}
-    for row in flow_def_rows or []:
-        vid = row.get("ActiveVersionId")
-        dev_name = row.get("DeveloperName")
-        if vid and dev_name:
-            version_to_name[vid] = dev_name
-
-    flow_children: dict[str, list[dict]] = {}
-    for version_id, record in (flow_metadata or {}).items():
-        flow_name = version_to_name.get(version_id)
-        if not flow_name:
-            # No matching FlowDefinition row — can't key the children list.
-            continue
-        if not isinstance(record, dict):
-            continue
-        md = record.get("Metadata") or {}
-        if not isinstance(md, dict):
-            continue
-
-        children: list[dict] = []
-
-        # actionCalls — each entry has `name` (element id), `actionType`,
-        # `actionName`. `actionType`/`actionName` may be missing on edge
-        # cases (flow authored against an older API version that omits
-        # the field); classify_action_call tolerates empty strings and
-        # will return UNKNOWN.
-        for ac in md.get("actionCalls") or []:
-            if not isinstance(ac, dict):
-                continue
-            element_name = ac.get("name")
-            action_type = ac.get("actionType") or ""
-            action_name = ac.get("actionName") or ""
-            if not element_name:
-                # An unnamed actionCall can't be addressed in the tree
-                # view; drop rather than synthesize a placeholder.
-                continue
-            children.append(
-                parse_wave.classify_action_call(action_type, action_name, element_name)
-            )
-
-        # subflows — each has `name` (element id) + `flowName` (target).
-        for sub in md.get("subflows") or []:
-            if not isinstance(sub, dict):
-                continue
-            element_name = sub.get("name")
-            target = sub.get("flowName")
-            if not element_name or not target:
-                continue
-            children.append({
-                "kind": "FLOW",
-                "element_name": element_name,
-                "api_name": target,
-            })
-
-        flow_children[flow_name] = children
-
-    return flow_children
-
-
-# ---------------------------------------------------------------------------
-# Flow-ID → DeveloperName normalization
-# ---------------------------------------------------------------------------
-
-
-def _normalize_flow_id_targets(bundle_parsed: dict, flow_def_rows: list[dict]) -> None:
-    """Rewrite action invocationTargets that are Flow IDs → DeveloperNames.
-
-    Mutates `bundle_parsed` in place. No-op when no flow_def_rows match.
-
-    Classic bots occasionally store 300Uv-prefix FlowDefinition IDs or
-    301-prefix Flow version IDs in `GenAiFunctionDefinition.InvocationTarget`
-    instead of DeveloperNames. Wave B's FlowDefinition fetch (by-id branch)
-    already resolved those IDs; the rows carry both Id + ActiveVersionId +
-    DeveloperName. We build a bi-directional map (300-id → name, 301-id →
-    name via ActiveVersionId) and rewrite every action whose target is a
-    known ID.
-
-    Unmatched IDs (Flow genuinely not queryable or belongs to a managed
-    package we can't see) stay as-is so the pipeline surfaces them in
-    _pending_fetches rather than silently discarding.
-    """
-    # Build ID → DeveloperName lookup from both Id and ActiveVersionId keys.
-    id_to_name: dict[str, str] = {}
-    for row in flow_def_rows or []:
-        dev_name = row.get("DeveloperName")
-        if not dev_name:
-            continue
-        row_id = row.get("Id")
-        if row_id:
-            id_to_name[row_id] = dev_name
-        active_ver = row.get("ActiveVersionId")
-        if active_ver:
-            id_to_name[active_ver] = dev_name
-
-    if not id_to_name:
-        return
-
-    def _rewrite_action(action: dict) -> None:
-        target = action.get("invocationTarget")
-        ttype = (action.get("invocationTargetType") or "").strip().lower()
-        if ttype != "flow" or not isinstance(target, str):
-            return
-        resolved = id_to_name.get(target)
-        if resolved:
-            # Preserve the original ID for traceability — consumers that
-            # need it can still read `_original_invocation_target_id`.
-            action["_original_invocation_target_id"] = target
-            action["invocationTarget"] = resolved
-
-    for topic in bundle_parsed.get("topics") or []:
-        for action in topic.get("actions") or []:
-            _rewrite_action(action)
-    for action in bundle_parsed.get("plannerActions") or []:
-        _rewrite_action(action)
-
-
-def _normalize_prompt_template_id_targets(
-    bundle_parsed: dict, prompt_template_rows: list[dict],
-) -> None:
-    """Rewrite action invocationTargets that are GenAiPromptTemplate Ids
-    (0hf-prefix) → DeveloperNames.
-
-    Bug 1 fix (2026-05-05): when GenAiFunctionDefinition.InvocationTarget
-    stores a 0hf-prefix prompt template Id instead of a DeveloperName
-    (observed in live my-org-alias org), the Metadata API retrieve
-    can't match it — Wave B enqueues the Id as-is and the template
-    stays in `_pending_fetches.PROMPT_TEMPLATE` forever.
-
-    Parallel to `_normalize_flow_id_targets`: build an Id → DeveloperName
-    map from `list_prompt_template_metadata` rows (projected to
-    {Id, DeveloperName} shape by `_fetch_wave_b_by_names`), mutate the
-    bundle in place. Unmatched Ids stay as-is (genuinely missing template,
-    or the Metadata API listing failed).
-    """
-    id_to_name: dict[str, str] = {}
-    for row in prompt_template_rows or []:
-        row_id = row.get("Id")
-        dev_name = row.get("DeveloperName")
-        if row_id and dev_name:
-            id_to_name[row_id] = dev_name
-
-    if not id_to_name:
-        return
-
-    def _rewrite_action(action: dict) -> None:
-        target = action.get("invocationTarget")
-        ttype = (action.get("invocationTargetType") or "").strip().lower()
-        # Match the same ttype predicate used by _route for prompt-template
-        # targets — otherwise a Flow action whose target happens to collide
-        # with a prompt template Id (unlikely but possible) wouldn't be
-        # caught. _route's predicate is the authority on what's a prompt.
-        is_prompt_ttype = (
-            ttype in ("prompttemplate", "generatepromptresponse")
-            or ttype.startswith("prompt")
-            or ttype.startswith("genai")
-        )
-        if not is_prompt_ttype or not isinstance(target, str):
-            return
-        resolved = id_to_name.get(target)
-        if resolved:
-            action["_original_invocation_target_id"] = target
-            action["invocationTarget"] = resolved
-
-    for topic in bundle_parsed.get("topics") or []:
-        for action in topic.get("actions") or []:
-            _rewrite_action(action)
-    for action in bundle_parsed.get("plannerActions") or []:
-        _rewrite_action(action)
-
-
-def _normalize_apex_id_targets(
-    bundle_parsed: dict, apex_by_id_rows: list[dict],
-) -> None:
-    """Rewrite action invocationTargets that are Apex (01p-prefix Id)
-    -> ApexClass Name.
-
-    Gap B fix (2026-05-05): when GenAiFunctionDefinition.InvocationTarget
-    stores a 01p-prefix ApexClass Id instead of a class Name (observed in
-    live my-org-alias org, e.g. 01p000000000000AAA ->
-    MyController), downstream Wave B body retrieval enqueues
-    the Id as-is into `_pending_fetches.APEX` and the tree renders the raw
-    Id instead of the class name.
-
-    Parallel to `_normalize_prompt_template_id_targets`: build an Id ->
-    Name map from `fetch_apex_bodies_by_ids` rows (ApexClass uses `Name`,
-    not `DeveloperName`), mutate the bundle in place. Unmatched Ids stay
-    as-is (genuinely missing class, or the by-Id fetch failed).
-    """
-    id_to_name: dict[str, str] = {}
-    for row in apex_by_id_rows or []:
-        row_id = row.get("Id")
-        class_name = row.get("Name")
-        if row_id and class_name:
-            id_to_name[row_id] = class_name
-
-    if not id_to_name:
-        return
-
-    def _rewrite_action(action: dict) -> None:
-        target = action.get("invocationTarget")
-        ttype = (action.get("invocationTargetType") or "").strip().lower()
-        # Match the same ttype predicate used by _route for apex targets.
-        # Mirrors the prompt-template normalizer's ttype gate so a Flow
-        # action whose target happens to collide with an ApexClass Id
-        # (unlikely but possible) isn't miscaught.
-        is_apex_ttype = ttype in ("apex", "apexaction") or ttype.startswith("apex")
-        if not is_apex_ttype or not isinstance(target, str):
-            return
-        # Prefix-gate the rewrite to the ApexClass key prefix (01p).
-        # Mirrors the `target[:3].lower() == "01p"` check in _collect_wave_b_targets.
-        if target[:3].lower() != "01p":
-            return
-        resolved = id_to_name.get(target)
-        if resolved:
-            action["_original_invocation_target_id"] = target
-            action["invocationTarget"] = resolved
-
-    for topic in bundle_parsed.get("topics") or []:
-        for action in topic.get("actions") or []:
-            _rewrite_action(action)
-    for action in bundle_parsed.get("plannerActions") or []:
-        _rewrite_action(action)
-
-
-# ---------------------------------------------------------------------------
-# Signature derivation — Apex + Flow (rendered in Section 7 of architecture.md)
-# ---------------------------------------------------------------------------
-
-
-def _derive_apex_signature(apex_row: dict) -> str | None:
-    """Return a compact one-line signature string for an Apex class, or None.
-
-    Sourced from `SymbolTable.methods[]` on the ApexClass Tooling row. Picks
-    the "primary" method:
-      1. Prefer a method annotated `@InvocableMethod` (what Flow / Agentforce
-         actually invoke — typically exactly one per Agentforce-relevant
-         class).
-      2. Else prefer a `global` or `public static` non-constructor method.
-      3. Else fall back to the first method in SymbolTable source order.
-
-    Format: `<modifiers> <returnType> <name>(<p1_type> <p1_name>, ...)`. If
-    `returnType` is absent (constructor shape) it's omitted. Parameters are
-    rendered as `<type> <name>`; empty param list becomes `()`.
-
-    Returns None when `SymbolTable` is missing/empty or contains no method
-    candidates. Body parsing is intentionally NOT attempted — too brittle.
-    """
-    if not isinstance(apex_row, dict):
-        return None
-    symbol_table = apex_row.get("SymbolTable")
-    if not isinstance(symbol_table, dict):
-        return None
-    methods = symbol_table.get("methods")
-    if not isinstance(methods, list) or not methods:
-        return None
-
-    def _is_invocable(m: dict) -> bool:
-        anns = m.get("annotations") or []
-        for ann in anns:
-            if isinstance(ann, dict):
-                if (ann.get("name") or "").lower() == "invocablemethod":
-                    return True
-            elif isinstance(ann, str):
-                if ann.lower() == "invocablemethod":
-                    return True
-        return False
-
-    def _is_constructor(m: dict) -> bool:
-        # SymbolTable represents constructors via `constructors[]`, but some
-        # payloads fold them into `methods[]` with a null/empty returnType.
-        rt = m.get("returnType")
-        return not rt
-
-    def _is_promoted(m: dict) -> bool:
-        mods = [str(x).lower() for x in (m.get("modifiers") or [])]
-        if _is_constructor(m):
-            return False
-        if "global" in mods:
-            return True
-        if "public" in mods and "static" in mods:
-            return True
-        return False
-
-    candidates = [m for m in methods if isinstance(m, dict)]
-    if not candidates:
-        return None
-
-    primary: dict | None = next((m for m in candidates if _is_invocable(m)), None)
-    if primary is None:
-        primary = next((m for m in candidates if _is_promoted(m)), None)
-    if primary is None:
-        # Last-resort: first method. Skip if it's purely a private/local helper
-        # with no chance of being the public entry point — those add noise.
-        primary = candidates[0]
-        mods = [str(x).lower() for x in (primary.get("modifiers") or [])]
-        if "private" in mods and not _is_invocable(primary):
-            return None
-
-    modifiers = [str(x) for x in (primary.get("modifiers") or [])]
-    return_type = primary.get("returnType") or ""
-    name = primary.get("name") or ""
-    if not name:
-        return None
-
-    params_out: list[str] = []
-    for p in primary.get("parameters") or []:
-        if not isinstance(p, dict):
-            continue
-        p_type = p.get("type") or ""
-        p_name = p.get("name") or ""
-        if p_type and p_name:
-            params_out.append(f"{p_type} {p_name}")
-        elif p_type:
-            params_out.append(p_type)
-        elif p_name:
-            params_out.append(p_name)
-    params_str = ", ".join(params_out)
-
-    parts: list[str] = []
-    if modifiers:
-        parts.append(" ".join(modifiers))
-    if return_type:
-        parts.append(return_type)
-    parts.append(f"{name}({params_str})")
-    return " ".join(parts)
-
-
-def _derive_flow_signature(flow_metadata_record: dict) -> str | None:
-    """Return a compact signature string for a Flow, or None.
-
-    Sourced from `Metadata.variables[]` on the Tooling Flow record
-    (`fetch_flow_metadata` output — the `flow_metadata_record` is the
-    full Tooling row, and `.Metadata` is the decoded complexvalue dict).
-
-    Flow variables carry boolean `isInput` / `isOutput` flags. A variable
-    with `isInput: true` contributes to the `in:` side; `isOutput: true`
-    contributes to the `out:` side; a variable can set both (round-trip)
-    and will appear on BOTH sides. Variables with neither flag are locals
-    and are skipped.
-
-    Format: `in: <name>: <type>[, ...] | out: <name>: <type>[, ...]`.
-    If only one side has entries, only that side is emitted. Returns None
-    when neither side has entries.
-
-    Collection variables render as `List<<dataType>>`. sObject variables
-    use the `objectType` field (e.g. `List<Case>` rather than
-    `List<SObject>`). Insertion order from `variables[]` is preserved —
-    we deliberately do not sort, to keep the signature aligned with the
-    flow author's declared order.
-    """
-    if not isinstance(flow_metadata_record, dict):
-        return None
-    md = flow_metadata_record.get("Metadata")
-    if not isinstance(md, dict):
-        # Test convenience: accept a bare Metadata dict, not just the full row.
-        if "variables" in flow_metadata_record:
-            md = flow_metadata_record
-        else:
-            return None
-
-    variables = md.get("variables") or []
-    if not isinstance(variables, list):
-        return None
-
-    def _render_type(var: dict) -> str:
-        data_type = (var.get("dataType") or "").strip()
-        obj_type = (var.get("objectType") or "").strip()
-        apex_class = (var.get("apexClass") or "").strip()
-        dt_lower = data_type.lower()
-        # sObject variables carry the concrete SObject name in `objectType`
-        # (e.g. `Case`). Apex-typed variables carry the concrete class name
-        # in `apexClass` (e.g. `CX_OrgSelector.Org`). Without the apexClass
-        # branch, collections of Apex-typed values render as the useless
-        # `List<Apex>` instead of `List<CX_OrgSelector.Org>`.
-        if dt_lower == "sobject" and obj_type:
-            base = obj_type
-        elif dt_lower == "apex" and apex_class:
-            base = apex_class
-        else:
-            base = data_type or "Object"
-        if var.get("isCollection"):
-            return f"List<{base}>"
-        return base
-
-    inputs: list[str] = []
-    outputs: list[str] = []
-    for v in variables:
-        if not isinstance(v, dict):
-            continue
-        name = v.get("name")
-        if not name:
-            continue
-        rendered = f"{name}: {_render_type(v)}"
-        if v.get("isInput"):
-            inputs.append(rendered)
-        if v.get("isOutput"):
-            outputs.append(rendered)
-
-    if not inputs and not outputs:
-        return None
-
-    parts: list[str] = []
-    if inputs:
-        parts.append("in: " + ", ".join(inputs))
-    if outputs:
-        parts.append("out: " + ", ".join(outputs))
-    return " | ".join(parts)
-
-
-def _stamp_signatures(
-    node: dict,
-    apex_sigs: dict[str, str],
-    flow_sigs: dict[str, str],
-    flow_reasons: dict[str, str] | None = None,
-) -> None:
-    """Recursively stamp `node["signature"]` on matching APEX / FLOW leaves.
-
-    Shared utility flows / helpers that appear in multiple branches all
-    receive the same stamped signature — they point at the same
-    FlowDefinition / ApexClass, so the signature is the same.
-
-    Gap 2 fix (2026-05-05): when a FLOW leaf has no signature but *does*
-    have an explanation in `flow_reasons` (e.g. managed-pkg body not
-    retrievable via the Data API fallback), stamp `node["_signature_reason"]`
-    so the renderer can distinguish a silent hole from a known limitation.
-    """
-    if not isinstance(node, dict):
-        return
-    kind = node.get("kind")
-    name = node.get("api_name")
-    if kind == "APEX" and name and name in apex_sigs:
-        node["signature"] = apex_sigs[name]
-    elif kind == "FLOW" and name:
-        if name in flow_sigs:
-            node["signature"] = flow_sigs[name]
-        elif flow_reasons and name in flow_reasons:
-            node["_signature_reason"] = flow_reasons[name]
-    for child in node.get("children") or []:
-        _stamp_signatures(child, apex_sigs, flow_sigs, flow_reasons)
-
-
-# ---------------------------------------------------------------------------
-# Gap C (2026-05-05): prompt template body retrieve + stamp
-# ---------------------------------------------------------------------------
-
-
-def _is_prompt_ttype(ttype: str) -> bool:
-    """Mirror the ttype predicate used by `_route` /
-    `_normalize_prompt_template_id_targets` so collection + rewrite +
-    retrieve all recognize the same action kind."""
-    t = (ttype or "").strip().lower()
-    return (
-        t in ("prompttemplate", "generatepromptresponse")
-        or t.startswith("prompt")
-        or t.startswith("genai")
-    )
-
-
-def _collect_prompt_template_names(bundle_parsed: dict) -> set[str]:
-    """Walk topics + plannerActions, collect prompt-template DeveloperNames.
-
-    Called AFTER `_normalize_prompt_template_id_targets` — any 0hf-prefix
-    Id that resolved via Wave B's Id-list-metadata should already be a
-    DeveloperName. Defensive: drop anything that still looks Id-shaped
-    (0hf prefix) so we don't send a malformed
-    `GenAiPromptTemplate:0hfUv...` spec to the retrieve CLI.
-    """
-    names: set[str] = set()
-
-    def _collect(action: dict) -> None:
-        ttype = action.get("invocationTargetType") or ""
-        if not _is_prompt_ttype(ttype):
-            return
-        target = action.get("invocationTarget")
-        if not isinstance(target, str) or not target:
-            return
-        if target[:3].lower() == "0hf":
-            # Id never got rewritten — the list_metadata lookup missed it
-            # (managed-pkg template, permission issue). Skip; it stays in
-            # _pending_fetches with the Id as the key.
-            return
-        names.add(target)
-
-    for topic in bundle_parsed.get("topics") or []:
-        for action in topic.get("actions") or []:
-            _collect(action)
-    for action in bundle_parsed.get("plannerActions") or []:
-        _collect(action)
-    return names
-
-
-def _collect_flow_nested_prompt_template_names(
-    node: dict,
-    already_retrieved: dict[str, dict],
-    out: set[str],
-) -> None:
-    """Walk the finalized tree and collect PROMPT_TEMPLATE leaves whose
-    body wasn't stamped during the bundle-scoped retrieve.
-
-    Bundle-scoped `_collect_prompt_template_names` only sees prompt
-    templates declared as top-level topic/planner InvocationTargets.
-    Prompt templates referenced from inside a Flow (via a
-    `generatePromptResponse` actionCall) are discovered later during
-    Wave B's BFS of flow XML and end up as PROMPT_TEMPLATE leaves in the
-    tree — but their names never reached the first retrieve, so their
-    `_body_available` stays False and content is silently lost.
-
-    Defensive: drop 0hf-Id-shape names (managed-pkg templates whose Id
-    never rewrote to a DeveloperName) — sending
-    `GenAiPromptTemplate:0hfUv...` to the retrieve CLI yields a
-    malformed spec; the Id stays in `_pending_fetches.PROMPT_TEMPLATE`
-    as intended.
-    """
-    if not isinstance(node, dict):
-        return
-    if node.get("kind") == "PROMPT_TEMPLATE":
-        name = node.get("api_name")
-        if (
-            isinstance(name, str)
-            and name
-            and name[:3].lower() != "0hf"
-            and not node.get("_body_available", False)
-        ):
-            body = already_retrieved.get(name)
-            if not (body and body.get("content")):
-                out.add(name)
-    for child in node.get("children") or []:
-        _collect_flow_nested_prompt_template_names(child, already_retrieved, out)
-
-
-def _stamp_prompt_template_bodies(
-    node: dict,
-    bodies: dict[str, dict],
-) -> None:
-    """Recursively stamp prompt-template body fields onto matching
-    PROMPT_TEMPLATE leaves.
-
-    For each leaf whose `api_name` matches a key in `bodies`, attach:
-      - master_label, content, inputs, active_version_identifier
-      - _body_available = True
-
-    Leaves with no matching body get `_body_available = False` so the
-    renderer can distinguish "no body retrieved" from "body successfully
-    empty". Shared templates appearing in multiple branches receive the
-    same stamped body (they reference the same DeveloperName).
-    """
-    if not isinstance(node, dict):
-        return
-    kind = node.get("kind")
-    name = node.get("api_name")
-    if kind == "PROMPT_TEMPLATE" and name:
-        body = bodies.get(name)
-        if body:
-            node["master_label"] = body.get("masterLabel")
-            node["content"] = body.get("content")
-            node["inputs"] = body.get("inputs") or []
-            node["active_version_identifier"] = body.get(
-                "activeVersionIdentifier"
-            )
-            node["_body_available"] = True
-        else:
-            node["_body_available"] = False
-    for child in node.get("children") or []:
-        _stamp_prompt_template_bodies(child, bodies)
-
-
-# ---------------------------------------------------------------------------
-# Phase 9: build declared_action_tree.json via parse_wave primitives
-# ---------------------------------------------------------------------------
-
-
-def _run_parse_wave(
-    bot_info: dict,
-    bundle_parsed: dict,
-    wave_b: dict,
-    args: argparse.Namespace,
-    work_dir: Path,
-) -> dict:
-    """Invoke parse_wave's init_tree + root-children builder in-process.
-
-    parse_wave was written to be invoked as a subprocess with env vars
-    carrying AGENT_API_NAME / AGENT_VERSION / BOT_ID / etc. For Phase 2
-    Batch 1 we set those env vars transiently and call the module's
-    public helpers — no subprocess overhead, same behavior.
-    """
-    import parse_wave
-
-    # parse_wave reads these via os.environ.
-    prior_env = {
-        "AGENT_API_NAME": os.environ.get("AGENT_API_NAME"),
-        "AGENT_VERSION": os.environ.get("AGENT_VERSION"),
-        "BOT_ID": os.environ.get("BOT_ID"),
-        "BOT_MASTER_LABEL": os.environ.get("BOT_MASTER_LABEL"),
-        "VERSION_AUTO_PICKED": os.environ.get("VERSION_AUTO_PICKED"),
-    }
-    os.environ["AGENT_API_NAME"] = args.agent_api_name
-    os.environ["AGENT_VERSION"] = bot_info["version"]
-    os.environ["BOT_ID"] = bot_info["bot_id"]
-    os.environ["BOT_MASTER_LABEL"] = bot_info["master_label"]
-    os.environ["VERSION_AUTO_PICKED"] = "true" if bot_info["version_auto_picked"] else "false"
-
-    try:
-        # Persist the bundle for parse_wave's finalize_cap path.
-        bundle_out = work_dir / "_bundle_parsed.json"
-        bundle_out.write_text(json.dumps(bundle_parsed, indent=2))
-
-        # Persist a fake _bot_definition.json so init_tree reads real
-        # metadata for the agent block.
-        bd_file = work_dir / "_bot_definition.json"
-        bd_file.write_text(json.dumps({
-            "result": {"records": [bot_info.get("bot_definition") or {}]},
-        }))
-
-        tree = parse_wave.init_tree(work_dir, bundle_parsed)
-
-        # Build root children + track bundle-derived BFS refs.
-        # call the public `empty_kind_sets` /
-        # `BFS_KINDS` symbols — reaching into `parse_wave._*` reopened the
-        # leading-underscore surface that closed for `redact_text`.
-        visited_by_kind = parse_wave.empty_kind_sets()
-        aux_visited: set[tuple[str, str]] = set()
-        children, bundle_refs = parse_wave.build_root_children(
-            bundle_parsed, visited_by_kind, aux_visited,
-        )
-        tree["root"]["children"] = children
-
-        # Merge Flow metadata into flow_children. parse_wave wants this as
-        # `{flow_name: [child_refs]}`. Build it from the in-memory
-        # `Flow.Metadata` JSON Wave B already fetched — the Tooling REST
-        # API decodes the `Metadata` complexvalue field into a plain dict,
-        # so no XML parsing is needed (see `_build_flow_children` +
-        # fixture `CLASSIC_FLOW_METADATA`). Without this, every FLOW leaf
-        # in `metadata_tree.json` shipped with `children: []` and the
-        # user's recursive-tree view was flat.
-        flow_children = _build_flow_children(
-            wave_b["flow_metadata"], wave_b["flow_def_rows"],
-        )
-
-        # BFS routing for bundle refs.
-        pending_by_kind, _cycles = parse_wave.bfs_step(
-            parse_wave.empty_kind_sets(), visited_by_kind, bundle_refs,
-        )
-
-        # Depth-cap accumulator threaded through inflate.
-        depth_cap_pending = parse_wave.empty_kind_sets()
-        parse_wave.walk_and_inflate(
-            tree["root"], flow_children, pending_out=depth_cap_pending,
-        )
-
-        # Merge any Apex / Flow we actually fetched into visited — they
-        # no longer count as pending.
-        for row in wave_b["apex_rows"]:
-            nm = row.get("Name")
-            if nm:
-                visited_by_kind["APEX"].add(nm)
-        for row in wave_b["flow_def_rows"]:
-            nm = row.get("DeveloperName")
-            if nm:
-                visited_by_kind["FLOW"].add(nm)
-        # Gap C (2026-05-05): prompt templates whose bodies we retrieved
-        # count as visited and must drop out of _pending_fetches.
-        # Templates the retrieve didn't return (permission / managed-pkg /
-        # retrieve failure) stay out of `visited` so they surface there,
-        # mirroring the Flow-by-name "no rows = stays pending" pattern.
-        prompt_template_bodies = wave_b.get("prompt_template_bodies") or {}
-        for name in prompt_template_bodies:
-            if name:
-                visited_by_kind["PROMPT_TEMPLATE"].add(name)
-
-        # Stamp Apex / Flow signatures onto every matching tree node so
-        # render_architecture.py can populate Section 7. Wave B already
-        # fetched SymbolTable (Apex) + Metadata (Flow); we just project it
-        # onto `{kind, api_name}` leaves here. Shared utility flows /
-        # helpers that appear in multiple positions all receive the same
-        # stamped signature — that's the correct behavior (same definition).
-        apex_sigs: dict[str, str] = {}
-        for row in wave_b["apex_rows"]:
-            nm = row.get("Name")
-            if not nm:
-                continue
-            sig = _derive_apex_signature(row)
-            if sig:
-                apex_sigs[nm] = sig
-
-        flow_sigs: dict[str, str] = {}
-        # Gap 2 fix (2026-05-05): explain silent signature holes. Managed
-        # flows come back from `fetch_flow_definition_ids_by_names` via the
-        # FlowDefinitionView fallback with _source="FlowDefinitionView",
-        # ActiveVersionId=None, _body_available=False — by design, since
-        # managed-pkg flow bodies are IP-protected. Previously every such
-        # row produced an unexplained "_Signature not captured._" in the
-        # rendered markdown. Now we surface the structural reason.
-        #
-        # For the generic "no usable metadata record" case (Tooling row
-        # present but flow_metadata missing — e.g. metadata fetch failed
-        # or the flow has no active version at all) we also stamp a reason
-        # so the renderer never silently drops the node.
-        flow_reasons: dict[str, str] = {}
-        flow_metadata_by_vid = wave_b.get("flow_metadata") or {}
-        for row in wave_b["flow_def_rows"]:
-            dev_name = row.get("DeveloperName") or row.get("_bare_developer_name")
-            if not dev_name:
-                continue
-            source = row.get("_source") or ""
-            if source == "FlowDefinitionView":
-                ns = row.get("NamespacePrefix") or ""
-                reason = (
-                    f"managed-package (ns={ns}); body not retrievable via Tooling/Metadata API"
-                    if ns
-                    else "managed-package; body not retrievable via Tooling/Metadata API"
-                )
-                flow_reasons[dev_name] = reason
-                continue
-            active_ver = row.get("ActiveVersionId")
-            if not active_ver:
-                flow_reasons[dev_name] = "no active version"
-                continue
-            md_record = flow_metadata_by_vid.get(active_ver)
-            if not md_record:
-                flow_reasons[dev_name] = "flow metadata fetch returned no record"
-                continue
-            sig = _derive_flow_signature(md_record)
-            if sig:
-                flow_sigs[dev_name] = sig
-            else:
-                flow_reasons[dev_name] = "flow metadata has no in/out params"
-
-        _stamp_signatures(tree["root"], apex_sigs, flow_sigs, flow_reasons)
-
-        # Gap C: stamp retrieved prompt-template bodies onto the tree.
-        # Leaves with a matching body gain content/master_label/inputs;
-        # leaves without get `_body_available = False` so the renderer
-        # can distinguish "retrieve missed" from "body truly absent".
-        _stamp_prompt_template_bodies(tree["root"], prompt_template_bodies)
-
-        for kind in parse_wave.BFS_KINDS:
-            pending_by_kind[kind] |= depth_cap_pending.get(kind, set())
-
-        depth_cap_tripped = any(depth_cap_pending[k] for k in parse_wave.BFS_KINDS)
-
-        tree["_pending_fetches"] = {
-            k: sorted(pending_by_kind.get(k, set()) - visited_by_kind.get(k, set()))
-            for k in parse_wave.BFS_KINDS
-        }
-
-        any_pending = any(tree["_pending_fetches"][k] for k in parse_wave.BFS_KINDS)
-        if depth_cap_tripped:
-            tree["_partial"] = True
-            tree["_partial_reason"] = "max-depth-cap"
-        elif any_pending:
-            tree["_partial"] = True
-            if not tree.get("_partial_reason"):
-                tree["_partial_reason"] = "pending-refs"
-        else:
-            tree["_partial"] = False
-            tree["_partial_reason"] = None
-
-        # Surface Wave-B-level unresolved items (e.g. unknown ID prefixes).
-        for u in wave_b.get("unresolved", []) or []:
-            tree.setdefault("_unresolved", []).append(u)
-
-        node_count, depth, kind_counts = parse_wave.compute_stats(tree["root"])
-        tree["node_count"] = node_count
-        tree["depth"] = depth
-        tree["_kind_counts"] = kind_counts
-
-        all_visited: set[tuple[str, str]] = set(aux_visited)
-        for kind, names in visited_by_kind.items():
-            for n in names:
-                all_visited.add((kind, n))
-        tree["_visited"] = [list(v) for v in sorted(all_visited)]
-
-        tree_path = work_dir / "declared_action_tree.json"
-        tmp = tree_path.with_suffix(tree_path.suffix + ".tmp")
-        tmp.write_text(json.dumps(tree, indent=2))
-        os.replace(tmp, tree_path)
-        return tree
-    finally:
-        # Restore env so test runners that reuse the process don't leak
-        # state across invocations.
-        for k, v in prior_env.items():
-            if v is None:
-                os.environ.pop(k, None)
-            else:
-                os.environ[k] = v
-
-
-# ---------------------------------------------------------------------------
-# Phase 11: finalize
-# ---------------------------------------------------------------------------
-
-
-def _swap_dir_atomic(target: Path, staging: Path) -> None:
-    """Per-file overwrite from `staging` into `target` — preserves any
-    unrelated sibling content already present in `target`.
-
-    P0 fix (2026-05-05): the prior implementation did
-    ``os.replace(target, backup); os.replace(staging, target)`` — an
-    atomic whole-directory swap that was correct in isolation but
-    DESTRUCTIVE of co-tenants. The `<agent>__<ver>/` dir is co-tenanted:
-    co-tenants write per-session subdirs
-    (`<session_id>/`) alongside architecture's files. Swapping the whole
-    directory silently wiped every cached session trace.
-
-    New behavior: iterate `staging`'s immediate children and `os.replace`
-    each one into `target`. The directory `target` itself is never
-    moved or deleted, so any session subdirs under it survive.
-
-    Trade-off: the old helper supported atomic rollback (restore from
-    backup on failure). The per-file pattern cannot — a crash partway
-    through the loop leaves architecture's output in a split state
-    (some new files, some old). This is acceptable because:
-      - per-file `os.replace` is still atomic (no empty-path window
-        for any individual file, so the "concurrent reader sees
-        empty dir" bug that  addressed is still closed);
-      - `last_built_at.txt` is written LAST by the caller, so
-        consumers can treat its presence as the success sentinel;
-      - architecture is re-runnable, co-tenant session traces are not.
-
-    Callers must still guarantee `staging` is on the same filesystem as
-    `target` (helper constructs `staging` as a sibling of `target`, so
-    that holds by construction).
-    """
-    import shutil
-
-    if not staging.is_dir():
-        raise OSError(f"staging dir missing: {staging}")
-
-    target.mkdir(parents=True, exist_ok=True)
-
-    for src in staging.iterdir():
-        dst = target / src.name
-        # Clear any existing destination so `os.replace` lands cleanly
-        # when the incoming type differs (file replacing dir or vice
-        # versa). For same-type overwrites `os.replace` would handle
-        # files on its own, but directories require an empty target or
-        # same-name existing dir — safer to unify both here.
-        if dst.exists() or dst.is_symlink():
-            if dst.is_dir() and not dst.is_symlink():
-                shutil.rmtree(dst)
-            else:
-                dst.unlink()
-        os.replace(src, dst)
-
-    # Staging should be empty now; best-effort teardown.
-    try:
-        staging.rmdir()
-    except OSError:
-        shutil.rmtree(staging, ignore_errors=True)
-
-
-def _run_finalize(
-    data_dir: Path,
-    cache_dir: Path,
-    tree: dict,
-    work_dir: Path,
-    agent_api_name: str,
-    agent_version: str,
-    planner_name: str,
-) -> None:
-    """Atomic-write tree + summary + manifest. Keep it simple.
-
-    For Phase 2 Batch 1 we replicate finalize.py's essential behavior
-    (tree + manifest) but skip the sf_meta mirror — there's no
-    sf_meta dir when main.py runs the pipeline SOQL-first. Metadata-API
-    retrieves land in Batch 2/3.
-
-    both `data_dir` and `cache_dir` are swapped
-    via `_swap_dir_atomic` to close the "rmtree then rename" empty-dir
-    window. A crash during the second swap restores the original from
-    the staging-sibling `.<name>.backup.<pid>` rather than leaving an
-    empty path.
-    """
-    import datetime as dt
-    import shutil
-
-    built_at = dt.datetime.now(dt.timezone.utc).isoformat().replace("+00:00", "Z")
-    tree_base = f"{agent_api_name}_{agent_version}_metadata_tree"
-
-    # Finalize's _partial computation. Mirrors finalize.py:109-117 — both
-    # buckets (_pending_fetches AND _unresolved) must be empty for a
-    # clean run. _unresolved captures wave-B failures (HTTP 4xx,
-    # iteration-cap exhaustion, managed-flow filter misses) that have
-    # already been moved out of _pending_fetches; checking only the
-    # latter would silently call a partial run "converged".
-    planner_ok = bool(planner_name)
-    pending_total = sum(len(v) for v in (tree.get("_pending_fetches") or {}).values())
-    unresolved_count = len(tree.get("_unresolved") or [])
-    waves_converged = pending_total == 0 and unresolved_count == 0
-    tree["_partial"] = not (planner_ok and waves_converged)
-    tree.pop("_visited", None)
-
-    # Pin deterministic child ordering as the last assembly step before
-    # the authoritative write. Shared with the standalone `finalize.py`
-    # subprocess so both paths produce byte-identical trees. Downstream
-    # readers see one canonical order from disk; they do not re-sort.
-    from finalize import sort_tree_in_place
-    sort_tree_in_place(tree.get("root") or {})
-
-    # staging names are siblings (same parent) so the
-    # `os.replace` used by `_swap_dir_atomic` is a same-filesystem atomic
-    # rename. `.staging.<pid>` disambiguates concurrent pipelines on the
-    # same host.
-    data_parent = data_dir.parent
-    data_staging = data_parent / f".{data_dir.name}.staging.{os.getpid()}"
-    if data_staging.exists():
-        shutil.rmtree(data_staging)
-    data_staging.mkdir(parents=True)
-    tree_out = data_staging / f"{tree_base}.json"
-    tree_out.write_text(json.dumps(tree, indent=2))
-
-    # P2.2-1: phase 10 (architecture.md renderer). Imported lazily so a
-    # renderer bug can't break the existing Batch 1 pipeline before the
-    # tree JSON has been written — the tree + manifest remain the
-    # authoritative outputs, architecture.md is a derived artifact.
-    #
-    # filename now self-identifying —
-    # `{agent_api_name}_{agent_version}_architecture.md` (e.g.
-    # `MyAgent_v5_architecture.md`). Same shape as the tree JSON,
-    # minus the `_metadata_tree` suffix. The `.error` sidecar follows
-    # the same shape.
-    arch_base = f"{agent_api_name}_{agent_version}"
-    arch_name = f"{arch_base}_architecture.md"
-    arch_error_name = f"{arch_base}_architecture.md.error"
-    try:
-        from render_architecture import render as _render_architecture
-        _render_architecture(tree_out, data_staging / arch_name)
-    except Exception as e:
-        # Best-effort: a render failure downgrades the run to "tree OK,
-        # architecture skipped" rather than aborting finalize. The
-        # reason string surfaces in the next-run logs for triage.
-        (data_staging / arch_error_name).write_text(
-            f"render_architecture failed: {type(e).__name__}: {e}\n"
-        )
-
-    # dropped `{tree_base}.summary.md` from the output contract —
-    # was a redundant summary of the tree JSON; consumers should read the
-    # JSON directly. See CHANGELOG for details.
-    (data_staging / "last_built_at.txt").write_text(built_at + "\n")
-
-    _swap_dir_atomic(data_dir, data_staging)
-
-    # CACHE_DIR staging — same two-phase swap.
-    cache_parent = cache_dir.parent
-    cache_staging = cache_parent / f".{cache_dir.name}.staging.{os.getpid()}"
-    if cache_staging.exists():
-        shutil.rmtree(cache_staging)
-    cache_staging.mkdir(parents=True)
-
-    manifest = {
-        "built_at_utc": built_at,
-        "schema_version": tree.get("_schema_version", SCHEMA_VERSION),
-        "agent": tree.get("agent", {}),
-        "node_count": tree.get("node_count", 0),
-        "depth": tree.get("depth", 0),
-        "kind_counts": tree.get("_kind_counts", {}),
-        "ttl_days": CACHE_TTL_DAYS,
-        "data_path": str(data_dir / f"{tree_base}.json"),
-        "partial": tree.get("_partial", False),
-        "unresolved_count": len(tree.get("_unresolved", []) or []),
-    }
-    (cache_staging / "manifest.json").write_text(json.dumps(manifest, indent=2))
-    # Copy tree + bundle sidecar for cache replay
-    (cache_staging / "declared_action_tree.json").write_text(json.dumps(tree, indent=2))
-    bundle_src = work_dir / "_bundle_parsed.json"
-    if bundle_src.is_file():
-        (cache_staging / "_bundle_parsed.json").write_text(bundle_src.read_text())
-
-    _swap_dir_atomic(cache_dir, cache_staging)
-
-
-# ---------------------------------------------------------------------------
-# Emit helpers
-# ---------------------------------------------------------------------------
-
-
-def _read_built_at_utc(cache_dir: Path | None) -> str:
-    if cache_dir is None:
-        return ""
-    try:
-        return json.loads((cache_dir / "manifest.json").read_text()).get("built_at_utc", "") or ""
-    except (OSError, ValueError):
-        return ""
-
-
-def _emit_fail(
-    args: argparse.Namespace,
-    extra_ctx: dict | None,
-    status: str,
-    error_detail: str = "",
-    start_epoch: float | None = None,
-) -> int:
-    """Write an .emit_ctx.json with STATUS=<status>.
-
-    STATUS enum (from emit_result.py):
-        OK, PARTIAL_OK, INVALID_INPUT, AUTH_REQUIRED, AGENT_NOT_FOUND,
-        AGENT_VERSION_NOT_FOUND, RETRIEVE_FAILED, WRITE_FAILED.
-
-    For probe failures, the plan's description suggested SCHEMA_DRIFT
-    but emit_result doesn't carry that enum value. We map probe failures
-    to RETRIEVE_FAILED with an explicit error_detail — the RESULT block's
-    ERROR_DETAIL carries the "schema-drift" reason. Adding a new enum
-    value would require touching emit_result (out of scope P1 primitive);
-    the mapping preserves emit_result's existing contract.
-
-    Returns the exit code the caller should return.
-    """
-    work_dir = Path(args.work_dir)
-    work_dir.mkdir(parents=True, exist_ok=True)
-    ctx = {
-        "status": status,
-        "error_detail": error_detail,
-        "agent_api_name": args.agent_api_name,
-        "agent_version": args.agent_version or "",
-        "version_auto_picked": False,
-        "agent_generation": "unknown",
-        "bot_id": "",
-        "org_id_15": "",
-        "org_id_18": "",
-        "cache_hit": False,
-        "cached_at_utc": "",
-        "cache_path": "",
-        "output_json_path": "",
-        "output_summary_path": "",
-        "node_count": 0,
-        "depth": 0,
-        "partial": status == "PARTIAL_OK",
-        "partial_reason": "",
-        "pending_fetches_count": 0,
-        "unresolved_count": 0,
-        "available_bots": "",
-        "available_versions": "",
-        # Bug fix (2026-05-05): start_epoch captured once at pipeline entry
-        # and threaded through every _emit_* helper. Previously each helper
-        # re-captured time.time() AFTER the pipeline had already run, so
-        # emit_result.py computed WALL_TIME_SECONDS against a timestamp taken
-        # ~tens of seconds AFTER the real work finished and reported ~0.0s.
-        "start_epoch": start_epoch if start_epoch is not None else time.time(),
-        "data_dir": str(DATA_ROOT),
-        "work_dir": str(work_dir),
-        # failure paths never invoke the renderer.
-        "architecture_path": "",
-        "render_failed": False,
-        "render_error_detail": "",
-    }
-    if extra_ctx:
-        ctx.update(extra_ctx)
-    (work_dir / ".emit_ctx.json").write_text(json.dumps(ctx, indent=2))
-    return 1
-
-
-def _emit_cache_hit(
-    args: argparse.Namespace,
-    data_dir: Path,
-    cache_dir: Path,
-    manifest: dict,
-    start_epoch: float | None = None,
-    *,
-    org_id_15: str = "",
-    org_id_18: str = "",
-) -> int:
-    work_dir = Path(args.work_dir)
-    work_dir.mkdir(parents=True, exist_ok=True)
-    agent_version = manifest.get("agent", {}).get("version", "")
-    tree_base = f"{args.agent_api_name}_{agent_version}_metadata_tree"
-
-    # on a cache hit the renderer is NOT re-invoked — but the
-    # architecture.md from the prior run is a legitimate output of the
-    # cached data_dir. Surface it when present, skip the .error sidecar
-    # since render_failed semantics only apply to THIS run's renderer.
-    # filename rename to `{agent}_{ver}_architecture.md` —
-    # NB `tree_base` above still carries the `_metadata_tree` suffix (it
-    # names the JSON); architecture filenames drop the suffix.
-    arch_base = f"{args.agent_api_name}_{agent_version}"
-    arch_path = data_dir / f"{arch_base}_architecture.md"
-    architecture_path = str(arch_path) if arch_path.is_file() else ""
-
-    ctx = {
-        "status": "OK",
-        "error_detail": "",
-        "agent_api_name": args.agent_api_name,
-        "agent_version": manifest.get("agent", {}).get("version", ""),
-        "version_auto_picked": manifest.get("agent", {}).get("_version_auto_picked", False),
-        "agent_generation": manifest.get("agent", {}).get("generation", "unknown"),
-        "bot_id": manifest.get("agent", {}).get("bot_id", ""),
-        "org_id_15": org_id_15,
-        "org_id_18": org_id_18,
-        "cache_hit": True,
-        "cached_at_utc": manifest.get("built_at_utc", ""),
-        "cache_path": str(cache_dir),
-        "output_json_path": str(data_dir / f"{tree_base}.json"),
-        # summary.md dropped from the output contract. Field kept
-        # empty for RESULT-block shape stability.
-        "output_summary_path": "",
-        "node_count": int(manifest.get("node_count", 0) or 0),
-        "depth": int(manifest.get("depth", 0) or 0),
-        "partial": bool(manifest.get("partial", False)),
-        "partial_reason": "",
-        "pending_fetches_count": 0,
-        "unresolved_count": int(manifest.get("unresolved_count", 0) or 0),
-        "available_bots": "",
-        "available_versions": "",
-        # Bug fix (2026-05-05): see _emit_fail note — start_epoch is captured
-        # at pipeline entry and threaded through. Cache-hit paths are short-
-        # running so the drift is smaller, but the field should still reflect
-        # the invocation's real wall time.
-        "start_epoch": start_epoch if start_epoch is not None else time.time(),
-        "data_dir": str(data_dir),
-        "work_dir": str(work_dir),
-        # architecture-render outcome signals. render_failed
-        # stays False for cache replays — that flag tracks THIS run's
-        # renderer, not the cached run's; a cache hit implies no retry.
-        "architecture_path": architecture_path,
-        "render_failed": False,
-        "render_error_detail": "",
-    }
-    (work_dir / ".emit_ctx.json").write_text(json.dumps(ctx, indent=2))
-    return 0
-
-
-def _emit_ok(
-    args: argparse.Namespace,
-    data_dir: Path,
-    tree: dict,
-    bot_info: dict,
-    org_id_15: str,
-    start_epoch: float | None = None,
-    cache_dir: Path | None = None,
-    org_id_18: str = "",
-) -> int:
-    work_dir = Path(args.work_dir)
-    work_dir.mkdir(parents=True, exist_ok=True)
-    agent_version = bot_info["version"]
-    tree_base = f"{args.agent_api_name}_{agent_version}_metadata_tree"
-    pending_total = sum(len(v) for v in (tree.get("_pending_fetches") or {}).values())
-
-    # surface architecture-render outcome on the success path.
-    # finalize writes either `{agent}_{ver}_architecture.md` (render OK) or
-    # `{agent}_{ver}_architecture.md.error` (render raised) into the
-    # data_dir; we read whichever is present and plumb the fields through
-    # the ctx. emit_result consumes the boolean to auto-promote
-    # OK -> PARTIAL_OK when the tree landed but the diagram render failed.
-    # filename rename — self-identifying shape. `tree_base` above
-    # is for the JSON path (carries `_metadata_tree`); architecture uses
-    # the unsuffixed agent+version base.
-    arch_base = f"{args.agent_api_name}_{agent_version}"
-    arch_path = data_dir / f"{arch_base}_architecture.md"
-    arch_sidecar = data_dir / f"{arch_base}_architecture.md.error"
-    architecture_path = str(arch_path) if arch_path.is_file() else ""
-    render_failed = arch_sidecar.is_file()
-    render_error_detail = ""
-    if render_failed:
-        try:
-            raw = arch_sidecar.read_text(errors="replace").strip()
-        except OSError:
-            raw = ""
-        if raw:
-            # Single-line cap, 200-char truncation, scrubbed via the
-            # rest_client redactor (same contract as write_emit_ctx).
-            from rest_client import redact_text as _redact
-            render_error_detail = _redact(raw.splitlines()[0])[:200]
-
-    ctx = {
-        "status": "PARTIAL_OK" if tree.get("_partial") else "OK",
-        "error_detail": "",
-        "agent_api_name": args.agent_api_name,
-        "agent_version": bot_info["version"],
-        "version_auto_picked": bot_info["version_auto_picked"],
-        "agent_generation": tree.get("agent", {}).get("generation", "unknown"),
-        "bot_id": bot_info["bot_id"],
-        "org_id_15": org_id_15,
-        # Gap 3 fix (2026-05-05): the 18-char id is available from
-        # `sf org display` in _derive_org_ids but was previously dropped.
-        # Now threaded from pipeline entry so the RESULT contract field is
-        # actually populated on success.
-        "org_id_18": org_id_18,
-        "cache_hit": False,
-        "cached_at_utc": _read_built_at_utc(cache_dir),
-        # Gap 4 fix (2026-05-05): non-cache-hit runs write the manifest into
-        # `cache_dir` (see _run_finalize) so the field should point at the
-        # same path a subsequent invocation would probe. Caller passes the
-        # already-computed cache_dir; we skip the leading-empty fallback
-        # only when it's truly unknown (shouldn't happen on _emit_ok).
-        "cache_path": str(cache_dir) if cache_dir is not None else "",
-        "output_json_path": str(data_dir / f"{tree_base}.json"),
-        # summary.md dropped from the output contract.
-        "output_summary_path": "",
-        "node_count": int(tree.get("node_count", 0) or 0),
-        "depth": int(tree.get("depth", 0) or 0),
-        "partial": bool(tree.get("_partial", False)),
-        "partial_reason": tree.get("_partial_reason") or "",
-        "pending_fetches_count": pending_total,
-        "unresolved_count": len(tree.get("_unresolved", []) or []),
-        "available_bots": "",
-        "available_versions": "",
-        # Bug fix (2026-05-05): see _emit_fail note — start_epoch threaded
-        # from pipeline entry so WALL_TIME_SECONDS reflects the full run.
-        "start_epoch": start_epoch if start_epoch is not None else time.time(),
-        "data_dir": str(data_dir),
-        "work_dir": str(work_dir),
-        # architecture-render outcome signals.
-        "architecture_path": architecture_path,
-        "render_failed": render_failed,
-        "render_error_detail": render_error_detail,
-    }
-    (work_dir / ".emit_ctx.json").write_text(json.dumps(ctx, indent=2))
-    return 0
-
-
-# ---------------------------------------------------------------------------
-# Entry point
-# ---------------------------------------------------------------------------
-
-
-def _run_pipeline(args: argparse.Namespace, start_epoch: float) -> int:  # noqa: PLR0911, PLR0915
-    """Execute the 12-phase pipeline. Extracted from `main()` so the
-    top-level entry point can wrap any uncaught exception in a RESULT
-    block .
-
-    Every structured failure path here already routes through
-    `_emit_fail` and returns a non-zero exit code. Exceptions that
-    escape this function are, by definition, bugs we hadn't thought of
-    yet — `main()` catches them so the skill contract (RESULT block on
-    every exit path) holds regardless.
-    """
-    work_dir = Path(args.work_dir)
-    work_dir.mkdir(parents=True, exist_ok=True)
-
-    # Phase 2 Batch 1: single creds cell shared between provider + refresh.
-    # Refresh mutates the cell; provider reads it on every attempt — this
-    # is the `` refresh contract.
-    #
-    # Wave B fetches run N concurrent Flow.Metadata
-    # calls through parallel_retrieve.fetch_bodies_parallel. `refresh_fn`
-    # serializes behind a lock + 1-second monotonic dedupe window so
-    # concurrent 401s don't each fork their own `sf org display`. See
-    # `_build_creds_plumbing`.
-    try:
-        initial = _resolve_creds(args.org_alias)
-    except (AuthRequired, SfCliError) as e:
-        return _emit_fail(
-            args, None, "AUTH_REQUIRED",
-            error_detail=redact_error(e),
-            start_epoch=start_epoch,
-        )
-
-    creds_provider, refresh_fn, _creds_cell = _build_creds_plumbing(
-        initial,
-        resolve_creds=lambda: _resolve_creds(args.org_alias),
-    )
-
-    # Phase 2.5: derive org_id_15 + org_id_18 + api_version
-    try:
-        org_id_15, org_id_18, api_version = _derive_org_ids(args.org_alias)
-    except (AuthRequired, SfCliError) as e:
-        return _emit_fail(
-            args, None, "AUTH_REQUIRED",
-            error_detail=redact_error(e),
-            start_epoch=start_epoch,
-        )
-
-    # Phase 3: probe channels
-    channels = probe_channels(
-        args.org_alias, org_id_15, api_version,
-        force_refresh=args.reprobe,
-    )
-    if channels.get("status") == "PROBE_FAILED":
-        # Plan suggested STATUS=SCHEMA_DRIFT; emit_result's STATUS enum
-        # doesn't include that value. Mapping to RETRIEVE_FAILED with a
-        # "schema-drift" ERROR_DETAIL preserves the existing enum
-        # contract while surfacing the cause. A future batch may add
-        # SCHEMA_DRIFT to the enum; that change lives in emit_result.
-        missing = [
-            (sobj, e.get("mandatory_missing", []))
-            for sobj, e in (channels.get("channels") or {}).items()
-            if e.get("mandatory_missing")
-        ]
-        return _emit_fail(
-            args, None, "RETRIEVE_FAILED",
-            error_detail=f"schema-drift: mandatory fields missing: {missing[:3]}",
-            start_epoch=start_epoch,
-        )
-
-    # Phase 4: resolve bot + version
-    try:
-        bot_info = _resolve_bot(
-            args.agent_api_name, args.agent_version,
-            creds_provider, refresh_fn,
-            api_version=api_version,
-        )
-    except (RestClientError, SoqlParamError) as e:
-        return _emit_fail(
-            args, None, "AUTH_REQUIRED",
-            error_detail=redact_error(e),
-            start_epoch=start_epoch,
-        )
-
-    if bot_info is None:
-        # AGENT_NOT_FOUND — emit without a list-of-available-bots context.
-        # The unbounded bot-list SELECT was removed (LIMIT-less unfiltered
-        # query on BotDefinition). Operators can run their own SOQL if
-        # they need to enumerate available bots.
-        return _emit_fail(
-            args,
-            {"org_id_15": org_id_15},
-            "AGENT_NOT_FOUND",
-            error_detail=f"BotDefinition.DeveloperName '{args.agent_api_name}' not found",
-            start_epoch=start_epoch,
-        )
-
-    if bot_info.get("_version_not_found"):
-        vers_csv = ",".join(
-            f"{v['version']}({v['status']})" for v in bot_info.get("all_versions", [])
-        )
-        return _emit_fail(
-            args,
-            {"available_versions": vers_csv, "org_id_15": org_id_15},
-            "AGENT_VERSION_NOT_FOUND",
-            error_detail=f"No matching BotVersion (requested: {args.agent_version!r})",
-            start_epoch=start_epoch,
-        )
-
-    # Phase 5: cache check
-    data_dir = build_agent_data_dir(org_id_15, args.agent_api_name, bot_info["version"])
-    cache_dir = build_agent_cache_dir(org_id_15, args.agent_api_name, bot_info["version"])
-    if not args.force_refresh:
-        manifest = _cache_is_fresh(cache_dir)
-        if manifest is not None:
-            return _emit_cache_hit(
-                args, data_dir, cache_dir, manifest,
-                start_epoch=start_epoch,
-                org_id_15=org_id_15,
-                org_id_18=org_id_18,
-            )
-
-    # Phase 6: Wave A — 7 queries, DAG-ordered parallel layers. A1 now
-    # takes (agent_api_name, version) and resolves the canonical planner
-    # DeveloperName from the live chain naming invariant (v1 = <Agent>,
-    # vN = <Agent>...%\_vN); the row's DeveloperName becomes the
-    # authoritative `planner_name` for finalize/render downstream.
-    try:
-        wave_a = _run_wave_a(
-            args.agent_api_name, bot_info["version"],
-            creds_provider, refresh_fn,
-            api_version=api_version,
-            parallelism=args.parallelism,
-        )
-    except (RestClientError, SoqlParamError) as e:
-        return _emit_fail(
-            args, None, "RETRIEVE_FAILED",
-            error_detail=f"wave-a-failed:{redact_error(e)}",
-            start_epoch=start_epoch,
-        )
-
-    if wave_a is None:
-        return _emit_fail(
-            args, {"org_id_15": org_id_15},
-            "AGENT_NOT_FOUND",
-            error_detail=(
-                f"GenAiPlannerDefinition chain not found for "
-                f"agent={args.agent_api_name!r} version={bot_info['version']!r}"
-            ),
-            start_epoch=start_epoch,
-        )
-
-    # Phase 7: join Wave A → bundle-shaped dict
-    bundle_parsed = _join_wave_a_to_bundle(bot_info, wave_a)
-
-    # Phase 8: Wave B — body fetches
-    try:
-        wave_b = _run_wave_b(
-            bundle_parsed,
-            creds_provider, refresh_fn,
-            api_version=api_version,
-            org_alias=args.org_alias,
-            parallelism=args.parallelism,
-        )
-    except (RestClientError, SoqlParamError) as e:
-        return _emit_fail(
-            args, None, "RETRIEVE_FAILED",
-            error_detail=f"wave-b-failed:{redact_error(e)}",
-            start_epoch=start_epoch,
-        )
-
-    # Phase 8.5: iterative Wave B — follow subflow + apex refs from fetched
-    # Flow.Metadata bodies until fixed-point. Without this pass, shared
-    # utility flows (handleFlowFault) and nested subflows ship as empty
-    # leaves even though their bodies are reachable via Tooling API.
-    # Iteration cap safeguards against pathological flow graphs.
-    try:
-        wave_b = _iterate_wave_b(
-            wave_b,
-            creds_provider, refresh_fn,
-            api_version=api_version,
-            org_alias=args.org_alias,
-            parallelism=args.parallelism,
-            max_iterations=5,
-        )
-    except (RestClientError, SoqlParamError) as e:
-        return _emit_fail(
-            args, None, "RETRIEVE_FAILED",
-            error_detail=f"wave-b-iter-failed:{redact_error(e)}",
-            start_epoch=start_epoch,
-        )
-
-    # Surface Wave-A layer-2/3 task failures alongside Wave-B's so the
-    # downstream `_run_parse_wave` sweep folds them into `tree["_unresolved"]`
-    # and `_partial_reason` flips to PARTIAL_OK.
-    wave_a_unresolved = wave_a.get("unresolved") or []
-    if wave_a_unresolved:
-        wave_b["unresolved"] = [*wave_a_unresolved, *(wave_b.get("unresolved") or [])]
-
-    # normalize Flow-ID InvocationTargets → DeveloperName.
-    # Classic ReAct bots occasionally store NGA-style 300Uv-prefix Flow IDs
-    # in GenAiFunctionDefinition.InvocationTarget (observed in one real-org
-    # benchmark run, 6 flows out of 6). Wave B's fetch_flow_definition_by_ids
-    # successfully resolves them, but the resolved DeveloperName never
-    # propagates back into bundle_parsed — so parse_wave sees the raw ID as
-    # the flow's api_name, which never matches visited["FLOW"] (keyed on
-    # DeveloperName), and every such flow ends up in _pending_fetches.
-    # Result: PARTIAL_OK on what should be OK, plus unreadable Flow IDs in
-    # rendered architecture.md.
-    #
-    # Fix: rewrite bundle_parsed's action invocationTarget in-place from
-    # ID → DeveloperName using wave_b["flow_def_rows"] (both the IN-by-names
-    # and the IN-by-ids branches populate it). Unresolved IDs (Flow not
-    # found in the org) stay as-is and will land in _pending_fetches as
-    # intended (they really are unresolved).
-    _normalize_flow_id_targets(bundle_parsed, wave_b["flow_def_rows"])
-
-    # Bug 1 fix (2026-05-05): analogous rewrite for GenAiPromptTemplate Ids.
-    # Wave B's prompt-template Id fetch resolves 0hf-prefix Ids to
-    # DeveloperNames; without this rewrite the bundle would enqueue the
-    # raw Id into _pending_fetches.PROMPT_TEMPLATE and the downstream
-    # Metadata retrieve would never match.
-    _normalize_prompt_template_id_targets(
-        bundle_parsed, wave_b.get("prompt_template_id_rows") or [],
-    )
-
-    # Gap B fix (2026-05-05): analogous rewrite for ApexClass Ids.
-    # Wave B's fetch_apex_bodies_by_ids resolves 01p-prefix Ids to ApexClass
-    # Name; without this rewrite the bundle would enqueue the raw Id into
-    # _pending_fetches.APEX and the tree would render the bare Id instead
-    # of the class name.
-    _normalize_apex_id_targets(
-        bundle_parsed, wave_b.get("apex_rows") or [],
-    )
-
-    # Gap C fix (2026-05-05): retrieve GenAiPromptTemplate bodies.
-    # GenAiPromptTemplate is NOT SOQL-queryable (Tooling or Data API). The
-    # only way to fetch the body is `sf project retrieve start
-    # --metadata GenAiPromptTemplate:<name>,...`. After
-    # _normalize_prompt_template_id_targets has rewritten 0hf-Ids to
-    # DeveloperNames, collect the names and retrieve in a single sf
-    # subprocess call. The resulting bodies get stashed on wave_b so
-    # _run_parse_wave can stamp them onto PROMPT_TEMPLATE leaves (parallel
-    # to the Apex/Flow signature stamping pattern).
-    prompt_template_names = _collect_prompt_template_names(bundle_parsed)
-    prompt_template_bodies: dict[str, dict] = {}
-    if prompt_template_names:
-        try:
-            prompt_template_bodies = retrieve_prompt_templates(
-                args.org_alias,
-                sorted(prompt_template_names),
-                work_dir,
-            )
-        except AuthRequired:
-            raise
-        except SfCliError as e:
-            wave_b.setdefault("unresolved", []).append({
-                "kind": "PROMPT_TEMPLATE",
-                "reason": f"prompt-template-retrieve-failed:{redact_error(e)}",
-            })
-    wave_b["prompt_template_bodies"] = prompt_template_bodies
-
-    # Phase 9: parse_wave -> declared_action_tree.json
-    try:
-        tree = _run_parse_wave(bot_info, bundle_parsed, wave_b, args, work_dir)
-    except (OSError, KeyError) as e:
-        return _emit_fail(
-            args, None, "WRITE_FAILED",
-            error_detail=f"parse-wave-failed:{redact_error(e)}",
-            start_epoch=start_epoch,
-        )
-
-    # Phase 10: render architecture.md — invoked inline from _run_finalize
-    # so the write lands in the same staging dir as the tree JSON and
-    # participates in the atomic _swap_dir_atomic below. See P2.2-1.
-
-    # Flow-nested prompt-template catch-up (2026-05-05). The bundle-scoped
-    # retrieve at step 1 above only covers prompt templates declared as
-    # top-level topic/planner InvocationTargets. Templates referenced from
-    # inside a Flow (via a `generatePromptResponse` actionCall) are
-    # discovered during parse_wave's BFS of flow XML — too late for the
-    # first retrieve. Without this second pass their `_body_available`
-    # stays False and the md renders `_Body not retrieved._` with no
-    # PARTIAL flag (silent content loss). `_stamp_prompt_template_bodies`
-    # is idempotent, so re-stamping already-stamped leaves is safe.
-    flow_nested_names: set[str] = set()
-    _collect_flow_nested_prompt_template_names(
-        tree["root"], prompt_template_bodies, flow_nested_names,
-    )
-    if flow_nested_names:
-        try:
-            more_bodies = retrieve_prompt_templates(
-                args.org_alias,
-                sorted(flow_nested_names),
-                work_dir,
-            )
-        except AuthRequired:
-            raise
-        except SfCliError as e:
-            tree.setdefault("_unresolved", []).append({
-                "kind": "PROMPT_TEMPLATE",
-                "reason": f"prompt-template-retrieve-failed:{redact_error(e)}",
-            })
-        else:
-            prompt_template_bodies.update(more_bodies)
-            _stamp_prompt_template_bodies(tree["root"], prompt_template_bodies)
-            # _kind_counts / _pending_fetches are unchanged: the leaves
-            # already existed and were counted; this pass only attaches
-            # body content to them. No BFS-kind reshuffling needed.
-
-    # Phase 11: finalize. The canonical planner_name now comes from the
-    # resolved planner row (Wave A), which joins into bundle_parsed as
-    # `plannerName`; fall back to the agent api name if the resolver
-    # returned a row without a DeveloperName (shouldn't happen on a
-    # healthy planner but keeps finalize's _partial flag well-defined).
-    planner_name = bundle_parsed.get("plannerName") or args.agent_api_name
-    try:
-        _run_finalize(
-            data_dir, cache_dir, tree, work_dir,
-            args.agent_api_name, bot_info["version"],
-            planner_name,
-        )
-    except OSError as e:
-        return _emit_fail(
-            args, None, "WRITE_FAILED",
-            error_detail=f"finalize-failed:{redact_error(e)}",
-            start_epoch=start_epoch,
-        )
-
-    # Phase 12: emit RESULT
-    return _emit_ok(
-        args, data_dir, tree, bot_info, org_id_15,
-        start_epoch=start_epoch,
-        cache_dir=cache_dir,
-        org_id_18=org_id_18,
-    )
-
-
-def main(argv: list[str] | None = None) -> int:
-    """Entry point — parses args, runs pipeline, guarantees a RESULT block.
-
-    the skill contract promises that every exit
-    path emits `=== RESULT ===` with a structured STATUS. The prior
-    implementation let any uncaught exception from the pipeline (e.g.
-    the HTTP 405 from , or any future bug we haven't foreseen)
-    propagate to the top of the process — the user saw a Python
-    traceback on stderr and the wrapper skill never got its RESULT
-    block. We now wrap `_run_pipeline` in a broad `except Exception` and
-    funnel uncaught failures through `_emit_fail` with
-    STATUS=RETRIEVE_FAILED + ERROR_DETAIL="uncaught-exception: <redacted
-    message>". `redact_error` keeps tokens / full-URL querystrings out
-    of the ctx file. `SystemExit` + `KeyboardInterrupt` are NOT caught —
-    argparse's `--help` path + Ctrl-C must propagate normally.
-    """
-    args = parse_args(argv)
-    # MUST happen before any pipeline phase reads DATA_ROOT / CACHE_ROOT.
-    # See _apply_path_overrides docstring for the 3-level rebind contract.
-    _apply_path_overrides(args)
-    # Bug fix (2026-05-05): capture start_epoch ONCE at real pipeline entry
-    # and thread it through every _emit_* call so WALL_TIME_SECONDS measures
-    # actual pipeline duration, not ctx-write→emit_result drift.
-    start_epoch = time.time()
-    try:
-        return _run_pipeline(args, start_epoch)
-    except Exception as exc:
-        # broad catch — anything that reaches here is a bug
-        # but the skill contract requires a structured exit. redact_error
-        # strips bearer tokens and accessToken values from the message
-        # ; the exception class name leads the detail so triage
-        # can still identify the shape even when the message is terse.
-        redacted = redact_error(exc)
-        return _emit_fail(
-            args,
-            None,
-            "RETRIEVE_FAILED",
-            error_detail=f"uncaught-exception: {redacted}",
-            start_epoch=start_epoch,
-        )
-
-
-if __name__ == "__main__":
-    sys.exit(main())