infraweaver 0.1.0

package/src/main.ts

@@ -0,0 +1,815 @@
+// changes to tool permissions should be reflected in wiki/granular-tools.md
+
+import { existsSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { agents } from "#app/agents/index";
+import {
+  createTokenQuota,
+  RUN_TOKEN_QUOTA_INPUT,
+  resolveRunTokenQuota,
+} from "#app/agents/tokenQuota";
+import { reportProgress } from "#app/mcp/comment";
+import { startInstallation } from "#app/mcp/dependencies";
+import {
+  startMcpHttpServer,
+  subagentDeniedToolNames,
+  type ToolContext,
+} from "#app/mcp/server";
+import { coerceLibrary, loadFixMemory } from "#app/mcp/terraform/fixMemory";
+import { coerceNoiseProfile } from "#app/mcp/terraform/noiseProfile";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import { coerceProvenTransforms } from "#app/mcp/terraform/transformPacks";
+import { computeModes } from "#app/modes";
+import {
+  mergeRemediationModeInstructions,
+  mergeReviewModeInstructions,
+} from "#app/reviewQuality";
+import { initToolState } from "#app/toolState";
+import {
+  type ActivityTimeout,
+  AGENT_ACTIVITY_TIMEOUT_MS,
+  createProcessOutputActivityTimeout,
+  DEFAULT_ACTIVITY_CHECK_INTERVAL_MS,
+} from "#app/utils/activity";
+import { isBackendConfigured } from "#app/utils/apiUrl";
+import { resolveBody } from "#app/utils/body";
+import { log } from "#app/utils/cli";
+import { INFRAWEAVER_DATA_DIR } from "#app/utils/codexHome";
+import { recordDiffReadFromToolUse } from "#app/utils/diffCoverage";
+import { onExitSignal } from "#app/utils/exitHandler";
+import { resolveGit, setGitAuthServer } from "#app/utils/gitAuth";
+import { startGitAuthServer } from "#app/utils/gitAuthServer";
+import {
+  createOctokit,
+  writeGitHubUsageSummaryToFile,
+} from "#app/utils/github";
+import { resolveInstructions } from "#app/utils/instructions";
+import { persistLearnings, seedLearningsFile } from "#app/utils/learnings";
+import {
+  describeSetupFailure,
+  executeLifecycleHook,
+} from "#app/utils/lifecycle";
+import {
+  captureModelAuthority,
+  resolveRunModel,
+} from "#app/utils/modelResolver";
+import { normalizeEnv } from "#app/utils/normalizeEnv";
+import { applyOverrides } from "#app/utils/overrides";
+import {
+  ensurePackageManager,
+  packageManagerBinDir,
+  resolvePackageManagerSpec,
+} from "#app/utils/packageManager";
+import {
+  aggregateUsage,
+  patchWorkflowRunFields,
+} from "#app/utils/patchWorkflowRunFields";
+import {
+  resolveOutputSchema,
+  resolvePayload,
+  resolvePromptInput,
+} from "#app/utils/payload";
+import {
+  fetchPreviousSnapshot,
+  persistSummary,
+  seedSummaryFile,
+} from "#app/utils/prSummary";
+import { handleAgentResult } from "#app/utils/run";
+import { resolveRunContextData } from "#app/utils/runContextData";
+import { renderRunError } from "#app/utils/runErrorRenderer";
+import {
+  finalizeSuccessRun,
+  persistRunArtifacts,
+  writeRunErrorOutputs,
+} from "#app/utils/runLifecycle";
+import { logRunStartup } from "#app/utils/runStartupLog";
+import { setEnvAllowlist } from "#app/utils/secrets";
+import {
+  createTempDirectory,
+  setupGit,
+  wipeRunnerLeakSurface,
+} from "#app/utils/setup";
+import { killTrackedChildren } from "#app/utils/subprocess";
+import { resolveTimeoutMs, TIMEOUT_DISABLED } from "#app/utils/time";
+import { Timer } from "#app/utils/timer";
+import { createTodoTracker } from "#app/utils/todoTracking";
+import {
+  getGitHubInstallationToken,
+  getJobToken,
+  getMcpTokenRefresh,
+  resolveTokens,
+} from "#app/utils/token";
+import {
+  cleanupVertexCredentials,
+  materializeVertexCredentials,
+  type VertexCredentials,
+} from "#app/utils/vertex";
+import { resolveRun } from "#app/utils/workflow";
+
+export { Inputs } from "#app/utils/payload";
+
+export interface MainResult {
+  success: boolean;
+  output?: string | undefined;
+  error?: string | undefined;
+  result?: string | undefined;
+}
+
+export async function main(): Promise<MainResult> {
+  // normalize env var names to uppercase (handles case-insensitive workflow files)
+  normalizeEnv();
+
+  // apply caller-supplied env overrides — JSON object forwarded as the
+  // UNSAFE_OVERRIDES env var (NOT a `with:` input). gated by `actions:write`
+  // on the repo and refuses integrity-critical names; see utils/overrides.ts
+  // for the deny-list and wiki/e2e-testing.md for usage + threat model.
+  // the `unsafe` prefix is intentional: GH echoes the env-block value in the
+  // step-header log, so the raw JSON is visible to anyone with `actions:read`.
+  const overridesRaw = process.env.UNSAFE_OVERRIDES ?? "";
+  if (overridesRaw.trim()) {
+    const result = applyOverrides({ raw: overridesRaw, env: process.env });
+    if (result.applied.length > 0) {
+      log.info(
+        `» applied ${result.applied.length} env override(s): ${result.applied.join(", ")}`,
+      );
+    }
+    if (result.denied.length > 0) {
+      log.warning(
+        `» refused to override ${result.denied.length} protected env var(s): ${result.denied.join(", ")}`,
+      );
+    }
+  }
+
+  // write usage summary on SIGINT/SIGTERM so the worker can read it after sandbox.exec
+  const usageSummaryPath = process.env.INFRAWEAVER_USAGE_SUMMARY_PATH;
+  if (usageSummaryPath) {
+    onExitSignal(() => writeGitHubUsageSummaryToFile(usageSummaryPath));
+  }
+
+  const timer = new Timer();
+  let activityTimeout: ActivityTimeout | null = null;
+  let safetyNetTimer: NodeJS.Timeout | undefined;
+
+  // parse prompt early to extract progressComment for toolState
+  const resolvedPromptInput = resolvePromptInput();
+
+  const toolState = initToolState({
+    progressComment:
+      typeof resolvedPromptInput !== "string"
+        ? resolvedPromptInput.progressComment
+        : undefined,
+  });
+
+  // resolve and fingerprint git binary before any agent code runs
+  resolveGit();
+
+  // get job token for initial API calls
+  const jobToken = getJobToken();
+  const initialOctokit = createOctokit(jobToken);
+  const runContext = await resolveRunContextData({
+    octokit: initialOctokit,
+    token: jobToken,
+  });
+  timer.checkpoint("runContextData");
+
+  // Called for its side effect: `createTempDirectory()` sets INFRAWEAVER_TEMP_DIR,
+  // which `installFromNpmTarball` reads when the opencode CLI install runs below
+  // for BYOK introspection, and which agent + mcp server setup further down also
+  // consume. The returned path isn't needed directly here.
+  createTempDirectory();
+
+  // install OpenCode (fs-cached, so the duplicate call inside the opencode
+  // agent's run() is a no-op), then capture the BYOK model authority. The
+  // baseline→Codex-auth→authorized ordering that used to live inline here is
+  // owned by captureModelAuthority; the returned set feeds resolveRunModel.
+  const opencodeCliPath = await agents.opencode.install();
+  const authorizedModels = captureModelAuthority(opencodeCliPath);
+
+  // configure env allowlist for subprocess filtering
+  if (runContext.repoSettings.envAllowlist) {
+    setEnvAllowlist(runContext.repoSettings.envAllowlist);
+  }
+
+  // resolve payload to determine shell permission. The org's Cloud "required
+  // controls" policy (org-scoped, from run-context) is merged into the gate here.
+  const payload = resolvePayload(
+    resolvedPromptInput,
+    runContext.repoSettings,
+    runContext.requiredControls,
+    runContext.moduleCredentials,
+  );
+  toolState.model = payload.model;
+  // user-facing language for the fixed comment/footer chrome — mirrored onto the
+  // tool state so surfaces that only hold a ToolState (errorReport) localize too.
+  toolState.language = payload.language;
+  if (payload.event.trigger === "pull_request_synchronize") {
+    toolState.beforeSha = payload.event.before_sha;
+  }
+
+  // §5.12 seed the proven-fix library so the terraform_fix_memory tool can offer
+  // proven priors during Remediate: the org's Cloud fleet library (has reuse
+  // stats) first, then any committed local `.infraweaver.fix-memory.json`. Deduped
+  // by finding-type at match time (Cloud wins on a tie). Only when opted in.
+  if (payload.fixMemory) {
+    scanSessionOf(toolState).fixMemoryLibrary = [
+      ...coerceLibrary(runContext.provenFixes),
+      ...loadFixMemory(payload.cwd),
+    ];
+  }
+
+  // G7 seed the org's fleet-wide dismissal record so terraform_scan can down-rank
+  // finding types this org has repeatedly waived, with the reasons shown. Not
+  // opt-in like fix memory: it changes only the ORDER of a report that already
+  // contains everything, so there is nothing to consent to. Empty for OSS and
+  // unentitled runs, which then rank exactly as they do today.
+  scanSessionOf(toolState).noiseProfile = coerceNoiseProfile(
+    runContext.noiseProfile,
+  );
+
+  // TC-2.2 seed the org's proven-transform counters so terraform_provider_upgrade
+  // can say how widely a migration has already planned cleanly across the fleet.
+  // Not opt-in for the same reason as the noise profile: it adds a count beside a
+  // transform that is reported either way, and never decides anything.
+  scanSessionOf(toolState).provenTransformLibrary = coerceProvenTransforms(
+    runContext.provenTransforms,
+  );
+
+  // resolve tokens first — acquireNewToken needs OIDC env vars for token exchange
+  await using tokenRef = await resolveTokens({ push: payload.push });
+
+  // wipe the GHA runner's known credential leak surface inside $RUNNER_TEMP
+  // before the agent spawns. our installation token is already in memory
+  // (tokenRef above), and setupGit's includeIf strip handles the matching
+  // dangling references in the user's .git/config. see wipeRunnerLeakSurface
+  // for the leak inventory and threat model.
+  wipeRunnerLeakSurface();
+
+  // clear OIDC env vars to prevent the agent from minting tokens. this is NOT
+  // gated on shell mode: `shell: "enabled"` widens the command surface, it does
+  // not grant credential access, and resolveTokens() above already took what the
+  // engine needs. inheritEnv() also denies the pair, so this is defence in depth.
+  delete process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+  delete process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+
+  // create octokit with MCP token for GitHub API calls. the refresh fn lets it
+  // re-acquire a fresh token on a 401 (post-mint replication window). see #891.
+  const octokit = createOctokit(tokenRef.mcpToken, getMcpTokenRefresh());
+
+  const runInfo = await resolveRun({ octokit });
+  let toolContext: ToolContext | undefined;
+  let progressCallbackDisabled = false;
+  let todoTracker: ReturnType<typeof createTodoTracker> | undefined;
+  let vertexCredentials: VertexCredentials | undefined;
+
+  try {
+    if (payload.cwd && process.cwd() !== payload.cwd) {
+      process.chdir(payload.cwd);
+    }
+
+    const tmpdir = createTempDirectory();
+
+    // resolve body - fetches body_html and converts to markdown if images present
+    // this ensures agents receive markdown with working signed image URLs
+    const originalBody = payload.event.body;
+    const resolvedBody = await resolveBody({
+      event: payload.event,
+      octokit,
+      repo: runContext.repo,
+      tmpdir,
+      githubToken: tokenRef.mcpToken,
+    });
+    if (resolvedBody !== originalBody) {
+      payload.event.body = resolvedBody;
+      // also update prompt if original body was included there
+      if (originalBody && payload.prompt.includes(originalBody)) {
+        payload.prompt = payload.prompt
+          .split(originalBody)
+          .join(resolvedBody ?? "");
+      }
+    }
+
+    await using gitAuthServer = await startGitAuthServer(tmpdir);
+    setGitAuthServer(gitAuthServer);
+
+    // Resolve the model + auth in one call: BYOK gate → managed EU Bedrock proxy
+    // overlay → env patch → api-key validation. Surfaces a BillingError if the org
+    // has no payment method; keeps the free fallback if the proxy isn't live.
+    const routed = await resolveRunModel({
+      slug: payload.model,
+      plan: runContext.plan,
+      credential: runContext.apiToken,
+      authorized: authorizedModels,
+      repo: { owner: runContext.repo.owner, name: runContext.repo.name },
+    });
+    for (const warning of routed.warnings) {
+      log.warning(warning);
+    }
+    if (routed.fallback) {
+      toolState.modelFallback = { from: routed.fallback.from };
+    }
+
+    const resolvedModel = routed.model;
+    const effectiveSlug = routed.effectiveSlug;
+    const agent = routed.agent;
+
+    vertexCredentials = materializeVertexCredentials({ model: resolvedModel });
+
+    // surface the effective model in comment/review footers. payload.model is
+    // just the stored slug (often undefined when the agent auto-selects).
+    toolState.model = resolvedModel ?? effectiveSlug;
+
+    await setupGit({
+      gitToken: tokenRef.gitToken,
+      owner: runContext.repo.owner,
+      name: runContext.repo.name,
+      octokit,
+      toolState,
+      shell: payload.shell,
+      postCheckoutScript: runContext.repoSettings.postCheckoutScript,
+    });
+    timer.checkpoint("git");
+
+    // pin the project's package manager via corepack BEFORE the setup hook
+    // runs. without this, a customer setup script like `npm i -g pnpm &&
+    // pnpm install` installs whatever pnpm is "latest" today and writes
+    // unrelated lockfile drift (e.g. the `packageManagerDependencies`
+    // block pnpm 11.3 added) into our commit — see #844. resolution
+    // honors pnpm 11+ precedence (`devEngines.packageManager` over
+    // `packageManager`); failure is non-fatal — we fall back to whatever
+    // is on PATH with a warning. the shim lands in a private bin dir
+    // (prepended to PATH), not the node bin dir, so a setup `npm i -g pnpm`
+    // can't collide with it.
+    const pmSpec = await resolvePackageManagerSpec(process.cwd());
+    if (pmSpec) {
+      await ensurePackageManager({
+        spec: pmSpec,
+        binDir: packageManagerBinDir(tmpdir),
+      });
+    }
+    timer.checkpoint("packageManager");
+
+    // execute the setup lifecycle hook (runs once at initialization). best-effort:
+    // a failure no longer aborts the run — we warn the operator and surface it to
+    // the agent via the SETUP HOOK FAILED banner so it can verify the env and adapt.
+    const setupHook = await executeLifecycleHook({
+      event: "setup",
+      script: runContext.repoSettings.setupScript,
+      normalizeWorkingTreeAfter: true,
+    });
+    if (setupHook.warning) {
+      log.warning(setupHook.warning);
+    }
+    timer.checkpoint("lifecycleHooks::setup");
+
+    const agentId = agent.name;
+    const modes = [...computeModes(agentId), ...runContext.repoSettings.modes];
+
+    const outputSchema = resolveOutputSchema();
+
+    // mcpServerUrl and tmpdir are set after server starts
+    toolContext = {
+      agentId,
+      repo: runContext.repo,
+      payload,
+      octokit,
+      // a getter (not the static mint-time value) so raw-token consumers that
+      // bypass octokit's refresh hook — issue/PR comment GETs, prSummary,
+      // selectMode, install — pick up a mid-run re-minted MCP token. see #891.
+      get githubInstallationToken() {
+        return getGitHubInstallationToken();
+      },
+      // live getter, same reason as githubInstallationToken above: after a
+      // mid-run git-token re-mint the old token is revoked, so push/tags/delete/
+      // fetch tools reading ctx.gitToken must see the current one, never a
+      // stale snapshot captured at ctx-construction time. see #964.
+      get gitToken() {
+        return tokenRef.gitToken;
+      },
+      refreshGitToken: tokenRef.refreshGitToken,
+      apiToken: runContext.apiToken,
+      modes,
+      postCheckoutScript: runContext.repoSettings.postCheckoutScript,
+      prepushScript: runContext.repoSettings.prepushScript,
+      prApproveEnabled: runContext.repoSettings.prApproveEnabled,
+      // workflow-file review policy / FP precedents compose with the
+      // backend-provided per-mode instructions (both owner-controlled). The two
+      // mergers stack — review instructions onto the Review key, then the
+      // remediation/refactor addenda onto their mode keys — so all four
+      // instruction inputs land additively; no engine-owned prompt is replaced.
+      modeInstructions: mergeRemediationModeInstructions(
+        mergeReviewModeInstructions(runContext.repoSettings.modeInstructions, {
+          reviewInstructions: payload.reviewInstructions,
+          fpFilteringInstructions: payload.fpFilteringInstructions,
+        }),
+        {
+          remediationInstructions: payload.remediationInstructions,
+          refactorInstructions: payload.refactorInstructions,
+        },
+      ),
+      toolState,
+      runId: runInfo.runId,
+      mcpServerUrl: "",
+      mcpServerToken: "",
+      tmpdir,
+      oss: runContext.oss,
+      plan: runContext.plan,
+      resolvedModel,
+    };
+    await using mcpHttpServer = await startMcpHttpServer(toolContext, {
+      outputSchema,
+    });
+    toolContext.mcpServerUrl = mcpHttpServer.url;
+    toolContext.mcpServerToken = mcpHttpServer.token;
+    log.info(`» MCP server started at ${mcpHttpServer.url}`);
+    timer.checkpoint("mcpServer");
+
+    // derive the subagent deny set from the same tool registry the server just
+    // registered (each tool's `mutates` flag), to embed into the agent's gate.
+    const subagentDeniedTools = subagentDeniedToolNames(
+      toolContext,
+      outputSchema,
+    );
+
+    // seed the rolling repo-level learnings tmpfile. the agent reads the file
+    // at startup (path is surfaced in the LEARNINGS section of the prompt) and
+    // may edit it during the post-run reflection turn. persistLearnings reads
+    // it back at end-of-run and PATCHes any changes to Repo.learnings.
+    //
+    // gated on a configured backend: learnings only have somewhere to persist
+    // when a real backend is wired (hosted SaaS / local dev). in a standalone
+    // BYOK run there is no store, so seeding the file would only provoke the
+    // post-run reflection turn (an extra billed LLM turn) to edit a file whose
+    // changes get dropped — and persistLearnings would then PATCH the default
+    // marketing host and warn on its 404. leaving learningsFilePath unset makes
+    // every downstream consumer (`persistLearnings`, agent harnesses,
+    // `resolveInstructions`) treat this as "no learnings affordance this run".
+    //
+    // wrapped in best-effort try/catch: an unwrapped filesystem failure
+    // (ENOSPC, EACCES, hostile sandbox) would unwind into the outer main()
+    // catch and flip an otherwise-successful run to "❌ Infraweaver failed".
+    if (isBackendConfigured()) {
+      try {
+        const learningsPath = await seedLearningsFile({
+          tmpdir,
+          current: runContext.repoSettings.learnings,
+        });
+        toolState.learningsFilePath = learningsPath;
+        // file on disk is the verbatim DB body, so the seed used for
+        // change-detection is just `current ?? ""` (trimmed). persistLearnings
+        // byte-compares against the trimmed read-back to skip no-op PATCHes.
+        toolState.learningsSeed = (
+          runContext.repoSettings.learnings ?? ""
+        ).trim();
+        log.info(
+          `» learnings seeded at ${learningsPath} (existing=${runContext.repoSettings.learnings ? "yes" : "no"})`,
+        );
+        const ctxForExit = toolContext;
+        onExitSignal(() => persistLearnings(ctxForExit));
+      } catch (err) {
+        log.warning(
+          `» learnings seed failed: ${err instanceof Error ? err.message : String(err)} — continuing without learnings file`,
+        );
+      }
+    } else {
+      log.debug(
+        "no backend configured (API_URL unset) — skipping learnings seed + reflection turn",
+      );
+    }
+
+    // seed the rolling PR summary tmpfile when the dispatcher requested it.
+    // gated on event being a PR — issue/workflow_dispatch runs have no
+    // summarySnapshot to maintain. file path is exposed to the agent via
+    // the select_mode response addendum (action/mcp/selectMode.ts).
+    if (
+      payload.generateSummary &&
+      payload.event.is_pr &&
+      payload.event.issue_number
+    ) {
+      const previousSnapshot = await fetchPreviousSnapshot(
+        toolContext,
+        payload.event.issue_number,
+      );
+      const filePath = await seedSummaryFile({ tmpdir, previousSnapshot });
+      toolState.summaryFilePath = filePath;
+      // capture the exact bytes the agent will see at startup. used by
+      // the post-run retry loop to detect the agent forgetting to edit
+      // the file (byte-identical to seed → nudge once via resume turn)
+      // and by persistSummary to skip the DB write when nothing changed.
+      try {
+        toolState.summarySeed = await readFile(filePath, "utf8");
+      } catch {
+        // intentionally empty — summarySeed stays undefined
+      }
+      log.info(
+        `» summary snapshot seeded at ${filePath} (previous=${previousSnapshot ? "yes" : "no"})`,
+      );
+      // on SIGINT/SIGTERM we still want to persist whatever the agent has
+      // written so far. handler is best-effort: any failure inside is
+      // swallowed by Promise.allSettled in exitHandler.ts, and the
+      // summaryPersistAttempted guard prevents double-execution if the
+      // signal arrives after the normal path already persisted. capture a
+      // narrowed reference so the closure doesn't depend on the outer
+      // `toolContext` variable being defined later.
+      const ctxForExit = toolContext;
+      onExitSignal(() => persistSummary(ctxForExit));
+    }
+
+    startInstallation(toolContext);
+
+    logRunStartup({ payload, resolvedModel, agentName: agent.name });
+
+    const instructions = resolveInstructions({
+      payload,
+      repo: runContext.repo,
+      modes,
+      agentId,
+      outputSchema,
+      learningsFilePath: toolState.learningsFilePath ?? null,
+      learningsHeadings: runContext.repoSettings.learningsHeadings,
+      setupHookFailure: describeSetupFailure(setupHook.failure),
+    });
+    const logParts = [
+      instructions.eventInstructions
+        ? `EVENT-LEVEL INSTRUCTIONS:\n${instructions.eventInstructions}`
+        : null,
+      instructions.user ? `USER REQUEST:\n${instructions.user}` : null,
+      instructions.event,
+    ].filter(Boolean);
+    log.box(logParts.join("\n\n---\n\n"), {
+      title: "Instructions",
+    });
+    log.group("View full prompt", () => {
+      log.info(instructions.full);
+    });
+
+    // OpenCode loads .opencode/plugin/ files at startup. if the repo has any,
+    // eagerly await dependency installation so plugin imports can resolve.
+    if (agentId === "opencode") {
+      const pluginDir = join(process.cwd(), ".opencode", "plugin");
+      const hasPlugins =
+        existsSync(pluginDir) &&
+        readdirSync(pluginDir).some((f) => /\.[jt]sx?$/.test(f));
+      if (hasPlugins && toolState.dependencyInstallation?.promise) {
+        log.info(
+          "» .opencode/plugin/ detected — awaiting dependency installation before agent start",
+        );
+        await toolState.dependencyInstallation.promise.catch(() => {});
+        timer.checkpoint("awaitDepsForPlugins");
+      }
+    }
+
+    // LLM10 — bound the run in TOKENS as well as in time. The watchdogs below
+    // bound idleness; a remediation loop that cannot converge streams the whole
+    // way and never trips them, and on a self-hosted run no Cloud meter sees it.
+    const tokenQuota = createTokenQuota(
+      resolveRunTokenQuota(payload.maxRunTokens),
+    );
+    log.info(
+      tokenQuota.limit > 0
+        ? `» run token quota: ${tokenQuota.limit.toLocaleString("en-GB")} billable tokens`
+        : `» run token quota: disabled (${RUN_TOKEN_QUOTA_INPUT}: 0)`,
+    );
+
+    // run agent, optionally with timeout enforcement
+    activityTimeout = createProcessOutputActivityTimeout({
+      timeoutMs: AGENT_ACTIVITY_TIMEOUT_MS,
+      checkIntervalMs: DEFAULT_ACTIVITY_CHECK_INTERVAL_MS,
+    });
+    activityTimeout.promise.catch(() => {}); // prevent unhandled rejection if agent wins race
+    todoTracker = createTodoTracker(async (body) => {
+      if (progressCallbackDisabled || !toolContext) return;
+      try {
+        // liveProgress: this is the auto-rendered checklist, not a deliberate
+        // final answer — must not flip wasUpdated / lastProgressBody (see #868).
+        await reportProgress(toolContext, { body, liveProgress: true });
+      } catch (err) {
+        log.debug(`progress update failed: ${err}`);
+      }
+    });
+    toolState.todoTracker = todoTracker;
+
+    // on cancellation, stop scheduling new tracker writes immediately. without this, a
+    // debounced write queued just before SIGTERM could land at GitHub *after* the
+    // workflow_run.completed webhook has already replaced the comment with the
+    // "This run was cancelled" body, clobbering it back to the task list. we can't
+    // await in-flight writes (the process is exiting), but cancelling the timer
+    // shrinks the race window.
+    onExitSignal(() => {
+      todoTracker?.cancel();
+    });
+
+    // when the agent subprocess is killed for inner activity timeout, stop
+    // the MCP HTTP server so mcp-proxy's SSE reconnect attempts don't keep
+    // the outer activity timer alive. start a short safety-net timer — if
+    // the agent promise hasn't resolved within 5min after the inner kill,
+    // force-reject the outer timer so the run can exit.
+    let innerTimeoutFired = false;
+    const onInnerActivityTimeout = () => {
+      if (innerTimeoutFired) return;
+      innerTimeoutFired = true;
+      log.info(
+        "» inner activity timeout fired — stopping MCP server and starting 5min safety-net timer",
+      );
+      // fire and forget — the server's dispose is idempotent so the
+      // `await using` cleanup at block exit is still safe.
+      mcpHttpServer[Symbol.asyncDispose]().catch((err) => {
+        log.debug(
+          `mcp server stop after inner kill failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+      safetyNetTimer = setTimeout(
+        () => {
+          activityTimeout?.forceReject(
+            "agent still pending 5min after inner activity kill — forcing exit",
+          );
+        },
+        5 * 60 * 1000,
+      );
+      safetyNetTimer.unref?.();
+    };
+
+    const agentPromise = agent.run({
+      payload,
+      resolvedModel,
+      mcpServerUrl: mcpHttpServer.url,
+      mcpServerToken: mcpHttpServer.token,
+      tmpdir,
+      // INFRAWEAVER_DATA_DIR (/var/lib/infraweaver) holds codex auth.json + any
+      // future infraweaver-managed on-disk secrets. bash via MCP tmpfs-overlays
+      // it; agent native FS tools deny it via the same secretDenyPaths plumbing
+      // used for vertex creds. see wiki/security.md "Filesystem Sandbox".
+      secretDenyPaths: [
+        INFRAWEAVER_DATA_DIR,
+        ...(vertexCredentials ? [vertexCredentials.secretDir] : []),
+      ],
+      subagentDeniedTools,
+      instructions,
+      todoTracker,
+      stopScript: runContext.repoSettings.stopScript,
+      toolState,
+      apiToken: runContext.apiToken,
+      onActivityTimeout: onInnerActivityTimeout,
+      tokenQuota,
+      onToolUse: (event) => {
+        const wasTracked = recordDiffReadFromToolUse({
+          state: toolState.diffCoverage,
+          toolName: event.toolName,
+          input: event.input,
+          cwd: process.cwd(),
+        });
+        if (!wasTracked) return;
+        const trackedRanges = toolState.diffCoverage?.coveredRanges ?? [];
+        log.debug(
+          `» diff coverage tracked from tool ${event.toolName} (${trackedRanges.length} merged range${trackedRanges.length === 1 ? "" : "s"})`,
+        );
+      },
+    });
+    // symmetric with the activityTimeout/timeoutPromise catches below: if a
+    // timeout wins the race, agentPromise is stranded and its later rejection
+    // becomes an unhandled rejection. node 15+ terminates the process on
+    // unhandled rejection by default, which would kill main() mid-cleanup and
+    // lose the error-reporting / usage-summary work that follows. the race
+    // still sees the rejection (the original promise is shared); this catch
+    // only keeps node from treating a post-race rejection as unobserved.
+    agentPromise.catch(() => {});
+
+    // timeout enforcement: default is 1 hour, but can be overridden via flags in the prompt:
+    // - --timeout=2h (or any duration like "--timeout=30m", "--timeout=1h30m") to set a custom timeout
+    // - --notimeout to disable timeout entirely
+    let result: Awaited<typeof agentPromise>;
+    if (payload.timeout === TIMEOUT_DISABLED) {
+      result = await Promise.race([agentPromise, activityTimeout.promise]);
+    } else {
+      // resolveTimeoutMs rejects unparseable / zero / setTimeout-overflow inputs
+      // so a bad string can't silently resolve to an instant timeout. fall back
+      // to the 1h default with a warning — users who want runtime measured in
+      // weeks should use --notimeout.
+      const usable = resolveTimeoutMs(payload.timeout);
+      if (payload.timeout && usable === null) {
+        log.warning(
+          `invalid timeout "${payload.timeout}" (use --notimeout to disable), using 1h`,
+        );
+      }
+      const timeoutMs = usable ?? 3600000;
+      const actualTimeout = usable !== null ? payload.timeout : "1h";
+      let timeoutId: NodeJS.Timeout | undefined;
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(new Error(`agent run timed out after ${actualTimeout}`));
+        }, timeoutMs);
+      });
+      timeoutPromise.catch(() => {}); // prevent unhandled rejection if agent wins race
+      try {
+        result = await Promise.race([
+          agentPromise,
+          timeoutPromise,
+          activityTimeout.promise,
+        ]);
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+
+    // accumulate top-level agent usage
+    if (result.usage) {
+      toolState.usageEntries.push(result.usage);
+    }
+
+    // validate this before writing job summary to avoid masking the error
+    if (outputSchema && !toolState.output) {
+      throw new Error(
+        "output_schema was provided but agent did not call set_output — structured output is required",
+      );
+    }
+
+    // success-path cleanup: postReview → persistSummary → persistLearnings →
+    // failure-error-report → stranded-comment cleanup → job summary → output
+    // marker. each step is best-effort; see `finalizeSuccessRun` for ordering
+    // rationale (notably: progress-comment deletion lives in
+    // create_pull_request_review for review-mode runs, so deletion here
+    // covers the non-review success paths).
+    await finalizeSuccessRun({
+      toolContext,
+      toolState,
+      result,
+      repo: runContext.repo,
+      // Prefer the run-context-resolved credential (an explicit org token, or the
+      // run token Cloud mints from our OIDC identity on the App path) over the
+      // raw `api_token` input — the latter is empty under tokenless OIDC, and the
+      // OIDC env is already stripped here so reportToCloud can't re-mint one.
+      cloudApiToken: toolContext.apiToken || payload.cloudApiToken,
+    });
+
+    return await handleAgentResult({
+      result,
+      toolContext,
+      silent: payload.event.silent ?? false,
+    });
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : "unknown error occurred";
+    progressCallbackDisabled = true;
+    todoTracker?.cancel();
+    killTrackedChildren();
+    log.error(errorMessage);
+
+    // classify (BillingError reclassification + hang detection + API-key auth
+    // detection) and render to {summary, comment} markdown bodies.
+    const rendered = renderRunError({
+      errorMessage,
+      repo: runContext.repo,
+      agentDiagnostic: toolState.agentDiagnostic,
+    });
+    await writeRunErrorOutputs({ rendered, toolState });
+
+    // best-effort cleanup: review dispatch, summary persist, learnings persist.
+    // a partial edit before the crash is still worth keeping.
+    if (toolContext) {
+      await persistRunArtifacts(toolContext);
+    }
+
+    return {
+      success: false,
+      error: errorMessage,
+    };
+  } finally {
+    activityTimeout?.stop();
+    if (safetyNetTimer) clearTimeout(safetyNetTimer);
+    // also reap on the success-with-failure path (agent returned
+    // `{success: false}`) which skips the catch above and would otherwise hang
+    // ~60s on the eager dep install. idempotent SIGKILL. see #862.
+    killTrackedChildren();
+    if (usageSummaryPath) {
+      // a write error here (ENOSPC, EACCES, dirname removed) must not mask
+      // either the try's successful return or the catch's error return.
+      // the summary is informational — log and move on.
+      try {
+        await writeGitHubUsageSummaryToFile(usageSummaryPath);
+      } catch (err) {
+        log.debug(
+          `failed to write usage summary to ${usageSummaryPath}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+
+    // persist aggregated token + cost usage to the WorkflowRun row.
+    // this is the single shared cleanup path across every agent implementation:
+    // each agent harness returns a single AgentUsage from agent.run() that
+    // already aggregates its internal retries via mergeAgentUsage, and the
+    // success branch above pushes that entry into toolState.usageEntries.
+    // aggregateUsage sums across those entries (one per agent.run()).
+    //
+    // caveat: if the agent promise rejected (timeout or uncaught throw) the
+    // usage was never pushed, so nothing gets persisted for that run. runs
+    // that returned AgentResult with success=false still report their partial
+    // usage because the harness populates AgentUsage before returning.
+    if (toolContext) {
+      const patch = aggregateUsage(toolState.usageEntries);
+      if (Object.keys(patch).length > 0) {
+        await patchWorkflowRunFields(toolContext, patch);
+      }
+    }
+    cleanupVertexCredentials(vertexCredentials);
+  }
+}