@intentius/chant 0.57.0 → 0.59.0

package/src/op/activities/lifecycle.ts

@@ -0,0 +1,85 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+export interface LifecycleSnapshotArgs {
+  /** Environment name (e.g. "dev", "staging", "prod"). */
+  env: string;
+}
+
+/**
+ * Take a chant lifecycle snapshot for the given environment.
+ * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ */
+export async function lifecycleSnapshot(args: LifecycleSnapshotArgs, signal?: AbortSignal): Promise<void> {
+  const { stdout, stderr } = await execAsync(`chant lifecycle snapshot ${args.env}`, { signal });
+  if (stdout) console.log(stdout);
+  if (stderr) console.error(stderr);
+}
+
+export interface LifecycleDiffArgs {
+  /** Environment name (e.g. "dev", "staging", "prod"). */
+  env: string;
+  /**
+   * When true, run `chant lifecycle diff <env> --live` (queries cloud APIs).
+   * When false (default), run digest-only diff against the last snapshot.
+   */
+  live?: boolean;
+}
+
+export interface LifecycleDiffResult {
+  /** Combined stdout + stderr from the chant command. */
+  output: string;
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /**
+   * True when the diff output contains any drift indicators
+   * (MISSING / ORPHAN / DRIFTED / DISAPPEARED section headers from
+   * `chant lifecycle diff --live`).
+   */
+  drifted: boolean;
+}
+
+/**
+ * Section headers emitted by `chant lifecycle diff --live` that indicate a
+ * non-empty drift category. See packages/core/src/cli/handlers/state.ts.
+ */
+const DRIFT_HEADERS = [
+  "MISSING",
+  "ORPHAN",
+  "DISAPPEARED",
+  "DRIFTED",
+  "ARTIFACTS ADDED",
+  "ARTIFACTS REMOVED",
+  "ARTIFACTS CHANGED",
+];
+
+function detectDrift(output: string): boolean {
+  return DRIFT_HEADERS.some((h) => output.includes(`${h} (`) || output.includes(`\n${h}`));
+}
+
+/**
+ * Run `chant lifecycle diff <env>` and return the output + structured drift
+ * flag. Read-only; intended for use inside watch/observation Ops.
+ * Uses fastIdempotent profile.
+ *
+ * The `drifted` field is computed by scanning the output for any of the
+ * MISSING / ORPHAN / DRIFTED / DISAPPEARED section headers documented in
+ * cli/state.mdx. Pair with `outcomeAttribute: { name: "Drift", from: "drifted" }`
+ * on a WatchOp activity step to surface drift as the run's `Drift` outcome.
+ */
+export async function lifecycleDiff(args: LifecycleDiffArgs, signal?: AbortSignal): Promise<LifecycleDiffResult> {
+  const liveFlag = args.live ? " --live" : "";
+  try {
+    const { stdout, stderr } = await execAsync(`chant lifecycle diff ${args.env}${liveFlag}`, { signal });
+    const output = `${stdout}${stderr}`.trim();
+    if (output) console.log(output);
+    return { output, exitCode: 0, drifted: detectDrift(output) };
+  } catch (err) {
+    const e = err as { code?: number; stdout?: string; stderr?: string };
+    const output = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
+    if (output) console.error(output);
+    return { output, exitCode: e.code ?? 1, drifted: detectDrift(output) };
+  }
+}

package/src/op/activities/pipeline-audit.test.ts

@@ -0,0 +1,67 @@
+import { describe, test, expect } from "vitest";
+import {
+  pipelineSupplyChainAudit,
+  collectPipelineRefs,
+  type PipelineRefResolution,
+  type GitlabRefResolver,
+} from "./pipeline-audit";
+
+const PIPELINE = `include:
+  - project: my-group/ci-templates
+    ref: v1.2.3
+    file: /build.yml
+  - component: gitlab.example.com/my-group/my-comp@1.0.0
+
+build:
+  image:
+    name: node:20
+  script:
+    - npm ci
+`;
+
+function recordedResolver(records: Record<string, PipelineRefResolution>): GitlabRefResolver {
+  return async (kind, identifier, ref) =>
+    records[`${kind}:${identifier}@${ref}`] ?? { exists: true, archived: false, advisories: [] };
+}
+
+describe("collectPipelineRefs (#303)", () => {
+  test("collects include:project, component, and image refs", () => {
+    const refs = collectPipelineRefs(PIPELINE);
+    const ids = refs.map((r) => `${r.refKind}:${r.identifier}`);
+    expect(ids).toContain("include:my-group/ci-templates");
+    expect(ids).toContain("component:gitlab.example.com/my-group/my-comp");
+    expect(ids).toContain("image:node:20");
+    expect(refs.find((r) => r.refKind === "include")?.ref).toBe("v1.2.3");
+    expect(refs.find((r) => r.refKind === "component")?.ref).toBe("1.0.0");
+  });
+
+  test("skips variable-based images", () => {
+    const refs = collectPipelineRefs(`build:\n  image:\n    name: $CI_REGISTRY_IMAGE:latest\n`);
+    expect(refs.filter((r) => r.refKind === "image")).toHaveLength(0);
+  });
+});
+
+describe("pipelineSupplyChainAudit (#303)", () => {
+  test("flags unresolved, archived, and moved references", async () => {
+    const resolver = recordedResolver({
+      "include:my-group/ci-templates@v1.2.3": { exists: true, archived: true, advisories: [] },
+      "component:gitlab.example.com/my-group/my-comp@1.0.0": { exists: false, archived: false, advisories: [] },
+      "image:node:20@20": { exists: true, archived: false, advisories: ["GHSA-img"], movedTo: undefined },
+    });
+    const result = await pipelineSupplyChainAudit({ yaml: PIPELINE, resolver, mode: "merge-request" });
+    const kinds = result.findings.map((f) => `${f.identifier}:${f.kind}`);
+
+    expect(kinds).toContain("my-group/ci-templates:archived");
+    expect(kinds).toContain("gitlab.example.com/my-group/my-comp:unresolved");
+    expect(kinds).toContain("node:20:advisory");
+    expect(result.mode).toBe("merge-request");
+    expect(result.summary).toContain("Pipeline include/component audit");
+  });
+
+  test("clean pipeline yields no findings", async () => {
+    const resolver = recordedResolver({});
+    const result = await pipelineSupplyChainAudit({ yaml: PIPELINE, resolver });
+    expect(result.findings).toHaveLength(0);
+    expect(result.summary).toContain("No live drift");
+  });
+});

package/src/op/activities/pipeline-audit.ts

@@ -0,0 +1,201 @@
+/**
+ * pipelineSupplyChainAudit — the live counterpart to the gitlab post-synth
+ * include/component/image checks (#297).
+ *
+ * Some include/component checks can only be answered against a moving external
+ * truth: whether a pinned component/include ref still resolves upstream, whether
+ * the upstream project was archived or moved, or whether a new advisory now
+ * covers a component/image already in use. These change independent of the
+ * source, so they cannot live in the deterministic build — this activity owns
+ * *only* the checks that require live resolution.
+ *
+ * Dependency-free and primitives-only: it reads the emitted `.gitlab-ci.yml`
+ * (passed as a string) and resolves references through an injectable
+ * `GitlabRefResolver`, so `chant run` can schedule it and tests can run
+ * it against recorded responses with no live network.
+ */
+
+/** What the audit produces on findings. For GitLab the PR mode is a merge request. */
+export type PipelineAuditMode = "report" | "issue" | "merge-request";
+
+/** The kind of reference being resolved. */
+export type PipelineRefKind = "include" | "component" | "image";
+
+/** Live resolution of a single pipeline reference against its upstream. */
+export interface PipelineRefResolution {
+  /** Does the project/component/image (at this ref/version) still resolve? */
+  exists: boolean;
+  /** Has the upstream project been archived? */
+  archived: boolean;
+  /** Has the upstream project moved (new path), if known. */
+  movedTo?: string;
+  /** Disclosed advisory identifiers affecting this reference. */
+  advisories: string[];
+}
+
+/** Pluggable upstream resolver — overridden in tests with recorded responses. */
+export type GitlabRefResolver = (kind: PipelineRefKind, identifier: string, ref: string) => Promise<PipelineRefResolution>;
+
+export type PipelineAuditFindingKind = "unresolved" | "archived" | "moved" | "advisory";
+
+export interface PipelineAuditFinding {
+  kind: PipelineAuditFindingKind;
+  refKind: PipelineRefKind;
+  /** project path / component address / image. */
+  identifier: string;
+  /** ref / version / tag. */
+  ref: string;
+  detail: string;
+}
+
+export interface PipelineAuditArgs {
+  /** One emitted `.gitlab-ci.yml` document. */
+  yaml?: string;
+  /** Several emitted documents. */
+  yamls?: string[];
+  /** Path to an emitted `.gitlab-ci.yml` to read at run time (default `.gitlab-ci.yml`). */
+  pipelineFile?: string;
+  /** What to produce. Default: report. */
+  mode?: PipelineAuditMode;
+  /** Injectable upstream resolver. Defaults to the live GitLab REST resolver. */
+  resolver?: GitlabRefResolver;
+}
+
+export interface PipelineAuditResult {
+  mode: PipelineAuditMode;
+  findings: PipelineAuditFinding[];
+  summary: string;
+}
+
+interface CollectedRef {
+  refKind: PipelineRefKind;
+  identifier: string;
+  ref: string;
+}
+
+/**
+ * Collect `include:project` (+ ref), `component:` (with @version), and `image:`
+ * references from a `.gitlab-ci.yml`.
+ */
+export function collectPipelineRefs(yaml: string): CollectedRef[] {
+  const out: CollectedRef[] = [];
+
+  // include:\n  - project: group/proj\n    ref: main
+  const projectRe = /-\s+project:\s*['"]?([^\s'"]+)['"]?[\s\S]*?ref:\s*['"]?([^\s'"]+)['"]?/g;
+  let m: RegExpExecArray | null;
+  while ((m = projectRe.exec(yaml)) !== null) {
+    out.push({ refKind: "include", identifier: m[1], ref: m[2] });
+  }
+
+  // - component: host/group/comp@1.0.0
+  const componentRe = /-\s+component:\s*['"]?([^\s'"@]+)@([^\s'"]+)['"]?/g;
+  while ((m = componentRe.exec(yaml)) !== null) {
+    out.push({ refKind: "component", identifier: m[1], ref: m[2] });
+  }
+
+  // Images: inline `image: name` or block `image:\n  name: ...` (and services).
+  const lines = yaml.split("\n");
+  const imgSeen = new Set<string>();
+  const addImage = (raw: string) => {
+    const image = raw.trim().replace(/^['"]|['"]$/g, "");
+    if (!image || image.includes("$") || imgSeen.has(image)) return;
+    imgSeen.add(image);
+    const at = image.lastIndexOf("@");
+    const colon = image.lastIndexOf(":");
+    const ref = at !== -1 ? image.slice(at + 1) : colon > image.lastIndexOf("/") ? image.slice(colon + 1) : "latest";
+    out.push({ refKind: "image", identifier: image, ref });
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const inline = lines[i].match(/^\s+image:[ \t]+(\S.*)$/);
+    if (inline) { addImage(inline[1]); continue; }
+    if (/^\s+image:\s*$/.test(lines[i]) || /^\s+-\s+name:[ \t]+(\S.*)$/.test(lines[i])) {
+      const svcName = lines[i].match(/^\s+-\s+name:[ \t]+(\S.*)$/);
+      if (svcName) { addImage(svcName[1]); continue; }
+      const nameLine = lines.slice(i + 1, i + 4).find((l) => /^\s+name:[ \t]+/.test(l));
+      if (nameLine) addImage(nameLine.replace(/^\s+name:[ \t]+/, ""));
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Default resolver: query the GitLab REST API for project existence / archive /
+ * move status. Best-effort and resilient — errors yield an "unknown" resolution
+ * (exists=true, no findings) rather than a false positive. Component/image
+ * advisory lookups are left to a configured resolver.
+ */
+export const defaultGitlabRefResolver: GitlabRefResolver = async (kind, identifier) => {
+  const unknown: PipelineRefResolution = { exists: true, archived: false, advisories: [] };
+  if (kind === "image") return unknown; // image advisory feeds are resolver-specific
+  const host = "https://gitlab.com";
+  const project = kind === "component" ? identifier.split("/").slice(1, 3).join("/") : identifier;
+  try {
+    const resp = await fetch(`${host}/api/v4/projects/${encodeURIComponent(project)}`, {
+      headers: process.env.GITLAB_TOKEN ? { "PRIVATE-TOKEN": process.env.GITLAB_TOKEN } : {},
+    });
+    if (resp.status === 404) return { exists: false, archived: false, advisories: [] };
+    if (!resp.ok) return unknown;
+    const p = (await resp.json()) as { archived?: boolean };
+    return { exists: true, archived: !!p.archived, advisories: [] };
+  } catch {
+    return unknown;
+  }
+};
+
+function renderSummary(findings: PipelineAuditFinding[]): string {
+  if (findings.length === 0) return "## Pipeline include/component audit\n\nNo live drift detected against upstream references.\n";
+  let out = `## Pipeline include/component audit\n\n${findings.length} finding(s) against live upstream truth:\n\n`;
+  out += "| Reference | Ref | Finding | Detail |\n|---|---|---|---|\n";
+  for (const f of findings) out += `| ${f.identifier} (${f.refKind}) | ${f.ref} | ${f.kind} | ${f.detail} |\n`;
+  return out;
+}
+
+async function readFileBestEffort(path: string): Promise<string[]> {
+  try {
+    const { readFile } = await import("node:fs/promises");
+    return [await readFile(path, "utf-8")];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve each include/component/image reference in the emitted pipeline against
+ * live upstreams and report drift.
+ */
+export async function pipelineSupplyChainAudit(args: PipelineAuditArgs): Promise<PipelineAuditResult> {
+  const resolver = args.resolver ?? defaultGitlabRefResolver;
+  const mode = args.mode ?? "report";
+  let yamls = args.yamls ?? (args.yaml ? [args.yaml] : []);
+  if (yamls.length === 0) {
+    yamls = await readFileBestEffort(args.pipelineFile ?? ".gitlab-ci.yml");
+  }
+
+  const findings: PipelineAuditFinding[] = [];
+  const seen = new Set<string>();
+  for (const yaml of yamls) {
+    for (const { refKind, identifier, ref } of collectPipelineRefs(yaml)) {
+      const key = `${refKind}:${identifier}@${ref}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const res = await resolver(refKind, identifier, ref);
+      if (!res.exists) {
+        findings.push({ kind: "unresolved", refKind, identifier, ref, detail: `${refKind} "${identifier}@${ref}" no longer resolves upstream` });
+        continue;
+      }
+      if (res.archived) {
+        findings.push({ kind: "archived", refKind, identifier, ref, detail: `${identifier} has been archived upstream` });
+      }
+      if (res.movedTo) {
+        findings.push({ kind: "moved", refKind, identifier, ref, detail: `${identifier} moved to ${res.movedTo}` });
+      }
+      for (const adv of res.advisories) {
+        findings.push({ kind: "advisory", refKind, identifier, ref, detail: `disclosed advisory ${adv} covers ${identifier}` });
+      }
+    }
+  }
+
+  return { mode, findings, summary: renderSummary(findings) };
+}

package/src/op/activities/policy.test.ts

@@ -0,0 +1,19 @@
+import { describe, test, expect } from "vitest";
+import { resolve } from "node:path";
+import { policyGate } from "./policy";
+
+// The #201 org-policy example: a compliant workload + a policy pack
+// (ORG-COST-CENTER all-envs, ORG-PROD-TLS prod-only). policyGate builds it and
+// runs the policies — passing in dev, blocking in prod.
+const orgPolicySrc = resolve(import.meta.dirname, "../../../../../lexicons/k8s/examples/org-policy/src");
+
+describe("policyGate activity (#201 T4 — gate an apply on policy)", () => {
+  test("passes when policy is satisfied (no env, and dev)", async () => {
+    await expect(policyGate({ path: orgPolicySrc })).resolves.toBeUndefined();
+    await expect(policyGate({ path: orgPolicySrc, env: "dev" })).resolves.toBeUndefined();
+  }, 30_000);
+
+  test("blocks the apply on a prod policy violation", async () => {
+    await expect(policyGate({ path: orgPolicySrc, env: "prod" })).rejects.toThrow(/ORG-PROD-TLS/);
+  }, 30_000);
+});

package/src/op/activities/policy.ts

@@ -0,0 +1,37 @@
+import { nonRetryableFailure } from "../activity-failure";
+import { evaluateProjectPolicies } from "../../lint/policy";
+
+export interface PolicyGateArgs {
+  /** Project/source directory to build and evaluate. Default ".". */
+  path?: string;
+  /** Environment for policy evaluation (falls back to `ownership.env`). */
+  env?: string;
+}
+
+/**
+ * Gate an apply on organizational policy: build the project, run its
+ * `lint.policies` over the resolved resources, and **block** on any violation.
+ * Place it as a step before the apply phase — a violation fails the run
+ * (non-retryable; the `policyCheck` profile is single-attempt) so nothing is
+ * applied. A clean evaluation passes through.
+ *
+ * A plain activity on every runtime, not a `gate` step.
+ */
+export async function policyGate(args: PolicyGateArgs, _signal?: AbortSignal): Promise<void> {
+  const { violations, suppressed, env } = await evaluateProjectPolicies({ path: args.path ?? ".", env: args.env });
+  if (violations.length > 0) {
+    const summary = violations
+      .map((v) => `[${v.checkId}]${v.entity ? ` ${v.entity}:` : ""} ${v.message}`)
+      .join("; ");
+    throw nonRetryableFailure(
+      `Organizational policy blocked the apply — ${violations.length} violation(s): ${summary}`,
+      "PolicyViolation",
+    );
+  }
+  // chant #1138 — a check `lint.rules` turned "off" is counted here rather
+  // than vanishing silently, mirroring `chant build`'s own suppressed-count line.
+  if (suppressed.length > 0) {
+    console.log(`[policy] ${suppressed.length} finding(s) suppressed via lint.rules`);
+  }
+  console.log(`[policy] ${env ? `env=${env}: ` : ""}no violations — apply may proceed`);
+}

package/src/op/activities/reconcile.test.ts

@@ -0,0 +1,161 @@
+import { describe, test, expect, vi } from "vitest";
+import {
+  reconcilePr,
+  reconcileSummary,
+  reconcileBranchName,
+  entriesFromPlan,
+  commentMarker,
+  pullRequestContextFrom,
+} from "./reconcile";
+
+const entries = [
+  { name: "bucket", action: "adopt", type: "AWS::S3::Bucket" },
+  { name: "queue", action: "update", type: "AWS::SQS::Queue" },
+];
+
+describe("reconcileBranchName (#122)", () => {
+  test("deterministic, slugified per env", () => {
+    expect(reconcileBranchName("prod")).toBe("chant/reconcile-prod");
+    expect(reconcileBranchName("us-east/1")).toBe("chant/reconcile-us-east-1");
+  });
+});
+
+describe("reconcileSummary (#122)", () => {
+  test("summarizes which entries triggered the reconcile", () => {
+    const body = reconcileSummary("prod", entries);
+    expect(body).toContain("live environment `prod`");
+    expect(body).toContain("| bucket | adopt | AWS::S3::Bucket |");
+    expect(body).toContain("| queue | update | AWS::SQS::Queue |");
+  });
+
+  test("handles an empty entry set", () => {
+    expect(reconcileSummary("prod", [])).toContain("_(none)_");
+  });
+});
+
+describe("entriesFromPlan (#123)", () => {
+  test("maps a ChangeSet, dropping noop entries", () => {
+    const plan = JSON.stringify({
+      env: "prod",
+      entries: [
+        { name: "a", action: "create", type: "T1", evidence: {}, ownership: "unknown" },
+        { name: "b", action: "noop", type: "T2", evidence: {}, ownership: "unknown" },
+        { name: "c", action: "delete", type: "T3", evidence: {}, ownership: "owned" },
+      ],
+    });
+    expect(entriesFromPlan(plan)).toEqual([
+      { name: "a", action: "create", type: "T1" },
+      { name: "c", action: "delete", type: "T3" },
+    ]);
+  });
+
+  test("tolerates an empty / entry-less plan", () => {
+    expect(entriesFromPlan(JSON.stringify({ env: "prod" }))).toEqual([]);
+  });
+});
+
+describe("reconcilePr report mode (#122)", () => {
+  test("returns the summary without any git/network IO", async () => {
+    const result = await reconcilePr({ env: "prod", entries, mode: "report" });
+    expect(result.mode).toBe("report");
+    expect(result.prUrl).toBeUndefined();
+    expect(result.branch).toBeUndefined();
+    expect(result.summary).toContain("| bucket | adopt | AWS::S3::Bucket |");
+    expect(result.entries).toEqual(entries);
+  });
+});
+
+describe("reconcilePr pre-built body (#2087)", () => {
+  test("a caller-supplied body is used verbatim, in place of the change-set table", async () => {
+    const plan = "Terraform will perform the following actions:\n\n  # null_resource.first will be created";
+    const result = await reconcilePr({ env: "app", mode: "report", body: plan });
+    expect(result.summary).toBe(plan);
+    expect(result.summary).not.toContain("| Entry | Action | Type |");
+  });
+
+  test("supplying a body derives no plan, so nothing shells to `chant lifecycle plan`", async () => {
+    // No `entries`, no mock, no network: if the derivation still ran this
+    // would spawn `chant lifecycle plan --json` and reject.
+    const result = await reconcilePr({ env: "app", mode: "report", body: "drift" });
+    expect(result.entries).toEqual([]);
+  });
+
+  test("explicit entries still ride alongside a supplied body", async () => {
+    const result = await reconcilePr({ env: "prod", mode: "report", entries, body: "drift" });
+    expect(result.summary).toBe("drift");
+    expect(result.entries).toEqual(entries);
+  });
+});
+
+describe("reconcilePr comment mode: the marker (#2231)", () => {
+  test("the marker is deterministic per env, so a re-run finds its own comment", () => {
+    expect(commentMarker("app")).toBe("<!-- chant-reconcile:app -->");
+    expect(commentMarker("app")).toBe(commentMarker("app"));
+    expect(commentMarker("app")).not.toBe(commentMarker("db"));
+  });
+
+  test("the marker slugifies the env, so nothing it is interpolated next to can be escaped out of", () => {
+    // The marker is interpolated into a jq `startswith("…")` string and into a
+    // shell word. A quote or a backslash surviving into it would break both.
+    const marker = commentMarker('us-east/1" or true; #');
+    expect(marker).toBe("<!-- chant-reconcile:us-east-1-or-true- -->");
+    expect(marker).not.toMatch(/["'\\]/);
+  });
+});
+
+describe("pullRequestContextFrom (#2231)", () => {
+  const repo = "INTENTIUS/chant";
+
+  test("reads the number off a pull_request event payload", () => {
+    expect(pullRequestContextFrom({ GITHUB_REPOSITORY: repo }, { number: 2231 })).toEqual({
+      repo,
+      number: 2231,
+    });
+  });
+
+  test("accepts the nested pull_request.number the same payload also carries", () => {
+    expect(
+      pullRequestContextFrom({ GITHUB_REPOSITORY: repo }, { pull_request: { number: 7 } }),
+    ).toEqual({ repo, number: 7 });
+  });
+
+  test("falls back to GITHUB_REF when the payload is unreadable", () => {
+    expect(
+      pullRequestContextFrom({ GITHUB_REPOSITORY: repo, GITHUB_REF: "refs/pull/42/merge" }),
+    ).toEqual({ repo, number: 42 });
+  });
+
+  test("a push run has no pull request", () => {
+    expect(
+      pullRequestContextFrom(
+        { GITHUB_REPOSITORY: repo, GITHUB_REF: "refs/heads/main" },
+        { ref: "refs/heads/main", after: "abc" },
+      ),
+    ).toBeUndefined();
+  });
+
+  test("a cron run off any forge has neither variable", () => {
+    expect(pullRequestContextFrom({})).toBeUndefined();
+    expect(pullRequestContextFrom({ GITHUB_REF: "refs/pull/1/merge" })).toBeUndefined();
+  });
+});
+
+describe("reconcilePr comment mode refuses a run with no pull request (#2231)", () => {
+  test("the message names the mode and every variable it looked for", async () => {
+    vi.stubEnv("GITHUB_REPOSITORY", "");
+    vi.stubEnv("GITHUB_REF", "");
+    vi.stubEnv("GITHUB_EVENT_PATH", "");
+    try {
+      // No `gh` is ever reached: the context check runs first, so a failure
+      // here is the refusal rather than a missing binary.
+      await expect(reconcilePr({ env: "app", mode: "comment", body: "plan" })).rejects.toThrow(
+        /mode "comment".*GITHUB_REPOSITORY.*GITHUB_EVENT_PATH.*GITHUB_REF/s,
+      );
+      await expect(reconcilePr({ env: "app", mode: "comment", body: "plan" })).rejects.toThrow(
+        /findingMode "issue" or "report"/,
+      );
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+});