jules-orchestrator-kit 0.72.2 → 0.73.0

package/src/ops/doctor-registry.mjs

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { execFileSync, spawnSync } from "node:child_process";
-import { loadConfig } from "../config.mjs";
+import { loadConfig, detectStack } from "../config.mjs";
 import { probeProvider, detectAvailableProviders, probeProviderLiveness } from "../provider-readiness.mjs";
 import { resolveConcurrency } from "../budget.mjs";
 
@@ -121,7 +121,11 @@ export async function runDoctorChecks(options = {}) {
   // runtime.git
   let gitPassed = false;
   try {
-    const gitOut = execFileSync("git", ["--version"], { encoding: "utf-8", timeout: 5000 });
+    const gitOut = execFileSync("git", ["--version"], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
     gitPassed = true;
     addResult({
       id: "runtime.git",
@@ -167,18 +171,46 @@ export async function runDoctorChecks(options = {}) {
     let isRepo = false;
     let headSha = "";
     try {
-      headSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf-8" }).trim();
-      isRepo = true;
-      addResult({
-        id: "repo.root",
-        category: "Repository",
-        title: "Repository Root Verification",
-        status: "pass",
-        severity: "info",
-        summary: `Valid repository at ${root} (HEAD: ${headSha.slice(0, 8)})`,
-        evidence: [{ label: "headSha", value: headSha, sensitive: false }],
-      });
-    } catch {
+      const insideWorkTree = execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+        cwd: root,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+      if (insideWorkTree === "true") {
+        isRepo = true;
+        try {
+          headSha = execFileSync("git", ["rev-parse", "--verify", "--quiet", "HEAD"], {
+            cwd: root,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+          }).trim();
+        } catch (_) {}
+
+        if (headSha) {
+          addResult({
+            id: "repo.root",
+            category: "Repository",
+            title: "Repository Root Verification",
+            status: "pass",
+            severity: "info",
+            summary: `Valid repository at ${root} (HEAD: ${headSha.slice(0, 8)})`,
+            evidence: [{ label: "headSha", value: headSha, sensitive: false }],
+          });
+        } else {
+          addResult({
+            id: "repo.root",
+            category: "Repository",
+            title: "Repository Root Verification",
+            status: "pass",
+            severity: "info",
+            summary: `Valid repository at ${root} (unborn HEAD, 0 commits)`,
+            evidence: [{ label: "headSha", value: "", sensitive: false }],
+          });
+        }
+      }
+    } catch (_) {}
+
+    if (!isRepo) {
       addResult({
         id: "repo.root",
         category: "Repository",
@@ -191,7 +223,11 @@ export async function runDoctorChecks(options = {}) {
 
     if (isRepo) {
       try {
-        const statusOut = execFileSync("git", ["status", "--porcelain"], { cwd: root, encoding: "utf-8" }).trim();
+        const statusOut = execFileSync("git", ["status", "--porcelain"], {
+          cwd: root,
+          encoding: "utf-8",
+          stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
         const modifiedCount = statusOut ? statusOut.split("\n").length : 0;
         if (modifiedCount === 0) {
           addResult({
@@ -300,49 +336,96 @@ export async function runDoctorChecks(options = {}) {
   }
 
   // 4. Verification Oracle Checks
+  // Judge the command the gate will actually run — `verify.test` from the
+  // config, falling back to the npm `test` script — rather than package.json
+  // alone. package.json-only logic told a fresh Python/Rust/Go or zero-test
+  // repo "missing test script" (a warning, exit 0) while config carried the
+  // real command, or nothing at all; and a green `doctor` right before an
+  // `agentctl gate`/`agentctl task create` that both hard-fail with "No
+  // Verification Oracle" sent newcomers into a contradiction. When verification
+  // is required and there is no oracle, that is a genuine health failure and is
+  // reported red so `doctor`'s exit code matches what the gate will do.
   const pkgPath = join(root, "package.json");
+  let pkgTestScript = "";
+  let pkgValid = false;
   if (existsSync(pkgPath)) {
     try {
       const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-      const testScript = pkg.scripts && pkg.scripts.test;
-      if (testScript) {
-        addResult({
-          id: "oracle.test",
-          category: "Verification",
-          title: "Test Oracle Configuration",
-          status: "pass",
-          severity: "info",
-          summary: `Test oracle script found: "npm test" -> "${testScript}"`,
-          evidence: [{ label: "testScript", value: testScript, sensitive: false }],
-        });
-      } else {
-        addResult({
-          id: "oracle.test",
-          category: "Verification",
-          title: "Test Oracle Configuration",
-          status: "warn",
-          severity: "medium",
-          summary: "package.json missing test script entry",
-        });
-      }
+      pkgValid = true;
+      pkgTestScript = (pkg.scripts && pkg.scripts.test) || "";
     } catch {
-      addResult({
-        id: "oracle.test",
-        category: "Verification",
-        title: "Test Oracle Configuration",
-        status: "warn",
-        severity: "medium",
-        summary: "Malformed package.json file",
-      });
+      pkgValid = false;
     }
-  } else {
+  }
+  let cfg = null;
+  try {
+    cfg = loadConfig(root);
+  } catch (_) {
+    // A config the loader rejects is already reported by config.present; fall
+    // through with null and treat verification as required (the default).
+  }
+  const configTest = (cfg?.verify?.test || "").trim();
+  // verify.required defaults to true; an operator who sets it false is saying
+  // "scope/secret gating only, on purpose" — which is a warning, not a failure.
+  const verificationRequired = cfg?.verify?.required !== false;
+  // The gate auto-detects a per-stack command even before init writes config
+  // (e.g. `python3 -m pytest` for a .py repo), so detection counts as an oracle
+  // too — otherwise a detected but not-yet-onboarded stack would report red.
+  const detectedTest = detectStack(root)?.testCmd || "";
+  const effectiveTest = configTest || pkgTestScript || detectedTest;
+
+  if (effectiveTest) {
+    const source = configTest
+      ? "verify.test in config"
+      : pkgTestScript
+        ? "package.json test script"
+        : "auto-detected from repository stack";
     addResult({
       id: "oracle.test",
       category: "Verification",
       title: "Test Oracle Configuration",
       status: "pass",
       severity: "info",
-      summary: "Non-Node workspace verified",
+      summary: `Verification oracle: "${effectiveTest}" (${source})`,
+      evidence: [{ label: "testCommand", value: effectiveTest, sensitive: false }],
+    });
+  } else if (existsSync(pkgPath) && !pkgValid) {
+    addResult({
+      id: "oracle.test",
+      category: "Verification",
+      title: "Test Oracle Configuration",
+      status: "warn",
+      severity: "medium",
+      summary: "Malformed package.json file",
+    });
+  } else if (!verificationRequired) {
+    addResult({
+      id: "oracle.test",
+      category: "Verification",
+      title: "Test Oracle Configuration",
+      status: "warn",
+      severity: "medium",
+      summary: "No verification oracle — verify.required: false (scope/secret gating only)",
+    });
+  } else {
+    addResult({
+      id: "oracle.test",
+      category: "Verification",
+      title: "Test Oracle Configuration",
+      status: "fail",
+      severity: "high",
+      summary:
+        "No verification command is configured, so the gate rejects every change with a No Verification Oracle finding",
+      fixes: [
+        {
+          id: "oracle.bootstrap",
+          title: "Generate a verification oracle",
+          summary: "Run `agentctl bootstrap` to create one for this stack, or set verify.test in .agent/config.yml",
+          risk: "low",
+          automatic: true,
+          requiresProbe: false,
+        },
+      ],
     });
   }
 
@@ -514,7 +597,11 @@ export async function runDoctorChecks(options = {}) {
   if (existsSync(envFile)) {
     let tracked = false;
     try {
-      const res = spawnSync("git", ["ls-files", "--error-unmatch", ".env"], { cwd: root, encoding: "utf-8" });
+      const res = spawnSync("git", ["ls-files", "--error-unmatch", ".env"], {
+        cwd: root,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
       tracked = res.status === 0;
     } catch (_) {}
 

package/src/ops/handover.mjs

@@ -5,15 +5,9 @@ import {
   readdirSync,
   statSync,
   unlinkSync,
-  renameSync,
-  openSync,
-  writeSync,
-  fsyncSync,
-  closeSync,
 } from "node:fs";
 import { join, resolve, relative, isAbsolute, basename } from "node:path";
-import { randomUUID } from "node:crypto";
-import { redactSecrets } from "../security.mjs";
+import { redactSecrets, safeAtomicWrite } from "../security.mjs";
 import { resolveRoot } from "../config.mjs";
 
 export class HandoverError extends Error {
@@ -77,25 +71,6 @@ function sanitizeText(value) {
   return redactSecrets(String(value).trim());
 }
 
-function writeFileAtomically(filePath, content) {
-  const tmpPath = `${filePath}.${randomUUID()}.tmp`;
-  let fd;
-  try {
-    fd = openSync(tmpPath, "wx", 0o600);
-    writeSync(fd, content, "utf-8");
-    fsyncSync(fd);
-    closeSync(fd);
-    fd = undefined;
-    renameSync(tmpPath, filePath);
-  } catch (err) {
-    if (fd !== undefined) {
-      try { closeSync(fd); } catch (_) {}
-    }
-    try { unlinkSync(tmpPath); } catch (_) {}
-    throw err;
-  }
-}
-
 /**
  * Creates and persists a Baton Pass handover manifest in .agent/handovers/YYYY-MM-DD-[sessionId].md.
  *
@@ -192,7 +167,8 @@ export function createHandover(root = resolveRoot(), data = {}, options = {}) {
   bodySections.push("");
   const fullContent = frontmatterLines.join("\n") + bodySections.join("\n");
 
-  writeFileAtomically(filePath, fullContent);
+  // Handover transcripts can quote session content; keep the private 0600 mode.
+  safeAtomicWrite(filePath, fullContent, { mode: 0o600 });
 
   const retention = typeof options.maxRetention === "number" ? options.maxRetention : 20;
   if (retention > 0) {

package/src/ops/pr-harvest.mjs

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { classifyRiskTier, RISK_TIERS } from "../risk.mjs";
-import { checkSafetyGate } from "../../scripts/jules-merge-swarm.mjs";
+import { checkSafetyGate } from "../merge-swarm.mjs";
 import { normalizePath, loadConfig } from "../config.mjs";
 
 /**

package/src/prompt-guard.mjs

@@ -6,7 +6,7 @@
  * neutralizes LLM control role markers and prompt injection patterns, and wraps inputs in strict tags.
  */
 
-const ZERO_WIDTH_AND_BIDI_REGEX = /[\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/g;
+const ZERO_WIDTH_AND_BIDI_REGEX = /[\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]|[\u{E0000}-\u{E007F}]/gu;
 const ANSI_ESCAPE_REGEX = /\u001B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g;
 
 const CONTROL_TAGS_REGEX = /<\|im_start\|>|<\|im_end\|>|<\|system\|>|<\|assistant\|>|<\|user\|>|<\|endoftext\|>|\[INST\]|\[\/INST\]|<<SYS>>|<\/SYS>>/gi;
@@ -27,29 +27,59 @@ const INJECTION_PATTERNS = [
  * to prevent false-positive safety classifier tripwires in Google VM environments.
  */
 export const STERILE_VOCABULARY_MAP = [
+  { pattern: /\bkill\s+-9\b/gi, replacement: "terminate with SIGTERM" },
+  { pattern: /\bSIGKILL\b/gi, replacement: "SIGTERM" },
   { pattern: /\bkill\s+(?:the\s+)?processes\b/gi, replacement: "terminate the processes" },
   { pattern: /\bkill\s+(?:the\s+)?process\b/gi, replacement: "terminate the process" },
   { pattern: /\bkill\s+(?:the\s+)?pid\b/gi, replacement: "terminate the PID" },
+  { pattern: /\breap\s+(?:the\s+)?(?:zombie\s+)?processes\b/gi, replacement: "collect child processes" },
+  { pattern: /\breap\s+(?:the\s+)?(?:zombie\s+)?process\b/gi, replacement: "collect child process" },
+  { pattern: /\breap\s+(?:the\s+)?zombies\b/gi, replacement: "collect child processes" },
   { pattern: /\bamputate\s+(?:dead\s+|unused\s+)?code\b/gi, replacement: "prune unused code" },
   { pattern: /\bamputate\b/gi, replacement: "prune" },
   { pattern: /\bsabotage\s+(?:the\s+)?tests?\b/gi, replacement: "mutate test logic" },
   { pattern: /\bsabotage\b/gi, replacement: "mutate" },
   { pattern: /\bdestroy\s+(?:the\s+)?(state|cache|file|data|directory)\b/gi, replacement: "purge the $1" },
   { pattern: /\bwipe\s+(?:the\s+)?(state|cache|directory|disk|table)\b/gi, replacement: "clear the $1" },
+  { pattern: /\bexploit_payload\b/gi, replacement: "test_payload" },
 ];
 
 /**
- * Sanitizes aggressive phrases into clinical equivalents.
+ * Sanitizes aggressive phrases into clinical equivalents while preserving
+ * code blocks (```...```) and inline backticks (`...`) verbatim.
  *
  * @param {string} text - Prompt text
  * @returns {string} Sanitized prompt with clinical vocabulary
  */
 export function sanitizePromptVocabulary(text) {
   if (!text || typeof text !== "string") return text || "";
-  let sanitized = text;
+
+  const codeSpans = [];
+  const placeholderPrefix = "@@VERBATIM_CODE_SPAN_";
+
+  // Protect fenced code blocks
+  let protectedText = text.replace(/```[\s\S]*?```/g, (match) => {
+    const idx = codeSpans.length;
+    codeSpans.push(match);
+    return `${placeholderPrefix}${idx}@@`;
+  });
+
+  // Protect inline code spans
+  protectedText = protectedText.replace(/`[^`\n]+`/g, (match) => {
+    const idx = codeSpans.length;
+    codeSpans.push(match);
+    return `${placeholderPrefix}${idx}@@`;
+  });
+
+  let sanitized = protectedText;
   for (const { pattern, replacement } of STERILE_VOCABULARY_MAP) {
     sanitized = sanitized.replace(pattern, replacement);
   }
+
+  for (let i = 0; i < codeSpans.length; i++) {
+    sanitized = sanitized.replace(`${placeholderPrefix}${i}@@`, codeSpans[i]);
+  }
+
   return sanitized;
 }
 

package/src/provider.mjs

@@ -185,19 +185,36 @@ const NAMED_PRESETS = {
  * Multi-token manager with round-robin rotation, 429 quarantine/cooldown, and failover.
  */
 export class TokenPool {
-  constructor(tokens = []) {
+  constructor(tokens = [], options = {}) {
     this.tokens = Array.from(new Set(tokens.filter(Boolean)));
     this.currentIndex = 0;
     this.cooldowns = new Map(); // token -> cooldownExpiryTimestamp
     this.usage24h = new Map(); // token -> count
+    this.limits = new Map(Object.entries(options.limits || {}));
+  }
+
+  getLimit(token, index) {
+    if (this.limits.has(token)) return this.limits.get(token);
+    return index === 0 ? 100 : 15;
   }
 
   static fromEnv(config = {}) {
-    const rawList = (process.env.JULES_API_KEYS || process.env.JULES_API_KEY_SECONDARY || "")
+    const rawList = (
+      process.env.JULES_API_KEYS ||
+      process.env.JULES_API_KEY_SECONDARY ||
+      process.env.JULES_SECONDARY_TOKENS ||
+      process.env.AGENT_SECONDARY_TOKENS ||
+      ""
+    )
       .split(",")
       .map((t) => t.trim())
       .filter(Boolean);
-    const primary = (process.env.JULES_API_KEY || "").trim();
+    const primary = (
+      process.env.JULES_API_KEY ||
+      process.env.JULES_MAIN_TOKEN ||
+      process.env.AGENT_MAIN_TOKEN ||
+      ""
+    ).trim();
     const configKeys = Array.isArray(config.julesApiKeys) ? config.julesApiKeys : [];
     const combined = Array.from(new Set([primary, ...rawList, ...configKeys].filter(Boolean)));
     return new TokenPool(combined);
@@ -211,15 +228,38 @@ export class TokenPool {
     if (this.tokens.length === 0) return "";
     const now = Date.now();
 
-    // Find first non-cooldown token starting from currentIndex
+    // Collect available (non-cooldown) candidates
+    const available = [];
     for (let i = 0; i < this.tokens.length; i++) {
       const idx = (this.currentIndex + i) % this.tokens.length;
       const token = this.tokens[idx];
       const cooldownUntil = this.cooldowns.get(token) || 0;
       if (now >= cooldownUntil) {
-        this.currentIndex = (idx + 1) % this.tokens.length;
-        return token;
+        const usage = this.usage24h.get(token) || 0;
+        const limit = this.getLimit(token, idx);
+        const utilization = limit > 0 ? usage / limit : 1;
+        available.push({ token, idx, usage, limit, utilization });
+      }
+    }
+
+    if (available.length > 0) {
+      // If any usage has been recorded, pick the one with lowest utilization
+      const hasUsage = available.some((a) => a.usage > 0);
+      if (hasUsage) {
+        let best = available[0];
+        for (const candidate of available) {
+          if (candidate.utilization < best.utilization) {
+            best = candidate;
+          }
+        }
+        this.currentIndex = (best.idx + 1) % this.tokens.length;
+        return best.token;
       }
+
+      // If no usage recorded yet, preserve exact round-robin behavior
+      const chosen = available[0];
+      this.currentIndex = (chosen.idx + 1) % this.tokens.length;
+      return chosen.token;
     }
 
     // If all are in cooldown, pick the one that expires earliest
@@ -253,6 +293,8 @@ export class TokenPool {
       const cooldownUntil = this.cooldowns.get(token) || 0;
       const inCooldown = now < cooldownUntil;
       const maskedToken = token.length <= 8 ? "****" : `${token.slice(0, 4)}...${token.slice(-4)}`;
+      const limit = this.getLimit(token, index);
+      const usage = this.usage24h.get(token) || 0;
       return {
         id: `key-${index + 1}`,
         index,
@@ -260,7 +302,9 @@ export class TokenPool {
         maskedToken,
         inCooldown,
         cooldownRemainingMs: inCooldown ? cooldownUntil - now : 0,
-        usage: this.usage24h.get(token) || 0,
+        usage,
+        limit,
+        utilization: limit > 0 ? usage / limit : 1,
       };
     });
   }

package/src/remediation.mjs

@@ -285,7 +285,7 @@ export function createWhackAMoleDetector(opts = {}) {
       const oscillatingTests = [...cycleTests];
 
       const testSummary = oscillatingTests.length > 0 ? oscillatingTests.join(" <-> ") : "tests";
-      const promptDirective = `[WHACK_A_MOLE_WARNING] You are trapped in a local optimization cycle where fixing one test breaks another (<UNTRUSTED>${testSummary}</UNTRUSTED>). Do not add more conditional edge-case band-aids. Revert recent patches and refactor the core logic cleanly.`;
+      const promptDirective = `[Test Oscillation Circuit Breaker Activated] Switching verification strategy: fixing one test repeatedly breaks another (<UNTRUSTED>${testSummary}</UNTRUSTED>). Do not add more conditional edge-case patches. Revert recent patches and refactor the core logic cleanly.`;
 
       return {
         whackAMole: true,
@@ -293,7 +293,7 @@ export function createWhackAMoleDetector(opts = {}) {
         oscillatingTests,
         occurrences,
         promptDirective,
-        reason: `Whack-a-Mole Test Oscillation Detected: Test failure signature repeated across repair turns (${testSummary}).`,
+        reason: `Test Oscillation Circuit Breaker Activated: Test failure signature repeated across repair turns (${testSummary}).`,
       };
     }
 

package/src/role-resolver.mjs

@@ -19,6 +19,89 @@ import { loadConfig } from "./config.mjs";
  */
 export const ROLE_PROMPT_TOKENS = ["VERIFY_TEST", "VERIFY_LINT", "VERIFY_BUILD", "DIFF_KB", "BASE_BRANCH"];
 
+/**
+ * Legacy and convenience aliases for the standard engineering roles.
+ *
+ * Strictly one-directional: every key is a non-canonical name and every
+ * value is a canonical role. Provides full backward-compatibility for prior
+ * command flags (--role bolt, etc.) without letting a canonical role ever
+ * resolve away from its own prompt file.
+ */
+export const ROLE_ALIASES = Object.freeze({
+  // Legacy RPG/fantasy names mapped to canonical engineering roles
+  overseer: "auditor",
+  bolt: "performance",
+  sentinel: "security",
+  janitor: "hygiene",
+  spectator: "e2e",
+  scribe: "docs",
+  alchemist: "database",
+  bulwark: "resilience",
+  typist: "types",
+  hunter: "debugger",
+
+  // Common operator shortcuts
+  perf: "performance",
+  sec: "security",
+  db: "database",
+  cleanup: "hygiene",
+  accessibility: "a11y",
+  documentation: "docs",
+  visual: "e2e",
+  playwright: "e2e",
+  schema: "database",
+  migration: "database",
+  reliability: "resilience",
+  typecheck: "types",
+  "type-safety": "types",
+  debug: "debugger",
+  "defect-fix": "debugger",
+  lead: "auditor",
+  coordinator: "auditor",
+  test: "testing",
+  "unit-test": "testing",
+  "integration-test": "testing",
+  qa: "testing",
+  tester: "testing",
+});
+
+export const CANONICAL_ROLES = Object.freeze([
+  "auditor",
+  "performance",
+  "security",
+  "hygiene",
+  "a11y",
+  "docs",
+  "e2e",
+  "database",
+  "resilience",
+  "types",
+  "debugger",
+  "testing",
+]);
+
+/**
+ * Pre-consolidation prompt filenames, canonical role -> legacy file stem.
+ *
+ * Deliberately NOT part of ROLE_ALIASES: the alias table answers "what did
+ * the operator mean", while this map answers "what might an older checkout
+ * still have on disk". Keeping the two separate is what lets ROLE_ALIASES
+ * stay strictly one-directional without stranding repos scaffolded before
+ * the legacy duplicates were deleted.
+ */
+const LEGACY_PROMPT_FILENAMES = Object.freeze({
+  auditor: "overseer",
+  performance: "bolt",
+  security: "sentinel",
+  hygiene: "janitor",
+  e2e: "spectator",
+  docs: "scribe",
+  database: "alchemist",
+  resilience: "bulwark",
+  types: "typist",
+  debugger: "hunter",
+});
+
 /**
  * Substitutes `{{TOKEN}}` placeholders in a role prompt from resolved config.
  *
@@ -51,14 +134,41 @@ export function hydrateRolePrompt(content = "", config = {}) {
 export function resolveRolePrompt(root = process.cwd(), roleName = "", opts = {}) {
   if (!roleName || typeof roleName !== "string") return null;
   const cleanName = roleName.trim().toLowerCase();
+  const directAlias = ROLE_ALIASES[cleanName];
+  const canonical = directAlias && CANONICAL_ROLES.includes(directAlias)
+    ? directAlias
+    : (CANONICAL_ROLES.includes(cleanName) ? cleanName : null);
+
+  const candidates = [];
+  if (canonical) {
+    candidates.push(canonical);
+  }
+  if (!candidates.includes(cleanName)) {
+    candidates.push(cleanName);
+  }
+  // Secondary fallback: a checkout scaffolded before consolidation may still
+  // hold only the legacy filename on disk (e.g. Bolt.md). The canonical file
+  // always wins when both exist; this branch just keeps old trees working.
+  if (canonical && LEGACY_PROMPT_FILENAMES[canonical] && !candidates.includes(LEGACY_PROMPT_FILENAMES[canonical])) {
+    candidates.push(LEGACY_PROMPT_FILENAMES[canonical]);
+  }
+  // Include direct alias if not yet present
+  if (directAlias && !candidates.includes(directAlias)) {
+    candidates.push(directAlias);
+  }
+
   const promptsDir = join(root, ".agent", "prompts");
   if (!existsSync(promptsDir)) return null;
 
   try {
     const files = readdirSync(promptsDir);
-    const matched = files.find(
-      (f) => f.toLowerCase() === `${cleanName}.md` || f.toLowerCase() === cleanName
-    );
+    let matched = null;
+    for (const cand of candidates) {
+      matched = files.find(
+        (f) => f.toLowerCase() === `${cand}.md` || f.toLowerCase() === cand
+      );
+      if (matched) break;
+    }
     if (matched) {
       const fullPath = join(promptsDir, matched);
       const raw = readFileSync(fullPath, "utf-8").trim();