jules-orchestrator-kit 0.74.0 → 0.75.0

package/src/ops/tui-menu.mjs

@@ -0,0 +1,192 @@
+/**
+ * Terminal Navigation Hub (TUI Menu).
+ * Zero-dependency interactive menu using native TTY raw mode.
+ */
+import { isTTY, select, input, confirm, ANSI } from "../tui.mjs";
+import { KIT_VERSION } from "../version.mjs";
+import { loadConfig } from "../config.mjs";
+import { budgetStatus } from "../budget.mjs";
+import { runDoctorChecks } from "./doctor-registry.mjs";
+import { detectAvailableProviders } from "../provider-readiness.mjs";
+import { runTaskCreateWizard } from "../wizard-task.mjs";
+import { listWebTemplates, getWebTemplate } from "../web-templates.mjs";
+import { scorePromptFalsifiability } from "../task-optimizer.mjs";
+import { scanCodebaseForTodos } from "../todo-scanner.mjs";
+import { gate } from "../engine.mjs";
+
+/**
+ * Launch the interactive terminal navigation hub.
+ * @param {string} root - Repository root path
+ * @param {object} [options]
+ * @param {import("node:stream").Readable} [options.stdin]
+ * @param {import("node:stream").Writable} [options.stdout]
+ * @param {boolean} [options.singleAction]
+ * @returns {Promise<{ ok: boolean, action?: string, headless?: boolean }>}
+ */
+export async function runTuiMenu(root = process.cwd(), options = {}) {
+  const stdin = options.stdin || process.stdin;
+  const stdout = options.stdout || process.stdout;
+
+  if (!isTTY(stdin) && !options.allowHeadless) {
+    stdout.write("Interactive terminal menu requires a TTY terminal. Use 'agentctl --help' for CLI commands.\n");
+    return { ok: true, headless: true };
+  }
+
+  while (true) {
+    stdout.write(`\n${ANSI.bold}${ANSI.cyan}🚀 agentctl v${KIT_VERSION}${ANSI.reset} — Interactive Terminal Hub\n`);
+    stdout.write(`   ${ANSI.dim}Repository:${ANSI.reset} ${root}\n\n`);
+
+    const actions = [
+      { label: "🛡️  Run Safety Gate", value: "gate", description: "Audit CI security, scope & verification" },
+      { label: "🔍  System Diagnostics", value: "doctor", description: "Run 13 health checks and provider checks" },
+      { label: "📊  Operating Status", value: "status", description: "View daily budget, locks, pending tasks" },
+      { label: "✨  Create Task Envelope", value: "task-create", description: "Interactive wizard for falsifiable tasks" },
+      { label: "📋  Browse Task Templates", value: "task-template", description: "21 specialized templates: a11y, SEO, CWV..." },
+      { label: "🎯  Optimize Task Prompt", value: "task-optimize", description: "Score prompt falsifiability and suggest fixes" },
+      { label: "🔌  Agent Providers", value: "providers", description: "Inspect Jules, Claude, Codex, Gemini readiness" },
+      { label: "🔎  Scan Codebase (TODOs)", value: "scan", description: "Find task candidates in code" },
+      { label: "🌐  Start Web Dashboard", value: "dashboard", description: "Start local web UI on port 4100" },
+      { label: "🚪  Exit", value: "exit", description: "Quit menu" },
+    ];
+
+    const choice = await select(actions, "Select an action:", { stdin, stdout, defaultIdx: 0 });
+
+    if (choice === "exit") {
+      stdout.write(`${ANSI.dim}Bye!${ANSI.reset}\n`);
+      return { ok: true, action: "exit" };
+    }
+
+    if (choice === "gate") {
+      const modeChoice = await select(
+        [
+          { label: "Working tree", value: "working-tree", description: "Default — evaluate uncommitted changes" },
+          { label: "Staged changes", value: "staged", description: "Evaluate git staged changes only" },
+          { label: "Committed changes", value: "committed", description: "Evaluate committed changes on branch" },
+          { label: "Dry-run simulation", value: "dry-run", description: "Simulate gate without persisting evidence" },
+        ],
+        "Select gate evaluation mode:",
+        { stdin, stdout, defaultIdx: 0 }
+      );
+      const isDry = modeChoice === "dry-run";
+      const mode = isDry ? "working-tree" : modeChoice;
+      stdout.write(`\nRunning Safety Gate (mode: ${mode})...\n`);
+      const res = await gate({ root, mode, dryRun: isDry });
+      stdout.write(`\nGate Result: ${res.ok ? `${ANSI.green}APPROVED (Exit 0)${ANSI.reset}` : `${ANSI.red}REJECTED (Exit ${res.code})${ANSI.reset}`}\n`);
+      for (const p of res.phases || []) {
+        const icon = p.ok ? `${ANSI.green}✅ PASS${ANSI.reset}` : `${ANSI.red}❌ FAIL${ANSI.reset}`;
+        stdout.write(`  Phase [${p.phase.toUpperCase()}] : ${icon}\n`);
+      }
+    } else if (choice === "doctor") {
+      stdout.write(`\nRunning system diagnostics...\n`);
+      const rep = await runDoctorChecks({ root });
+      stdout.write(`\nDiagnostics: ${rep.summary.pass} passed, ${rep.summary.warn} warning(s), ${rep.summary.fail} failure(s)\n`);
+      const iconMap = { pass: `${ANSI.green}✅${ANSI.reset}`, warn: `${ANSI.yellow}⚠️${ANSI.reset}`, fail: `${ANSI.red}❌${ANSI.reset}` };
+      for (const r of rep.results || []) {
+        stdout.write(`  ${iconMap[r.status] || "•"} ${r.title}\n`);
+        if (r.status !== "pass" || r.alwaysShowSummary) {
+          stdout.write(`       ${ANSI.dim}${r.summary}${ANSI.reset}\n`);
+        }
+      }
+    } else if (choice === "status") {
+      const config = loadConfig(root);
+      const b = budgetStatus(config, root);
+      stdout.write(`\n📊 Status Summary:\n`);
+      stdout.write(`  Root: ${root}\n`);
+      stdout.write(`  Config: ${config._file || "None"}\n`);
+      stdout.write(`  Daily Budget: ${b.used} / ${b.limit} tasks in last 24h\n`);
+    } else if (choice === "task-create") {
+      await runTaskCreateWizard(root, { interactive: true, stdin, stdout });
+    } else if (choice === "task-template") {
+      const templates = listWebTemplates();
+      const tOptions = templates.map((t) => ({
+        label: t.id.padEnd(24),
+        value: t.id,
+        description: `${t.category} — ${t.title}`,
+      }));
+      tOptions.push({ label: "← Back", value: "__back__", description: "Return to main menu" });
+      const picked = await select(tOptions, "Select a task template to inspect:", { stdin, stdout });
+      if (picked !== "__back__") {
+        const tpl = getWebTemplate(picked);
+        if (tpl) {
+          stdout.write(`\n${ANSI.bold}${tpl.title}${ANSI.reset} [${tpl.category}]\n`);
+          stdout.write(`Default Oracle: ${tpl.defaultOracle}\n`);
+          stdout.write(`${tpl.description}\n\n`);
+          const action = await select(
+            [
+              { label: "Create task from this template", value: "create" },
+              { label: "View full template envelope", value: "view" },
+              { label: "← Back to menu", value: "back" },
+            ],
+            "Template action:",
+            { stdin, stdout }
+          );
+          if (action === "create") {
+            await runTaskCreateWizard(root, { template: tpl.id, interactive: true, stdin, stdout });
+          } else if (action === "view") {
+            const { synthesizeWebEnvelope } = await import("../web-templates.mjs");
+            const env = synthesizeWebEnvelope(tpl.id, { rootDir: root });
+            stdout.write(`\n${env}\n\n`);
+          }
+        }
+      }
+    } else if (choice === "task-optimize") {
+      const promptText = await input("Enter task prompt to score and optimize:", { stdin, stdout });
+      if (promptText && promptText.trim()) {
+        const analysis = scorePromptFalsifiability(promptText.trim(), { rootDir: root });
+        stdout.write(`\n${ANSI.bold}Prompt Score: ${analysis.score}/100 (Grade ${analysis.grade})${ANSI.reset}\n`);
+        stdout.write(`Falsifiable: ${analysis.falsifiable ? `${ANSI.green}YES${ANSI.reset}` : `${ANSI.red}NO${ANSI.reset}`}\n`);
+        if (analysis.issues && analysis.issues.length > 0) {
+          stdout.write(`Issues identified:\n`);
+          for (const issue of analysis.issues) {
+            stdout.write(`  - [${issue.type}] ${issue.message}\n`);
+          }
+        }
+        if (analysis.suggestions && analysis.suggestions.length > 0) {
+          stdout.write(`Suggestions:\n`);
+          for (const s of analysis.suggestions) {
+            stdout.write(`  - ${s}\n`);
+          }
+        }
+      }
+    } else if (choice === "providers") {
+      const probes = detectAvailableProviders();
+      stdout.write(`\n🔌 Detected Agent Providers:\n`);
+      for (const p of probes) {
+        const icon = p.ready ? `${ANSI.green}✅${ANSI.reset}` : `${ANSI.dim}⬜${ANSI.reset}`;
+        stdout.write(`  ${icon} ${ANSI.bold}${p.name.padEnd(14)}${ANSI.reset} ${p.label}\n`);
+        stdout.write(`       ${ANSI.dim}${p.reason}${ANSI.reset}\n`);
+      }
+    } else if (choice === "scan") {
+      stdout.write(`\nScanning codebase for TODO/FIXME annotations...\n`);
+      const todos = scanCodebaseForTodos(root);
+      stdout.write(`Found ${todos.length} annotation(s):\n`);
+      for (const item of todos.slice(0, 15)) {
+        stdout.write(`  - ${item.file}:${item.line} [${item.tag}] ${item.text}\n`);
+      }
+      if (todos.length > 15) {
+        stdout.write(`  ... and ${todos.length - 15} more.\n`);
+      }
+    } else if (choice === "dashboard") {
+      stdout.write(`\n🌐 To start web dashboard, run:\n`);
+      stdout.write(`   agentctl dashboard --port 4100\n`);
+      const startNow = await confirm("Start web dashboard now?", false, { stdin, stdout });
+      if (startNow) {
+        const { createDashboardServer } = await import("../dashboard.mjs");
+        createDashboardServer({ root, port: 4100, host: "127.0.0.1" });
+        stdout.write(`Dashboard running at http://127.0.0.1:4100\nPress Ctrl+C to exit.\n`);
+        return new Promise(() => {});
+      }
+    }
+
+    if (options.singleAction) {
+      return { ok: true, action: choice };
+    }
+
+    const again = await confirm("\nReturn to main menu?", true, { stdin, stdout });
+    if (!again) {
+      break;
+    }
+  }
+
+  return { ok: true };
+}

package/src/process-tree.mjs

@@ -0,0 +1,146 @@
+/**
+ * Cross-platform process-tree cleanup for timed-out commands.
+ *
+ * Zero third-party deps. Used by `runCmd` when a spawnSync hits ETIMEDOUT so
+ * orphaned workers (children / grandchildren) do not linger after the parent
+ * is killed.
+ *
+ * Platform notes:
+ * - win32: `taskkill /F /T /PID` terminates the whole tree. `detached` is NOT
+ *   set on Windows spawn options in runCmd — taskkill does not need a separate
+ *   process group, and detached consoles behave differently under cmd.exe.
+ * - POSIX (linux/darwin): prefer `process.kill(-pid, signal)` against the
+ *   process group (runCmd sets `detached: true` so the child is group leader).
+ *   Also walk descendants via `pgrep -P` so cleanup still works when the child
+ *   was not started in its own group.
+ */
+
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+
+/**
+ * @param {unknown} pid
+ * @returns {number} Positive integer pid, or 0 if invalid.
+ */
+function normalizePid(pid) {
+  const n = typeof pid === "number" ? pid : Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return 0;
+  return n;
+}
+
+/**
+ * List direct children of `pid` via `pgrep -P`. Empty on failure / none.
+ * @param {number} pid
+ * @returns {number[]}
+ */
+function listDirectChildren(pid) {
+  try {
+    const ret = spawnSync("pgrep", ["-P", String(pid)], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    // pgrep exits 1 when there are no matches — treat as empty, not failure.
+    if (ret.error || !ret.stdout) return [];
+    return ret.stdout
+      .split(/\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map(Number)
+      .filter((n) => Number.isInteger(n) && n > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Breadth-first collect all descendants, returned deepest-first so parents are
+ * signalled after their children (reduces reparent races during cleanup).
+ * @param {number} pid
+ * @returns {number[]}
+ */
+function collectDescendants(pid) {
+  const out = [];
+  const queue = [pid];
+  const seen = new Set([pid]);
+  while (queue.length > 0) {
+    const current = queue.shift();
+    for (const child of listDirectChildren(current)) {
+      if (seen.has(child)) continue;
+      seen.add(child);
+      out.push(child);
+      queue.push(child);
+    }
+  }
+  return out.reverse();
+}
+
+/**
+ * Signal a single pid; never throws (ESRCH / EPERM / already-dead are quiet).
+ * @param {number} pid
+ * @param {NodeJS.Signals|number} signal
+ */
+function safeKill(pid, signal) {
+  try {
+    process.kill(pid, signal);
+  } catch (err) {
+    const code = err && err.code;
+    if (code === "ESRCH" || code === "EPERM") return;
+    // Any other failure is still swallowed: cleanup must not fail the caller.
+  }
+}
+
+/**
+ * Kill `pid` and its descendants.
+ *
+ * Never throws for missing / already-dead processes (ESRCH, taskkill exit
+ * 128+, empty pgrep). Invalid pids are a no-op.
+ *
+ * @param {number|string} pid
+ * @param {NodeJS.Signals|number} [signal="SIGTERM"]
+ */
+export function killProcessTree(pid, signal = "SIGTERM") {
+  const n = normalizePid(pid);
+  if (!n) return;
+
+  if (process.platform === "win32") {
+    try {
+      // /T = tree, /F = force. Non-zero exit (e.g. 128 "not found") is fine.
+      spawnSync("taskkill", ["/F", "/T", "/PID", String(n)], {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } catch {
+      // spawn failure or already gone — ignore
+    }
+    return;
+  }
+
+  // Snapshot the tree while parent→child links still exist. After the parent
+  // dies, Linux reparents orphans to the subreaper and `pgrep -P` goes blind.
+  const descendants = collectDescendants(n);
+
+  // Process-group signal: effective when `pid` is a group leader (detached spawn).
+  try {
+    process.kill(-n, signal);
+  } catch (err) {
+    const code = err && err.code;
+    if (code !== "ESRCH" && code !== "EPERM") {
+      // fall through to per-pid cleanup
+    }
+  }
+
+  // Belt-and-suspenders: direct-child pkill (covers callers that skip the walk).
+  try {
+    const sigName = typeof signal === "string" ? signal.replace(/^SIG/i, "") : String(signal);
+    spawnSync("pkill", [`-${sigName}`, "-P", String(n)], {
+      stdio: "ignore",
+    });
+  } catch {
+    // pkill missing or no children — ignore
+  }
+
+  for (const childPid of descendants) {
+    safeKill(childPid, signal);
+  }
+  safeKill(n, signal);
+}

package/src/scaffold.mjs

@@ -35,6 +35,9 @@ export const RUNTIME_GITIGNORE_ENTRIES = [
   "!.agent/jules-queue/README.md",
 ];
 
+/** Comment header `ensureGitignore` writes above runtime ignore entries. */
+export const RUNTIME_GITIGNORE_HEADER = "# Jules Orchestrator runtime state & credentials";
+
 /**
  * Ensure `.gitignore` lists every runtime path in {@link RUNTIME_GITIGNORE_ENTRIES}.
  *
@@ -57,12 +60,57 @@ export function ensureGitignore(root) {
   const prefix = current && !current.endsWith("\n") ? "\n" : "";
   appendFileSync(
     gitignorePath,
-    `${prefix}\n# Jules Orchestrator runtime state & credentials\n${missing.join("\n")}\n`,
+    `${prefix}\n${RUNTIME_GITIGNORE_HEADER}\n${missing.join("\n")}\n`,
     "utf-8"
   );
   return missing;
 }
 
+/**
+ * Remove kit-owned runtime ignore blocks from a `.gitignore` body.
+ *
+ * Only strips contiguous runs that begin with {@link RUNTIME_GITIGNORE_HEADER}
+ * and continue through lines that match {@link RUNTIME_GITIGNORE_ENTRIES}.
+ * User entries — including a pre-existing `.env` that was never part of a kit
+ * block — are left alone.
+ *
+ * @param {string} content
+ * @returns {{ text: string, stripped: boolean }}
+ */
+export function stripRuntimeGitignoreBlock(content) {
+  const entries = new Set(RUNTIME_GITIGNORE_ENTRIES);
+  const lines = String(content).split(/\r?\n/);
+  const out = [];
+  let stripped = false;
+  let i = 0;
+  while (i < lines.length) {
+    if (lines[i].trim() === RUNTIME_GITIGNORE_HEADER) {
+      stripped = true;
+      i += 1;
+      while (i < lines.length) {
+        const trimmed = lines[i].trim();
+        if (trimmed === "") {
+          // Trailing blank that ensureGitignore leaves after the block.
+          i += 1;
+          break;
+        }
+        if (entries.has(trimmed)) {
+          i += 1;
+          continue;
+        }
+        break;
+      }
+      continue;
+    }
+    out.push(lines[i]);
+    i += 1;
+  }
+  while (out.length > 0 && out[out.length - 1] === "") out.pop();
+  let text = out.join("\n");
+  if (text.length > 0) text += "\n";
+  return { text, stripped };
+}
+
 /**
  * Copy every file from a directory shipped in the package into the target repo.
  *

package/src/scope-guard.mjs

@@ -9,7 +9,7 @@
  */
 
 import { basename } from "node:path";
-import { canonicalizePath, isWindowsAbsolutePath } from "./config.mjs";
+import { canonicalizePath, isWindowsAbsolutePath, CI_DEFINITIONS } from "./config.mjs";
 
 /**
  * Glob matcher.
@@ -178,8 +178,8 @@ export const ENV_TEMPLATE_BASENAMES = new Set([
  * @param {string} pattern - the deny pattern that matched
  * @returns {boolean}
  */
-export function isEnvTemplateException(file, pattern) {
-  if (!BUILTIN_ENV_DENY_PATTERNS.has(pattern)) return false;
+export function isEnvTemplateException(file, pattern = "") {
+  if (pattern && !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
@@ -187,6 +187,70 @@ export function isEnvTemplateException(file, pattern) {
   return /^\.env\..+\.(example|sample|template|dist|defaults)$/.test(name);
 }
 
+/**
+ * Patterns in deny that are strictly non-waivable under any circumstances.
+ * Credentials, private keys, cloud auth configurations, lock-manager files,
+ * and secret roots must NEVER be permitted by a workflow or protected-path waiver.
+ */
+export const UNWAIVABLE_DENY_PATTERNS = [
+  ".git/**",
+  "**/.env",
+  "**/.env.*",
+  "**/*.pem",
+  "**/*.key",
+  "**/id_rsa*",
+  ".agent/jules-queue/**",
+  "**/.envrc",
+  "**/.git-credentials",
+  "**/.aws/**",
+  "**/.ssh/**",
+  "**/.kube/**",
+  "**/kubeconfig*",
+  "**/.docker/config.json",
+  "**/*.p12",
+  "**/*.pfx",
+  "**/*.p8",
+  "**/id_ed25519*",
+  "**/credentials.json",
+  "**/service-account*.json",
+  "**/*.tfstate",
+  "**/*.tfstate.*",
+  "**/secrets/**",
+  "**/lock-manager/**",
+];
+
+export function isUnwaivableForbiddenPath(file, pattern = "") {
+  const normFile = canonicalizePath(file);
+  if (isEnvTemplateException(normFile, pattern)) return false;
+  if (pattern && UNWAIVABLE_DENY_PATTERNS.some((pat) => matchesGlob(pattern, pat, { caseInsensitive: true }))) {
+    return true;
+  }
+  return UNWAIVABLE_DENY_PATTERNS.some((pat) =>
+    matchesGlob(normFile, pat, { caseInsensitive: true })
+  );
+}
+
+/**
+ * True when a deny hit is a forge CI workflow definition (e.g. .github/**)
+ * being modified under an active maintainer-approved waiver (opts.allowProtected === true).
+ * Unwaivable credentials and non-CI forbidden paths are never exempt.
+ *
+ * @param {string} file - canonicalised repo-relative path
+ * @param {string} pattern - the deny pattern that matched
+ * @param {{ allowProtected?: boolean }} [opts]
+ * @returns {boolean}
+ */
+export function isProtectedWorkflowException(file, pattern = "", opts = {}) {
+  if (!opts.allowProtected) return false;
+  if (isUnwaivableForbiddenPath(file, pattern)) return false;
+
+  const normFile = canonicalizePath(file);
+  const isCiDefinition = CI_DEFINITIONS.some((ciPat) =>
+    matchesGlob(normFile, ciPat, { caseInsensitive: true })
+  );
+  return isCiDefinition;
+}
+
 export function checkScope(files = [], scope = {}, opts = {}) {
   const violations = [];
   const deny = scope.deny || [];
@@ -220,8 +284,12 @@ export function checkScope(files = [], scope = {}, opts = {}) {
     // directory as ".github/", so a case-sensitive deny is bypassable there.
     const matchedDeny = deny.find((pat) => matchesGlob(file, pat, { caseInsensitive: true }));
     if (matchedDeny && !isEnvTemplateException(file, matchedDeny)) {
-      violations.push({ file, reason: `Forbidden path restriction matched pattern "${matchedDeny}"`, rule: "deny", pattern: matchedDeny });
-      continue;
+      if (opts.allowProtected && isProtectedWorkflowException(file, matchedDeny, opts)) {
+        // Human-reviewed and SHA-bound waiver explicitly authorizes this CI workflow definition.
+      } else {
+        violations.push({ file, reason: `Forbidden path restriction matched pattern "${matchedDeny}"`, rule: "deny", pattern: matchedDeny });
+        continue;
+      }
     }
 
     // Allow stays case-sensitive on purpose: a case mismatch here yields "not

package/src/secret-scanner.mjs

@@ -156,7 +156,7 @@ const INVISIBLE_CHARS = /[\u00AD\u200B-\u200F\u2028\u2029\u202A-\u202E\u2060-\u2
 // distinct code points with no compatibility decomposition. A credential
 // scanner without this table can be defeated by a single substituted glyph,
 // e.g. `ghp_` spelled with Cyrillic `р`.
-const CONFUSABLE_TO_ASCII = new Map([
+export const CONFUSABLE_TO_ASCII = new Map([
   // Cyrillic
   ["А", "A"], ["В", "B"], ["Е", "E"], ["К", "K"], ["М", "M"], ["Н", "H"],
   ["О", "O"], ["Р", "P"], ["С", "C"], ["Т", "T"], ["У", "Y"], ["Х", "X"],

package/src/security.mjs

@@ -19,7 +19,10 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { detectCrossPackageBoundaryViolations, detectEdgeRuntime } from "./stack-detector.mjs";
-import { checkTrojanSource } from "./bidi-guard.mjs";
+import {
+  checkUnicodeSecurity,
+  locateUnicodeFindingLine,
+} from "./bidi-guard.mjs";
 import {
   hasHighConfidenceSecret,
   hasLowConfidenceSecret,
@@ -331,42 +334,35 @@ export function scanDiff(diffTextStr = "", options = {}) {
   for (const segment of segments) {
     const addedText = segment.lines.map((l) => l.text).join("\n");
 
-    // Check Trojan Source
-    if (!segment.file || !segment.file.endsWith('.md')) {
-      const tsRes = checkTrojanSource(addedText, options);
-      if (!tsRes.ok) {
-        // Find line number where it happened if possible
-        const bidiRegex = /[\u202A\u202B\u202C\u202D\u202E\u2066\u2067\u2068\u2069\u061C\u200E\u200F]/;
-        let lineNo = null;
-        for (const l of segment.lines) {
-          if (bidiRegex.test(l.text)) {
-            lineNo = l.no;
-            break;
-          }
-        }
-        for (const v of tsRes.violations) {
+    const hit = classifyAddedLines(addedText, segment.file);
+    if (hit) {
+      const line = segment.file ? locateFindingLine(segment.lines, hit.type, segment.file) : null;
+      const at = segment.file ? ` (${segment.file}${line ? `:${line}` : ""})` : "";
+      findings.push({
+        severity: hit.severity,
+        type: hit.type,
+        file: segment.file,
+        line,
+        description: `${hit.description}${at}`,
+      });
+    }
+
+    // Unicode security: BiDi Trojan Source, invisible obfuscation, mixed-script
+    // confusables. Markdown remains exempt (documentation may cite the controls).
+    if (!segment.file || !segment.file.endsWith(".md")) {
+      const uniRes = checkUnicodeSecurity(addedText, options);
+      if (!uniRes.ok) {
+        for (const v of uniRes.violations) {
           findings.push({
             severity: "CRITICAL",
-            type: "TROJAN_SOURCE_DETECTED",
+            type: v.type,
             file: segment.file,
-            line: lineNo,
+            line: locateUnicodeFindingLine(segment.lines, v.type),
             description: v.reason,
           });
         }
       }
     }
-
-    const hit = classifyAddedLines(addedText, segment.file);
-    if (!hit) continue;
-    const line = segment.file ? locateFindingLine(segment.lines, hit.type, segment.file) : null;
-    const at = segment.file ? ` (${segment.file}${line ? `:${line}` : ""})` : "";
-    findings.push({
-      severity: hit.severity,
-      type: hit.type,
-      file: segment.file,
-      line,
-      description: `${hit.description}${at}`,
-    });
   }
 
   // Scanning per file loses anything that only matches across a file boundary,
@@ -462,6 +458,9 @@ export {
   ENV_TEMPLATE_BASENAMES,
   isEnvTemplateException,
   checkScope,
+  isProtectedWorkflowException,
+  UNWAIVABLE_DENY_PATTERNS,
+  isUnwaivableForbiddenPath,
 } from "./scope-guard.mjs";
 export {
   HIGH_CONFIDENCE_PATTERNS,
@@ -475,4 +474,12 @@ export {
   hasHighEntropyToken,
 } from "./secret-scanner.mjs";
 export { TAMPER_KINDS, TAMPER_KIND_NAMES, resolveAllowedTamperKinds, checkTestTampering } from "./test-tamper-guard.mjs";
-export { checkTrojanSource } from "./bidi-guard.mjs";
+export {
+  checkTrojanSource,
+  checkUnicodeSecurity,
+  BIDI_CONTROL_REGEX,
+  INVISIBLE_OBFUSCATION_REGEX,
+  PLANE14_TAG_REGEX,
+  hasMixedScriptConfusable,
+  locateUnicodeFindingLine,
+} from "./bidi-guard.mjs";