safe_output_handler_manager.cjs

// @ts-check
/// <reference types="@actions/github-script" />

/**
 * Safe Output Handler Manager
 *
 * This module manages the dispatch of safe output messages to dedicated handlers.
 * It reads configuration, loads the appropriate handlers for enabled safe output types,
 * and processes messages from the agent output file while maintaining a shared temporary ID map.
 */

const { loadAgentOutput } = require("./load_agent_output.cjs");
const { getErrorMessage } = require("./error_helpers.cjs");
const { ERR_CONFIG, ERR_PARSE, ERR_VALIDATION } = require("./error_codes.cjs");
const { hasUnresolvedTemporaryIds, replaceTemporaryIdReferences, replaceArtifactUrlReferences, normalizeTemporaryId } = require("./temporary_id.cjs");
const { generateMissingInfoSections } = require("./missing_info_formatter.cjs");
const { setCollectedMissings } = require("./missing_messages_helper.cjs");
const { writeSafeOutputSummaries } = require("./safe_output_summary.cjs");
const { getAssignToAgentAssigned, getAssignToAgentErrors, getAssignToAgentErrorCount, writeAssignToAgentSummary } = require("./assign_to_agent.cjs");
const { getCreateAgentSessionNumber, getCreateAgentSessionUrl, writeCreateAgentSessionSummary } = require("./create_agent_session.cjs");
const { createReviewBuffer } = require("./pr_review_buffer.cjs");
const { sanitizeContent } = require("./sanitize_content.cjs");
const { createManifestLogger, ensureManifestExists, extractCreatedItemFromResult, writeTemporaryIdMapFile } = require("./safe_output_manifest.cjs");
const { loadCustomSafeOutputJobTypes, loadCustomSafeOutputScriptHandlers, loadCustomSafeOutputActionHandlers, isStagedMode } = require("./safe_output_helpers.cjs");
const { emitSafeOutputActionOutputs } = require("./safe_outputs_action_outputs.cjs");
const { listCommentMemoryFiles, COMMENT_MEMORY_DIR } = require("./comment_memory_helpers.cjs");
const { expandFileReferences } = require("./runtime_import.cjs");
const nodePath = require("path");
const fs = require("fs");

/**
 * Handler map configuration
 * Maps safe output types to their handler module file paths
 */
const HANDLER_MAP = {
  create_issue: "./create_issue.cjs",
  add_comment: "./add_comment.cjs",
  comment_memory: "./comment_memory.cjs",
  create_discussion: "./create_discussion.cjs",
  close_issue: "./close_issue.cjs",
  close_discussion: "./close_discussion.cjs",
  add_labels: "./add_labels.cjs",
  remove_labels: "./remove_labels.cjs",
  update_issue: "./update_issue.cjs",
  update_discussion: "./update_discussion.cjs",
  link_sub_issue: "./link_sub_issue.cjs",
  update_release: "./update_release.cjs",
  create_pull_request_review_comment: "./create_pr_review_comment.cjs",
  submit_pull_request_review: "./submit_pr_review.cjs",
  reply_to_pull_request_review_comment: "./reply_to_pr_review_comment.cjs",
  resolve_pull_request_review_thread: "./resolve_pr_review_thread.cjs",
  create_pull_request: "./create_pull_request.cjs",
  push_to_pull_request_branch: "./push_to_pull_request_branch.cjs",
  update_pull_request: "./update_pull_request.cjs",
  merge_pull_request: "./merge_pull_request.cjs",
  close_pull_request: "./close_pull_request.cjs",
  mark_pull_request_as_ready_for_review: "./mark_pull_request_as_ready_for_review.cjs",
  hide_comment: "./hide_comment.cjs",
  set_issue_type: "./set_issue_type.cjs",
  add_reviewer: "./add_reviewer.cjs",
  assign_milestone: "./assign_milestone.cjs",
  assign_to_user: "./assign_to_user.cjs",
  unassign_from_user: "./unassign_from_user.cjs",
  assign_to_agent: "./assign_to_agent.cjs",
  create_agent_session: "./create_agent_session.cjs",
  create_code_scanning_alert: "./create_code_scanning_alert.cjs",
  autofix_code_scanning_alert: "./autofix_code_scanning_alert.cjs",
  dispatch_workflow: "./dispatch_workflow.cjs",
  dispatch_repository: "./dispatch_repository.cjs",
  call_workflow: "./call_workflow.cjs",
  create_missing_tool_issue: "./create_missing_tool_issue.cjs",
  missing_tool: "./missing_tool.cjs",
  create_missing_data_issue: "./create_missing_data_issue.cjs",
  missing_data: "./missing_data.cjs",
  noop: "./noop_handler.cjs",
  report_incomplete: "./report_incomplete_handler.cjs",
  create_report_incomplete_issue: "./create_report_incomplete_issue.cjs",
  create_project: "./create_project.cjs",
  create_project_status_update: "./create_project_status_update.cjs",
  update_project: "./update_project.cjs",
  upload_artifact: "./upload_artifact.cjs",
};

/**
 * Message types handled by standalone steps (not through the handler manager)
 * These types should not trigger warnings when skipped by the handler manager
 *
 * Standalone types: upload_asset, noop
 *   - Have dedicated processing steps with specialized logic
 */
const STANDALONE_STEP_TYPES = new Set(["upload_asset", "noop"]);

/**
 * Code-push safe output types that must succeed before remaining outputs are processed.
 * If any of these fail, the remaining non-code-push messages are cancelled with a clear reason.
 */
const CODE_PUSH_TYPES = new Set(["push_to_pull_request_branch", "create_pull_request"]);

function buildCommentMemoryMessagesFromFiles(existingMessages, config) {
  if (!config.comment_memory) {
    return [];
  }

  const fallbackMemoryId = normalizeCommentMemoryId(config?.comment_memory?.memory_id, "default");
  const existingMemoryIds = new Set(existingMessages.filter(isCommentMemoryMessage).map(message => normalizeCommentMemoryId(message.memory_id, fallbackMemoryId)));

  const fileEntries = listCommentMemoryFiles(COMMENT_MEMORY_DIR);
  if (fileEntries.length === 0) {
    return [];
  }

  const messages = [];
  for (const entry of fileEntries) {
    if (existingMemoryIds.has(entry.memoryId)) {
      continue;
    }
    let body = "";
    try {
      body = fs.readFileSync(entry.filePath, "utf8").replace(/\n+$/, "");
    } catch (error) {
      core.warning(`Failed to read comment-memory file '${entry.filePath}': ${getErrorMessage(error)}`);
      continue;
    }
    messages.push({
      type: "comment_memory",
      memory_id: entry.memoryId,
      body,
    });
  }

  if (messages.length > 0) {
    core.info(`Loaded ${messages.length} comment_memory message(s) from ${COMMENT_MEMORY_DIR}`);
  }
  return messages;
}

function isCommentMemoryMessage(message) {
  // memory_id normalization/validation is handled separately in normalizeCommentMemoryId.
  return message?.type === "comment_memory";
}

function normalizeCommentMemoryId(memoryId, fallback = "default") {
  if (typeof memoryId !== "string") {
    return fallback;
  }
  const normalized = memoryId.trim();
  return normalized.length > 0 ? normalized : fallback;
}

/**
 * Load configuration for safe outputs
 * Reads configuration from GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG environment variable
 * @returns {Object} Safe outputs configuration
 */
function loadConfig() {
  if (!process.env.GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG) {
    throw new Error(`${ERR_CONFIG}: GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG environment variable is required but not set`);
  }

  try {
    const config = JSON.parse(process.env.GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG);
    core.info(`Loaded config from GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: ${JSON.stringify(config)}`);
    // Normalize config keys: convert hyphens to underscores
    return Object.fromEntries(Object.entries(config).map(([k, v]) => [k.replace(/-/g, "_"), v]));
  } catch (error) {
    throw new Error(`${ERR_PARSE}: Failed to parse GH_AW_SAFE_OUTPUTS_HANDLER_CONFIG: ${getErrorMessage(error)}`);
  }
}

/** @type {Set<string>} Handler types that participate in the PR review buffer */
const PR_REVIEW_HANDLER_TYPES = new Set(["create_pull_request_review_comment", "submit_pull_request_review"]);

/**
 * Load and initialize handlers for enabled safe output types
 * Calls each handler's factory function (main) to get message processors
 * @param {Object} config - Safe outputs configuration
 * @param {Object} prReviewBuffer - Shared PR review buffer instance
 * @returns {Promise<Map<string, Function>>} Map of type to message handler function
 */
async function loadHandlers(config, prReviewBuffer) {
  const messageHandlers = new Map();

  core.info("Loading and initializing safe output handlers based on configuration...");

  for (const [type, handlerPath] of Object.entries(HANDLER_MAP)) {
    // Check if this safe output type is enabled in the config
    // The presence of the config key indicates the handler should be loaded
    if (config[type]) {
      try {
        const handlerModule = require(handlerPath);
        if (handlerModule && typeof handlerModule.main === "function") {
          // Call the factory function with config to get the message handler
          const handlerConfig = { ...(config[type] || {}) };

          // Inject shared PR review buffer into handlers that need it
          if (PR_REVIEW_HANDLER_TYPES.has(type)) {
            handlerConfig._prReviewBuffer = prReviewBuffer;
          }

          const messageHandler = await handlerModule.main(handlerConfig);

          if (typeof messageHandler !== "function") {
            // This is a fatal error - the handler is misconfigured
            // Re-throw to fail the step rather than continuing
            const error = new Error(`Handler ${type} main() did not return a function - expected a message handler function but got ${typeof messageHandler}`);
            core.error(`✗ Fatal error loading handler ${type}: ${error.message}`);
            throw error;
          }

          messageHandlers.set(type, messageHandler);
          core.info(`✓ Loaded and initialized handler for: ${type}`);
        } else {
          core.warning(`Handler module ${type} does not export a main function`);
        }
      } catch (error) {
        // Re-throw fatal handler validation errors
        const errorMessage = getErrorMessage(error);
        if (errorMessage.includes("did not return a function")) {
          throw error;
        }
        // For other errors (e.g., module not found), log warning and continue
        core.warning(`Failed to load handler for ${type}: ${errorMessage}`);
      }
    } else {
      core.debug(`Handler not enabled: ${type}`);
    }
  }

  // Load custom script handlers from GH_AW_SAFE_OUTPUT_SCRIPTS
  // These are inline scripts defined in safe-outputs.scripts that run in the handler loop
  const customScriptHandlers = loadCustomSafeOutputScriptHandlers();
  if (customScriptHandlers.size > 0) {
    core.info(`Loading ${customScriptHandlers.size} custom script handler(s): ${[...customScriptHandlers.keys()].join(", ")}`);
    const scriptBaseDir = nodePath.join(process.env.RUNNER_TEMP || "/tmp", "gh-aw", "actions");
    for (const [scriptType, scriptFilename] of customScriptHandlers) {
      // Sanitize scriptFilename to prevent path traversal attacks: only the basename
      // (no directory separators or ".." sequences) is allowed.
      const safeFilename = nodePath.basename(scriptFilename);
      if (safeFilename !== scriptFilename) {
        core.error(`Invalid script filename for ${scriptType}: path traversal detected in "${scriptFilename}" — skipping`);
        continue;
      }
      const scriptPath = nodePath.join(scriptBaseDir, safeFilename);
      // Defense-in-depth: verify the resolved path remains within the expected directory.
      // Use path.relative() to check containment robustly across all platforms.
      const relativeToBase = nodePath.relative(scriptBaseDir, scriptPath);
      if (relativeToBase.startsWith("..") || nodePath.isAbsolute(relativeToBase)) {
        core.error(`Script path outside expected directory for ${scriptType}: "${scriptPath}" — skipping`);
        continue;
      }
      try {
        const scriptModule = require(scriptPath);
        if (scriptModule && typeof scriptModule.main === "function") {
          const handlerConfig = config[scriptType] || {};
          const messageHandler = await scriptModule.main(handlerConfig);
          if (typeof messageHandler !== "function") {
            // Non-fatal: warn and skip this custom script handler rather than crashing the
            // entire safe-output loop. A misconfigured user script should not block all
            // other safe-output operations.
            core.warning(`✗ Custom script handler ${scriptType} main() did not return a function (got ${typeof messageHandler}) — this handler will be skipped`);
          } else {
            messageHandlers.set(scriptType, messageHandler);
            core.info(`✓ Loaded and initialized custom script handler for: ${scriptType}`);
          }
        } else {
          core.warning(`Custom script handler module ${scriptType} does not export a main function — skipping`);
        }
      } catch (error) {
        // Non-fatal: log a warning and continue loading the remaining handlers. A broken
        // custom script should not prevent built-in or other custom handlers from running.
        core.warning(`Failed to load custom script handler for ${scriptType}: ${getErrorMessage(error)} — this handler will be skipped`);
      }
    }
  }

  // Load custom action handlers from GH_AW_SAFE_OUTPUT_ACTIONS
  // These are GitHub Actions configured in safe-outputs.actions. The handler applies
  // temporary ID substitutions to the payload and exports `action_<name>_payload` outputs
  // that compiler-generated `uses:` steps consume.
  const customActionHandlers = loadCustomSafeOutputActionHandlers();
  if (customActionHandlers.size > 0) {
    core.info(`Loading ${customActionHandlers.size} custom action handler(s): ${[...customActionHandlers.keys()].join(", ")}`);
    const actionHandlerPath = require("path").join(__dirname, "safe_output_action_handler.cjs");
    for (const [actionType, actionName] of customActionHandlers) {
      try {
        const actionModule = require(actionHandlerPath);
        if (actionModule && typeof actionModule.main === "function") {
          const handlerConfig = { action_name: actionName, ...(config[actionType] || {}) };
          const messageHandler = await actionModule.main(handlerConfig);
          if (typeof messageHandler !== "function") {
            core.warning(`✗ Custom action handler ${actionType} main() did not return a function (got ${typeof messageHandler}) — this handler will be skipped`);
          } else {
            messageHandlers.set(actionType, messageHandler);
            core.info(`✓ Loaded and initialized custom action handler for: ${actionType}`);
          }
        } else {
          core.warning(`Custom action handler module does not export a main function — skipping ${actionType}`);
        }
      } catch (error) {
        core.warning(`Failed to load custom action handler for ${actionType}: ${getErrorMessage(error)} — this handler will be skipped`);
      }
    }
  }

  core.info(`Loaded ${messageHandlers.size} handler(s)`);
  return messageHandlers;
}

/**
 * Collect missing_tool, missing_data, noop, and report_incomplete messages from the messages array
 * @param {Array<Object>} messages - Array of safe output messages
 * @returns {{missingTools: Array<any>, missingData: Array<any>, noopMessages: Array<any>, reportIncomplete: Array<any>}} Object with collected missing items, noop messages, and incomplete signals
 */
function collectMissingMessages(messages) {
  const missingTools = [];
  const missingData = [];
  const noopMessages = [];
  const reportIncomplete = [];

  for (const message of messages) {
    if (message.type === "missing_tool") {
      // Extract relevant fields from missing_tool message
      if (message.tool && message.reason) {
        missingTools.push({
          tool: message.tool,
          reason: message.reason,
          alternatives: message.alternatives || null,
        });
      }
    } else if (message.type === "missing_data") {
      // Extract relevant fields from missing_data message
      if (message.data_type && message.reason) {
        missingData.push({
          data_type: message.data_type,
          reason: message.reason,
          context: message.context || null,
          alternatives: message.alternatives || null,
        });
      }
    } else if (message.type === "noop") {
      // Extract relevant fields from noop message
      if (message.message) {
        noopMessages.push({
          message: message.message,
        });
      }
    } else if (message.type === "report_incomplete") {
      // Extract relevant fields from report_incomplete message
      if (message.reason) {
        reportIncomplete.push({
          reason: message.reason,
          details: message.details || null,
        });
      }
    }
  }

  core.info(`Collected ${missingTools.length} missing tool(s), ${missingData.length} missing data item(s), ${noopMessages.length} noop message(s), and ${reportIncomplete.length} incomplete signal(s)`);
  return { missingTools, missingData, noopMessages, reportIncomplete };
}

/**
 * Format a log message for a manifest entry.
 * Prefers the URL when available, otherwise falls back to the item number.
 *
 * @param {{type: string, url?: string, number?: number}} item - Manifest item
 * @returns {string} Formatted log message
 */
function formatManifestLogMessage(item) {
  if (item.url) return `📝 Manifest: logged ${item.type} → ${item.url}`;
  if (item.number != null) return `📝 Manifest: logged ${item.type} #${item.number}`;
  return `📝 Manifest: logged ${item.type}`;
}

/**
 * Process all messages from agent output in the order they appear
 * Dispatches each message to the appropriate handler while maintaining shared state (temporary ID map)
 * Tracks outputs created with unresolved temporary IDs and generates synthetic updates after resolution
 *
 * @param {Map<string, Function>} messageHandlers - Map of message handler functions
 * @param {Array<Object>} messages - Array of safe output messages
 * @param {((item: {type: string, url?: string, number?: number, repo?: string, temporaryId?: string}) => void)|null} [onItemCreated] - Optional callback invoked after each successful create operation (for manifest logging)
 * @returns {Promise<{success: boolean, results: Array<any>, temporaryIdMap: Object, artifactUrlMap: Map<string, string>, outputsWithUnresolvedIds: Array<any>, missings: Object, codePushFailures: Array<{type: string, error: string}>}>}
 */
async function processMessages(messageHandlers, messages, onItemCreated = null) {
  const results = [];

  // Collect missing_tool, missing_data, noop, and report_incomplete messages first
  const missings = collectMissingMessages(messages);

  // Initialize shared temporary ID map
  // This will be populated by handlers as they create entities with temporary IDs
  /** @type {Map<string, {repo: string, number: number}>} */
  const temporaryIdMap = new Map();

  // Track artifact URL mappings: normalised tmpId → artifact download URL.
  // Populated after each successful upload_artifact call so that subsequent
  // messages can have '#aw_ID' references replaced with the real artifact URL.
  /** @type {Map<string, string>} */
  const artifactUrlMap = new Map();

  // Track outputs that were created with unresolved temporary IDs
  // Format: {type, message, result, originalTempIdMapSize}
  /** @type {Array<{type: string, message: any, result: any, originalTempIdMapSize: number}>} */
  const outputsWithUnresolvedIds = [];

  // Track messages that were deferred due to unresolved temporary IDs
  // These will be retried after the first pass when more temp IDs may be resolved
  /** @type {Array<{type: string, message: any, messageIndex: number, handler: Function}>} */
  const deferredMessages = [];

  // Track code-push failures for fail-fast behaviour.
  // If a code-push type (push_to_pull_request_branch / create_pull_request) fails,
  // all subsequent non-code-push messages are cancelled with a clear reason.
  /** @type {Array<{type: string, error: string}>} */
  const codePushFailures = [];

  // Track when a code-push operation falls back to creating an issue or pull request instead.
  // When set, subsequent add_comment messages will receive a correction note prepended
  // to their body so the posted comment accurately reflects the actual fallback target.
  /** @type {{type: string, fallbackTargetType: "issue" | "pull_request", number: number, url: string}|null} */
  let codePushFallbackInfo = null;

  // Load custom safe output job types (from GH_AW_SAFE_OUTPUT_JOBS env var)
  // These are processed by dedicated custom job steps, not by this handler manager
  const customJobTypes = loadCustomSafeOutputJobTypes();
  if (customJobTypes.size > 0) {
    core.info(`Loaded ${customJobTypes.size} custom safe output job type(s): ${[...customJobTypes].join(", ")}`);
  }

  core.info(`Processing ${messages.length} message(s) in order of appearance...`);

  // Process messages in order of appearance
  for (let i = 0; i < messages.length; i++) {
    const message = messages[i];
    const messageType = message.type;

    if (!messageType) {
      core.warning(`Skipping message ${i + 1} without type`);
      continue;
    }

    // Fail-fast: if a previous code-push operation failed, cancel non-code-push messages.
    // Exception: add_comment messages are allowed through so the status comment still reaches
    // the user — they will be annotated with a failure note (see effectiveMessage logic below).
    if (codePushFailures.length > 0 && !CODE_PUSH_TYPES.has(messageType) && messageType !== "add_comment") {
      const cancelReason = `Cancelled: code push operation failed (${codePushFailures[0].type}: ${codePushFailures[0].error})`;
      core.info(`⏭ Message ${i + 1} (${messageType}) cancelled — ${cancelReason}`);
      results.push({
        type: messageType,
        messageIndex: i,
        success: false,
        cancelled: true,
        reason: cancelReason,
      });
      continue;
    }

    const messageHandler = messageHandlers.get(messageType);

    if (!messageHandler) {
      // Check if this message type is handled by a standalone step
      if (STANDALONE_STEP_TYPES.has(messageType)) {
        // Silently skip - this is handled by a dedicated step
        core.debug(`Message ${i + 1} (${messageType}) will be handled by standalone step`);
        results.push({
          type: messageType,
          messageIndex: i,
          success: false,
          skipped: true,
          reason: "Handled by standalone step",
        });
        continue;
      }

      // Check if this message type is handled by a custom safe output job
      if (customJobTypes.has(messageType)) {
        core.debug(`Message ${i + 1} (${messageType}) will be handled by custom safe output job`);

        // Log the dispatch to the manifest so the operation is counted in SafeItemsCount.
        // The custom job does the actual work; here we record the intent from the message.
        if (onItemCreated) {
          // Prefer item_number (explicit target), fall back to issue_number then pull_request_number.
          // This mirrors the precedence order used by individual safe output handlers.
          const rawNumber = message.item_number ?? message.issue_number ?? message.pull_request_number;
          const itemNumber = rawNumber != null ? parseInt(String(rawNumber), 10) : undefined;
          const validNumber = itemNumber != null && !isNaN(itemNumber) ? itemNumber : undefined;

          const messageResult = {
            ...(validNumber != null ? { number: validNumber } : {}),
            ...(message.repo ? { repo: message.repo } : {}),
          };
          const createdItem = extractCreatedItemFromResult(messageType, messageResult);
          if (createdItem) {
            core.info(formatManifestLogMessage(createdItem));
            onItemCreated(createdItem);
          }
        }

        results.push({
          type: messageType,
          messageIndex: i,
          success: false,
          skipped: true,
          reason: "Handled by custom safe output job",
        });
        continue;
      }

      // Unknown message type - warn the user
      core.warning(
        `⚠️ No handler loaded for message type '${messageType}' (message ${i + 1}/${messages.length}). The message will be skipped. This may happen if the safe output type is not configured in the workflow's safe-outputs section.`
      );
      results.push({
        type: messageType,
        messageIndex: i,
        success: false,
        error: `No handler loaded for type '${messageType}'`,
      });
      continue;
    }

    try {
      core.info(`Processing message ${i + 1}/${messages.length}: ${messageType}`);

      // Convert Map to plain object for handler
      const resolvedTemporaryIds = Object.fromEntries(temporaryIdMap);

      // Record the temp ID map size before processing to detect new IDs
      const tempIdMapSizeBefore = temporaryIdMap.size;

      // For add_comment messages: prepend any relevant correction notes before the AI-generated
      // body so users see the clarification immediately.
      let effectiveMessage = message;
      if (messageType === "add_comment") {
        // If a previous code-push operation fell back to a review issue, prepend a correction note
        // so the posted comment accurately reflects the outcome.
        if (codePushFallbackInfo) {
          const fallbackNote =
            codePushFallbackInfo.fallbackTargetType === "pull_request"
              ? `\n\n---\n> [!NOTE]\n> Direct push to the original pull request branch was not possible (diverged/non-fast-forward). A fallback pull request was created instead: [#${codePushFallbackInfo.number}](${codePushFallbackInfo.url})\n\n`
              : `\n\n---\n> [!NOTE]\n> The pull request was not created — a fallback review issue was created instead due to protected file changes: [#${codePushFallbackInfo.number}](${codePushFallbackInfo.url})\n\n`;
          effectiveMessage = { ...effectiveMessage, body: fallbackNote + (effectiveMessage.body || "") };
          core.info(`Prepending fallback correction note to add_comment body (fallback ${codePushFallbackInfo.fallbackTargetType}: #${codePushFallbackInfo.number})`);
        }
        // If a previous code-push operation failed outright (e.g. patch application error),
        // prepend a failure warning so the status comment accurately reflects that the
        // code changes were not applied.
        if (codePushFailures.length > 0) {
          const failure = codePushFailures[0];
          const failureNote = `\n\n---\n> [!WARNING]\n> The \`${failure.type}\` operation failed: ${failure.error}. The code changes were not applied.\n\n`;
          effectiveMessage = { ...effectiveMessage, body: failureNote + (effectiveMessage.body || "") };
          core.info(`Prepending code push failure note to add_comment body (${failure.type}: ${failure.error})`);
        }
      }

      // Pre-process: replace any '#aw_ID' artifact URL references in the message body
      // with the actual artifact URL so handlers receive the resolved URL directly.
      // This is applied to all message types that carry a 'body' field.
      if (artifactUrlMap.size > 0 && effectiveMessage.body && typeof effectiveMessage.body === "string") {
        const resolvedBody = replaceArtifactUrlReferences(effectiveMessage.body, artifactUrlMap);
        if (resolvedBody !== effectiveMessage.body) {
          effectiveMessage = { ...effectiveMessage, body: resolvedBody };
          core.info(`Resolved artifact URL reference(s) in ${messageType} body`);
        }
      }

      // Pre-process: expand @/absolute/path file references in the message body.
      // Agents may write a path like @/tmp/gh-aw/agent/comment-body.md as the body
      // value; this resolves the file and inlines its contents before the handler runs.
      // Only paths within GITHUB_WORKSPACE or /tmp/gh-aw are expanded; all others are ignored.
      if (effectiveMessage.body && typeof effectiveMessage.body === "string") {
        const workspaceDir = process.env.GITHUB_WORKSPACE || "";
        const expandedBody = expandFileReferences(effectiveMessage.body, workspaceDir);
        if (expandedBody !== effectiveMessage.body) {
          effectiveMessage = { ...effectiveMessage, body: expandedBody };
          core.info(`Expanded @filepath reference(s) in ${messageType} body`);
        }
      }

      // Call the message handler with the individual message and resolved temp IDs
      const result = await messageHandler(effectiveMessage, resolvedTemporaryIds, temporaryIdMap);

      // Check if the handler explicitly returned a skipped result (e.g. if_no_changes: warn/ignore).
      // Skipped results should NOT trigger fail-fast cancellation of subsequent messages.
      if (result && result.success === false && result.skipped === true && !result.deferred) {
        const msg = result.error || "Handler returned success: false with skipped: true";
        core.info(`⏭ Message ${i + 1} (${messageType}) skipped — ${msg}`);
        results.push({
          type: messageType,
          messageIndex: i,
          success: false,
          skipped: true,
          error: msg,
        });
        continue;
      }

      // Check if the handler explicitly returned a failure
      if (result && result.success === false && !result.deferred) {
        const errorMsg = result.error || "Handler returned success: false";
        core.error(`✗ Message ${i + 1} (${messageType}) failed: ${errorMsg}`);
        results.push({
          type: messageType,
          messageIndex: i,
          success: false,
          error: errorMsg,
        });
        // Track code-push failures for fail-fast behaviour
        if (CODE_PUSH_TYPES.has(messageType)) {
          codePushFailures.push({ type: messageType, error: errorMsg });
          core.warning(`⚠️ Code push operation '${messageType}' failed — remaining safe outputs will be cancelled`);
        }
        continue;
      }

      // Check if the operation was deferred due to unresolved temporary IDs
      if (result && result.deferred === true) {
        core.info(`⏸ Message ${i + 1} (${messageType}) deferred - will retry after first pass`);
        deferredMessages.push({
          type: messageType,
          message: effectiveMessage,
          messageIndex: i,
          handler: messageHandler,
        });
        results.push({
          type: messageType,
          messageIndex: i,
          success: false,
          deferred: true,
          result,
        });
        continue;
      }

      // If handler returned a temp ID mapping, add it to our map
      if (result && result.temporaryId && result.repo && result.number) {
        const normalizedTempId = normalizeTemporaryId(result.temporaryId);
        temporaryIdMap.set(normalizedTempId, {
          repo: result.repo,
          number: result.number,
        });
        core.info(`Registered temporary ID: ${result.temporaryId} -> ${result.repo}#${result.number}`);
      }

      // If this was a successful upload_artifact, register the artifact URL so that
      // subsequent messages can have '#aw_ID' references replaced with the real URL.
      // upload_artifact returns { tmpId, artifactUrl } (not temporaryId/repo/number).
      if (messageType === "upload_artifact" && result && result.tmpId && result.artifactUrl) {
        const normalizedTmpId = normalizeTemporaryId(result.tmpId);
        if (!artifactUrlMap.has(normalizedTmpId)) {
          artifactUrlMap.set(normalizedTmpId, result.artifactUrl);
          core.info(`Registered artifact URL for temporary ID: ${result.tmpId}`);
        } else {
          core.warning(`Duplicate artifact temporary ID '${result.tmpId}' encountered; keeping the first registered URL and ignoring the later upload.`);
        }
      }

      // Track when a code-push operation falls back to an issue or pull request so subsequent
      // add_comment messages can include a correction note.
      if (CODE_PUSH_TYPES.has(messageType) && result && result.fallback_used === true) {
        if (result.issue_number != null && result.issue_url) {
          codePushFallbackInfo = {
            type: messageType,
            fallbackTargetType: "issue",
            number: result.issue_number,
            url: result.issue_url,
          };
          core.info(`Code push '${messageType}' fell back to review issue #${result.issue_number} — add_comment messages will be annotated`);
        } else if (result.pull_request_number != null && result.pull_request_url) {
          codePushFallbackInfo = {
            type: messageType,
            fallbackTargetType: "pull_request",
            number: result.pull_request_number,
            url: result.pull_request_url,
          };
          core.info(`Code push '${messageType}' fell back to pull request #${result.pull_request_number} — add_comment messages will be annotated`);
        }
      }

      // Check if this output was created with unresolved temporary IDs
      // For create_issue, create_discussion, add_comment - check if body has unresolved IDs

      // Handle add_comment which returns an array of comments
      if (messageType === "add_comment" && Array.isArray(result)) {
        const contentToCheck = getContentToCheck(messageType, message, result);
        if (contentToCheck && hasUnresolvedTemporaryIds(contentToCheck, temporaryIdMap, artifactUrlMap)) {
          // Track each comment that was created with unresolved temp IDs
          for (const comment of result) {
            if (comment._tracking) {
              core.info(`Comment ${comment._tracking.commentId} on ${comment._tracking.repo}#${comment._tracking.itemNumber} was created with unresolved temporary IDs - tracking for update`);
              outputsWithUnresolvedIds.push({
                type: messageType,
                message: message,
                result: {
                  commentId: comment._tracking.commentId,
                  itemNumber: comment._tracking.itemNumber,
                  repo: comment._tracking.repo,
                  isDiscussion: comment._tracking.isDiscussion,
                },
                originalTempIdMapSize: tempIdMapSizeBefore,
              });
            }
          }
        }
      } else if (result && result.number && result.repo) {
        // Handle create_issue, create_discussion
        const contentToCheck = getContentToCheck(messageType, message, result);
        if (contentToCheck && hasUnresolvedTemporaryIds(contentToCheck, temporaryIdMap, artifactUrlMap)) {
          core.info(`Output ${result.repo}#${result.number} was created with unresolved temporary IDs - tracking for update`);
          outputsWithUnresolvedIds.push({
            type: messageType,
            message: message,
            result: result,
            originalTempIdMapSize: tempIdMapSizeBefore,
          });
        }
      }

      results.push({
        type: messageType,
        messageIndex: i,
        success: true,
        result,
      });

      // Log to manifest if this was a create operation
      if (onItemCreated) {
        if (Array.isArray(result)) {
          for (const item of result) {
            const createdItem = extractCreatedItemFromResult(messageType, item);
            if (createdItem) {
              core.info(formatManifestLogMessage(createdItem));
              onItemCreated(createdItem);
            }
          }
        } else {
          const createdItem = extractCreatedItemFromResult(messageType, result);
          if (createdItem) {
            core.info(formatManifestLogMessage(createdItem));
            onItemCreated(createdItem);
          }
        }
      }

      core.info(`✓ Message ${i + 1} (${messageType}) completed successfully`);
    } catch (error) {
      core.error(`✗ Message ${i + 1} (${messageType}) failed: ${getErrorMessage(error)}`);
      results.push({
        type: messageType,
        messageIndex: i,
        success: false,
        error: getErrorMessage(error),
      });
      // Track code-push failures for fail-fast behaviour
      if (CODE_PUSH_TYPES.has(messageType)) {
        codePushFailures.push({ type: messageType, error: getErrorMessage(error) });
        core.warning(`⚠️ Code push operation '${messageType}' failed — remaining safe outputs will be cancelled`);
      }
    }
  }

  // Retry deferred messages now that more temporary IDs may have been resolved
  // This retry loop mirrors the main processing loop but operates on messages that were
  // deferred during the first pass (e.g., link_sub_issue waiting for parent/sub creation).
  // IMPORTANT: Like the main loop, this must register temporary IDs and track outputs
  // with unresolved IDs to enable full synthetic update resolution.
  if (deferredMessages.length > 0) {
    core.info(`\n=== Retrying Deferred Messages ===`);
    core.info(`Found ${deferredMessages.length} deferred message(s) to retry`);

    for (const deferred of deferredMessages) {
      try {
        core.info(`Retrying message ${deferred.messageIndex + 1}/${messages.length}: ${deferred.type}`);

        // Convert Map to plain object for handler
        const resolvedTemporaryIds = Object.fromEntries(temporaryIdMap);

        // Record the temp ID map size before processing to detect new IDs
        const tempIdMapSizeBefore = temporaryIdMap.size;

        // Call the handler again with updated temp ID map
        const result = await deferred.handler(deferred.message, resolvedTemporaryIds, temporaryIdMap);

        // Check if the handler explicitly returned a failure
        if (result && result.success === false && !result.deferred) {
          const errorMsg = result.error || "Handler returned success: false";
          core.error(`✗ Retry of message ${deferred.messageIndex + 1} (${deferred.type}) failed: ${errorMsg}`);
          // Update the result to error
          const resultIndex = results.findIndex(r => r.messageIndex === deferred.messageIndex);
          if (resultIndex >= 0) {
            results[resultIndex].success = false;
            results[resultIndex].error = errorMsg;
          }
          continue;
        }

        // Check if still deferred
        if (result && result.deferred === true) {
          core.warning(`⏸ Message ${deferred.messageIndex + 1} (${deferred.type}) still deferred - some temporary IDs remain unresolved`);
          // Update the existing result entry
          const resultIndex = results.findIndex(r => r.messageIndex === deferred.messageIndex);
          if (resultIndex >= 0) {
            results[resultIndex].result = result;
          }
        } else {
          core.info(`✓ Message ${deferred.messageIndex + 1} (${deferred.type}) completed on retry`);

          // If handler returned a temp ID mapping, add it to our map
          // This ensures that sub-issues created during deferred retry have their temporary IDs
          // registered so parent issues can reference them in synthetic updates
          if (result && result.temporaryId && result.repo && result.number) {
            const normalizedTempId = normalizeTemporaryId(result.temporaryId);
            temporaryIdMap.set(normalizedTempId, {
              repo: result.repo,
              number: result.number,
            });
            core.info(`Registered temporary ID: ${result.temporaryId} -> ${result.repo}#${result.number}`);
          }

          // Check if this output was created with unresolved temporary IDs
          // For create_issue, create_discussion - check if body has unresolved IDs
          // This enables synthetic updates to resolve references after all items are created
          if (result && result.number && result.repo) {
            const contentToCheck = getContentToCheck(deferred.type, deferred.message, result);
            if (contentToCheck && hasUnresolvedTemporaryIds(contentToCheck, temporaryIdMap, artifactUrlMap)) {
              core.info(`Output ${result.repo}#${result.number} was created with unresolved temporary IDs - tracking for update`);
              outputsWithUnresolvedIds.push({
                type: deferred.type,
                message: deferred.message,
                result: result,
                originalTempIdMapSize: tempIdMapSizeBefore,
              });
            }
          }

          // Update the result to success
          const resultIndex = results.findIndex(r => r.messageIndex === deferred.messageIndex);
          if (resultIndex >= 0) {
            results[resultIndex].success = true;
            results[resultIndex].deferred = false;
            results[resultIndex].result = result;
          }

          // Log to manifest after deferred retry success
          if (onItemCreated) {
            const createdItem = extractCreatedItemFromResult(deferred.type, result);
            if (createdItem) {
              core.info(formatManifestLogMessage(createdItem));
              onItemCreated(createdItem);
            }
          }
        }
      } catch (error) {
        core.error(`✗ Retry of message ${deferred.messageIndex + 1} (${deferred.type}) failed: ${getErrorMessage(error)}`);
        // Update the result to error
        const resultIndex = results.findIndex(r => r.messageIndex === deferred.messageIndex);
        if (resultIndex >= 0) {
          results[resultIndex].error = getErrorMessage(error);
        }
      }
    }
  }

  // Return outputs with unresolved IDs for synthetic update processing
  // Convert temporaryIdMap to plain object for serialization
  const temporaryIdMapObj = Object.fromEntries(temporaryIdMap);

  return {
    success: true,
    results,
    temporaryIdMap: temporaryIdMapObj,
    artifactUrlMap,
    outputsWithUnresolvedIds,
    missings,
    codePushFailures,
  };
}

/**
 * Get the content field to check for unresolved temporary IDs based on message type
 * @param {string} messageType - Type of the message
 * @param {any} message - The message object
 * @param {any} [result] - Handler result (used for transformed/managed bodies)
 * For comment_memory, handlers return a managedBody that includes XML wrapper/footer;
 * this differs from message.body and must be used for temporary ID detection.
 * @returns {string|null} Content to check for temporary IDs
 */
function getContentToCheck(messageType, message, result) {
  switch (messageType) {
    case "create_issue":
      return message.body || "";
    case "create_discussion":
      return message.body || "";
    case "add_comment":
      return message.body || "";
    case "comment_memory":
      return result?.managedBody || message.body || "";
    default:
      return null;
  }
}

/**
 * Update the body of an issue with resolved temporary IDs
 * @param {any} github - GitHub API client
 * @param {any} context - GitHub Actions context
 * @param {string} repo - Repository in "owner/repo" format
 * @param {number} issueNumber - Issue number to update
 * @param {string} updatedBody - Updated body content with resolved temp IDs
 * @returns {Promise<void>}
 */
async function updateIssueBody(github, context, repo, issueNumber, updatedBody) {
  const [owner, repoName] = repo.split("/");

  core.info(`Updating issue ${repo}#${issueNumber} body with resolved temporary IDs`);

  await github.rest.issues.update({
    owner,
    repo: repoName,
    issue_number: issueNumber,
    body: sanitizeContent(updatedBody),
  });

  core.info(`✓ Updated issue ${repo}#${issueNumber}`);
}

/**
 * Update the body of a discussion with resolved temporary IDs
 * @param {any} github - GitHub API client
 * @param {any} context - GitHub Actions context
 * @param {string} repo - Repository in "owner/repo" format
 * @param {number} discussionNumber - Discussion number to update
 * @param {string} updatedBody - Updated body content with resolved temp IDs
 * @returns {Promise<void>}
 */
async function updateDiscussionBody(github, context, repo, discussionNumber, updatedBody) {
  const [owner, repoName] = repo.split("/");

  core.info(`Updating discussion ${repo}#${discussionNumber} body with resolved temporary IDs`);

  // Get the discussion node ID first
  const query = `
    query($owner: String!, $repo: String!, $number: Int!) {
      repository(owner: $owner, name: $repo) {
        discussion(number: $number) {
          id
        }
      }
    }
  `;

  const result = await github.graphql(query, {
    owner,
    repo: repoName,
    number: discussionNumber,
  });

  const discussionId = result.repository.discussion.id;

  // Update the discussion body using GraphQL mutation
  const mutation = `
    mutation($discussionId: ID!, $body: String!) {
      updateDiscussion(input: {discussionId: $discussionId, body: $body}) {
        discussion {
          id
          number
        }
      }
    }
  `;

  await github.graphql(mutation, {
    discussionId,
    body: sanitizeContent(updatedBody),
  });

  core.info(`✓ Updated discussion ${repo}#${discussionNumber}`);
}

/**
 * Update the body of a comment with resolved temporary IDs
 * @param {any} github - GitHub API client
 * @param {any} context - GitHub Actions context
 * @param {string} repo - Repository in "owner/repo" format
 * @param {number} commentId - Comment ID to update
 * @param {string} updatedBody - Updated body content with resolved temp IDs
 * @param {boolean} isDiscussion - Whether this is a discussion comment
 * @returns {Promise<void>}
 */
async function updateCommentBody(github, context, repo, commentId, updatedBody, isDiscussion = false) {
  const [owner, repoName] = repo.split("/");

  core.info(`Updating comment ${commentId} body with resolved temporary IDs`);

  const sanitizedBody = sanitizeContent(updatedBody);

  if (isDiscussion) {
    // For discussion comments, we need to use GraphQL
    // Get the comment node ID first
    const mutation = `
      mutation($commentId: ID!, $body: String!) {
        updateDiscussionComment(input: {commentId: $commentId, body: $body}) {
          comment {
            id
          }
        }
      }
    `;

    await github.graphql(mutation, {
      commentId,
      body: sanitizedBody,
    });
  } else {
    // For issue/PR comments, use REST API
    await github.rest.issues.updateComment({
      owner,
      repo: repoName,
      comment_id: commentId,
      body: sanitizedBody,
    });
  }

  core.info(`✓ Updated comment ${commentId}`);
}

/**
 * Process synthetic updates by directly updating the body of outputs with resolved temporary IDs
 * Does not use safe output handlers - directly calls GitHub API to update content
 * @param {any} github - GitHub API client
 * @param {any} context - GitHub Actions context
 * @param {Array<{type: string, message: any, result: any, originalTempIdMapSize: number}>} trackedOutputs - Outputs that need updating
 * @param {Map<string, {repo: string, number: number}>} temporaryIdMap - Current temporary ID map
 * @param {Map<string, string>} [artifactUrlMap] - Optional artifact URL map for resolving artifact references
 * @returns {Promise<number>} Number of successful updates
 */
async function processSyntheticUpdates(github, context, trackedOutputs, temporaryIdMap, artifactUrlMap) {
  let updateCount = 0;

  core.info(`\n=== Processing Synthetic Updates ===`);
  core.info(`Found ${trackedOutputs.length} output(s) with unresolved temporary IDs`);

  for (const tracked of trackedOutputs) {
    // Check if any new temporary IDs were resolved since this output was created.
    // Also trigger an update when artifact URLs have been registered (artifactUrlMap is non-empty),
    // since artifact IDs embedded in the body need to be replaced with their real URLs.
    const resolvedArtifacts = artifactUrlMap && artifactUrlMap.size > 0;
    if (temporaryIdMap.size > tracked.originalTempIdMapSize || resolvedArtifacts) {
      const contentToCheck = getContentToCheck(tracked.type, tracked.message, tracked.result);

      // Only process if we have content to check
      if (contentToCheck !== null && contentToCheck !== "") {
        // Check if the content still has unresolved IDs (some may now be resolved)
        const stillHasUnresolved = hasUnresolvedTemporaryIds(contentToCheck, temporaryIdMap, artifactUrlMap);
        const resolvedCount = temporaryIdMap.size - tracked.originalTempIdMapSize;

        if (!stillHasUnresolved) {
          // All temporary IDs are now resolved - update the body directly
          let logInfo = tracked.result.commentId ? `comment ${tracked.result.commentId} on ${tracked.result.repo}#${tracked.result.itemNumber}` : `${tracked.result.repo}#${tracked.result.number}`;
          core.info(`Updating ${tracked.type} ${logInfo} (${resolvedCount} temp ID(s) resolved)`);

          try {
            // Replace artifact URL references first, then issue number references
            let updatedContent = replaceArtifactUrlReferences(contentToCheck, artifactUrlMap);
            updatedContent = replaceTemporaryIdReferences(updatedContent, temporaryIdMap, tracked.result.repo);

            // Update based on the original type
            switch (tracked.type) {
              case "create_issue":
                await updateIssueBody(github, context, tracked.result.repo, tracked.result.number, updatedContent);
                updateCount++;
                break;
              case "create_discussion":
                await updateDiscussionBody(github, context, tracked.result.repo, tracked.result.number, updatedContent);
                updateCount++;
                break;
              case "add_comment":
                // Update comment using the tracked comment ID
                if (tracked.result.commentId) {
                  await updateCommentBody(github, context, tracked.result.repo, tracked.result.commentId, updatedContent, tracked.result.isDiscussion);
                  updateCount++;
                } else {
                  core.debug(`Skipping synthetic update for comment - comment ID not tracked`);
                }
                break;
              case "comment_memory":
                if (tracked.result.commentId) {
                  await updateCommentBody(github, context, tracked.result.repo, tracked.result.commentId, updatedContent, false);
                  updateCount++;
                } else {
                  core.debug(`Skipping synthetic update for comment_memory - comment ID not tracked`);
                }
                break;
              default:
                core.debug(`Unknown output type: ${tracked.type}`);
            }
          } catch (error) {
            core.warning(`✗ Failed to update ${tracked.type} ${tracked.result.repo}#${tracked.result.number}: ${getErrorMessage(error)}`);
          }
        } else {
          core.debug(`Output ${tracked.result.repo}#${tracked.result.number} still has unresolved temporary IDs`);
        }
      }
    }
  }

  if (updateCount > 0) {
    core.info(`Completed ${updateCount} synthetic update(s)`);
  } else {
    core.info(`No synthetic updates needed`);
  }

  return updateCount;
}

/**
 * Main entry point for the handler manager
 * This is called by the consolidated safe output step
 *
 * @returns {Promise<void>}
 */
async function main() {
  // Detect staged mode before try/finally so it's accessible in the finally block.
  // In staged mode (🎭 Staged Mode Preview) no real items are created in GitHub so no manifest should be emitted.
  const isStaged = isStagedMode();

  try {
    core.info("Safe Output Handler Manager starting...");

    // Load configuration
    const config = loadConfig();
    core.debug(`Configuration: ${JSON.stringify(Object.keys(config))}`);

    // Load agent output
    const agentOutput = loadAgentOutput();
    const agentOutputItems = agentOutput.success ? agentOutput.items : [];
    if (!agentOutput.success) {
      core.info("No agent output available from tool calls");
    } else {
      core.info(`Found ${agentOutput.items.length} message(s) in agent output`);
    }

    const fileBackedCommentMemoryMessages = buildCommentMemoryMessagesFromFiles(agentOutputItems, config);
    const allMessages = [...agentOutputItems, ...fileBackedCommentMemoryMessages];
    if (allMessages.length === 0) {
      core.info("No safe-output messages available - nothing to process");
      if (!isStaged) ensureManifestExists();
      core.setOutput("temporary_id_map", "{}");
      core.setOutput("processed_count", 0);
      return;
    }

    // Create the shared PR review buffer instance (no global state)
    const prReviewBuffer = createReviewBuffer();

    // Apply footer config with priority:
    // 1. submit_pull_request_review.footer (highest priority — footer controls review body)
    // 2. Default: "always"
    let footerConfig = undefined;
    if (config.submit_pull_request_review?.footer !== undefined) {
      footerConfig = config.submit_pull_request_review.footer;
      core.info(`Using footer config from submit_pull_request_review: ${footerConfig}`);
    }

    if (footerConfig !== undefined) {
      prReviewBuffer.setFooterMode(footerConfig);
    }

    // Load and initialize handlers based on configuration (factory pattern)
    const messageHandlers = await loadHandlers(config, prReviewBuffer);

    if (messageHandlers.size === 0) {
      core.info("No handlers loaded - nothing to process");
      // Ensure manifest file exists even when no handlers are loaded (skip in staged mode)
      if (!isStaged) ensureManifestExists();
      // Set empty outputs for downstream steps
      core.setOutput("temporary_id_map", "{}");
      core.setOutput("processed_count", 0);
      return;
    }

    // Create manifest logger for recording created items.
    // createManifestLogger() touches the file immediately so it exists for artifact upload.
    // In staged mode, pass null so no items are logged (nothing is actually created).
    const logCreatedItem = isStaged ? null : createManifestLogger();

    // Process all messages in order of appearance
    const processingResult = await processMessages(messageHandlers, allMessages, logCreatedItem);

    // Finalize buffered PR review — submit when comments or metadata exist
    if (prReviewBuffer.hasBufferedComments() || prReviewBuffer.hasReviewMetadata()) {
      core.info(`\n=== Finalizing PR Review ===`);
      const bufferedCount = prReviewBuffer.getBufferedCount();
      if (bufferedCount > 0) {
        core.info(`Submitting ${bufferedCount} buffered review comment(s) as a single PR review`);
      } else {
        core.info("Submitting PR review (body-only, no inline comments)");
      }
      try {
        const reviewResult = await prReviewBuffer.submitReview();
        if (reviewResult.success && !reviewResult.skipped) {
          core.info(`✓ PR review submitted successfully: ${reviewResult.review_url}`);
        } else if (!reviewResult.success) {
          core.warning(`✗ Failed to submit PR review: ${reviewResult.error}`);
        }
      } catch (reviewError) {
        const errorMessage = reviewError instanceof Error ? reviewError.message : String(reviewError);
        core.warning(`✗ Exception while submitting PR review: ${errorMessage}`);
      }
    }

    // Store collected missings in helper module for handlers to access
    if (processingResult.missings) {
      setCollectedMissings(processingResult.missings);
      core.info(
        `Stored ${processingResult.missings.missingTools.length} missing tool(s), ${processingResult.missings.missingData.length} missing data item(s), ${processingResult.missings.noopMessages.length} noop message(s), and ${processingResult.missings.reportIncomplete.length} incomplete signal(s) for footer generation`
      );
    }

    // Process synthetic updates by directly updating issue/discussion bodies
    let syntheticUpdateCount = 0;
    if (processingResult.outputsWithUnresolvedIds && processingResult.outputsWithUnresolvedIds.length > 0) {
      // Convert temp ID map back to Map
      const temporaryIdMap = new Map(Object.entries(processingResult.temporaryIdMap));

      syntheticUpdateCount = await processSyntheticUpdates(github, context, processingResult.outputsWithUnresolvedIds, temporaryIdMap, processingResult.artifactUrlMap);
    }

    // Write step summaries for all processed safe-outputs
    await writeSafeOutputSummaries(processingResult.results, allMessages);

    // Log summary
    const successCount = processingResult.results.filter(r => r.success).length;
    const failureCount = processingResult.results.filter(r => !r.success && !r.deferred && !r.skipped && !r.cancelled).length;
    const cancelledCount = processingResult.results.filter(r => r.cancelled).length;
    const deferredCount = processingResult.results.filter(r => r.deferred).length;
    const skippedStandaloneResults = processingResult.results.filter(r => r.skipped && r.reason === "Handled by standalone step");
    const skippedCustomJobResults = processingResult.results.filter(r => r.skipped && r.reason === "Handled by custom safe output job");
    const skippedNoHandlerResults = processingResult.results.filter(r => !r.success && !r.skipped && r.error?.includes("No handler loaded"));
    const skippedHandlerResults = processingResult.results.filter(r => r.skipped && !r.reason && !r.deferred && !r.cancelled);

    core.info(`\n=== Processing Summary ===`);
    core.info(`Total messages: ${processingResult.results.length}`);
    core.info(`Successful: ${successCount}`);
    core.info(`Failed: ${failureCount}`);
    if (cancelledCount > 0) {
      core.info(`Cancelled (code push failed): ${cancelledCount}`);
    }
    if (deferredCount > 0) {
      core.info(`Deferred: ${deferredCount}`);
    }
    if (skippedHandlerResults.length > 0) {
      core.info(`Skipped (no context or limit reached): ${skippedHandlerResults.length}`);
      const skippedHandlerTypes = [...new Set(skippedHandlerResults.map(r => r.type))];
      core.info(`  Types: ${skippedHandlerTypes.join(", ")}`);
    }
    if (skippedStandaloneResults.length > 0) {
      core.info(`Skipped (standalone step): ${skippedStandaloneResults.length}`);
      const standaloneTypes = [...new Set(skippedStandaloneResults.map(r => r.type))];
      core.info(`  Types: ${standaloneTypes.join(", ")}`);
    }
    if (skippedCustomJobResults.length > 0) {
      core.info(`Skipped (custom safe output job): ${skippedCustomJobResults.length}`);
      const customJobTypesList = [...new Set(skippedCustomJobResults.map(r => r.type))];
      core.info(`  Types: ${customJobTypesList.join(", ")}`);
    }
    if (skippedNoHandlerResults.length > 0) {
      core.warning(`Skipped (no handler): ${skippedNoHandlerResults.length}`);
      const noHandlerTypes = [...new Set(skippedNoHandlerResults.map(r => r.type))];
      core.info(`  Types: ${noHandlerTypes.join(", ")}`);
    }
    core.info(`Temporary IDs registered: ${Object.keys(processingResult.temporaryIdMap).length}`);
    core.info(`Synthetic updates: ${syntheticUpdateCount}`);

    if (failureCount > 0) {
      core.warning(`${failureCount} message(s) failed to process`);
      const failedItems = processingResult.results
        .filter(r => !r.success && !r.deferred && !r.skipped && !r.cancelled)
        .map(r => `  - ${r.type}: ${r.error || "Unknown error"}`)
        .join("\n");
      core.setFailed(`${failureCount} safe output(s) failed:\n${failedItems}`);
    }
    if (cancelledCount > 0) {
      core.warning(`${cancelledCount} message(s) were cancelled because a code push operation failed`);
    }
    if (skippedNoHandlerResults.length > 0) {
      core.warning(`${skippedNoHandlerResults.length} message(s) were skipped because no handler was loaded. Check your workflow's safe-outputs configuration.`);
    }

    // Export temporary ID map as output for downstream steps
    const temporaryIdMapJson = JSON.stringify(processingResult.temporaryIdMap);
    core.setOutput("temporary_id_map", temporaryIdMapJson);
    core.info(`Exported temporary ID map with ${Object.keys(processingResult.temporaryIdMap).length} mapping(s)`);

    // Write temporary ID map to file for inclusion in the safe-outputs-items artifact.
    // This allows reviewers and auditors to inspect the full map of temporary IDs
    // to resolved GitHub resources (issue numbers, repos) without parsing step outputs.
    if (!isStaged) {
      writeTemporaryIdMapFile(processingResult.temporaryIdMap);
      core.info(`Wrote temporary ID map to file for artifact upload`);
    }

    // Export processed count for consistency with project handler
    core.setOutput("processed_count", successCount);

    // Export assign_to_agent outputs when the handler was loaded
    if (messageHandlers.has("assign_to_agent")) {
      const assignToAgentAssigned = getAssignToAgentAssigned();
      const assignToAgentErrors = getAssignToAgentErrors();
      const assignToAgentErrorCount = getAssignToAgentErrorCount();
      core.setOutput("assign_to_agent_assigned", assignToAgentAssigned);
      core.setOutput("assign_to_agent_assignment_errors", assignToAgentErrors);
      core.setOutput("assign_to_agent_assignment_error_count", assignToAgentErrorCount.toString());
      if (assignToAgentErrorCount > 0) {
        core.warning(`${assignToAgentErrorCount} agent assignment(s) failed`);
      }
      core.info(`Exported assign_to_agent outputs (${assignToAgentErrorCount} error(s))`);
      await writeAssignToAgentSummary();
    }

    // Export create_agent_session outputs when the handler was loaded
    if (messageHandlers.has("create_agent_session")) {
      const sessionNumber = getCreateAgentSessionNumber();
      const sessionUrl = getCreateAgentSessionUrl();
      core.setOutput("session_number", sessionNumber);
      core.setOutput("session_url", sessionUrl);
      core.info(`Exported create_agent_session outputs (session_number=${sessionNumber})`);
      await writeCreateAgentSessionSummary();
    }

    // Export create_discussion errors for conclusion job
    // Exclude cancelled results (cancelled == the discussion was skipped because a code-push
    // operation failed earlier in the same run; that failure is already reported separately).
    const createDiscussionErrors = processingResult.results
      .filter(r => r.type === "create_discussion" && !r.success && !r.deferred && !r.skipped && !r.cancelled)
      .map((r, index) => {
        const message = allMessages[r.messageIndex];
        const title = message?.title || "Discussion";
        const repo = message?.repo || process.env.GITHUB_REPOSITORY || "unknown";
        const errorMsg = r.error || r.reason || "Unknown error";
        return `discussion:${index}:${repo}:${title}:${errorMsg}`;
      })
      .join("\n");

    const createDiscussionErrorCount = processingResult.results.filter(r => r.type === "create_discussion" && !r.success && !r.deferred && !r.skipped && !r.cancelled).length;

    core.setOutput("create_discussion_errors", createDiscussionErrors);
    core.setOutput("create_discussion_error_count", createDiscussionErrorCount.toString());

    if (createDiscussionErrorCount > 0) {
      core.info(`Exported ${createDiscussionErrorCount} create_discussion error(s)`);
    }

    // Export code-push failure outputs for conclusion job
    const codePushFailureErrors = (processingResult.codePushFailures || []).map(f => `${f.type}:${f.error}`).join("\n");
    const codePushFailureCount = (processingResult.codePushFailures || []).length;

    core.setOutput("code_push_failure_errors", codePushFailureErrors);
    core.setOutput("code_push_failure_count", codePushFailureCount.toString());

    if (codePushFailureCount > 0) {
      core.info(`Exported ${codePushFailureCount} code push failure(s)`);
    }

    // Emit named action outputs (e.g. created_issue_number, created_issue_url)
    // for the first successful result of each safe output type.
    emitSafeOutputActionOutputs(processingResult);

    // Ensure the manifest file always exists for artifact upload (even if no items were created).
    // Skip in staged mode — no real items were created so no manifest should be emitted.
    // Note: createManifestLogger() also calls ensureManifestExists() when the logger is created,
    // so this is a safety net for cases where we never reached the logger creation.
    if (!isStaged) ensureManifestExists();

    core.info("Safe Output Handler Manager completed");
  } catch (error) {
    core.setFailed(`${ERR_VALIDATION}: Handler manager failed: ${getErrorMessage(error)}`);
  } finally {
    // Guarantee the manifest file exists for artifact upload even when the handler fails.
    // This is a no-op if the file was already created by createManifestLogger().
    if (!isStaged) {
      try {
        ensureManifestExists();
      } catch (_e) {
        // Ignore errors here — we must not mask the original failure
      }
    }
  }
}

module.exports = { main, loadConfig, loadHandlers, processMessages, buildCommentMemoryMessagesFromFiles };