infraweaver 0.1.0

package/src/utils/runLifecycle.ts

@@ -0,0 +1,360 @@
+/**
+ * End-of-run cleanup phases extracted out of `main.ts`. Three shapes:
+ *
+ *   - `persistRunArtifacts`: best-effort post-review cleanup + summary +
+ *     learnings persistence. Shared by both the success path and the
+ *     error-catch path; idempotent (each step has its own guard against
+ *     double-execution).
+ *
+ *   - `finalizeSuccessRun`: success-only — calls `persistRunArtifacts`
+ *     first, then surfaces harness-side failures in the progress comment,
+ *     deletes stranded progress comments, writes the GitHub Actions job
+ *     summary, and emits the structured output marker.
+ *
+ *   - `writeRunErrorOutputs`: error-only — writes the rendered error
+ *     summary to the Actions summary tab and mirrors it to the PR
+ *     progress comment. The catch path calls this and then
+ *     `persistRunArtifacts` separately so the rendered error lands before
+ *     the persistence calls, in case the latter throw.
+ *
+ * All three swallow their own non-fatal errors (`log.debug` or empty
+ * `catch {}`) so a cleanup failure can't flip an already-decided run
+ * outcome.
+ */
+
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import * as core from "@actions/core";
+import type { AgentResult } from "#app/agents/shared";
+import { SARIF_FILE } from "#app/brand";
+import { deleteProgressComment } from "#app/mcp/comment";
+import { requiredControlViolations } from "#app/mcp/crosswalk";
+import type { ToolContext } from "#app/mcp/server";
+import { evaluateGate, loadBaseline } from "#app/mcp/terraform/baseline";
+import { buildSarifReport } from "#app/mcp/terraform/findings";
+import { scanSessionOf } from "#app/mcp/terraform/scanSession";
+import type { ToolState } from "#app/toolState";
+import { buildFindingAnnotations } from "#app/utils/annotations";
+import {
+  describeDispatchTally,
+  formatDispatchSummary,
+} from "#app/agents/dispatchMetrics";
+import { formatUsageSummary, log, writeSummary } from "#app/utils/cli";
+import { reportToCloud } from "#app/utils/cloudReport";
+import { reportErrorToComment } from "#app/utils/errorReport";
+import { persistLearnings } from "#app/utils/learnings";
+import { persistSummary } from "#app/utils/prSummary";
+import { postReviewCleanup } from "#app/utils/reviewCleanup";
+import {
+  type RenderedRunError,
+  renderRunError,
+} from "#app/utils/runErrorRenderer";
+
+/**
+ * Best-effort cleanup shared by both run-end paths:
+ *   1. post-review cleanup (dispatch follow-up re-review on submitted reviews)
+ *   2. persist the agent-edited PR summary tmpfile
+ *   3. persist the agent-edited repo-level learnings tmpfile
+ *
+ * Each step is idempotent and swallows its own errors. Safe to call from
+ * both `main()`'s success path and its catch path.
+ */
+export async function persistRunArtifacts(
+  toolContext: ToolContext,
+): Promise<void> {
+  await postReviewCleanup(toolContext).catch((error) => {
+    log.debug(`post-review cleanup failed: ${error}`);
+  });
+  await persistSummary(toolContext);
+  await persistLearnings(toolContext);
+}
+
+/**
+ * Run the success-path cleanup waterfall:
+ *
+ *   1. shared best-effort cleanup via `persistRunArtifacts`
+ *   2. when the harness returned `success=false` (e.g. unsubmitted-review
+ *      gate exhausted retries, stop-hook persistently failing), render via
+ *      `renderRunError` and surface the error in BOTH the progress comment
+ *      (rendered.comment) and the Actions job summary (rendered.summary,
+ *      prepended below in step 4) — same classifier as the catch path so
+ *      the user sees it instead of a deleted-comment void / empty summary
+ *      tab
+ *   3. when the run succeeded, some write landed (`wasUpdated`), but the
+ *      progress comment was never finalized via `report_progress`, delete
+ *      the stranded comment (abandoned checklist, or a substantive artifact
+ *      written via another MCP write tool that skipped report_progress). a
+ *      run where NO write landed keeps its comment for handleAgentResult to
+ *      salvage into — see the `wasUpdated` guard below and #868
+ *   4. write the GitHub Actions step summary (best-effort — a write
+ *      failure must not throw past this point because we'd hit the outer
+ *      catch and clobber any progress comment we just wrote)
+ *   5. emit the structured output marker for tests + workflow consumers
+ */
+export async function finalizeSuccessRun(input: {
+  toolContext: ToolContext;
+  toolState: ToolState;
+  result: AgentResult;
+  repo: { owner: string; name: string };
+  /** Infraweaver Cloud org token (the `api_token` input). When set, the run's
+   *  findings/posture are reported to Cloud (best-effort). */
+  cloudApiToken?: string | undefined;
+}): Promise<void> {
+  await persistRunArtifacts(input.toolContext);
+
+  // shared rendering for the !success branch — same classifier as the
+  // outer catch path (BillingError reclassify → hang → BYOK billing →
+  // api-key → generic), so a harness-returned `{success: false}` lands an
+  // actionable error block in the job summary alongside the matching body
+  // in the progress comment. hang and generic get the `### ❌ Infraweaver
+  // failed` H3 banner; BillingError, BYOK billing, and api-key render
+  // their own provider-specific framing (no banner). renders once; reused
+  // for both surfaces below.
+  const rendered = !input.result.success
+    ? renderRunError({
+        errorMessage: input.result.error || "agent run failed",
+        repo: input.repo,
+        agentDiagnostic: input.toolState.agentDiagnostic,
+      })
+    : null;
+
+  // `createIfMissing: true` is load-bearing for silent triggers
+  // (IncrementalReview / pull_request_synchronize / auto-label) that have
+  // no progress comment to update — without it, terminal failures like
+  // BYOK billing exhaustion land only in the GH job summary, which most
+  // users never open. `reportErrorToComment` no-ops when both progress
+  // comment AND issue context are absent. see #835.
+  if (rendered) {
+    await reportErrorToComment({
+      toolState: input.toolState,
+      error: rendered.comment,
+      createIfMissing: true,
+    }).catch((error) => {
+      log.debug(`failure error report failed: ${error}`);
+    });
+  }
+
+  // create_pull_request_review owns its own deletion (see mcp/review.ts), so
+  // progressComment is already null by the time we get here for that path.
+  // uses finalSummaryWritten (not todoTracker.enabled or wasUpdated) so
+  // cleanup survives API failures in report_progress where cancel() ran but
+  // the write didn't succeed, and isn't fooled by writes to *other* artifacts.
+  //
+  // the extra `wasUpdated` guard preserves the comment when NO write landed at
+  // all: that's the case handleAgentResult salvages (raw-text answer / failed
+  // report_progress) by writing the agent's result into this very comment, or
+  // — when there's nothing to salvage — reports the failure into it. deleting
+  // here would strand the user with a vanished "Leaping into action" comment
+  // and a no-op error report (see #868).
+  //
+  // the `answerCommentPosted` clause handles the inverse: when the agent posted a
+  // standalone answer comment on the run's OWN target (create_issue_comment) AND
+  // finalized report_progress, the progress comment is redundant chrome duplicating
+  // the answer — delete it so the run leaves a single clean comment (the answer also
+  // notifies subscribers, which an in-place edit would not).
+  if (
+    input.result.success &&
+    input.toolState.progressComment &&
+    input.toolState.wasUpdated &&
+    (!input.toolState.finalSummaryWritten ||
+      input.toolState.answerCommentPosted)
+  ) {
+    await deleteProgressComment(input.toolContext).catch((error) => {
+      log.debug(`stranded progress comment cleanup failed: ${error}`);
+    });
+  }
+
+  try {
+    const usageSummary = formatUsageSummary(input.toolState.usageEntries);
+    // the specialist-routing watch (agents/dispatchMetrics.ts). rendered beside
+    // the usage table because the question it answers — "did hypothesis-coverage
+    // routing change what a run costs?" — is only answerable by comparing two
+    // runs, and this is where a human already looks to compare them.
+    const dispatchTally = input.toolState.dispatchMetrics.tally();
+    const dispatchLine = describeDispatchTally(dispatchTally);
+    if (dispatchLine) log.info(dispatchLine);
+    const dispatchSummary = formatDispatchSummary(dispatchTally);
+    const body = input.toolState.lastProgressBody || input.result.output;
+    const parts = [
+      rendered?.summary,
+      body,
+      usageSummary,
+      dispatchSummary,
+    ].filter(Boolean);
+    if (parts.length > 0) {
+      await writeSummary(parts.join("\n\n"));
+    }
+  } catch (error) {
+    log.debug(`job summary write failed: ${error}`);
+  }
+
+  if (input.toolState.output) {
+    log.info(
+      `::infraweaver-output::${Buffer.from(input.toolState.output).toString("base64")}`,
+    );
+    core.setOutput("result", input.toolState.output);
+  }
+
+  await emitFindingsOutputs(
+    input.toolState,
+    input.toolContext.payload.requiredControls ?? [],
+  );
+
+  // best-effort report to Infraweaver Cloud (no-ops without an org token /
+  // configured backend / a scan). reportToCloud swallows its own errors; the
+  // extra catch is belt-and-suspenders so a finalize step can't flip the run.
+  await reportToCloud({
+    toolState: input.toolState,
+    repo: input.repo,
+    apiToken: input.cloudApiToken,
+  }).catch((error) => {
+    log.debug(`cloud report failed: ${error}`);
+  });
+}
+
+/**
+ * when a deterministic scan ran this run (`terraform_scan` populated
+ * `lastScanConcerns`), expose its reported concern set to downstream workflow
+ * steps: the `findings-count` / `findings-sarif-path` action outputs, plus a
+ * safety-net SARIF write so modes that don't prompt the agent to call
+ * `terraform_emit_sarif` (Review) — or a Remediate run where the agent skipped
+ * that optional step — still surface a Code-Scanning artifact.
+ *
+ * When the agent already emitted a SARIF via `terraform_emit_sarif`
+ * (`scanSession.emittedSarifPath` set), this defers to that file — points the
+ * output at it, does not rewrite — so an agent report at a lower threshold or
+ * custom path is never clobbered. Otherwise it writes the safety-net file using
+ * the canonical `buildSarifReport` (the same builder the tool uses), so there is
+ * only ever one SARIF format.
+ *
+ * Unset outputs when no scan ran; `0` + a results-free SARIF when the scan was
+ * clean — so a workflow gate can distinguish "clean scan" from "not scanned".
+ * Best-effort like every other finalize step: an emit failure must not flip the
+ * run outcome.
+ */
+async function emitFindingsOutputs(
+  toolState: ToolState,
+  requiredControls: string[],
+): Promise<void> {
+  const session = scanSessionOf(toolState);
+  const concerns = session.lastScanConcerns;
+  if (!concerns) return;
+  const active = concerns.filter((c) => !c.suppression);
+  const suppressed = concerns.length - active.length;
+  const tail = suppressed ? ` (${suppressed} suppressed)` : "";
+  const workspace = process.env.GITHUB_WORKSPACE ?? process.cwd();
+  try {
+    core.setOutput("findings-count", String(active.length));
+
+    // 2c gate: fail the check only on NEW findings (vs a committed baseline) at or
+    // above High. With no baseline file present, every active concern is "new", so
+    // this is a plain High/Critical gate. Suppressed concerns are already excluded.
+    const gate = evaluateGate(active, loadBaseline(workspace));
+
+    // Required-controls policy: any OPEN finding mapping to a control the operator
+    // marked required fails the gate REGARDLESS of severity (binds the compliance
+    // crosswalk to the gate). Empty list → no-op.
+    const requiredViolations = requiredControlViolations(
+      active,
+      requiredControls,
+    );
+    const pass = gate.pass && requiredViolations.length === 0;
+
+    core.setOutput("findings-new-count", String(gate.newConcerns.length));
+    core.setOutput(
+      "findings-required-count",
+      String(requiredViolations.length),
+    );
+    core.setOutput("findings-gate", pass ? "pass" : "fail");
+    if (!gate.pass) {
+      const base = gate.hasBaseline ? " above the baseline" : "";
+      log.info(
+        `» gate: FAIL — ${gate.gating.length} new high/critical finding(s)${base}`,
+      );
+    }
+    if (requiredViolations.length > 0) {
+      log.info(
+        `» gate: FAIL — ${requiredViolations.length} open finding(s) on a required control (any severity)`,
+      );
+    }
+
+    // PR inline annotations: a new high/critical OR a required-control violation →
+    // error, everything else active → warning. Surfaces findings on the "Files
+    // changed" view + the check summary.
+    const gatingIds = new Set(
+      [...gate.gating, ...requiredViolations].map((c) => c.id),
+    );
+    for (const a of buildFindingAnnotations(active, gatingIds)) {
+      const props = { title: a.title, file: a.file, startLine: a.startLine };
+      if (a.level === "error") core.error(a.message, props);
+      else core.warning(a.message, props);
+    }
+    if (session.emittedSarifPath) {
+      core.setOutput("findings-sarif-path", session.emittedSarifPath);
+      log.info(
+        `» findings output: ${active.length} concern(s)${tail}, SARIF at ${session.emittedSarifPath} (agent-emitted)`,
+      );
+      return;
+    }
+    const sarifPath = join(
+      process.env.GITHUB_WORKSPACE ?? process.cwd(),
+      SARIF_FILE,
+    );
+    await writeFile(
+      sarifPath,
+      `${JSON.stringify(buildSarifReport(concerns), null, 2)}\n`,
+    );
+    core.setOutput("findings-sarif-path", sarifPath);
+    log.info(
+      `» findings output: ${active.length} concern(s)${tail}, SARIF at ${sarifPath}`,
+    );
+  } catch (error) {
+    log.debug(`findings output emit failed: ${error}`);
+  }
+}
+
+/**
+ * Write the rendered error to the GitHub Actions job summary tab + mirror
+ * to the PR progress comment when one exists. Catch path only.
+ *
+ * `lastProgressBody` and the usage table are appended to the summary so the
+ * partial work the agent did before failing isn't lost.
+ *
+ * `createIfMissing: true` is symmetric with `finalizeSuccessRun` — silent
+ * triggers (IncrementalReview / pull_request_synchronize / auto-label) that
+ * throw past `finalizeSuccessRun` (e.g. timeout race kills the agent
+ * mid-billing-exhausted-retry) reach this catch path with no progress
+ * comment to update, and without `createIfMissing` the terminal error
+ * lands only in the GH job summary that most users never open. see #835.
+ */
+export async function writeRunErrorOutputs(input: {
+  rendered: RenderedRunError;
+  toolState: ToolState;
+}): Promise<void> {
+  try {
+    const usageSummary = formatUsageSummary(input.toolState.usageEntries);
+    // a failed run's dispatch cost is exactly as informative as a successful
+    // one's — arguably more, since over-dispatch is a plausible cause of the
+    // timeout that got it here.
+    const dispatchSummary = formatDispatchSummary(
+      input.toolState.dispatchMetrics.tally(),
+    );
+    const parts = [
+      input.rendered.summary,
+      input.toolState.lastProgressBody,
+      usageSummary,
+      dispatchSummary,
+    ].filter(Boolean);
+    await writeSummary(parts.join("\n\n"));
+  } catch {}
+
+  try {
+    await reportErrorToComment({
+      toolState: input.toolState,
+      error: input.rendered.comment,
+      createIfMissing: true,
+    });
+  } catch {
+    // error reporting failed, but don't let it mask the original error
+  }
+}

package/src/utils/runStartupLog.ts

@@ -0,0 +1,67 @@
+/**
+ * Startup log formatting for the resolver pipeline. Computes the
+ * "model / agent / push / shell / timeout" block that main.ts prints
+ * after resolving the agent + model + payload.
+ */
+
+import { log } from "#app/utils/cli";
+import type { ResolvedPayload } from "#app/utils/payload";
+import { TIMEOUT_DISABLED } from "#app/utils/time";
+
+function resolveTimeoutForLog(timeout: string | undefined): string {
+  if (!timeout) return "1h (default)";
+  if (timeout === TIMEOUT_DISABLED) return "none (disabled)";
+  return timeout;
+}
+
+function resolveModelForLog(ctx: {
+  payload: ResolvedPayload;
+  resolvedModel: string | undefined;
+}): string {
+  const envModel = process.env.INFRAWEAVER_MODEL?.trim();
+  if (envModel) return `${envModel} (override via INFRAWEAVER_MODEL)`;
+  if (
+    ctx.resolvedModel &&
+    ctx.payload.model &&
+    ctx.payload.model !== ctx.resolvedModel
+  ) {
+    return `${ctx.resolvedModel} (resolved from ${ctx.payload.model})`;
+  }
+  if (ctx.resolvedModel) return ctx.resolvedModel;
+  if (ctx.payload.model) return `${ctx.payload.model} (unresolved)`;
+  return "auto";
+}
+
+function resolveAgentForLog(ctx: {
+  agentName: string;
+  resolvedModel: string | undefined;
+}): string {
+  const envAgent = process.env.INFRAWEAVER_AGENT?.trim();
+  if (envAgent && envAgent === ctx.agentName) {
+    return `${ctx.agentName} (override via INFRAWEAVER_AGENT)`;
+  }
+  if (ctx.agentName === "claude" && ctx.resolvedModel) {
+    return `${ctx.agentName} (auto-selected for ${ctx.resolvedModel})`;
+  }
+  return ctx.agentName;
+}
+
+/**
+ * Emit the startup block ("» model / agent / push / shell / timeout") after
+ * the agent and model are resolved. Single side-effect; no return.
+ */
+export function logRunStartup(ctx: {
+  payload: ResolvedPayload;
+  resolvedModel: string | undefined;
+  agentName: string;
+}): void {
+  log.info(
+    `» model:   ${resolveModelForLog({ payload: ctx.payload, resolvedModel: ctx.resolvedModel })}`,
+  );
+  log.info(
+    `» agent:   ${resolveAgentForLog({ agentName: ctx.agentName, resolvedModel: ctx.resolvedModel })}`,
+  );
+  log.info(`» push:    ${ctx.payload.push}`);
+  log.info(`» shell:   ${ctx.payload.shell}`);
+  log.info(`» timeout: ${resolveTimeoutForLog(ctx.payload.timeout)}`);
+}

package/src/utils/secrets.ts

@@ -0,0 +1,208 @@
+/**
+ * Secret detection and env filtering utilities
+ *
+ * subprocess env filtering: default-deny allowlist model.
+ * only vars in the safe set or user allowlist are passed to child processes.
+ *
+ * log redaction: SENSITIVE_PATTERNS are used to identify secret values
+ * for redaction in logs and GHA masking (independent of subprocess filtering).
+ */
+
+// --- log redaction (unchanged, independent of subprocess filtering) ---
+
+// patterns for sensitive env var names (used by normalizeEnv)
+export const SENSITIVE_PATTERNS = [
+  /_KEY$/i,
+  /_SECRET$/i,
+  /_TOKEN$/i,
+  /_PASSWORD$/i,
+  /_CREDENTIAL$/i,
+];
+
+// secret-bearing names the suffix patterns miss, because the credential sits in
+// the middle or the var is a host-suffixed family:
+// - ACTIONS_ID_TOKEN_REQUEST_URL ends in _URL, but with its sibling _TOKEN it
+//   mints OIDC tokens, so the pair is treated as one credential.
+// - TF_TOKEN_<host> is Terraform's per-host registry credential.
+// - GIT_CONFIG_VALUE_<n> can carry an http.<host>.extraheader Basic auth value.
+const SENSITIVE_ENV_PREFIXES = ["ACTIONS_ID_TOKEN_REQUEST_", "TF_TOKEN_", "GIT_CONFIG_VALUE_"];
+
+export function isSensitiveEnvName(key: string): boolean {
+  if (SENSITIVE_ENV_PREFIXES.some((p) => key.toUpperCase().startsWith(p))) return true;
+  return SENSITIVE_PATTERNS.some((p) => p.test(key));
+}
+
+// --- subprocess env filtering ---
+
+// prefixes whose vars are safe to pass through (runner metadata, toolchain).
+const SAFE_ENV_PREFIXES = ["RUNNER_", "JAVA_HOME_", "GOROOT_"];
+
+// GITHUB_* is an EXACT allowlist rather than a prefix: the set of context vars
+// the runner injects is well-known and closed, so listing them explicitly fails
+// closed on any unknown/future GITHUB_* var (e.g. a sensitive one that doesn't
+// end in _TOKEN/_KEY/_SECRET and would otherwise slip through the prefix).
+// GITHUB_TOKEN/GH_TOKEN are intentionally absent; isSensitiveEnvName() also
+// catches them via the _TOKEN suffix. Users can opt any var in via the allowlist.
+const SAFE_GITHUB_ENV_NAMES = new Set([
+  "GITHUB_ACTION",
+  "GITHUB_ACTION_PATH",
+  "GITHUB_ACTION_REPOSITORY",
+  "GITHUB_ACTIONS",
+  "GITHUB_ACTOR",
+  "GITHUB_ACTOR_ID",
+  "GITHUB_API_URL",
+  "GITHUB_BASE_REF",
+  "GITHUB_ENV",
+  "GITHUB_EVENT_NAME",
+  "GITHUB_EVENT_PATH",
+  "GITHUB_GRAPHQL_URL",
+  "GITHUB_HEAD_REF",
+  "GITHUB_JOB",
+  "GITHUB_OUTPUT",
+  "GITHUB_PATH",
+  "GITHUB_REF",
+  "GITHUB_REF_NAME",
+  "GITHUB_REF_PROTECTED",
+  "GITHUB_REF_TYPE",
+  "GITHUB_REPOSITORY",
+  "GITHUB_REPOSITORY_ID",
+  "GITHUB_REPOSITORY_OWNER",
+  "GITHUB_REPOSITORY_OWNER_ID",
+  "GITHUB_RETENTION_DAYS",
+  "GITHUB_RUN_ATTEMPT",
+  "GITHUB_RUN_ID",
+  "GITHUB_RUN_NUMBER",
+  "GITHUB_SERVER_URL",
+  "GITHUB_SHA",
+  "GITHUB_STEP_SUMMARY",
+  "GITHUB_TRIGGERING_ACTOR",
+  "GITHUB_WORKFLOW",
+  "GITHUB_WORKFLOW_REF",
+  "GITHUB_WORKFLOW_SHA",
+  "GITHUB_WORKSPACE",
+]);
+
+// exact var names safe to pass through (system + runner image toolchain)
+const SAFE_ENV_NAMES = new Set([
+  // system
+  "CI",
+  "HOME",
+  "LANG",
+  "LOGNAME",
+  "PATH",
+  "SHELL",
+  "SHLVL",
+  "TERM",
+  "TMPDIR",
+  "TZ",
+  "USER",
+  "XDG_CONFIG_HOME",
+  "XDG_RUNTIME_DIR",
+  "DEBIAN_FRONTEND",
+  // runner image toolchain
+  "ACCEPT_EULA",
+  "AGENT_TOOLSDIRECTORY",
+  "ANDROID_HOME",
+  "ANDROID_NDK",
+  "ANDROID_NDK_HOME",
+  "ANDROID_NDK_LATEST_HOME",
+  "ANDROID_NDK_ROOT",
+  "ANDROID_SDK_ROOT",
+  "ANT_HOME",
+  "AZURE_EXTENSION_DIR",
+  "BOOTSTRAP_HASKELL_NONINTERACTIVE",
+  "CHROME_BIN",
+  "CHROMEWEBDRIVER",
+  "CONDA",
+  "DOTNET_MULTILEVEL_LOOKUP",
+  "DOTNET_NOLOGO",
+  "DOTNET_SKIP_FIRST_TIME_EXPERIENCE",
+  "EDGEWEBDRIVER",
+  "GECKOWEBDRIVER",
+  "GHCUP_INSTALL_BASE_PREFIX",
+  "GRADLE_HOME",
+  "JAVA_HOME",
+  "HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS",
+  "HOMEBREW_NO_AUTO_UPDATE",
+  "ImageOS",
+  "ImageVersion",
+  "NVM_DIR",
+  "PIPX_BIN_DIR",
+  "PIPX_HOME",
+  "PSModulePath",
+  "SELENIUM_JAR_PATH",
+  "SGX_AESM_ADDR",
+  "SWIFT_PATH",
+  "VCPKG_INSTALLATION_ROOT",
+]);
+
+let _userAllowlist: Set<string> | null = null;
+
+export function setEnvAllowlist(raw: string): void {
+  const names = raw
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  _userAllowlist = new Set(names);
+}
+
+function isSafeEnvVar(key: string): boolean {
+  if (SAFE_ENV_NAMES.has(key)) return true;
+  if (SAFE_GITHUB_ENV_NAMES.has(key)) return true;
+  return SAFE_ENV_PREFIXES.some((p) => key.startsWith(p));
+}
+
+/** filter env vars using default-deny allowlist: safe set + user allowlist */
+export function filterEnv(): Record<string, string> {
+  const filtered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value === undefined) continue;
+    const userAllowed = _userAllowlist?.has(key) ?? false;
+    if (isSensitiveEnvName(key) && !userAllowed) continue;
+    if (isSafeEnvVar(key) || userAllowed) {
+      filtered[key] = value;
+    }
+  }
+  return filtered;
+}
+
+/**
+ * env for "inherit" mode: everything in process.env EXCEPT secret-bearing names.
+ *
+ * inherit exists to widen the *command* surface (arbitrary toolchain vars the
+ * restricted allowlist can't enumerate), not to hand the agent credentials — so
+ * this is a denylist over the full env rather than the restricted allowlist. A
+ * specific var can still be opted back in explicitly via the user allowlist.
+ *
+ * Without this, `shell: "enabled"` would let the agent read INPUT_*_TOKEN, a BYO
+ * model key, or the OIDC minting creds straight out of `env`.
+ */
+export function inheritEnv(): Record<string, string> {
+  const inherited: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value === undefined) continue;
+    const userAllowed = _userAllowlist?.has(key) ?? false;
+    if (isSensitiveEnvName(key) && !userAllowed) continue;
+    inherited[key] = value;
+  }
+  return inherited;
+}
+
+export type EnvMode = "restricted" | "inherit" | Record<string, string>;
+
+/**
+ * resolve env mode to actual env object
+ * - "restricted" (default): filterEnv() — only safe set + user allowlist
+ * - "inherit": full process.env minus secret-bearing names
+ * - object: custom env merged with restricted base
+ */
+export function resolveEnv(mode: EnvMode | undefined): Record<string, string | undefined> {
+  if (mode === "inherit") {
+    return inheritEnv();
+  }
+  if (mode === "restricted" || mode === undefined) {
+    return filterEnv();
+  }
+  // custom env object - merge with restricted base
+  return { ...filterEnv(), ...mode };
+}