jules-orchestrator-kit 0.52.8 → 0.53.0

package/src/ops/next-step.mjs

@@ -1,7 +1,32 @@
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { isTaskFile } from "../engine.mjs";
+import { probeProvider } from "../provider-readiness.mjs";
+
+/**
+ * The provider named in `.agent/config.yml`, without paying for a full
+ * `loadConfig()` (which detects the stack and shells out to git).
+ *
+ * A bare `agentctl` invocation has to stay instant, and the only field this
+ * advisor needs is one line of YAML.
+ *
+ * @param {string} root
+ * @returns {string}
+ */
+function readConfiguredProvider(root) {
+  for (const name of ["config.yml", "jules.yml"]) {
+    const file = join(root, ".agent", name);
+    if (!existsSync(file)) continue;
+    try {
+      const match = readFileSync(file, "utf-8").match(/^provider:\s*["']?([\w.-]+)["']?\s*$/m);
+      if (match) return match[1];
+    } catch (_) {
+      // An unreadable config is already reported by the `init` branch above.
+    }
+  }
+  return "jules";
+}
 
 /**
  * Work out the one thing the operator should do next.
@@ -52,13 +77,19 @@ export function resolveNextStep(root, env = process.env) {
     };
   }
 
-  if (!env.JULES_API_KEY && !env.GEMINI_API_KEY) {
+  // Which credential (or binary) is missing depends entirely on the provider
+  // the repository selected. Asking for JULES_API_KEY in a repository driving
+  // `claude-code` told the operator to fix something that was never broken.
+  const providerName = readConfiguredProvider(root);
+  const probe = probeProvider(providerName, { env });
+  if (!probe.ready) {
     return {
-      id: "key",
-      headline: "No provider API key in the environment",
-      detail:
-        "The key is read from the environment only — never written to config and never sent anywhere but the provider. Until it is set you can still run `agentctl gate` and `--dry-run` dispatches locally.",
-      command: "export JULES_API_KEY=...",
+      id: "provider",
+      headline: probe.known
+        ? `Provider '${probe.name}' is not usable yet`
+        : `Provider '${probe.name}' is not a built-in preset`,
+      detail: `${probe.reason} Until it is resolved you can still run \`agentctl gate\` and \`--dry-run\` dispatches locally — every verification gate works with no provider at all.`,
+      command: probe.remedy,
       blocking: false,
     };
   }

package/src/profiles-io.mjs

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { PROFILE_NAMES } from "./profiles.mjs";
+
+/**
+ * Set `verify.profile` in the repository's manifest, in place.
+ *
+ * A surgical text edit rather than a parse-and-reserialise: the kit's YAML
+ * reader is a subset parser, so round-tripping the file through it would drop
+ * every comment the wizard wrote and any key the subset does not model. The
+ * manifest is a file a human maintains; a tool that rewrites it must leave the
+ * rest of it alone.
+ *
+ * @param {string} root
+ * @param {string} profile - one of {@link PROFILE_NAMES}
+ * @returns {{ ok: boolean, file?: string, error?: string }}
+ */
+export function setVerificationProfile(root, profile) {
+  const name = String(profile || "").toLowerCase();
+  if (!PROFILE_NAMES.includes(name)) {
+    return { ok: false, error: `Unknown profile '${profile}'. Choose one of: ${PROFILE_NAMES.join(", ")}` };
+  }
+
+  const candidates = [join(root, ".agent", "config.yml"), join(root, ".agent", "jules.yml")];
+  const file = candidates.find((f) => existsSync(f));
+  if (!file) {
+    return { ok: false, error: "No .agent/config.yml found. Run `agentctl init` first." };
+  }
+
+  let text;
+  try {
+    text = readFileSync(file, "utf-8");
+  } catch (err) {
+    return { ok: false, error: `Could not read ${file}: ${err.message}` };
+  }
+
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = text.split(/\r?\n/);
+
+  // Find the `verify:` mapping and the `profile:` key nested directly under it.
+  let verifyIdx = -1;
+  let profileIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^verify:\s*$/.test(lines[i])) {
+      verifyIdx = i;
+      for (let j = i + 1; j < lines.length; j++) {
+        // A non-indented, non-blank line ends the block.
+        if (lines[j].trim() !== "" && !/^\s/.test(lines[j])) break;
+        if (/^\s+profile:\s*/.test(lines[j])) {
+          profileIdx = j;
+          break;
+        }
+      }
+      break;
+    }
+  }
+
+  if (profileIdx >= 0) {
+    const indent = lines[profileIdx].match(/^(\s*)/)[1];
+    lines[profileIdx] = `${indent}profile: ${name}`;
+  } else if (verifyIdx >= 0) {
+    lines.splice(verifyIdx + 1, 0, `  profile: ${name}`);
+  } else {
+    if (lines.length && lines[lines.length - 1] !== "") lines.push("");
+    lines.push("verify:", `  profile: ${name}`, "");
+  }
+
+  const tmp = `${file}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, lines.join(eol), "utf-8");
+    renameSync(tmp, file);
+  } catch (err) {
+    return { ok: false, error: `Could not write ${file}: ${err.message}` };
+  }
+
+  return { ok: true, file };
+}

package/src/profiles.mjs

@@ -0,0 +1,188 @@
+/**
+ * Verification profiles: one word in `.agent/config.yml` that turns the kit's
+ * verification primitives on as a coherent set.
+ *
+ * The kit ships mutation testing, V8 diff coverage, flakiness probing and
+ * anti-tamper detection, and every one of them was reachable only by knowing
+ * the command exists and typing it by hand. A repository that scaffolded a
+ * default config got exactly one gate — `npm test` — and none of the rest, so
+ * the capability shipped and then sat idle. A profile is the shortest sentence
+ * that says how hard this repository wants its agents verified.
+ *
+ * Profiles are expanded at load time (see `loadConfig`), not frozen into the
+ * scaffolded YAML, so the stage list stays correct when the stack changes and
+ * improves when the kit does.
+ */
+
+/** Ordered weakest to strictest; `standard` is the default for a fresh repo. */
+export const PROFILE_NAMES = ["minimal", "standard", "max"];
+
+export const PROFILE_DESCRIPTIONS = {
+  minimal: "Tests only. For a slow suite, an unfamiliar stack, or a first day with the kit.",
+  standard: "Lint, tests, build, plus anti-tamper on the diff. The everyday gate.",
+  max: "Everything mechanical: adds mutation scoring, diff coverage, and flakiness probing.",
+};
+
+/**
+ * Stacks whose test command runs on Node and therefore honours
+ * `NODE_V8_COVERAGE`, which is how `assert:diff-coverage` collects data.
+ *
+ * Bun and Deno are deliberately absent: they run JavaScript but do not emit V8
+ * coverage into that directory, so the assertion would find no coverage maps
+ * and fail every diff for a reason that has nothing to do with the diff.
+ */
+const V8_COVERAGE_STACKS = new Set(["node", "turbo", "pnpm", "nx", "react-native", "hardhat"]);
+
+/**
+ * Build the full verification pipeline for a profile.
+ *
+ * Returns the *complete* stage list, not an addendum: `gate()` replaces its
+ * built-in pipeline wholesale when `verify.stages` is present, so a profile
+ * that emitted only its extra assertions would silently drop the tests.
+ *
+ * @param {string} profile - one of {@link PROFILE_NAMES}
+ * @param {object} ctx
+ * @param {string} [ctx.stack] - detected stack id (see `detectPolyglotStack`)
+ * @param {{setup?: string, lint?: string, test?: string, unit?: string, e2e?: string, build?: string, policy?: object}} [ctx.verify]
+ * @returns {{ profile: string, stages: object[], skipped: Array<{id: string, reason: string}> }}
+ */
+export function buildProfileStages(profile, ctx = {}) {
+  const name = PROFILE_NAMES.includes(String(profile || "").toLowerCase())
+    ? String(profile).toLowerCase()
+    : "standard";
+  const verify = ctx.verify || {};
+  const stack = ctx.stack || "unknown";
+  const network = verify.policy?.networkAccess || "allow";
+  const testCmd = verify.test || verify.unit || "";
+
+  const stages = [];
+  const skipped = [];
+
+  // Dependency install always runs first when the stack declares one; without
+  // it every later stage fails on a missing toolchain rather than on the code.
+  if (verify.setup) {
+    stages.push({ id: "setup", kind: "setup", cmd: verify.setup, required: true, networkAccess: "allow" });
+  }
+
+  if (name !== "minimal" && verify.lint) {
+    stages.push({ id: "lint", kind: "lint", cmd: verify.lint, required: true, networkAccess: network });
+  }
+
+  if (testCmd) {
+    stages.push({ id: "unit", kind: "test", cmd: testCmd, required: true, networkAccess: network });
+  } else {
+    skipped.push({
+      id: "unit",
+      reason: "No test command is configured or detectable — set verify.test in .agent/config.yml.",
+    });
+  }
+
+  if (name !== "minimal" && verify.e2e) {
+    stages.push({ id: "e2e", kind: "e2e", cmd: verify.e2e, required: true, networkAccess: "allow" });
+  }
+
+  if (name !== "minimal" && verify.build) {
+    stages.push({ id: "build", kind: "build", cmd: verify.build, required: true, networkAccess: network });
+  }
+
+  // Anti-tamper is diff-based and language-agnostic: it costs nothing to run
+  // and it is the one check an agent under pressure to go green will trip.
+  if (name !== "minimal") {
+    stages.push({ id: "anti-tamper", kind: "assert", assert: "test-integrity", required: true });
+  }
+
+  if (name === "max") {
+    // Mutation operators are C-family (`===`, `&&`, `++`, `true`), so the score
+    // is strongest on JS/TS, Go, Rust, Java, C#, PHP, Swift and Dart, and
+    // weaker on Python/Ruby where the keywords differ. It is still safe
+    // everywhere: it only ever mutates lines the diff added, and a diff with no
+    // mutable operators scores 100 and passes.
+    stages.push({
+      id: "mutation",
+      kind: "assert",
+      assert: "mutation",
+      minScore: 60,
+      maxMutants: 20,
+      testCmd,
+      required: true,
+    });
+
+    if (V8_COVERAGE_STACKS.has(stack)) {
+      stages.push({
+        id: "diff-coverage",
+        kind: "assert",
+        assert: "diff-coverage",
+        minCoverage: 80,
+        testCmd,
+        required: true,
+      });
+    } else {
+      skipped.push({
+        id: "diff-coverage",
+        reason: `Diff coverage reads NODE_V8_COVERAGE, which stack '${stack}' does not produce.`,
+      });
+    }
+
+    // Three passes is the cheapest count that can distinguish "passed" from
+    // "passed this time": a single alternation is enough to quarantine.
+    stages.push({
+      id: "stability",
+      kind: "assert",
+      assert: "test-stability",
+      repeat: 3,
+      minPassRate: 1.0,
+      cmd: testCmd,
+      required: true,
+    });
+
+    // `assert:event-loop-lag` is deliberately not here. It measures the
+    // orchestrator's own loop while it blocks on a synchronous child process,
+    // so against a spawned test command it reports the blocking duration rather
+    // than the application's latency. It stays available as an explicit stage
+    // for repositories that know what they are measuring.
+    skipped.push({
+      id: "event-loop-lag",
+      reason: "Opt-in only: meaningful for in-process latency targets, not for a spawned test command.",
+    });
+  }
+
+  return { profile: name, stages, skipped };
+}
+
+/**
+ * The pipeline `gate()` runs when no profile and no explicit stages are set:
+ * every verification command the stack resolved, in dependency order.
+ *
+ * Lives here rather than inline in `gate()` so that `agentctl profile` can show
+ * an operator what will actually run without reimplementing — and drifting
+ * from — the sequence the gate uses.
+ *
+ * @param {{setup?: string, lint?: string, test?: string, unit?: string, fuzz?: string, invariant?: string, e2e?: string, build?: string, policy?: object}} verify
+ * @returns {object[]}
+ */
+export function buildDefaultStages(verify = {}) {
+  const network = verify.policy?.networkAccess || "allow";
+  const stages = [];
+  if (verify.setup) stages.push({ id: "setup", kind: "setup", cmd: verify.setup, required: true, networkAccess: "allow" });
+  if (verify.lint) stages.push({ id: "lint", kind: "lint", cmd: verify.lint, required: true, networkAccess: network });
+  if (verify.test || verify.unit) {
+    stages.push({ id: "unit", kind: "test", cmd: verify.test || verify.unit, required: true, networkAccess: network });
+  }
+  if (verify.fuzz) stages.push({ id: "fuzz", kind: "fuzz", cmd: verify.fuzz, required: true, networkAccess: network });
+  if (verify.invariant) stages.push({ id: "invariant", kind: "invariant", cmd: verify.invariant, required: true, networkAccess: network });
+  if (verify.e2e) stages.push({ id: "e2e", kind: "e2e", cmd: verify.e2e, required: true, networkAccess: "allow" });
+  if (verify.build) stages.push({ id: "build", kind: "build", cmd: verify.build, required: true, networkAccess: network });
+  return stages;
+}
+
+/**
+ * Short human-readable summary of what a profile will run, for `init` output
+ * and `doctor`.
+ *
+ * @param {ReturnType<typeof buildProfileStages>} plan
+ * @returns {string}
+ */
+export function describeProfilePlan(plan) {
+  const ids = plan.stages.map((s) => s.id);
+  return ids.length ? ids.join(" → ") : "(nothing to run)";
+}

package/src/provider-readiness.mjs

@@ -0,0 +1,215 @@
+import { existsSync, statSync } from "node:fs";
+import { join, delimiter } from "node:path";
+
+/**
+ * What each provider actually needs before a dispatch can succeed.
+ *
+ * The kit shipped four provider adapters (`src/provider.mjs`) but only ever
+ * asked one question about readiness: "is JULES_API_KEY set?". That question is
+ * meaningless for `claude-code` and `codex`, which authenticate through their
+ * own CLI and need a binary on PATH instead of an environment variable — so a
+ * repository driven by a local agent CLI was told, forever, that it was
+ * misconfigured. Readiness is a property of the *selected* provider, and this
+ * table is where that property lives.
+ *
+ * `envKeys` are alternatives, not requirements in sequence: any one satisfies
+ * the provider. `bin` is the executable the exec adapter spawns.
+ *
+ * No documentation URLs live here on purpose: `test/egress-allowlist.test.mjs`
+ * treats every host literal under src/ as a network destination to justify, and
+ * a vendor doc link that nothing ever fetches would spend that budget without
+ * buying anything. `install` and `remedy` carry the actionable part.
+ */
+export const PROVIDER_DESCRIPTORS = {
+  jules: {
+    name: "jules",
+    kind: "http",
+    label: "Google Jules — hosted asynchronous agent (REST)",
+    envKeys: ["JULES_API_KEY", "GEMINI_API_KEY"],
+    bin: null,
+    install: null,
+    remedy: "export JULES_API_KEY=...",
+    // Only the hosted provider clones a GitHub repository server-side, so only
+    // it needs to be told which one.
+    needsRepoSource: true,
+  },
+  "claude-code": {
+    name: "claude-code",
+    kind: "exec",
+    label: "Claude Code CLI — local agent",
+    envKeys: [],
+    bin: "claude",
+    install: "npm i -g @anthropic-ai/claude-code",
+    remedy: "Install the Claude Code CLI and run `claude` once to authenticate",
+    needsRepoSource: false,
+  },
+  codex: {
+    name: "codex",
+    kind: "exec",
+    label: "OpenAI Codex CLI — local agent",
+    envKeys: [],
+    bin: "codex",
+    install: "npm i -g @openai/codex",
+    remedy: "Install the Codex CLI and run `codex` once to authenticate",
+    needsRepoSource: false,
+  },
+  "gemini-flash": {
+    name: "gemini-flash",
+    kind: "exec",
+    label: "Gemini CLI — local agent (cheap/fast router tier)",
+    envKeys: ["GEMINI_API_KEY"],
+    bin: "gemini",
+    install: "npm i -g @google/gemini-cli",
+    remedy: "Install the Gemini CLI and export GEMINI_API_KEY",
+    needsRepoSource: false,
+  },
+};
+
+/** `gemini-cli` is an accepted spelling in NAMED_PRESETS; keep the two in step. */
+PROVIDER_DESCRIPTORS["gemini-cli"] = { ...PROVIDER_DESCRIPTORS["gemini-flash"], name: "gemini-cli" };
+
+/**
+ * Preference order when nothing is configured and several providers are ready.
+ *
+ * Hosted first because it is the only one that can run a task while the
+ * operator's machine is asleep; the local CLIs follow in descending
+ * capability. This is a *tie-break*, never an override: an explicit
+ * `provider:` in .agent/config.yml always wins.
+ */
+export const PROVIDER_PREFERENCE = ["jules", "claude-code", "codex", "gemini-flash"];
+
+/**
+ * Cross-platform `which`, without shelling out.
+ *
+ * Spawning `which`/`where` costs a process per probe and does not exist
+ * identically on Windows; PATHEXT resolution is the part that actually differs,
+ * and it is three lines. Returns the absolute path or null.
+ *
+ * @param {string} bin
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string|null}
+ */
+export function whichBinary(bin, env = process.env) {
+  if (!bin || typeof bin !== "string") return null;
+  const pathVar = env.PATH || env.Path || env.path || "";
+  if (!pathVar) return null;
+
+  const isWindows = process.platform === "win32";
+  // On Windows a bare name has no extension; PATHEXT lists the ones the shell
+  // would have tried. Elsewhere the name is the whole story.
+  const extensions = isWindows
+    ? (env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").map((e) => e.trim()).filter(Boolean)
+    : [""];
+
+  for (const dir of pathVar.split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of extensions) {
+      const candidate = join(dir, bin + ext);
+      try {
+        if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+      } catch (_) {
+        // Unreadable PATH entry (a stale mount, a permission-denied directory).
+        // A probe must never throw: an unreadable directory simply holds nothing.
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Report whether one named provider can be dispatched to right now.
+ *
+ * Never throws and never spawns the agent: this is called from `agentctl` with
+ * no arguments and from `doctor`, both of which must stay instant and free.
+ *
+ * @param {string} name
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env=process.env]
+ * @returns {{name: string, kind: string, label: string, ready: boolean, reason: string, remedy: string, keySource: string|null, binPath: string|null, known: boolean}}
+ */
+export function probeProvider(name, opts = {}) {
+  const env = opts.env || process.env;
+  const key = String(name || "").trim().toLowerCase();
+  const descriptor = PROVIDER_DESCRIPTORS[key];
+
+  if (!descriptor) {
+    return {
+      name: key || "(unset)",
+      kind: "unknown",
+      label: key ? `Custom provider '${key}'` : "No provider selected",
+      ready: false,
+      known: false,
+      reason: key
+        ? `'${key}' is not a built-in provider preset, so its readiness cannot be checked here.`
+        : "No provider is configured.",
+      remedy: `Set provider: to one of ${PROVIDER_PREFERENCE.join(", ")} in .agent/config.yml`,
+      keySource: null,
+      binPath: null,
+    };
+  }
+
+  const keySource = descriptor.envKeys.find((k) => (env[k] || "").trim()) || null;
+  const binPath = descriptor.bin ? whichBinary(descriptor.bin, env) : null;
+
+  // An http provider is gated purely on credentials; an exec provider is gated
+  // on the binary, and treats its env key as optional because the CLIs carry
+  // their own stored login.
+  const ready = descriptor.kind === "http" ? Boolean(keySource) : Boolean(binPath);
+
+  let reason;
+  if (ready) {
+    reason =
+      descriptor.kind === "http"
+        ? `Credential supplied via ${keySource} (read from the environment only).`
+        : `\`${descriptor.bin}\` found on PATH${keySource ? ` (plus ${keySource})` : ""}.`;
+  } else {
+    reason =
+      descriptor.kind === "http"
+        ? `None of ${descriptor.envKeys.join(", ")} is set in the environment.`
+        : `\`${descriptor.bin}\` is not on PATH.`;
+  }
+
+  return {
+    name: descriptor.name,
+    kind: descriptor.kind,
+    label: descriptor.label,
+    ready,
+    known: true,
+    reason,
+    remedy: descriptor.install && !binPath ? descriptor.install : descriptor.remedy,
+    keySource,
+    binPath,
+  };
+}
+
+/**
+ * Probe every built-in provider, ready ones first, in preference order.
+ *
+ * Used by `agentctl init` to propose a provider the machine can actually reach
+ * instead of scaffolding `provider: jules` into a repository whose operator has
+ * no Jules key and never wanted one.
+ *
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env=process.env]
+ * @returns {Array<ReturnType<typeof probeProvider>>}
+ */
+export function detectAvailableProviders(opts = {}) {
+  const probes = PROVIDER_PREFERENCE.map((name) => probeProvider(name, opts));
+  return probes.sort((a, b) => {
+    if (a.ready !== b.ready) return a.ready ? -1 : 1;
+    return PROVIDER_PREFERENCE.indexOf(a.name) - PROVIDER_PREFERENCE.indexOf(b.name);
+  });
+}
+
+/**
+ * The provider a fresh `init` should scaffold: the first one that is actually
+ * usable on this machine, falling back to the hosted default so a repository
+ * initialised offline still names something coherent.
+ *
+ * @param {object} [opts]
+ * @returns {string}
+ */
+export function suggestProvider(opts = {}) {
+  const ready = detectAvailableProviders(opts).find((p) => p.ready);
+  return ready ? ready.name : "jules";
+}

package/src/security.mjs

@@ -328,6 +328,47 @@ export function isForbiddenPath(filePath, config = {}) {
   return forbidden.some((pattern) => matchesGlob(normFile, pattern, { caseInsensitive: true }));
 }
 
+/**
+ * The builtin deny patterns that exist to keep credentials out of a diff, and
+ * the documented template filenames those patterns must not catch.
+ *
+ * The recursive dot-env glob is correct for `.env.local` and `.env.production`
+ * and wrong for `.env.example` — a file nearly every repository commits
+ * precisely so the environment can be documented without the values. Denying it
+ * meant no agent could ever be asked to document a new variable, in any project.
+ *
+ * The exemption is deliberately narrow. It applies only when one of the two
+ * *builtin* patterns matched: a repository that writes its own broader dot-env
+ * deny rule blocks templates too, because the pattern string is not one of
+ * these. And the diff secret scanner runs over every changed file regardless of
+ * scope, so a real credential pasted into a template still fails on exit 6.
+ */
+const BUILTIN_ENV_DENY_PATTERNS = new Set(["**/.env", "**/.env.*"]);
+export const ENV_TEMPLATE_BASENAMES = new Set([
+  ".env.example",
+  ".env.sample",
+  ".env.template",
+  ".env.dist",
+  ".env.defaults",
+]);
+
+/**
+ * True when a deny hit is the builtin credential rule catching a committed
+ * environment *template* rather than an environment file.
+ *
+ * @param {string} file - canonicalised repo-relative path
+ * @param {string} pattern - the deny pattern that matched
+ * @returns {boolean}
+ */
+export function isEnvTemplateException(file, pattern) {
+  if (!BUILTIN_ENV_DENY_PATTERNS.has(pattern)) return false;
+  const name = basename(file).toLowerCase();
+  if (ENV_TEMPLATE_BASENAMES.has(name)) return true;
+  // `.env.production.example`, `.env.test.sample`, ... — the documented-template
+  // suffix is what matters, not how many environment segments precede it.
+  return /^\.env\..+\.(example|sample|template|dist|defaults)$/.test(name);
+}
+
 export function checkScope(files = [], scope = {}, opts = {}) {
   const violations = [];
   const deny = scope.deny || [];
@@ -360,7 +401,7 @@ export function checkScope(files = [], scope = {}, opts = {}) {
     // Deny folds case: on macOS/Windows ".GitHub/" resolves to the same
     // directory as ".github/", so a case-sensitive deny is bypassable there.
     const matchedDeny = deny.find((pat) => matchesGlob(file, pat, { caseInsensitive: true }));
-    if (matchedDeny) {
+    if (matchedDeny && !isEnvTemplateException(file, matchedDeny)) {
       violations.push({ file, reason: `Forbidden path restriction matched pattern "${matchedDeny}"`, rule: "deny", pattern: matchedDeny });
       continue;
     }

package/src/tui.mjs

@@ -41,9 +41,20 @@ export function styleText(text, style) {
   return `${style}${text}${ANSI.reset}`;
 }
 
-import { WizardCancelledError } from "./ux/terminal-session.mjs";
-import { createKeyDecoder } from "./ux/key-decoder.mjs";
-export { WizardCancelledError };
+import { createKeyDecoder } from "./key-decoder.mjs";
+
+export class WizardCancelledError extends Error {
+  /**
+   * @param {string} [message]
+   * @param {"escape" | "ctrl-c" | "quit" | "stream-closed"} [reason="ctrl-c"]
+   */
+  constructor(message = "Wizard operation cancelled by user", reason = "ctrl-c") {
+    super(message);
+    this.name = "WizardCancelledError";
+    this.code = 130;
+    this.reason = reason;
+  }
+}
 
 /**
  * Read keypress in raw mode from TTY input stream without destroying stream on early return.