@salesforce/afv-skills 1.13.0 → 1.15.0

package/skills/investigating-agentforce-architecture/tools/emit_result.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Final-phase RESULT emitter for investigating-agentforce-architecture.
+
+Reads `$WORK_DIR/.emit_ctx.json` (populated by write_emit_ctx.py) and prints
+the final output:
+
+    1. One-line prose status (for humans; first signal in the log).
+    2. A blank line.
+    3. The `=== RESULT ===` KV block.
+
+BEFORE writing to stdout, the complete RESULT block is teed to
+`$DATA_DIR/last_result_block.txt`. Writing the tee first means a consumer
+reading the file can never see a truncated block — disk write is atomic
+(`tmp + os.replace`), and the stdout print is a best-effort afterthought.
+
+The callers that abort early (AGENT_NOT_FOUND, AGENT_VERSION_NOT_FOUND,
+INVALID_INPUT) emit their own RESULT blocks directly — resolve_bot.py and
+fs_guard.py have the same disk-tee discipline. All other terminal paths
+(OK, PARTIAL_OK, AUTH_REQUIRED, RETRIEVE_FAILED, WRITE_FAILED) flow through
+this script.
+
+Usage:
+    python3 emit_result.py
+
+Inputs:
+    env $WORK_DIR     reads $WORK_DIR/.emit_ctx.json
+
+Outputs:
+    $DATA_DIR/last_result_block.txt    full RESULT block (atomic write)
+    stdout                             prose line + RESULT block
+    exit 0                             always (this script emits; the bash
+                                       harness decides the agent's exit code)
+    exit 1                             missing env, missing ctx file, bad JSON
+"""
+import json
+import os
+import pathlib
+import sys
+import time
+
+STATUS_ENUM = {
+    "OK",
+    "PARTIAL_OK",
+    "INVALID_INPUT",
+    "AUTH_REQUIRED",
+    "AGENT_NOT_FOUND",
+    "AGENT_VERSION_NOT_FOUND",
+    "RETRIEVE_FAILED",
+    "WRITE_FAILED",
+}
+
+PROSE = {
+    "OK": "Declared action tree discovered and cached.",
+    "PARTIAL_OK": "Declared action tree partially discovered — see UNRESOLVED_COUNT.",
+    "INVALID_INPUT": "Input validation failed.",
+    "AUTH_REQUIRED": "sf CLI not authenticated for this org.",
+    "AGENT_NOT_FOUND": "BotDefinition.DeveloperName not found in the org.",
+    "AGENT_VERSION_NOT_FOUND": "No matching BotVersion under the bot.",
+    "RETRIEVE_FAILED": "Metadata API retrieve failed (auth/network/permissions).",
+    "WRITE_FAILED": "A filesystem write failed during finalize.",
+}
+
+
+def scrub(s) -> str:
+    if not isinstance(s, str):
+        s = "" if s is None else str(s)
+    bad = set("`$\"\\\r\t\0\n")
+    return "".join(c for c in s if c not in bad)
+
+
+def bool_str(v) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    s = str(v).lower()
+    return "true" if s in ("true", "1", "yes", "on") else "false"
+
+
+def build_block(ctx: dict, wall_time_seconds: float) -> str:
+    status = (ctx.get("status") or "").strip().upper()
+    if status not in STATUS_ENUM:
+        status = "WRITE_FAILED"
+
+    lines = ["=== RESULT ===", f"STATUS={status}"]
+
+    error_detail = scrub(ctx.get("error_detail", ""))
+    if error_detail:
+        lines.append(f"ERROR_DETAIL={error_detail}")
+
+    # Always-emitted identity fields (may be empty on early-abort paths)
+    lines.extend([
+        f"AGENT_API_NAME={scrub(ctx.get('agent_api_name', ''))}",
+        f"AGENT_VERSION={scrub(ctx.get('agent_version', ''))}",
+        f"VERSION_AUTO_PICKED={bool_str(ctx.get('version_auto_picked', False))}",
+        f"AGENT_GENERATION={scrub(ctx.get('agent_generation', '') or 'unknown')}",
+        f"BOT_ID={scrub(ctx.get('bot_id', ''))}",
+        f"ORG_ID_15={scrub(ctx.get('org_id_15', ''))}",
+        f"ORG_ID_18={scrub(ctx.get('org_id_18', ''))}",
+    ])
+
+    # Output + cache paths (populated on success; may be empty on fail paths)
+    # OUTPUT_ARCHITECTURE_PATH is always emitted — empty
+    # string on fail paths, cache-hit paths where the renderer wasn't
+    # invoked, or when render failed. Downstream consumers can distinguish
+    # "no architecture produced" from "architecture produced but stale"
+    # by cross-referencing RENDER_FAILED + CACHE_HIT.
+    lines.extend([
+        f"OUTPUT_JSON_PATH={scrub(ctx.get('output_json_path', ''))}",
+        f"OUTPUT_SUMMARY_PATH={scrub(ctx.get('output_summary_path', ''))}",
+        f"OUTPUT_ARCHITECTURE_PATH={scrub(ctx.get('architecture_path', '') or '')}",
+        f"CACHE_PATH={scrub(ctx.get('cache_path', ''))}",
+        f"CACHE_HIT={bool_str(ctx.get('cache_hit', False))}",
+        f"CACHED_AT_UTC={scrub(ctx.get('cached_at_utc', ''))}",
+    ])
+
+    # Tree stats
+    # emit `_partial_reason` + a rollup of `_pending_fetches` counts
+    # alongside the existing PARTIAL / UNRESOLVED_COUNT fields. The write
+    # path populates ctx["partial"], ctx["partial_reason"], and
+    # ctx["pending_fetches_count"] from the finalized tree JSON —
+    # emit_result is intentionally presentation-only and does not re-read
+    # the tree itself (ctx is the single source of truth per the emit
+    # contract).
+    partial_flag = bool(ctx.get("partial", False))
+    partial_reason = scrub(ctx.get("partial_reason", "") or "")
+    pending_fetches_count = int(ctx.get("pending_fetches_count", 0) or 0)
+
+    # If the upstream pipeline forgot to populate partial_reason but
+    # flagged partial=True, emit an empty value rather than nothing —
+    # downstream consumers can distinguish "no reason supplied" from
+    # "key missing" this way.
+    lines.extend([
+        f"NODE_COUNT={int(ctx.get('node_count', 0) or 0)}",
+        f"DEPTH={int(ctx.get('depth', 0) or 0)}",
+        f"PARTIAL={bool_str(partial_flag)}",
+        f"PARTIAL_REASON={partial_reason}",
+        f"PENDING_FETCHES_COUNT={pending_fetches_count}",
+        f"UNRESOLVED_COUNT={int(ctx.get('unresolved_count', 0) or 0)}",
+    ])
+
+    # when the tree is partial but status was left blank / "OK",
+    # auto-promote the status to PARTIAL_OK so the RESULT block reflects
+    # the tree's actual state. ERROR paths (AUTH_REQUIRED etc.) keep
+    # their original status — never clobber a failure status.
+    if partial_flag and status == "OK":
+        # positional safety — `lines[1]` is by construction
+        # "STATUS=...". If a future refactor reorders the header we want
+        # a loud failure here rather than silently rewriting the wrong
+        # line. Assertion cost is negligible; the payoff is catching a
+        # whole class of refactor bugs at test time.
+        assert lines[1].startswith("STATUS="), (
+            f"emit block reordered — lines[1]={lines[1]!r}"
+        )
+        lines[1] = "STATUS=PARTIAL_OK"
+        status = "PARTIAL_OK"
+
+    # emit RENDER_FAILED unconditionally, and auto-promote to
+    # PARTIAL_OK when the tree succeeded but the architecture.md render
+    # raised. The signal surface is:
+    # * RENDER_FAILED=true|false — always emitted.
+    # * RENDER_ERROR_DETAIL=<...> — emitted ONLY on true, redacted
+    # at write_emit_ctx-time.
+    # * STATUS auto-promoted OK -> PARTIAL_OK; _partial_reason pinned
+    # to "render-failed" when the tree wasn't already partial.
+    # ERROR paths (AUTH_REQUIRED etc.) retain their original status:
+    # render never runs in those cases, and render_failed defaults to
+    # False so the auto-promote below is a no-op.
+    render_failed = bool(ctx.get("render_failed", False))
+    lines.append(f"RENDER_FAILED={bool_str(render_failed)}")
+    if render_failed:
+        detail = scrub(ctx.get("render_error_detail", "") or "")
+        lines.append(f"RENDER_ERROR_DETAIL={detail}")
+        if status == "OK":
+            # Same positional-safety discipline as the partial auto-promote.
+            assert lines[1].startswith("STATUS="), (
+                f"emit block reordered — lines[1]={lines[1]!r}"
+            )
+            lines[1] = "STATUS=PARTIAL_OK"
+            status = "PARTIAL_OK"
+            # Pin a partial_reason so triagers can tell this apart from a
+            # tree-level partial. We walk backwards to find the existing
+            # PARTIAL_REASON line (always present — emitted above) and
+            # rewrite in place. A fresh line would create two competing
+            # reason values in the block.
+            for idx in range(len(lines) - 1, -1, -1):
+                if lines[idx].startswith("PARTIAL_REASON="):
+                    # Only overwrite when the tree didn't already claim
+                    # a reason — the tree's reason is more informative.
+                    if lines[idx] == "PARTIAL_REASON=":
+                        lines[idx] = "PARTIAL_REASON=render-failed"
+                    break
+
+    # Error-path-specific optional keys
+    if status == "AGENT_NOT_FOUND":
+        bots = scrub(ctx.get("available_bots", ""))
+        if bots:
+            lines.append(f"AVAILABLE_BOTS={bots}")
+    if status == "AGENT_VERSION_NOT_FOUND":
+        vers = scrub(ctx.get("available_versions", ""))
+        if vers:
+            lines.append(f"AVAILABLE_VERSIONS={vers}")
+
+    lines.append(f"WALL_TIME_SECONDS={wall_time_seconds:.2f}")
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    work_dir_s = os.environ.get("WORK_DIR", "")
+    if not work_dir_s:
+        sys.stderr.write("emit_result.py: $WORK_DIR not set\n")
+        return 1
+
+    ctx_path = pathlib.Path(work_dir_s) / ".emit_ctx.json"
+    try:
+        ctx = json.loads(ctx_path.read_text())
+    except FileNotFoundError:
+        sys.stderr.write(f"emit_result.py: missing {ctx_path}\n")
+        return 1
+    except (OSError, json.JSONDecodeError) as e:
+        sys.stderr.write(f"emit_result.py: cannot read {ctx_path}: {e}\n")
+        return 1
+
+    start_epoch = float(ctx.get("start_epoch") or time.time())
+    wall = max(0.0, time.time() - start_epoch)
+
+    data_dir_s = scrub(ctx.get("data_dir", ""))
+    if not data_dir_s:
+        # Fallback default — runtime-agnostic. Mirrors runtime.resolve_data_root()
+        # in scripts/_shared/runtime.py (the pipeline's canonical helper). This
+        # tool runs standalone (no sys.path to scripts/), so we duplicate the
+        # default rather than import. If main.py ran with --data-dir, the
+        # ctx.data_dir field already carries the override value, so this
+        # branch is only reached when the pipeline aborted before writing it.
+        data_dir_s = str(
+            pathlib.Path.home()
+            / ".vibe"
+            / "data"
+            / "investigating-agentforce-architecture"
+            / "_agents"
+        )
+    data_dir = pathlib.Path(data_dir_s)
+    tee_path = data_dir / "last_result_block.txt"
+
+    body = build_block(ctx, wall)
+    body += f"RESULT_BLOCK_PATH={tee_path}\n"
+
+    try:
+        data_dir.mkdir(parents=True, exist_ok=True)
+        tmp = tee_path.with_suffix(tee_path.suffix + ".tmp")
+        tmp.write_text(body)
+        os.replace(tmp, tee_path)
+    except OSError as e:
+        sys.stderr.write(f"emit_result.py: tee failed ({e}); continuing with stdout\n")
+
+    status = (ctx.get("status") or "").strip().upper()
+    prose = PROSE.get(status, f"Unknown status {status}.")
+    sys.stdout.write(prose + "\n\n")
+    sys.stdout.write(body)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/investigating-agentforce-architecture/tools/sanitize.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Scrub dangerous characters from a string before splicing into the RESULT block.
+
+Strips characters that would corrupt the `KEY=VALUE` line format parsers use to read
+the RESULT block: backtick, dollar, double-quote, backslash, CR, tab, NUL, newline.
+
+Used when interpolating user-controlled values (session_id, org_alias, sf CLI stderr
+excerpts) into ERROR_DETAIL and other RESULT fields. Without scrubbing, a malicious
+or malformed input could inject fake KEY=VALUE pairs that downstream consumers
+would treat as authoritative.
+
+Usage:
+    _safe=$(python3 "$SKILL/tools/sanitize.py" "$raw_value")
+
+Arguments:
+    argv[1]  raw string (may be empty)
+
+Output:
+    stdout   scrubbed string (no trailing newline)
+    exit 0   always (even on empty input)
+"""
+import sys
+
+BAD = set("`$\"\\\r\t\0\n")
+
+
+def scrub(s: str) -> str:
+    return "".join(c for c in s if c not in BAD)
+
+
+if __name__ == "__main__":
+    raw = sys.argv[1] if len(sys.argv) > 1 else ""
+    sys.stdout.write(scrub(raw))

package/skills/investigating-agentforce-architecture/tools/write_emit_ctx.py

@@ -0,0 +1,332 @@
+#!/usr/bin/env python3
+"""Write the `$WORK_DIR/.emit_ctx.json` context file for `emit_result.py`.
+
+The agent's bash pipeline has ~10 places where it needs to populate this
+context file (one OK path + 6 error paths + cache-hit path). Previously this
+was done with inline `python3 - <<PYCTX` heredocs; extracting it into one
+script gives a stable allowlist footprint and a single source of truth for
+the ctx-file shape.
+
+This script reads every field from env vars the agent has already exported
+and writes the JSON atomically. Status-specific error messages come in via
+`STATUS` + `ERROR_DETAIL`; the rest of the fields are derived from the run's
+already-exported state.
+
+Usage:
+    STATUS=OK ERROR_DETAIL='' CACHE_HIT=false \\
+      python3 write_emit_ctx.py
+
+Inputs (env):
+    WORK_DIR             required — target dir for .emit_ctx.json
+    AGENT_API_NAME       required
+    AGENT_VERSION        required on success paths, may be empty on early fails
+    VERSION_AUTO_PICKED  'true'/'false'; defaults to false
+    AGENT_GENERATION     'classic'|'nga'|'unknown'; defaults to 'unknown'
+    BOT_ID               required on success paths, may be empty on early fails
+    ORG_ID_15            required on success paths, may be empty on early fails
+    ORG_ID_18            required on success paths, may be empty on early fails
+    CACHE_HIT            'true'/'false'; defaults to false
+    CACHED_AT_UTC        ISO-8601 or empty
+    NODE_COUNT           integer as string; defaults to 0
+    DEPTH                integer as string; defaults to 0
+    PARTIAL              'true'/'false'; defaults to false
+    UNRESOLVED_COUNT     integer as string; defaults to 0
+    START_EPOCH          float seconds since epoch
+    DATA_DIR             required — absolute path (may be org-less sentinel dir on early fail)
+    CACHE_PATH           optional — absolute path to cache dir (ends with /)
+    OUTPUT_JSON_PATH     optional — computed if empty on OK path
+    OUTPUT_SUMMARY_PATH  optional — computed if empty on OK path
+    AVAILABLE_BOTS       optional — csv, for AGENT_NOT_FOUND
+    AVAILABLE_VERSIONS   optional — csv, for AGENT_VERSION_NOT_FOUND
+    STATUS               required — one of the 7 enum values
+    ERROR_DETAIL         optional — human-readable error message
+
+ (REMEDIATE) derived keys (read from tree JSON, not env):
+    ctx["partial_reason"]         from tree["_partial_reason"] (default "")
+    ctx["pending_fetches_count"]  sum(len(v) for v in tree["_pending_fetches"].values())
+                                  (default 0)
+
+The tree is read from `$WORK_DIR/declared_action_tree.json` — this is
+where parse_wave.py writes. If the file is missing / unreadable / malformed,
+both keys default to empty / 0 (pre-remediation behavior). This keeps
+early-abort paths (AGENT_NOT_FOUND / AUTH_REQUIRED / etc.) working —
+they never produce a tree and rightly surface `partial_reason=""` +
+`pending_fetches_count=0`.
+
+derived keys (read from data_dir, not env):
+    ctx["architecture_path"]       absolute path to `architecture.md` when
+                                   the renderer produced one, else "".
+    ctx["render_failed"]           True iff a `architecture.md.error`
+                                   sidecar exists (written by
+                                   main._run_finalize on renderer exception).
+    ctx["render_error_detail"]     first 200 chars of sidecar, scrubbed via
+                                   rest_client.redact_text. Empty when
+                                   render_failed is False. The redact pass
+                                   is defensive — the sidecar shouldn't
+                                   carry tokens, but exception messages
+                                   can carry arbitrary org content.
+
+The sidecar convention pairs with `architecture.md`: finalize writes the
+`.error` only on exception; emit_result's RESULT-block auto-promote to
+PARTIAL_OK relies on this boolean to flag "tree OK, diagram skipped".
+
+Output:
+    $WORK_DIR/.emit_ctx.json
+    exit 0 on success, 1 on missing env / write failure
+"""
+import json
+import os
+import pathlib
+import re
+import sys
+
+
+# local, dependency-free token scrub mirroring the patterns in
+# `scripts/rest_client.redact_text`. Keeping the redactor inline preserves
+# the tools/ <-> scripts/ decoupling (tools/ is stdlib-only by policy) and
+# avoids adding a sys.path hop on every write_emit_ctx invocation. The two
+# implementations must stay in sync; the shared regex shapes are:
+# * Authorization: Bearer <token>
+# * access(_)?Token=<value> in query strings
+# * "access(_)?Token":"<value>" in JSON payloads
+# If a new redaction pattern is added to rest_client.redact_text it MUST be
+# mirrored here — the sidecar surface is narrow (render_architecture
+# exception messages) so the risk of drift is low, but the dual-impl is a
+# known trade-off for decoupling.
+_TOOLS_AUTH_HEADER_RE = re.compile(
+    r"(Authorization:\s*Bearer\s+)[^\s\"'<>]+",
+    flags=re.IGNORECASE,
+)
+_TOOLS_ACCESS_TOKEN_QS_RE = re.compile(
+    r"(access[_]?token=)[^&\s\"'<>]+",
+    flags=re.IGNORECASE,
+)
+_TOOLS_ACCESS_TOKEN_JSON_RE = re.compile(
+    r"(\"access[_]?token\"\s*:\s*\")[^\"]*",
+    flags=re.IGNORECASE,
+)
+
+
+def _redact(text: str) -> str:
+    if not text:
+        return text
+    text = _TOOLS_AUTH_HEADER_RE.sub(r"\1<redacted>", text)
+    text = _TOOLS_ACCESS_TOKEN_QS_RE.sub(r"\1<redacted>", text)
+    text = _TOOLS_ACCESS_TOKEN_JSON_RE.sub(r'\1<redacted>', text)
+    return text
+
+
+def _bool(v: str) -> bool:
+    return (v or "").strip().lower() == "true"
+
+
+def _int(v: str, default: int = 0) -> int:
+    try:
+        return int((v or "").strip() or default)
+    except ValueError:
+        return default
+
+
+def _read_architecture_signals(
+    data_dir: str,
+    agent_api_name: str = "",
+    agent_version: str = "",
+) -> tuple[str, bool, str]:
+    """surface architecture.md presence + render-failure sidecar.
+
+    filename is now self-identifying —
+    `{agent_api_name}_{agent_version}_architecture.md` (plus `.error`
+    sidecar). Callers pass both identifiers through; when either is
+    missing we fall back to the legacy bare `architecture.md` / `.error`
+    names so early-abort paths that haven't resolved an agent yet still
+    surface any stray files they produced.
+
+    Returns `(architecture_path, render_failed, render_error_detail)`:
+
+      * `architecture_path` — absolute str to the rendered architecture.md
+        when present; `""` otherwise. Empty also covers cache-hit paths
+        where a *past* run's file may exist — see the inline note.
+      * `render_failed` — True iff the `.error` sidecar exists (written by
+        main._run_finalize on renderer exception).
+      * `render_error_detail` — first 200 chars of the sidecar, stripped +
+        scrubbed via `_redact`. Empty when `render_failed` is False.
+
+    Tolerant of: missing dir, unreadable sidecar, binary content. A failure
+    to read the sidecar degrades to an empty detail string rather than
+    suppressing the render_failed flag — consumers still see the outage
+    signal, just without the triage text.
+
+    Cache-hit caveat: on a cache replay, the prior run's architecture.md
+    may still be present. We intentionally surface its path anyway (the
+    file *is* a product of this run's data_dir). Sidecar semantics are
+    different — the sidecar only lands via finalize, so a cache replay
+    cannot plant a stale `.error`.
+    """
+    if not data_dir:
+        return ("", False, "")
+    dd = pathlib.Path(data_dir)
+    if agent_api_name and agent_version:
+        arch = dd / f"{agent_api_name}_{agent_version}_architecture.md"
+        sidecar = dd / f"{agent_api_name}_{agent_version}_architecture.md.error"
+    else:
+        # Early-abort paths (no agent resolved) fall back to the legacy
+        # bare name so any stray file still surfaces.
+        arch = dd / "architecture.md"
+        sidecar = dd / "architecture.md.error"
+
+    arch_path = str(arch) if arch.is_file() else ""
+
+    if not sidecar.is_file():
+        return (arch_path, False, "")
+
+    try:
+        # read_text()'s default is utf-8 with strict errors; a sidecar
+        # written by finalize is always ascii prose, but be defensive in
+        # case future code changes widen the content set.
+        raw = sidecar.read_text(errors="replace")
+    except OSError:
+        return (arch_path, True, "")
+
+    # Truncate to a single-line-ish detail string. The sidecar format is
+    # `"render_architecture failed: <ExcType>: <msg>\n"`; we strip + cap
+    # at 200 chars to keep the RESULT block readable, then scrub.
+    detail = raw.strip().splitlines()[0] if raw.strip() else ""
+    detail = _redact(detail)[:200]
+    return (arch_path, True, detail)
+
+
+def _read_tree_partial_signals(work_dir: str) -> tuple[str, int]:
+    """extract `_partial_reason` + pending-fetches rollup from the tree.
+
+    Reads `$WORK_DIR/declared_action_tree.json` (parse_wave's output) and
+    returns `(partial_reason, pending_fetches_count)`.
+
+    Tolerant of: missing file, unreadable file, malformed JSON, missing
+    keys, wrong-typed keys. All of those degrade to `("", 0)` — the
+    pre-remediation defaults — so early-abort code paths (which never
+    produce a tree) behave unchanged.
+
+    This is intentionally defensive: write_emit_ctx runs on every exit
+    path, including ones where the tree was never created. A raise here
+    would turn a clean error status into a write failure.
+    """
+    try:
+        tree_path = pathlib.Path(work_dir) / "declared_action_tree.json"
+        if not tree_path.is_file():
+            return ("", 0)
+        tree = json.loads(tree_path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return ("", 0)
+
+    if not isinstance(tree, dict):
+        return ("", 0)
+
+    reason_raw = tree.get("_partial_reason")
+    reason = reason_raw if isinstance(reason_raw, str) else ""
+
+    pending = tree.get("_pending_fetches")
+    count = 0
+    if isinstance(pending, dict):
+        for v in pending.values():
+            if isinstance(v, list):
+                count += len(v)
+
+    return (reason, count)
+
+
+def main() -> int:
+    try:
+        work_dir = os.environ["WORK_DIR"]
+        data_dir = os.environ["DATA_DIR"]
+        status = os.environ["STATUS"]
+    except KeyError as e:
+        sys.stderr.write(f"write_emit_ctx.py: missing env {e}\n")
+        return 1
+
+    agent_api_name = os.environ.get("AGENT_API_NAME", "")
+    agent_version = os.environ.get("AGENT_VERSION", "")
+    org_id_15 = os.environ.get("ORG_ID_15", "")
+
+    # Default OUTPUT_*_PATH paths follow the agent-scoped naming convention.
+    # Caller can override by exporting directly. If DATA_DIR already ends with
+    # the per-agent suffix (because the agent bash composed it), don't re-append.
+    #
+    # summary.md dropped from the output contract — OUTPUT_SUMMARY_PATH
+    # is kept in the RESULT block (empty string) for shape stability.
+    default_json = ""
+    if status in ("OK", "PARTIAL_OK") and org_id_15 and agent_api_name and agent_version:
+        per_agent_suffix = f"{org_id_15}/{agent_api_name}__{agent_version}"
+        dd = data_dir.rstrip("/")
+        base = dd if dd.endswith(per_agent_suffix) else f"{dd}/{per_agent_suffix}"
+        default_json = f"{base}/{agent_api_name}_{agent_version}_metadata_tree.json"
+
+    output_json = os.environ.get("OUTPUT_JSON_PATH") or default_json
+    output_summary = os.environ.get("OUTPUT_SUMMARY_PATH") or ""
+
+    try:
+        start_epoch = float(os.environ.get("START_EPOCH", "0") or "0")
+    except ValueError:
+        start_epoch = 0.0
+
+    # derive partial_reason + pending_fetches_count from the tree
+    # on disk rather than relying on the agent bash to export them. The
+    # tree is the single source of truth — parse_wave wrote these fields;
+    # having the bash re-export them would be a narrow, drift-prone
+    # integration layer. Absent tree → default ("", 0).
+    partial_reason, pending_fetches_count = _read_tree_partial_signals(work_dir)
+
+    # derive architecture-output signals from the data_dir.
+    # Parallel to the partial-signals plumbing above: data_dir is the
+    # single source of truth for what finalize produced. A missing dir
+    # (early-abort paths) degrades to empty fields and render_failed=False.
+    architecture_path, render_failed, render_error_detail = (
+        _read_architecture_signals(data_dir, agent_api_name, agent_version)
+    )
+
+    ctx = {
+        "status": status,
+        "error_detail": os.environ.get("ERROR_DETAIL", ""),
+        "agent_api_name": agent_api_name,
+        "agent_version": agent_version,
+        "version_auto_picked": _bool(os.environ.get("VERSION_AUTO_PICKED", "")),
+        "agent_generation": os.environ.get("AGENT_GENERATION", "") or "unknown",
+        "bot_id": os.environ.get("BOT_ID", ""),
+        "org_id_15": org_id_15,
+        "org_id_18": os.environ.get("ORG_ID_18", ""),
+        "cache_hit": _bool(os.environ.get("CACHE_HIT", "")),
+        "cached_at_utc": os.environ.get("CACHED_AT_UTC", ""),
+        "cache_path": os.environ.get("CACHE_PATH", ""),
+        "output_json_path": output_json,
+        "output_summary_path": output_summary,
+        "node_count": _int(os.environ.get("NODE_COUNT", "0")),
+        "depth": _int(os.environ.get("DEPTH", "0")),
+        "partial": _bool(os.environ.get("PARTIAL", "")),
+        # plumbed from the tree, not env.
+        "partial_reason": partial_reason,
+        "pending_fetches_count": pending_fetches_count,
+        "unresolved_count": _int(os.environ.get("UNRESOLVED_COUNT", "0")),
+        "available_bots": os.environ.get("AVAILABLE_BOTS", ""),
+        "available_versions": os.environ.get("AVAILABLE_VERSIONS", ""),
+        "start_epoch": start_epoch,
+        "data_dir": data_dir,
+        "work_dir": work_dir,
+        # architecture-render outcome signals.
+        "architecture_path": architecture_path,
+        "render_failed": render_failed,
+        "render_error_detail": render_error_detail,
+    }
+
+    out = pathlib.Path(work_dir) / ".emit_ctx.json"
+    try:
+        out.parent.mkdir(parents=True, exist_ok=True)
+        tmp = out.with_suffix(out.suffix + ".tmp")
+        tmp.write_text(json.dumps(ctx, indent=2))
+        os.replace(tmp, out)
+    except OSError as e:
+        sys.stderr.write(f"write_emit_ctx.py: write failed: {e}\n")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())