jules-orchestrator-kit 0.75.0 → 0.75.2

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.75.2] - 2026-10-09
+
+### Fixed
+- **Committed Mode Snapshot Target (`src/engine.mjs`)**: Pointed `materializeSnapshot` to target commit `opts.head` (defaults to `HEAD`) instead of base commit when evaluating in committed mode.
+- **Auto-Merge CI PR Head Checkout (`src/ci-templates.mjs`)**: Detached checkout to fetched PR head (`git checkout --detach refs/pr-head`) before gate evaluation so PR verification tests candidate changes rather than base.
+- **TUI Interactive Fallback on Headless CI (`src/ops/tui-menu.mjs`)**: Allowed interactive terminal UI menu execution when custom mock streams are explicitly provided even if `process.env.CI` is defined.
+- **Pure JSON Output in Task Queue (`bin/agentctl.mjs`)**: Suppressed decorative informational messages during `agentctl queue --json` execution for uncorrupted machine consumption.
+
+### Added
+- **CLI Navigation Aliases & Gate Flags (`bin/agentctl.mjs`, `src/ops/command-registry.mjs`)**: Added `hub` alias for `menu`, `task new` alias for `task create`, and forwarded `--head` to `agentctl check` and verification gate.
+
+### Security
+- **Task Envelope & Pre-Dispatch Secret Prevention (`src/envelope.mjs`, `src/engine.mjs`)**: Rejected prompts and task intents containing unredacted high-confidence credentials before queuing or agent dispatch.
+
+## [0.75.1] - 2026-10-09
+
+### Added
+- **Auto-Merge CI Workflow Template (`src/ci-templates.mjs`, `bin/agentctl.mjs`)**: Added `buildAutoMergeWorkflow` and `--with-automerge` flag to `agentctl ci init`. Generates `.github/workflows/agent-automerge.yml` operating on `workflow_run` strictly from `ref: main`, enforcing secure bot actor validation (`google-labs-jules[bot]`, `github-actions[bot]`), untrusted commit data fetching, and base-branch gate verification before automated squash-merging.
+- **Quiet-Run Invariant (`AGENTS.md`, `JULES_RULES_TEMPLATE.md`)**: Enforced explicit invariant prohibiting cosmetic refactors and fabricated changes when scheduled or automated runs discover all constraints already satisfied.
+- **Automated SYNC-CORE Byte Parity Test (`test/cli-surface.test.mjs`)**: Added test verifying byte-level identity between `AGENTS.md` and `JULES_RULES_TEMPLATE.md` core rule blocks.
+
+### Security
+- **Symlink & Mode Inspection Hardening (`scripts/ci-scope-guard.mjs`)**: Replaced `--name-only` diff inspection with null-delimited raw diff parsing (`git diff --raw -z --no-renames`). Inspects blob modes, rejects symlinks (`mode 120000`) resolving to protected paths or escaping repository root via `git cat-file blob <dstSha>` without local checkout, rejects git submodules (`mode 160000`), and fails closed on unreadable symlink targets.
+
 ## [0.75.0] - 2026-09-28
 
 ### Added
@@ -20,13 +44,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Goal Evidence Enforcement (`src/engine.mjs`)**: Disallowed silent early termination on goal tasks lacking explicit verification evidence.
 - **Test Environment Variable Bleed (`src/engine.mjs`)**: Sanitized test execution environment to prevent PR label bypass tokens from leaking into child test runs during gate evaluation.
 
+### Changed
+- **Stack-Neutral Invariants & Isolation Cleanup (`src/wizard-task.mjs`, `docs/`)**: Removed hardcoded vendor framework assumptions from task authoring in favor of project configuration and options; purged Swedish phrasing from internal test suites and scripts.
+
 ## [0.74.0] - 2026-09-19
 
 ### Added
 - **Native `agentctl.task/v1` Frontmatter Specification & Zero-Dependency Parser (`src/envelope.mjs`, `scripts/validate-envelope.mjs`)**: Added canonical YAML frontmatter envelope support for task files (`.md`) without third-party dependencies. Reconciles `scope.allow`, `scope.deny`, `verification.commands`, `invariants`, `mcp_directives`, and `flags` with 100% backward compatibility for legacy HTML comments (`<!-- JULES_TASK_ENVELOPE: ... -->`).
 - **Taxonomy Delegation Lanes (Green / Amber / Orange / Red) (`src/envelope.mjs`, `src/wizard-task.mjs`)**: Formulated formal risk lane delegation. Red tasks are rejected at validation; Orange tasks warn for external execution only; Amber tasks allow protected path changes (e.g. dependency upgrades in `package.json`, migrations, auth) under explicit plan approval (`requirePlanApproval: true`). Green tasks prevent unapproved protected scope mutations.
 - **Circuit Breaker & Verification Contract in Envelope (`src/envelope.mjs`)**: Added frontmatter declarations for `circuitBreaker` (`max_attempts`, `max_diff_lines`, `stop_if_same_failure_repeats`) and `verification` metadata (`require_nonzero_test_count`, `trusted_base`), alongside `constraints` alias support.
-- **Stack Invariant & MCP Directive Ingestion (`src/wizard-task.mjs`)**: Automatically infers runtime constraints (Zero-JS for Astro, workerd edge runtime constraints for Cloudflare Wrangler) and injects mandatory pre-execution documentation lookup directives into task instructions.
+- **Custom Invariant & MCP Directive Ingestion (`src/wizard-task.mjs`)**: Ingests project invariants and MCP directives from configuration and options, attaching pre-execution documentation lookup directives into task instructions.
 - **Dependency Upgrade Scope Harmonization (`src/wizard-task.mjs`)**: Updated `buildGuardrailFooter` to exclude explicitly authorized paths (`opts.allowedPaths`) from forbidden path warnings, eliminating conflicting instructions for dependency upgrade workloads.
 - **Diff Payload Governor Branch Base Comparison (`src/wizard-task.mjs`)**: Calculated diff payload sizes against `git diff origin/${baseBranch}...HEAD | wc -c` instead of local uncommitted diffs.
 

package/JULES_RULES_TEMPLATE.md

@@ -31,6 +31,9 @@ below and keep existing project instructions when adopting this template.
   affected checks if the base changes.
 - Report what changed, commands run, results and remaining limitations. Do not
   claim a check passed if it was skipped or could not run.
+- Do not invent changes or perform cosmetic refactors when no substantive work
+  is needed. If the assigned task or verification demonstrates that state is already
+  correct, report the finding and leave files unmodified.
 
 <!-- SYNC-CORE:END -->
 

package/README.md

@@ -17,7 +17,7 @@ You can also run local checks without connecting an agent provider.
 `agentctl repair` explicitly for repair workflows. Provider output and passing
 checks still need review before merging.
 
-The current release is **v0.75.0**, a pre-1.0 release. A long-term stability policy is a
+The current release is **v0.75.2**, a pre-1.0 release. A long-term stability policy is a
 [v1.0 goal](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/ROADMAP_V1.md).
 
 ## Quickstart
@@ -111,6 +111,7 @@ For direct `agentctl` commands, install globally with
 
 | Goal | Command |
 | --- | --- |
+| Interactive terminal navigation | `agentctl menu` (or `agentctl -i`) |
 | Inspect provider setup | `agentctl providers` |
 | Create a scoped task | `agentctl task create` |
 | Preview queued work | `agentctl queue --dry-run` |
@@ -153,6 +154,7 @@ and [SDK/MCP integration](https://github.com/FullThrottle83/jules-orchestrator-k
 
 | Command | Description |
 | --- | --- |
+| `menu` | Interactive terminal navigation hub; browse commands and launch workflows without typing arguments. |
 | `dashboard` | Local telemetry viewer; default port 4100. Set another port with `--port <n>`. |
 
 
@@ -174,7 +176,7 @@ npm run package-integrity
 npm run guard-reach
 ```
 
-The recorded baseline is **1650 unit tests across 210 suites**. Doc-sync compares
+The recorded baseline is **1670 unit tests across 210 suites**. Doc-sync compares
 that count with an actual run. Counts do not establish correctness for every
 provider or project. See
 [contributing](https://github.com/FullThrottle83/jules-orchestrator-kit/blob/main/CONTRIBUTING.md)

package/bin/agentctl.mjs

@@ -272,8 +272,8 @@ async function main() {
   if (!command) {
     if (args.includes("-i") || args.includes("--interactive")) {
       const { runTuiMenu } = await import("../src/ops/tui-menu.mjs");
-      await runTuiMenu(resolveRoot());
-      process.exit(0);
+      const res = await runTuiMenu(resolveRoot());
+      process.exit(res?.code || (res?.headless ? 1 : 0));
     }
     const { resolveNextStep, renderNextStep } = await import("../src/ops/next-step.mjs");
     const cwd = process.cwd();
@@ -343,6 +343,7 @@ async function main() {
           "require-plan-approval": { type: "boolean" },
           "auto-approve-plans": { type: "boolean" },
           "auto-approve": { type: "boolean" },
+          "auto-reply": { type: "boolean" },
           "check-premise": { type: "boolean" },
           "goal-check": { type: "string" },
           idempotent: { type: "boolean" },
@@ -396,6 +397,7 @@ async function main() {
       }
 
       const autoApprove = Boolean(values["auto-approve-plans"] || values["auto-approve"]);
+      const autoReply = Boolean(values["auto-reply"] || values.autoReply);
       const task = {
         title: values.title || "CLI Dispatch Task",
         prompt: promptContent,
@@ -406,6 +408,8 @@ async function main() {
         repoless: values.repoless,
         autoPr: values["auto-pr"],
         requirePlanApproval: autoApprove ? false : values["require-plan-approval"],
+        autoApprovePlan: autoApprove,
+        autoReply,
         checkPremise: values["check-premise"] || values.idempotent,
         goalCheck: values["goal-check"],
         author: values.author,
@@ -421,6 +425,8 @@ async function main() {
           source: values.source,
           branch: values.branch,
           checkPremise: values["check-premise"] || values.idempotent,
+          autoApprovePlan: autoApprove,
+          autoReply,
         });
         if (values.json) {
           console.log(JSON.stringify({ ok: true, session }, null, 2));
@@ -491,6 +497,7 @@ async function main() {
         args: args.slice(1),
         options: {
           base: { type: "string", short: "b" },
+          head: { type: "string" },
           mode: { type: "string", short: "m", default: "working-tree" },
           "working-tree": { type: "boolean" },
           staged: { type: "boolean" },
@@ -526,6 +533,7 @@ async function main() {
         root,
         config,
         base: values.base,
+        head: values.head,
         mode: selectedMode,
         fix: values.fix,
         allowProtected: values["allow-protected"],
@@ -1018,6 +1026,8 @@ async function main() {
           cmd: { type: "string", short: "c" },
           task: { type: "boolean", short: "t" },
           author: { type: "string" },
+          "auto-approve": { type: "boolean" },
+          "auto-reply": { type: "boolean" },
           json: { type: "boolean", short: "j" },
           "dry-run": { type: "boolean" },
         },
@@ -1069,7 +1079,13 @@ async function main() {
         }
         const repairRes = await repair(
           { stderr: cleanTrace, command: values.cmd || "verify" },
-          { root, dryRun: values["dry-run"], author: values.author }
+          {
+            root,
+            dryRun: values["dry-run"],
+            author: values.author,
+            autoApprove: values["auto-approve"],
+            autoReply: values["auto-reply"],
+          }
         );
 
         if (values.json) {
@@ -1388,24 +1404,29 @@ async function main() {
       } else {
         files = queueEntries.filter((f) => isTaskFile(f, queueDir));
       }
-      console.log(`Found ${files.length} queued task(s) in .agent/jules-queue/`);
-      if (files.length > 0) {
-        const concurrency = values.concurrency ? Number(values.concurrency) : undefined;
-        const results = await run(null, {
-          root,
-          config,
-          dag: values.dag,
-          concurrency,
-          dryRun: values["dry-run"],
-        });
+      if (!values.json) {
+        console.log(`Found ${files.length} queued task(s) in .agent/jules-queue/`);
+      }
+      if (files.length === 0) {
         if (values.json) {
-          console.log(JSON.stringify(results, null, 2));
-          const anyFailed = (results.results || []).some((r) => r && r.ok === false);
-          process.exit(anyFailed ? 1 : 0);
+          console.log(JSON.stringify({ ok: true, processed: 0, results: [], dryRun: Boolean(values["dry-run"]) }, null, 2));
         }
-        process.exit(reportRunOutcome(results));
+        process.exit(0);
       }
-      process.exit(0);
+      const concurrency = values.concurrency ? Number(values.concurrency) : undefined;
+      const results = await run(null, {
+        root,
+        config,
+        dag: values.dag,
+        concurrency,
+        dryRun: values["dry-run"],
+      });
+      if (values.json) {
+        console.log(JSON.stringify(results, null, 2));
+        const anyFailed = (results.results || []).some((r) => r && r.ok === false);
+        process.exit(anyFailed ? 1 : 0);
+      }
+      process.exit(reportRunOutcome(results));
       break;
     }
 
@@ -1881,7 +1902,7 @@ async function main() {
     case "ci": {
       const sub = args[1];
       if (sub !== "init") {
-        console.error(`❌ Unknown 'ci' action '${sub || ""}'. Usage: agentctl ci init [--target github|gitlab] [--force]`);
+        console.error(`❌ Unknown 'ci' action '${sub || ""}'. Usage: agentctl ci init [--target github|gitlab] [--force] [--with-automerge]`);
         process.exit(2);
       }
       const { values } = parseArgs({
@@ -1891,6 +1912,7 @@ async function main() {
           force: { type: "boolean", short: "f" },
           "dry-run": { type: "boolean", short: "d" },
           json: { type: "boolean", short: "j" },
+          "with-automerge": { type: "boolean" },
         },
         allowPositionals: true,
       });
@@ -1902,6 +1924,7 @@ async function main() {
         config,
         version: VERSION,
         stack: detectStack(root),
+        withAutomerge: values["with-automerge"],
       });
 
       if (values.json) {
@@ -1912,9 +1935,13 @@ async function main() {
         console.error(`❌ ${res.error}`);
         process.exit(1);
       }
-      console.log(`✅ ${res.written ? "Wrote" : "Would write"} ${res.file}`);
+      const filesDesc = Array.isArray(res.files) ? res.files.join(", ") : res.file;
+      console.log(`✅ ${res.written ? "Wrote" : "Would write"} ${filesDesc}`);
       console.log(`   Stack: ${res.stack} · runtime setup: ${res.setupSummary}`);
       console.log(`   The workflow runs: agentctl check --mode committed`);
+      if (values["with-automerge"]) {
+        console.log(`   Auto-merge: enabled for authorized agent pull requests via workflow_run`);
+      }
       if (!res.written && !values["dry-run"]) {
         console.log(`   (unchanged — pass --force to overwrite)`);
       }
@@ -2011,12 +2038,13 @@ async function main() {
       break;
     }
 
+    case "hub":
     case "menu":
     case "tui":
     case "ui": {
       const { runTuiMenu } = await import("../src/ops/tui-menu.mjs");
-      await runTuiMenu(root);
-      process.exit(0);
+      const res = await runTuiMenu(root);
+      process.exit(res?.code || (res?.headless ? 1 : 0));
       break;
     }
 
@@ -2175,7 +2203,7 @@ async function main() {
 
     case "task": {
       const subCommand = args[1] || "create";
-      if (subCommand === "create") {
+      if (subCommand === "create" || subCommand === "new") {
         const { values, positionals } = parseArgs({
           args: args.slice(2),
           options: {
@@ -2436,7 +2464,7 @@ async function main() {
 
         process.exit(result.ok ? 0 : 1);
       } else {
-        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create, agentctl task optimize, agentctl task template, agentctl task validate`);
+        console.error(`Unknown task subcommand '${subCommand}'. Supported: agentctl task create (or task new), agentctl task optimize, agentctl task template, agentctl task validate`);
         process.exit(1);
       }
       break;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.75.0",
-  "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for autonomous coding agents \u2014 Google Jules, Claude Code, Codex and Gemini CLI.",
+  "version": "0.75.2",
+  "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for autonomous coding agents — Google Jules, Claude Code, Codex and Gemini CLI.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/FullThrottle83/jules-orchestrator-kit.git"

package/scripts/ci-scope-guard.mjs

@@ -16,7 +16,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { checkScope } from "../src/security.mjs";
-import { normalizePath } from "../src/config.mjs";
+import { normalizePath, canonicalizePath } from "../src/config.mjs";
 
 /** Exit code 3 in the kit's registry: scope violation. */
 const EXIT_SCOPE_VIOLATION = 3;
@@ -74,36 +74,132 @@ export function loadProtectedPatterns(opts = {}) {
   );
 }
 
+/** Where a symlink at `link` pointing at `target` lands, as a repo-relative or absolute path. */
+export function resolveLinkTarget(link, target) {
+  const normLink = normalizePath(link);
+  const normTarget = normalizePath(target);
+  if (normTarget.startsWith("/") || /^[a-zA-Z]:[/\\]/.test(target)) {
+    return normTarget;
+  }
+  const linkDir = normLink.split("/").slice(0, -1).join("/");
+  return canonicalizePath(linkDir ? `${linkDir}/${normTarget}` : normTarget);
+}
+
+/**
+ * Parses `git diff --raw -z` output into structured file change entries.
+ *
+ * Each record emitted by `--raw -z` is:
+ *   ":<srcmode> <dstmode> <srcsha> <dstsha> <status>\0<path>\0"
+ * (or two paths if renames were enabled). With `--no-renames`, it is always 1 path.
+ *
+ * For symlinks (mode 120000), retrieves the link target blob via `git cat-file blob <dstSha>`
+ * without checking out the branch to disk.
+ *
+ * @param {string} raw - raw stdout from git diff --raw -z
+ * @param {string} [root] - repo root cwd
+ * @returns {Array<{ file: string, srcMode: string, dstMode: string, srcSha: string, dstSha: string, status: string, symlinkTarget?: string, symlinkUnreadable?: boolean }>}
+ */
+export function parseRawDiffEntries(raw, root = process.cwd()) {
+  if (!raw || typeof raw !== "string") return [];
+  const fields = raw.split("\0").filter((f) => f !== "");
+  const entries = [];
+
+  for (let i = 0; i < fields.length; i++) {
+    const meta = fields[i];
+    if (!meta.startsWith(":")) continue;
+    const parts = meta.slice(1).split(/\s+/);
+    const file = fields[i + 1];
+    i += 1;
+    if (!file) continue;
+
+    const srcMode = parts[0] || "";
+    const dstMode = parts[1] || "";
+    const srcSha = parts[2] || "";
+    const dstSha = parts[3] || "";
+    const status = (parts[4] || "").charAt(0);
+
+    let symlinkTarget = null;
+    let symlinkUnreadable = false;
+
+    if (dstMode === "120000") {
+      if (dstSha && !/^0+$/.test(dstSha)) {
+        try {
+          const rawTarget = execFileSync("git", ["cat-file", "blob", dstSha], {
+            cwd: root,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+          }).trim();
+          if (rawTarget) {
+            symlinkTarget = resolveLinkTarget(file, rawTarget);
+          } else {
+            symlinkUnreadable = true;
+          }
+        } catch (_) {
+          symlinkUnreadable = true;
+        }
+      } else {
+        symlinkUnreadable = true;
+      }
+    }
+
+    entries.push({
+      file: normalizePath(file),
+      srcMode,
+      dstMode,
+      srcSha,
+      dstSha,
+      status,
+      symlinkTarget,
+      symlinkUnreadable,
+    });
+  }
+
+  return entries;
+}
+
 /**
  * Lists the paths a pull request changes.
  *
- * `-z` and `core.quotePath=false` matter here: without them git splits on
- * whitespace and octal-escapes non-ASCII names, so `docs/min plan.md` and
- * `säkerhet/nyckel.pem` arrive as tokens that match no pattern — a protected
- * file walking past the guard because of how it is spelled.
+ * Inspects `git diff --raw -z --no-renames` to capture all paths while
+ * preserving spaces and non-ASCII characters without quoting corruption.
  *
  * @param {{ baseSha: string, headSha: string, root?: string }} opts
  * @returns {string[]}
  */
 export function listChangedFiles(opts = {}) {
+  return listChangedEntries(opts).map((e) => e.file);
+}
+
+/**
+ * Returns raw diff entries including blob mode and symlink resolution.
+ *
+ * @param {{ baseSha: string, headSha: string, root?: string }} opts
+ * @returns {Array<{ file: string, srcMode: string, dstMode: string, srcSha: string, dstSha: string, status: string, symlinkTarget?: string, symlinkUnreadable?: boolean }>}
+ */
+export function listChangedEntries(opts = {}) {
   const root = opts.root || process.cwd();
   const raw = execFileSync(
     "git",
-    ["-c", "core.quotePath=false", "diff", "-z", "--name-only", opts.baseSha, opts.headSha],
+    ["-c", "core.quotePath=false", "diff", "-z", "--raw", "--no-renames", opts.baseSha, opts.headSha],
     { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 10 * 1024 * 1024 }
   );
-  return raw.split("\0").map(normalizePath).filter(Boolean);
+  return parseRawDiffEntries(raw, root);
 }
 
 /**
  * Pure evaluation core, so the decision is testable without a git repository.
  *
- * @param {string[]} files
+ * Evaluates changed files and entries against protected patterns:
+ * - Rejects Git submodules (mode 160000)
+ * - Evaluates symlinks (mode 120000): rejects traversal / root escape, fails closed on unreadable targets,
+ *   and fails if the resolved symlink target points to a protected file.
+ *
+ * @param {Array<string|object>} filesOrEntries
  * @param {string[]} patterns
- * @param {{ labels?: string[] }} [opts]
+ * @param {{ labels?: string[], headSha?: string, symlinks?: Array<{ link: string, target: string }> }} [opts]
  * @returns {{ ok: boolean, bypassed: boolean, violations: Array<object> }}
  */
-export function evaluateScopeGuard(files = [], patterns = [], opts = {}) {
+export function evaluateScopeGuard(filesOrEntries = [], patterns = [], opts = {}) {
   const labels = (opts.labels || []).map((l) => String(l).toLowerCase().trim());
   const headSha = String(opts.headSha || "").trim().toLowerCase();
 
@@ -118,12 +214,88 @@ export function evaluateScopeGuard(files = [], patterns = [], opts = {}) {
     bypassed = labels.includes(BYPASS_LABEL) || labels.includes(LEGACY_BYPASS_LABEL);
   }
 
+  const normalizedEntries = [];
+  for (const item of filesOrEntries) {
+    if (typeof item === "string") {
+      normalizedEntries.push({ file: item });
+    } else if (item && typeof item === "object") {
+      normalizedEntries.push(item);
+    }
+  }
+
+  if (Array.isArray(opts.symlinks)) {
+    for (const s of opts.symlinks) {
+      if (s && s.link) {
+        normalizedEntries.push({
+          file: s.link,
+          dstMode: "120000",
+          symlinkTarget: s.target || null,
+        });
+      }
+    }
+  }
+
+  const explicitViolations = [];
+  const scopeCandidates = [];
+  const symlinkTargetOf = new Map();
+
+  for (const entry of normalizedEntries) {
+    const file = entry.file || "";
+    if (file) {
+      scopeCandidates.push(file);
+    }
+
+    // 1. Refuse Git submodules (mode 160000)
+    if (entry.dstMode === "160000") {
+      explicitViolations.push({
+        file,
+        reason: "Git submodule (mode 160000) is forbidden in agent pull requests",
+        rule: "deny",
+        pattern: "<submodule>",
+      });
+      continue;
+    }
+
+    // 2. Inspect Symlinks (mode 120000)
+    if (entry.dstMode === "120000") {
+      if (entry.symlinkUnreadable || !entry.symlinkTarget) {
+        explicitViolations.push({
+          file,
+          reason: "Unreadable or empty symlink target cannot be verified",
+          rule: "deny",
+          pattern: "<unreadable-symlink>",
+        });
+        continue;
+      }
+
+      const target = entry.symlinkTarget;
+      scopeCandidates.push(target);
+      symlinkTargetOf.set(target, file);
+    }
+  }
+
   // Matching always runs at full strength; the label only decides whether a
   // match blocks. Passing `allowProtected` into checkScope instead would make
   // a bypassed run report zero violations, and the job log is the record of
   // what a human waved through.
-  const res = checkScope(files, { protect: patterns }, { allowProtected: false });
-  return { ok: bypassed || res.ok, bypassed, violations: res.violations };
+  const res = checkScope(scopeCandidates, { protect: patterns }, { allowProtected: false });
+
+  const mappedScopeViolations = (res.violations || []).map((v) => {
+    const link = symlinkTargetOf.get(v.file);
+    if (link) {
+      return {
+        ...v,
+        link,
+        file: link,
+        target: v.file,
+        reason: `Symlink "${link}" -> "${v.file}": ${v.reason}`,
+      };
+    }
+    return v;
+  });
+
+  const allViolations = [...explicitViolations, ...mappedScopeViolations];
+  return { ok: bypassed || allViolations.length === 0, bypassed, violations: allViolations };
 }
 
 /**
@@ -157,21 +329,29 @@ function main() {
   }
 
   let patterns;
-  let files;
+  let entries = [];
   try {
     patterns = loadProtectedPatterns({ baseSha, baseRef, root });
-    files = listChangedFiles({ baseSha, headSha, root });
+    entries = listChangedEntries({ baseSha, headSha, root });
   } catch (err) {
     console.error(`::error::Agent Scope Guard could not evaluate this pull request: ${err.message}`);
     process.exit(EXIT_ERROR);
   }
 
   const labels = parseLabels(process.env.PR_LABELS);
-  const result = evaluateScopeGuard(files, patterns, { labels, headSha });
+  const result = evaluateScopeGuard(entries, patterns, { labels, headSha });
 
   console.log(`Protected patterns (${patterns.length}): ${patterns.join(", ")}`);
-  console.log(`Changed files (${files.length}):`);
-  for (const f of files) console.log(`  ${f}`);
+  console.log(`Changed files (${entries.length}):`);
+  for (const e of entries) {
+    if (e.dstMode === "120000") {
+      console.log(`  ${e.file} -> ${e.symlinkTarget || "(unresolved)"} [symlink]`);
+    } else if (e.dstMode === "160000") {
+      console.log(`  ${e.file} [submodule]`);
+    } else {
+      console.log(`  ${e.file}`);
+    }
+  }
 
   const labelName = headSha ? `${BYPASS_LABEL}:${headSha}` : BYPASS_LABEL;
   const legacyLabelName = headSha ? `${LEGACY_BYPASS_LABEL}:${headSha}` : LEGACY_BYPASS_LABEL;

package/scripts/run-tests.mjs

@@ -101,18 +101,22 @@ function reap(signal = "SIGKILL") {
 
 // Ctrl-C, a CI cancellation and a harness teardown all arrive as signals; each
 // must take the tree with it rather than detaching it from its parent.
+let shuttingDown = false;
 for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
   process.on(sig, () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
     reap("SIGTERM");
     // Give the group a moment to unwind, then make sure.
     setTimeout(() => {
       reap("SIGKILL");
-      process.exit(130);
+      process.exit(sig === "SIGINT" ? 130 : 143);
     }, 2000).unref();
   });
 }
 
 child.on("exit", (code, signal) => {
+  if (shuttingDown) return;
   // Stragglers outlive a clean exit too: a test that spawned a server and
   // failed before its teardown leaves it running.
   reap("SIGKILL");