terramend 0.2.0

package/src/reviewQuality.ts

@@ -0,0 +1,134 @@
+/**
+ * Review-quality controls for the Review / IncrementalReview modes: a curated
+ * false-positive precedents list and an adversarial per-finding verification
+ * pass. Both are embedded into the mode prompts (modes.ts) — the precedents
+ * also travel verbatim inside every verification dispatch, since subagents
+ * never see the orchestrator's prompt.
+ *
+ * Provenance: adapted from Anthropic's claude-code-security-review action
+ * (MIT) — its hard-exclusion rules, its LLM-judge "PRECEDENTS" list, and the
+ * /security-review slash command's refute-subagent pattern. See
+ * CLAUDE-CODE-SECURITY-REVIEW-VS-TERRAMEND.md (workspace root) §5.1–5.2 for
+ * the comparison that motivated this. Deliberate divergences from upstream:
+ *   - CCSR judges findings via sequential direct API calls; we dispatch
+ *     parallel read-only reviewfrog subagents (machine-gated, see
+ *     agents/subagentToolGates.ts) so verification adds one round of wall
+ *     time regardless of finding count.
+ *   - CCSR's judge gates on a bare confidence number; we gate on an explicit
+ *     verdict (confirmed/refuted/uncertain) plus confidence, because the
+ *     verdict is what the orchestrator acts on and the number alone invites
+ *     anchoring.
+ *   - CCSR drops "secrets stored on disk" findings (handled by a separate
+ *     pipeline there). Terramend reviews IaC where a hardcoded credential is
+ *     a core finding, so that exclusion is intentionally NOT inherited.
+ * Kept as-is from upstream: fail-open semantics (a broken verifier must
+ * never silently swallow a true positive) and suppression auditability
+ * (excluded findings are listed, never deleted).
+ */
+
+import { REVIEWER_AGENT_NAME } from "#app/agents/reviewer";
+
+/**
+ * False-positive precedents applied at aggregation time and inside every
+ * verification dispatch. Each entry encodes a recurring FP class; a candidate
+ * matching one needs specific evidence that the precedent does not apply, or
+ * it gets dropped. Ordered: hard exclusions (never post) → general code
+ * precedents → Terraform/IaC precedents → the final signal-quality bar.
+ */
+export const REVIEW_FINDING_PRECEDENTS = `### Finding precedents (false-positive control)
+
+Apply these when deciding whether a candidate finding is worth posting, and include this whole section verbatim in every verification dispatch. Each precedent encodes a recurring false-positive class: a candidate that matches one is dropped unless you have specific evidence the precedent does not apply here.
+
+**Hard exclusions — never post:**
+
+- Denial-of-service / resource-exhaustion concerns without a concrete, cheap-to-trigger attack path: missing rate limiting, "unbounded" loops over trusted input, "could exhaust memory/CPU".
+- Theoretical race conditions or timing attacks. Post a race only when it is concretely reachable and concretely harmful.
+- Memory-safety findings (buffer overflow, use-after-free, OOB) in memory-safe languages — Rust, Go, JS/TS, Python, Java, HCL.
+- Security findings whose anchor is a documentation file — a code snippet in \`.md\`/\`.mdx\` is not an attack surface. (Stale or incorrect docs remain valid *impact* findings; this exclusion is only for treating doc content as exploitable.)
+- "Lack of hardening" with no vulnerability: code is not required to implement every best practice, only to avoid concrete flaws.
+- Vulnerable-dependency reports based on version strings alone — dependency scanning is a separate pipeline with its own remediation flow.
+
+**General precedents:**
+
+- Environment variables, CLI flags, and workflow-dispatch inputs are operator-trusted. An attack that requires controlling them is invalid.
+- A missing permission/auth check in client-side code is not a finding; the server is the enforcement boundary. The same applies to client-side input validation.
+- React/Angular-class frameworks escape output by default — an XSS claim needs \`dangerouslySetInnerHTML\`, \`bypassSecurityTrustHtml\`, or an equivalent unsafe API in the diff.
+- SSRF requires control of host or protocol; path-only control is not SSRF. Neither SSRF nor path traversal applies to purely client-side code.
+- Command injection in shell scripts needs a named untrusted-input path; developer-invoked scripts taking developer-supplied arguments don't qualify.
+- Un-sanitized user input reaching logs is log spoofing, not a vulnerability. A logging finding is valid only when it exposes secrets, credentials, or PII.
+- UUIDs are unguessable; an attack that requires guessing one is invalid.
+
+**Terraform / IaC precedents:**
+
+- \`0.0.0.0/0\` **egress** is common and usually intentional — flag open **ingress**, or egress only with a concrete exfiltration concern attached.
+- Values from \`*.tfvars\`, \`locals\`, and module input variables are operator-trusted; "what if this variable is malicious" is invalid without naming an untrusted writer.
+- Missing encryption / versioning / access-logging on resources that demonstrably hold no sensitive data (short-retention log groups, test fixtures, scratch buckets) is ℹ️ at most, never 🚨.
+- Unpinned provider or module versions are style feedback for first-party modules; ⚠️ only for third-party module sources, where the unpinned ref is supply-chain surface.
+- Do not infer state drift, plan outcomes, or "this will destroy/replace the database" from static HCL — only \`terraform plan\` evidence supports those claims. Without plan evidence, phrase the concern as an open question, not a finding.
+- Missing tags and naming-convention deviations are nitpicks, not findings.
+- When a deterministic scanner rule covers the same issue (trivy \`AVD-*\`, checkov \`CKV_*\`, tflint), cite the rule id in the finding — that makes it ✗→✓ verifiable downstream instead of an unverifiable reviewer opinion.
+
+**Signal-quality bar** — a surviving candidate must still answer yes to all three: Is there a concrete failure or attack path? Is it a real risk rather than a theoretical best practice? Could the author act on it exactly as written?`;
+
+/**
+ * Adversarial verification pass, spliced into the aggregation step of Review
+ * and IncrementalReview (between the non-anchored-concern hunt and comment
+ * drafting). The 0-or-2+ lens rule does not apply here — that rule buys
+ * independence between discovery perspectives; verification is a per-claim
+ * judgment with no orthogonality to purchase, so one finding = one dispatch
+ * is correct even when there is exactly one finding.
+ */
+export const FINDING_VERIFICATION_PASS = `**Adversarial verification — required before posting any 🚨/⚠️ finding.** A candidate finding is a hypothesis until an independent pass has tried to kill it; your own trace is not independent, because you found it. For every candidate you intend to post at 🚨 critical or ⚠️ important, dispatch one \`${REVIEWER_AGENT_NAME}\` verification subagent — ALL of them in a single assistant turn as parallel Task tool_use blocks. One candidate = one subagent, and dispatching exactly one is fine here: the 0-or-2+ rule governs discovery lenses, where independence between perspectives is the point; verification is per-claim judgment with no orthogonality to buy. Skip verification only for:
+
+   - ℹ️ informational findings and nitpicks (post on your own judgment), and
+   - findings whose evidence is deterministic tool output — a scanner concern id, a failing test, a compiler/type error. Those re-verify mechanically and need no judge.
+
+   Each verification dispatch contains, in order:
+   - the absolute \`diffPath\` (and \`incrementalDiffPath\` when available) named verbatim — the reviewer's baked-in system prompt selects its first action on this token;
+   - the single finding under test: file, line, intended severity, the claim, and the evidence you collected;
+   - the **Finding precedents** section — plus any \`### Finding precedents — org addendum\` section from your instructions — included verbatim (the subagent cannot see your prompt);
+   - this charge: "Attempt to REFUTE this finding. Read the actual code — do not trust the claim's description of it. Apply the finding precedents. Report a verdict (\`confirmed\` / \`refuted\` / \`uncertain\`), a confidence score 1–10, and a 2–3 sentence justification quoting the code that decides it. When the attack or failure path is theoretical rather than demonstrated, bias toward \`refuted\`."
+
+   Set the Task \`description\` to \`verify:<file>:<line>\` so parallel verifications are distinguishable in CI logs. Asking for a verdict schema is correct here and does not violate the discovery-lens "no finding schema" discipline — the subagent is judging one claim, not exploring.
+
+   Gate on what comes back:
+   - \`refuted\` at confidence ≥ 7 → suppress the finding and record it for the audit trail.
+   - \`uncertain\`, or \`refuted\` at lower confidence → re-read the decisive code yourself; either downgrade to ℹ️ with the uncertainty stated, or suppress. Do not post it at 🚨/⚠️.
+   - \`confirmed\` → post it; fold the verifier's justification into the comment's technical-details block when it adds evidence.
+   - errored / timed out / nothing usable → retry once; if it still fails, KEEP the finding and add \`verification unavailable\` to its technical details. Fail open: a broken verifier must never silently swallow a true positive, and must never block the review.
+
+   Suppressed findings are recorded, never silently deleted — list every one in the \`Suppressed findings\` block at the bottom of the review body (shape defined in the format below): severity, \`file:line\`, the claim in a few words, the refutation in a few words. An unaudited filter eats true positives invisibly; the audit trail is what lets a human catch the filter being wrong.`;
+
+/**
+ * Heading under which `fp_filtering_instructions` (the action input carrying
+ * org-specific FP precedents) is appended to the Review mode instructions.
+ * FINDING_VERIFICATION_PASS names this heading when telling the orchestrator
+ * what to include verbatim in each verification dispatch — the two strings
+ * are a contract; change them together.
+ */
+export const FP_PRECEDENTS_ADDENDUM_HEADING = "### Finding precedents — org addendum";
+
+/**
+ * Merge the §5.5 action inputs into the per-mode user instructions that
+ * `select_mode` appends to the mode prompt (see buildOrchestratorGuidance in
+ * mcp/selectMode.ts). Both land on the "Review" key — IncrementalReview
+ * inherits Review's instructions via modeInstructionParent. Composes with
+ * (never replaces) backend-provided instructions: hosted settings and
+ * workflow-file inputs are both repo-owner-controlled surfaces.
+ */
+export function mergeReviewModeInstructions(
+  base: Record<string, string>,
+  inputs: { reviewInstructions?: string | undefined; fpFilteringInstructions?: string | undefined },
+): Record<string, string> {
+  const review = inputs.reviewInstructions?.trim();
+  const fp = inputs.fpFilteringInstructions?.trim();
+  if (!review && !fp) return base;
+
+  const sections = [base.Review, review];
+  if (fp) {
+    sections.push(
+      `${FP_PRECEDENTS_ADDENDUM_HEADING}\n\nApply these alongside the built-in Finding precedents, and include this whole section verbatim in every verification dispatch.\n\n${fp}`,
+    );
+  }
+  return { ...base, Review: sections.filter(Boolean).join("\n\n") };
+}

package/src/runCli.test.ts

@@ -0,0 +1,214 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, existsSync, mkdtempSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { runTerramendCli } from "#app/runCli";
+import actionPackageJson from "#package.json" with { type: "json" };
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return { ...actual, execFileSync: vi.fn() };
+});
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return {
+    ...actual,
+    accessSync: vi.fn(),
+    existsSync: vi.fn(() => true),
+    mkdtempSync: vi.fn(() => "/tmp/terramend-bootstrap-xyz"),
+  };
+});
+
+const nodeBinDir = dirname(process.execPath);
+
+/** make accessSync succeed only for paths matching the given predicate. */
+function allowExecutables(predicate: (path: string) => boolean): void {
+  vi.mocked(accessSync).mockImplementation((path) => {
+    if (!predicate(String(path))) {
+      throw new Error("EACCES");
+    }
+  });
+}
+
+function execCall(index = 0): {
+  command: string;
+  args: string[];
+  options: Record<string, unknown>;
+} {
+  const call = vi.mocked(execFileSync).mock.calls[index];
+  if (!call) throw new Error(`execFileSync call ${index} missing`);
+  return {
+    command: String(call[0]),
+    args: (call[1] ?? []) as string[],
+    options: (call[2] ?? {}) as Record<string, unknown>,
+  };
+}
+
+beforeEach(() => {
+  allowExecutables(() => true);
+  // pin the Windows executable-extension list so candidate paths are deterministic
+  vi.stubEnv("PATHEXT", ".CMD");
+  vi.stubEnv("GITHUB_WORKSPACE", "");
+  vi.stubEnv("GITHUB_ACTION_REF", "");
+  vi.stubEnv("GITHUB_ACTION_REPOSITORY", "");
+  vi.stubEnv("TERRAMEND_FORCE_LOCAL_CLI", "");
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+  vi.clearAllMocks();
+});
+
+describe("runTerramendCli – npx bootstrap path", () => {
+  it("runs the exact-pinned npm package via npx in a fresh tmpdir", () => {
+    runTerramendCli({ cliArgs: ["gha", "token"] });
+
+    const { command, args, options } = execCall();
+    expect(command).toContain("npx");
+    expect(args).toEqual(["--yes", `terramend@${actionPackageJson.version}`, "gha", "token"]);
+    expect(options.cwd).toBe("/tmp/terramend-bootstrap-xyz");
+    expect(mkdtempSync).toHaveBeenCalledWith(expect.stringContaining("terramend-bootstrap-"));
+
+    const env = options.env as NodeJS.ProcessEnv;
+    expect(env.npm_config_registry).toBe("https://registry.npmjs.org");
+    expect(env.COREPACK_NPM_REGISTRY).toBe("https://registry.npmjs.org");
+    expect(env.npm_config_min_release_age).toBe("0");
+    expect(env.pnpm_config_minimum_release_age).toBe("0");
+    expect(env.PATH).toContain(nodeBinDir);
+  });
+
+  it("falls back to corepack pnpm dlx when npx is missing", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    allowExecutables((path) => path.includes("corepack"));
+
+    runTerramendCli({ cliArgs: ["gha"] });
+
+    expect(warnSpy).toHaveBeenCalledWith("» npx not found, using corepack pnpm dlx");
+    const { command, args } = execCall();
+    expect(command).toContain("corepack");
+    expect(args).toEqual(["pnpm", "dlx", `terramend@${actionPackageJson.version}`, "gha"]);
+  });
+
+  it("throws when neither npx nor corepack can be found", () => {
+    allowExecutables(() => false);
+
+    expect(() => runTerramendCli({ cliArgs: ["gha"] })).toThrow(
+      /could not find npx or corepack on PATH/,
+    );
+    expect(execFileSync).not.toHaveBeenCalled();
+  });
+
+  it("ignores PATH entries inside the customer workspace and relative entries", () => {
+    const workspace = join(nodeBinDir, "workspace-checkout");
+    vi.stubEnv("GITHUB_WORKSPACE", workspace);
+    vi.stubEnv("PATH", `${join(workspace, "bin")}${process.platform === "win32" ? ";" : ":"}bin`);
+    // every candidate is "accessible" — only the untrusted-path filter can reject
+    allowExecutables((path) => path.startsWith(workspace) || !path.includes(nodeBinDir));
+
+    expect(() => runTerramendCli({ cliArgs: ["gha"] })).toThrow(
+      /could not find npx or corepack on PATH/,
+    );
+  });
+});
+
+describe("runTerramendCli – local CLI path", () => {
+  it("runs the checked-out cli.ts when TERRAMEND_FORCE_LOCAL_CLI=1", () => {
+    vi.stubEnv("TERRAMEND_FORCE_LOCAL_CLI", "1");
+
+    runTerramendCli({ cliArgs: ["gha"] });
+
+    const { command, args, options } = execCall();
+    expect(command).toBe(process.execPath);
+    expect(args).toEqual(["cli.ts", "gha"]);
+    expect(String(options.cwd)).toContain("src");
+  });
+
+  it("runs locally when the action ref is main on terramend/terramend", () => {
+    vi.stubEnv("GITHUB_ACTION_REF", "main");
+    vi.stubEnv("GITHUB_ACTION_REPOSITORY", "terramend/terramend");
+
+    runTerramendCli({ cliArgs: ["gha"] });
+
+    expect(execCall().command).toBe(process.execPath);
+  });
+
+  it("installs action dependencies via corepack pnpm when node_modules is missing", () => {
+    vi.stubEnv("TERRAMEND_FORCE_LOCAL_CLI", "1");
+    vi.mocked(existsSync).mockReturnValue(false);
+
+    runTerramendCli({ cliArgs: ["gha"] });
+
+    expect(execFileSync).toHaveBeenCalledTimes(2);
+    const install = execCall(0);
+    expect(install.command).toContain("corepack");
+    expect(install.args).toEqual(["pnpm", "install", "--frozen-lockfile", "--ignore-scripts"]);
+    expect(execCall(1).args).toEqual(["cli.ts", "gha"]);
+  });
+
+  it("throws a descriptive error when corepack is required but missing", () => {
+    vi.stubEnv("TERRAMEND_FORCE_LOCAL_CLI", "1");
+    vi.mocked(existsSync).mockReturnValue(false);
+    allowExecutables(() => false);
+
+    expect(() => runTerramendCli({ cliArgs: ["gha"] })).toThrow(
+      /could not find corepack on PATH \(needed to install action dependencies via pnpm\)/,
+    );
+  });
+});
+
+function mockProcessExit() {
+  return vi.spyOn(process, "exit").mockImplementation(((code?: number | string | null) => {
+    throw new Error(`process.exit:${code}`);
+  }) as never);
+}
+
+describe("runTerramendCli – child exit propagation", () => {
+  let exitSpy: ReturnType<typeof mockProcessExit>;
+
+  beforeEach(() => {
+    exitSpy = mockProcessExit();
+  });
+
+  it("propagates a numeric child exit status silently", () => {
+    const childError = Object.assign(new Error("Command failed"), { status: 3 });
+    vi.mocked(execFileSync).mockImplementationOnce(() => {
+      throw childError;
+    });
+
+    expect(() => runTerramendCli({ cliArgs: ["gha"] })).toThrow("process.exit:3");
+    expect(exitSpy).toHaveBeenCalledWith(3);
+  });
+
+  it("exits 1 when the child was killed by a signal", () => {
+    const childError = Object.assign(new Error("Command failed"), {
+      status: null,
+      signal: "SIGTERM",
+    });
+    vi.mocked(execFileSync).mockImplementationOnce(() => {
+      throw childError;
+    });
+
+    expect(() => runTerramendCli({ cliArgs: ["gha"] })).toThrow("process.exit:1");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it("rethrows genuine spawn failures", () => {
+    vi.mocked(execFileSync).mockImplementationOnce(() => {
+      throw new Error("spawn ENOENT");
+    });
+
+    expect(() => runTerramendCli({ cliArgs: ["gha"] })).toThrow("spawn ENOENT");
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("swallows errors and warns when swallowErrors is set", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.mocked(execFileSync).mockImplementationOnce(() => {
+      throw new Error("cleanup blew up");
+    });
+
+    expect(() => runTerramendCli({ cliArgs: ["gha"], swallowErrors: true })).not.toThrow();
+    expect(warnSpy).toHaveBeenCalledWith("» terramend cleanup bootstrap failed: cleanup blew up");
+  });
+});

package/src/runCli.ts

@@ -0,0 +1,282 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import actionPackageJson from "#package.json" with { type: "json" };
+
+interface RunTerramendCliParams {
+  cliArgs: string[];
+  swallowErrors?: boolean;
+}
+
+interface RuntimeContext {
+  actionRef: string | undefined;
+  actionRepository: string | undefined;
+  actionRoot: string;
+  nodeBinDir: string;
+  env: NodeJS.ProcessEnv;
+}
+
+const NPM_REGISTRY = "https://registry.npmjs.org";
+// Pin the EXACT version baked into this action ref, not a `^` range. A consumer
+// who SHA-pins `uses: terramend/terramend@<sha>` is pinning this file; resolving
+// `^x.y.z` at runtime would silently run a newer npm publish than the pinned
+// ref, so a single malicious/compromised publish would reach every consumer
+// despite their pin. Exact-pinning makes the executed code match the vetted ref.
+const FALLBACK_PACKAGE_SPEC = `terramend@${actionPackageJson.version}`;
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function canAccessExecutable(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    if (process.platform !== "win32") {
+      return false;
+    }
+  }
+
+  try {
+    accessSync(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// reject PATH entries that an attacker can plausibly write to before terramend
+// runs. specifically: relative entries (., bin, etc., which resolve against
+// cwd), and anything inside the customer's checkout. an attacker who can land
+// a malicious `npx` in the repo and prepend `$GITHUB_WORKSPACE/bin` to
+// `GITHUB_PATH` from a prior workflow step would otherwise get full code
+// execution under our action token.
+//
+// on Windows the filesystem is case-insensitive but `resolve()` preserves
+// input case, so we lowercase both sides before comparing — otherwise an
+// attacker can bypass the filter by varying the case of GITHUB_WORKSPACE in
+// their injected PATH entry (`d:\a\repo` vs `D:\a\repo`).
+function normalizePathForCompare(path: string): string {
+  return process.platform === "win32" ? resolve(path).toLowerCase() : resolve(path);
+}
+
+function isUntrustedPathEntry(entry: string, untrustedRoots: string[]): boolean {
+  if (!isAbsolute(entry)) return true;
+  const normalized = normalizePathForCompare(entry);
+  for (const root of untrustedRoots) {
+    if (normalized === root) return true;
+    if (normalized.startsWith(root + sep)) return true;
+  }
+  return false;
+}
+
+function getUntrustedPathRoots(env: NodeJS.ProcessEnv): string[] {
+  const roots: string[] = [];
+  const workspace = env.GITHUB_WORKSPACE;
+  if (workspace && isAbsolute(workspace)) roots.push(normalizePathForCompare(workspace));
+  return roots;
+}
+
+function resolveExecutable(params: { command: string; env: NodeJS.ProcessEnv }): string | null {
+  const pathValue = params.env.PATH ?? "";
+  const untrustedRoots = getUntrustedPathRoots(params.env);
+  const pathEntries = pathValue
+    .split(delimiter)
+    .filter(Boolean)
+    .filter((entry) => !isUntrustedPathEntry(entry, untrustedRoots));
+  const extensions =
+    process.platform === "win32"
+      ? (params.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+      : [""];
+
+  for (const pathEntry of pathEntries) {
+    for (const extension of extensions) {
+      const candidate = join(pathEntry, `${params.command}${extension.toLowerCase()}`);
+      if (canAccessExecutable(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  return null;
+}
+
+function createRuntimeContext(): RuntimeContext {
+  const actionRoot = dirname(fileURLToPath(import.meta.url));
+  const nodeBinDir = dirname(process.execPath);
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  env.npm_config_registry = NPM_REGISTRY;
+  env.COREPACK_NPM_REGISTRY = NPM_REGISTRY;
+  // bypass customer-side release-age gates (npm's `min-release-age`, pnpm's
+  // `minimumReleaseAge`) so our bootstrap can resolve the latest publish.
+  // terramend's npm version is server-stamped from a SHA-pinned action ref the
+  // customer already vets at the action layer — not a customer-vetted dep, so
+  // the gate is the wrong affordance here. env beats .npmrc in both tools.
+  // npm uses `npm_config_*`; pnpm v11+ requires `pnpm_config_*` (the v10→v11
+  // migration renamed the prefix). tracked: #713
+  env.npm_config_min_release_age = "0";
+  env.pnpm_config_minimum_release_age = "0";
+  const currentPath = process.env.PATH ?? "";
+  env.PATH = currentPath ? `${nodeBinDir}${delimiter}${currentPath}` : nodeBinDir;
+
+  return {
+    actionRef: process.env.GITHUB_ACTION_REF,
+    actionRepository: process.env.GITHUB_ACTION_REPOSITORY,
+    actionRoot,
+    nodeBinDir,
+    env,
+  };
+}
+
+// $GITHUB_WORKSPACE is the customer's repo. running `npx --yes terramend@…`
+// there makes npm read THEIR `package.json` first, which on npm v11+ enforces
+// `devEngines.packageManager` and aborts the bootstrap with EBADDEVENGINES
+// before the agent ever boots. our bootstrap doesn't need anything from the
+// customer's tree — a freshly-created tmpdir is package.json-free and
+// parent-less, so npm walks up to `/` finding nothing. see #837.
+//
+// `mkdtempSync` (vs raw `tmpdir()`): `$TMPDIR` is overridable from a prior
+// `$GITHUB_ENV` step, and a customer-authored or compromised prior step
+// could plant `node_modules/terramend/` in the resolved tmpdir to hijack
+// `npx --yes terramend@<version>` resolution. a fresh per-invocation
+// subdirectory is mode 0700 and not pre-writable by anything earlier in
+// the job.
+function runCommand(params: { context: RuntimeContext; command: string; args: string[] }): void {
+  execFileSync(params.command, params.args, {
+    cwd: mkdtempSync(join(tmpdir(), "terramend-bootstrap-")),
+    stdio: "inherit",
+    env: params.context.env,
+  });
+}
+
+// resolve a launcher binary by walking PATH (which already has the action
+// runtime's nodeBinDir prepended). some hosted Node 24 runner pools ship
+// `node` at `externals/node24/bin/node` without the sibling `npx`/`corepack`,
+// so a hardcoded sibling path can't be relied on — fall back to whatever the
+// runner image provides on PATH.
+function requireExecutable(params: {
+  context: RuntimeContext;
+  command: string;
+  purpose: string;
+}): string {
+  const resolved = resolveExecutable({ command: params.command, env: params.context.env });
+  if (!resolved) {
+    throw new Error(
+      `could not find ${params.command} on PATH (needed to ${params.purpose}); ` +
+        `runtime PATH was: ${params.context.env.PATH ?? "<empty>"}`,
+    );
+  }
+  return resolved;
+}
+
+function runPackageCli(context: RuntimeContext, packageSpec: string, cliArgs: string[]): void {
+  const npxPath = resolveExecutable({ command: "npx", env: context.env });
+  if (npxPath) {
+    runCommand({ context, command: npxPath, args: ["--yes", packageSpec, ...cliArgs] });
+    return;
+  }
+
+  const corepackPath = resolveExecutable({ command: "corepack", env: context.env });
+  if (corepackPath) {
+    console.warn("» npx not found, using corepack pnpm dlx");
+    runCommand({ context, command: corepackPath, args: ["pnpm", "dlx", packageSpec, ...cliArgs] });
+    return;
+  }
+
+  throw new Error(
+    `could not find npx or corepack on PATH to run ${packageSpec}; ` +
+      `runtime PATH was: ${context.env.PATH ?? "<empty>"}`,
+  );
+}
+
+function ensureActionDependencies(context: RuntimeContext): void {
+  const nodeModulesPath = join(context.actionRoot, "node_modules");
+  if (existsSync(nodeModulesPath)) {
+    return;
+  }
+
+  const corepackPath = requireExecutable({
+    context,
+    command: "corepack",
+    purpose: "install action dependencies via pnpm",
+  });
+  const adjacentCorepack = join(
+    context.nodeBinDir,
+    process.platform === "win32" ? "corepack.cmd" : "corepack",
+  );
+  if (corepackPath !== adjacentCorepack) {
+    // bad-runner case: GitHub's externals/node24/bin/ is missing the corepack
+    // sibling, so we resolved via PATH instead. logging this lets us correlate
+    // bootstrap path to runner pool when validating the fix.
+    console.warn(
+      `» nodeBinDir corepack missing (${adjacentCorepack}); using PATH-resolved ${corepackPath}`,
+    );
+  }
+  execFileSync(corepackPath, ["pnpm", "install", "--frozen-lockfile", "--ignore-scripts"], {
+    cwd: context.actionRoot,
+    stdio: "inherit",
+    env: context.env,
+  });
+}
+
+function runLocalCli(context: RuntimeContext, cliArgs: string[]): void {
+  ensureActionDependencies(context);
+  execFileSync(process.execPath, ["cli.ts", ...cliArgs], {
+    cwd: context.actionRoot,
+    stdio: "inherit",
+    env: context.env,
+  });
+}
+
+function runTerramendCliInner(context: RuntimeContext, cliArgs: string[]): void {
+  if (process.env.TERRAMEND_FORCE_LOCAL_CLI === "1") {
+    runLocalCli(context, cliArgs);
+    return;
+  }
+
+  if (context.actionRef === "main" && context.actionRepository === "terramend/terramend") {
+    runLocalCli(context, cliArgs);
+    return;
+  }
+
+  runPackageCli(context, FALLBACK_PACKAGE_SPEC, cliArgs);
+}
+
+// the inner CLI and the bootstrap install run with `stdio: "inherit"`, so on a
+// non-zero exit they've already printed their own `##[error]` line. node turns
+// that exit into a thrown `Error: Command failed…`; letting it bubble crashes
+// the outer bootstrap with a `node:internal/errors` stack trace that buries the
+// real failure (#862, #867). propagate the child's exit code silently instead;
+// only genuine spawn failures (ENOENT, missing npx, …) still surface.
+function propagateChildExit(error: unknown): never {
+  if (error instanceof Error && "status" in error && typeof error.status === "number") {
+    process.exit(error.status);
+  }
+  if (error instanceof Error && "signal" in error && error.signal != null) {
+    process.exit(1);
+  }
+  throw error;
+}
+
+export function runTerramendCli(params: RunTerramendCliParams): void {
+  const context = createRuntimeContext();
+
+  if (params.swallowErrors) {
+    try {
+      runTerramendCliInner(context, params.cliArgs);
+    } catch (error) {
+      console.warn(`» terramend cleanup bootstrap failed: ${getErrorMessage(error)}`);
+      // best-effort cleanup
+    }
+    return;
+  }
+
+  try {
+    runTerramendCliInner(context, params.cliArgs);
+  } catch (error) {
+    propagateChildExit(error);
+  }
+}