jules-orchestrator-kit 0.54.1 → 0.56.0

package/README.md

@@ -110,6 +110,7 @@ repository rather than from a template.
 
 | What differs | How it is resolved | Inspect / override |
 | :--- | :--- | :--- |
+| **Which suites to run** | A monorepo change resolves to the sub-projects it touches (`verify.scope: affected`), widening back to the root command as soon as it reaches a shared file. Off by default, on for repositories `init` detects as monorepos. | `agentctl check --json` · `verify.scope` in `.agent/config.yml` |
 | **The stack** | `detectStack()` recognises 24+ ecosystems (Cargo, Go, Python/Django, Maven/Gradle, .NET, PHP/Laravel, Ruby, Elixir, Swift, Flutter/Dart, CMake, Bun, Deno, Node + Turbo/pnpm/Nx workspaces) and derives the setup, lint, test and build commands from the manifest it finds. | `agentctl doctor` · `verify:` in `.agent/config.yml` |
 | **The agent** | `provider:` selects Google Jules (hosted REST), the Claude Code CLI, the Codex CLI or the Gemini CLI. Readiness means a credential for the hosted one and a binary on `PATH` for the local ones — never both. | `agentctl providers` · `agentctl init --provider <name>` |
 | **How hard to verify** | `verify.profile` expands at load time into a stage pipeline that skips gates the runtime cannot support, and says which and why. | `agentctl profile` · `agentctl profile --set max` |
@@ -198,11 +199,12 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **Cross-Platform Parity:** Verified 100% green across Linux, macOS (Darwin), and Windows on Node 20, 22, and 24.
 * **Autonomous Self-Healing Loop:** Captures test stderr/stdout, fingerprints error traces, and feeds structured context back into automated repair turns (up to 3 attempts) before human escalation.
 * **Fail-Closed Verification:** A change that ran no verification command at all is rejected, not approved — "nothing to run" is not a pass. Repositories using only the scope and secret phases opt out explicitly with `verify.required: false`.
+* **Anti-Tamper That Reads Semantics:** Counting assertions cannot see a value check swapped for a truthiness check. The guard tracks assertions that name an expected value, so weakening a test is a violation even when the line count is unchanged.
 * **Binary-Aware Scanning:** Files git renders as `Binary files ... differ` are read directly for structured credentials, and their real size is charged against the diff ceiling, so a leading NUL byte cannot hide a token and a committed blob cannot walk past the payload governor.
 * **Fail-Closed Security & Secret Redaction:** Evaluates explicit Deny rules before Allow rules against canonicalized, case-folded paths. Redacts high-entropy keys and base64-encoded credentials (such as Kubernetes `Secret` manifests).
 * **Complexity & Cost Router:** Zero-dependency heuristic classifier (`src/router.mjs`) routing mechanical tasks to lightweight models while reserving primary models for complex refactors, with a `node --check` syntax-verification gate that transparently escalates a FAST-tier result to the primary provider if it left broken JS on disk.
 * **Terminal UI & Diagnostic Matrix (`agentctl doctor`):** Interactive terminal dashboard, task sidecar manager, and automated transactional self-repair.
-* **Verified Test Suite:** Tested with **835 unit tests across 109 suites passing in < 14.0s**.
+* **Verified Test Suite:** Tested with **851 unit tests across 115 suites passing in < 14.0s**.
 
 <br/>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.54.1",
+  "version": "0.56.0",
   "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",

package/scripts/run-tests.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { cpus } from "node:os";
 
 const root = process.cwd();
 const testDir = join(root, "test");
@@ -24,10 +25,84 @@ const [major, minor] = process.versions.node.split(".").map(Number);
 const supportsTestTimeout = major > 20 || (major === 20 && minor >= 6);
 const timeoutArgs = supportsTestTimeout ? [`--test-timeout=${timeoutMs}`] : [];
 
-const res = spawnSync(process.execPath, ["--test", ...timeoutArgs, ...testFiles], {
+// Node runs one test file per core by default. Several suites here spawn a
+// verification command of their own — `npm test`, and in the monorepo fixtures
+// an `npm test --workspaces` that fans out to one node per package — so the
+// real peak is a multiple of the file count, not the file count. On a
+// twelve-core laptop that saturates every core for the length of the run,
+// which cooks the machine and makes the throughput assertions (1000 telemetry
+// appends under 6s) fail for reasons that have nothing to do with the code.
+//
+// Half the cores keeps the suite comfortably parallel while leaving room for
+// the children it spawns. JULES_TEST_CONCURRENCY overrides it — CI runners
+// with two cores are already below this and are unaffected.
+const cpuCount = Math.max(1, cpus().length);
+const envConcurrency = Number(process.env.JULES_TEST_CONCURRENCY);
+const concurrency = Number.isFinite(envConcurrency) && envConcurrency > 0
+  ? Math.floor(envConcurrency)
+  : Math.max(2, Math.floor(cpuCount / 2));
+const concurrencyArgs = supportsTestTimeout ? [`--test-concurrency=${concurrency}`] : [];
+
+// The runner leads its own process group, and nothing outlives it.
+//
+// `spawnSync` kills only the direct child when a run is interrupted, and this
+// suite's children spawn children of their own — a verification command, an
+// `npm` that fans out to a node per workspace, a git subprocess per fixture.
+// Interrupting a run therefore orphaned everything below the first level, and
+// those orphans kept running and kept spawning: a laptop accumulated enough of
+// them across several interrupted runs to exhaust 32 GB of RAM and 24 GB of
+// swap, and two CI runners logged pages of "Terminate orphan process" at the
+// end of a job that had already failed.
+//
+// Detaching makes the child a process-group leader, so one signal to the
+// negated pid reaches the whole tree.
+const child = spawn(process.execPath, ["--test", ...timeoutArgs, ...concurrencyArgs, ...testFiles], {
   cwd: root,
   stdio: "inherit",
   env: process.env,
+  detached: process.platform !== "win32",
+});
+
+/**
+ * Kill the runner and everything it spawned.
+ *
+ * POSIX takes a signal to `-pid`, which addresses the whole process group.
+ * Windows has no such concept, so `taskkill /T` walks the tree instead.
+ */
+function reap(signal = "SIGKILL") {
+  if (!child.pid) return;
+  try {
+    if (process.platform === "win32") {
+      spawnSync("taskkill", ["/T", "/F", "/PID", String(child.pid)], { stdio: "ignore" });
+    } else {
+      process.kill(-child.pid, signal);
+    }
+  } catch (_) {
+    // Already gone, or never had a group. Nothing left to reap either way.
+  }
+}
+
+// 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.
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => {
+    reap("SIGTERM");
+    // Give the group a moment to unwind, then make sure.
+    setTimeout(() => {
+      reap("SIGKILL");
+      process.exit(130);
+    }, 2000).unref();
+  });
+}
+
+child.on("exit", (code, signal) => {
+  // Stragglers outlive a clean exit too: a test that spawned a server and
+  // failed before its teardown leaves it running.
+  reap("SIGKILL");
+  process.exit(signal ? 1 : code ?? 1);
 });
 
-process.exit(res.status ?? 1);
+child.on("error", (err) => {
+  console.error(`Test runner failed to start: ${err.message}`);
+  process.exit(1);
+});

package/src/config.mjs

@@ -522,6 +522,13 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     teardown: rawTeardown ?? autoVerify.teardown ?? "",
     build: rawBuild ?? autoVerify.build,
     policy: parsed.verify?.policy ?? autoVerify.policy,
+    // "global" runs the repository's own verify commands; "affected" resolves
+    // the changed files to their sub-projects and runs only those suites. Opt-in
+    // on purpose: silently narrowing which tests run is the same class of defect
+    // as approving a change that ran none, and an existing repository's gate
+    // must not change meaning on an upgrade. `agentctl init` writes "affected"
+    // for a repository it detects as a monorepo.
+    scope: parsed.verify?.scope === "affected" ? "affected" : "global",
     // Whether the gate may approve a change that ran no verification at all.
     // True by default: "nothing to run" is not a pass, and a security tool that
     // says APPROVED after checking nothing is worse than no tool. A repository

package/src/engine.mjs

@@ -1,6 +1,6 @@
 import { loadConfig, parseYaml, normalizeScope } from "./config.mjs";
 import { checkScope, scanDiff, scanBinaryPayloads, redactSecrets } from "./security.mjs";
-import { changedFiles, diffBytes, diffText, binaryDiffEntries, showFromOrigin, runCmd } from "./git.mjs";
+import { changedFiles, diffBytes, diffText, binaryDiffEntries, symlinkChanges, showFromOrigin, runCmd } from "./git.mjs";
 import { createProvider, ProviderRateLimitError, ProviderUnavailableError } from "./provider.mjs";
 import { resolveRoutedProvider } from "./router.mjs";
 import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReservation, isConcurrencyGroupLocked, checkDailyBudget } from "./state.mjs";
@@ -20,6 +20,7 @@ import { resolveRolePrompt } from "./role-resolver.mjs";
 
 import { runAssertion } from "./assertions.mjs";
 import { buildDefaultStages } from "./profiles.mjs";
+import { resolveWorkspaceBoundary } from "./stack-detector.mjs";
 import {
   computeDirectoryHash,
   generateEvidenceManifest,
@@ -201,6 +202,7 @@ export async function gate(opts = {}) {
           // Read from the base commit like every other trusted field: an
           // uncommitted `required: false` must not be able to switch the gate off.
           required: parsed.verify?.required !== undefined ? parsed.verify.required !== false : config.verify.required !== false,
+          scope: parsed.verify?.scope || config.verify.scope || "global",
           timeoutMs: parsed.verify?.timeoutMs || parsed.verify?.timeout_ms || config.verify.timeoutMs,
         };
       }
@@ -213,9 +215,37 @@ export async function gate(opts = {}) {
     }
   }
 
-  const scopeResult = checkScope(files, trustedScope, {
+  // A symlink is judged by its own name, so `notes.md -> .agent/config.yml`
+  // walked straight past a deny list that names the target. Judge both: the
+  // link because it is what the diff adds, and the path it resolves to because
+  // that is what it grants reach to.
+  let symlinks = [];
+  try {
+    symlinks = symlinkChanges(root, base, mode);
+  } catch (_) {
+    // Scope must still be enforced on the ordinary file list if git cannot
+    // describe the links.
+  }
+  const scopeCandidates = [...files];
+  const symlinkTargetOf = new Map();
+  for (const { link, target } of symlinks) {
+    if (!target || scopeCandidates.includes(target)) continue;
+    scopeCandidates.push(target);
+    symlinkTargetOf.set(target, link);
+  }
+
+  const scopeResult = checkScope(scopeCandidates, trustedScope, {
     allowProtected: opts.allowProtected || process.env.JULES_ALLOW_COMMAND_FILE_CHANGES === "true",
   });
+  // Report the violation against the link the change actually introduced, not
+  // against a path the diff never names — the operator has to be able to find it.
+  for (const violation of scopeResult.violations || []) {
+    const link = symlinkTargetOf.get(violation.file);
+    if (!link) continue;
+    violation.reason = `${violation.reason} (reached through symlink ${link})`;
+    violation.symlink = link;
+    violation.file = link;
+  }
 
   phases.push({ phase: "scope", ok: scopeResult.ok, violations: scopeResult.violations });
   appendTelemetry(root, "gate_phase", { phase: "scope", ok: scopeResult.ok });
@@ -291,9 +321,52 @@ export async function gate(opts = {}) {
     NODE_OPTIONS: guardNodeOptions,
   };
 
+  // Node's test runner talks to its children through NODE_TEST_CONTEXT and
+  // NODE_CHANNEL_FD. Inherited by a verification command that is itself a
+  // `node --test` run, the child switches into child-reporter mode and its
+  // failures stop reaching the exit code — the gate then sees exit 0 and
+  // approves a change whose tests failed. src/perf.mjs already strips these for
+  // the same reason; the gate, which is the one that decides, did not.
+  for (const key of Object.keys(testEnv)) {
+    if (key.startsWith("NODE_TEST_") || key.startsWith("NODE_CHANNEL_")) delete testEnv[key];
+  }
+
   let flakyVerdictResult = null;
   const verifyTimeout = trustedVerify.timeoutMs || 60000;
 
+  // Monorepo scoping: run the suites the change can actually break.
+  //
+  // `resolveWorkspaceBoundary()` shipped, was drawn in the architecture
+  // diagrams and documented as a headline feature — and was called by nothing.
+  // Every change in a monorepo ran the root suite, so a one-package edit was
+  // gated on every other package's tests. It resolves the changed files to
+  // their sub-projects and composes the per-project commands.
+  //
+  // It stays opt-in (`verify.scope: affected`) because narrowing what runs is
+  // only safe when someone asked for it, and it yields to the global command
+  // whenever a shared file is touched or no sub-project command is found — a
+  // narrower run that misses the breakage is worse than a slow one.
+  let boundary = null;
+  if (trustedVerify.scope === "affected" && !(Array.isArray(trustedVerify.stages) && trustedVerify.stages.length > 0)) {
+    try {
+      boundary = resolveWorkspaceBoundary(files, root);
+    } catch (_) {
+      boundary = null;
+    }
+    if (boundary && boundary.isMonorepo && !boundary.globalFallback && boundary.testCmd) {
+      trustedVerify = {
+        ...trustedVerify,
+        test: boundary.testCmd,
+        unit: boundary.testCmd,
+        build: boundary.buildCmd || trustedVerify.build,
+      };
+      appendTelemetry(root, "verify_scope_narrowed", {
+        projects: boundary.projects.map((p) => p.path),
+        testCmd: boundary.testCmd,
+      });
+    }
+  }
+
   // Build sequential execution pipeline (Setup -> Lint -> Test/Unit -> Fuzz -> Invariant -> E2E -> Build -> Server -> Teardown)
   const stagesToRun = [];
   if (Array.isArray(trustedVerify.stages) && trustedVerify.stages.length > 0) {
@@ -966,6 +1039,33 @@ export async function dispatch(task = {}, opts = {}) {
 
   const cleanTask = { ...task, prompt: envelopedPrompt };
 
+  // Snapshot the tree before anything can change it.
+  //
+  // `agentctl rollback` shipped, was documented, and could never work:
+  // createCheckpoint() was defined and called from nowhere, so the checkpoint
+  // directory was always empty and the command answered "No checkpoints found"
+  // to everyone who reached for it — at exactly the moment they needed it. An
+  // exec provider edits this working tree directly, and `patch --apply` writes
+  // into it later, so this is the last moment the pre-agent state exists.
+  //
+  // Never fatal: a repository that cannot be snapshotted (no git, no disk) must
+  // still be able to dispatch. A missing checkpoint costs a rollback; a throw
+  // here costs the task.
+  if (!opts.dryRun && opts.checkpoint !== false) {
+    try {
+      const { createCheckpoint } = await import("./ops/checkpoint.mjs");
+      const checkpointId = String(task.id || task.taskId || `dispatch-${Date.now()}`).replace(/[^A-Za-z0-9_.-]/g, "-");
+      const snapshot = createCheckpoint(checkpointId, { root });
+      appendTelemetry(root, "checkpoint_created", {
+        id: snapshot.id,
+        headSha: snapshot.headSha,
+        uncommittedFiles: snapshot.uncommittedFiles?.length || 0,
+      });
+    } catch (err) {
+      console.warn(`⚠️  Could not create a pre-flight checkpoint (${err.message}). \`agentctl rollback\` will not be able to restore this dispatch.`);
+    }
+  }
+
   const runDispatch = () => provider.dispatch(cleanTask, { root, dryRun: opts.dryRun });
 
   // An estimated ceiling may warn but must not block: refusing a dispatch the

package/src/evidence.mjs

@@ -11,7 +11,7 @@ import {
   renameSync,
   unlinkSync,
 } from "node:fs";
-import { join, resolve, relative, isAbsolute, sep } from "node:path";
+import { join, resolve, relative, isAbsolute, sep, extname } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { execSync } from "node:child_process";
 
@@ -83,6 +83,19 @@ export function findFilesRecursively(dir, baseDir = dir) {
  * @param {string[]} [options.directories] - Specific directory names to scan (e.g. ['test', 'tests'])
  * @returns {{ treeHash: string, fileCount: number, fileHashes: Record<string, string> }}
  */
+/**
+ * Extensions that count as code when scanning the repository root.
+ *
+ * The directory walk above takes everything under `src/` and the test
+ * directories; this list only governs the loose files beside package.json,
+ * where a `.md` is documentation rather than something the evidence attests to.
+ */
+const SOURCE_EXTENSIONS = new Set([
+  ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts", ".cts",
+  ".py", ".go", ".rs", ".rb", ".php", ".java", ".kt", ".kts", ".cs", ".fs",
+  ".swift", ".dart", ".ex", ".exs", ".c", ".h", ".cc", ".cpp", ".hpp", ".sol",
+]);
+
 export function computeDirectoryHash(root, options = {}) {
   let fileList = [];
 
@@ -100,6 +113,29 @@ export function computeDirectoryHash(root, options = {}) {
         fileList.push(...found);
       }
     }
+
+    // Plenty of projects keep `app.test.mjs` or `index.js` beside package.json
+    // rather than under one of the directories above, and those files were
+    // invisible to every hash computed here — a manifest could attest to a
+    // pristine test suite while the only test in the repository had been
+    // replaced with garbage.
+    //
+    // Depth one only: recursing from the root would walk node_modules and
+    // vendor trees. Source extensions only: the hash exists to bind the
+    // manifest to the code it verified, and pulling in README.md or the
+    // EVIDENCE.md this very command is about to write would make the hash churn
+    // on its own output.
+    try {
+      for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isFile()) continue;
+        if (entry.name.startsWith(".")) continue;
+        if (!SOURCE_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue;
+        fileList.push(normalizePath(entry.name));
+      }
+    } catch (_) {
+      // An unreadable root yields whatever the directory walk already found.
+    }
+
     fileList = Array.from(new Set(fileList)).sort();
   }
 
@@ -154,6 +190,7 @@ export function computeEvidenceHash(manifest) {
     intent: manifest.intent,
     provenance: manifest.provenance,
     testIntegrity: manifest.testIntegrity,
+    ...(manifest.sourceIntegrity ? { sourceIntegrity: manifest.sourceIntegrity } : {}),
     executionRecords: manifest.executionRecords,
     securityChecks: manifest.securityChecks,
     ...(manifest.status ? { status: manifest.status } : {}),
@@ -235,6 +272,7 @@ export function generateEvidenceManifest(root = process.cwd(), options = {}) {
   // Compute test tree integrity
   const preTestHash = options.preTestHash || null;
   const currentTestState = computeDirectoryHash(root, { testOnly: true });
+  const currentSourceState = computeDirectoryHash(root);
   const postTestHash = currentTestState.treeHash;
 
   let tamperDetected = false;
@@ -278,6 +316,14 @@ export function generateEvidenceManifest(root = process.cwd(), options = {}) {
       testFileCount: currentTestState.fileCount,
       fileHashes: currentTestState.fileHashes,
     },
+    // The manifest attested to the test files and to nothing else, so the code
+    // under test could be replaced wholesale after the fact and verification
+    // still passed. Evidence that survives the thing it attests to being
+    // rewritten is not evidence.
+    sourceIntegrity: {
+      treeHash: currentSourceState.treeHash,
+      fileCount: currentSourceState.fileCount,
+    },
     executionRecords: options.executionRecords || [],
     securityChecks: {
       secretScanOk: options.secretScanOk ?? true,
@@ -466,7 +512,28 @@ export function verifyEvidenceManifest(root = process.cwd(), manifestOrPath = "m
     };
   }
 
-  // 3. Verify security checks
+  // 3. Verify the code the manifest attests to still is that code.
+  //
+  // Without this the manifest proved only that the *tests* had not changed,
+  // so `evidence generate` followed by rewriting src/ and committing left
+  // verification reporting PASSED over an implementation nobody had checked.
+  if (manifest.sourceIntegrity?.treeHash) {
+    const currentSourceState = computeDirectoryHash(root);
+    if (currentSourceState.treeHash !== manifest.sourceIntegrity.treeHash) {
+      return {
+        ok: false,
+        reason: `Source tree has changed since this evidence was generated (${manifest.sourceIntegrity.treeHash.slice(0, 12)} → ${currentSourceState.treeHash.slice(0, 12)}); the manifest no longer attests to what is on disk`,
+        details: {
+          currentHash: currentSourceState.treeHash,
+          manifestHash: manifest.sourceIntegrity.treeHash,
+          manifestCommit: manifest.provenance?.commitSha || null,
+          currentCommit: getGitProvenance(root).commitSha,
+        },
+      };
+    }
+  }
+
+  // 4. Verify security checks
   if (manifest.securityChecks?.secretScanOk === false) {
     return { ok: false, reason: "Evidence manifest records secret scanning failure" };
   }

package/src/git.mjs

@@ -1,7 +1,7 @@
 import { execFileSync, execSync } from "node:child_process";
-import { readFileSync, existsSync, statSync } from "node:fs";
+import { readFileSync, existsSync, statSync, readlinkSync } from "node:fs";
 import { join, delimiter } from "node:path";
-import { normalizePath } from "./config.mjs";
+import { normalizePath, canonicalizePath } from "./config.mjs";
 
 
 export const NET_GUARD_PRELOAD_URL = new URL("./preload-net-guard.mjs", import.meta.url).href;
@@ -412,14 +412,14 @@ export function diffText(root = process.cwd(), base = "main", mode = "committed"
  * @param {string} mode
  * @returns {Array<{ file: string, bytes: number }>}
  */
-export function binaryDiffEntries(root = process.cwd(), base = "main", mode = "committed") {
+export function parseRawDiff(root = process.cwd(), base = "main", mode = "committed") {
   const resolvedRef = resolveBase(root, base);
   const ranges =
     mode === "working-tree" || mode === "working"
       ? [[`${resolvedRef}...HEAD`], ["HEAD"]]
       : [[`${resolvedRef}...HEAD`]];
 
-  const entries = new Map();
+  const out = [];
   for (const range of ranges) {
     let raw = "";
     try {
@@ -433,29 +433,99 @@ export function binaryDiffEntries(root = process.cwd(), base = "main", mode = "c
       const meta = fields[i];
       if (!meta.startsWith(":")) continue;
       const parts = meta.slice(1).split(/\s+/);
-      const dstSha = parts[3];
-      const status = (parts[4] || "").charAt(0);
       const file = fields[i + 1];
       i += 1;
-      if (!file || status === "D") continue;
+      if (!file) continue;
+      out.push({
+        file,
+        srcMode: parts[0] || "",
+        dstMode: parts[1] || "",
+        srcSha: parts[2] || "",
+        dstSha: parts[3] || "",
+        status: (parts[4] || "").charAt(0),
+      });
+    }
+  }
+  return out;
+}
 
-      let bytes = 0;
-      if (dstSha && !/^0+$/.test(dstSha)) {
-        const size = git(["cat-file", "-s", dstSha], { cwd: root, ignoreError: true });
-        bytes = Number(size) || 0;
+/**
+ * Symlinks this change introduces, with the path each one points at.
+ *
+ * `checkScope` is purely lexical, by design — the paths it judges can come from
+ * a diff and need not exist on disk. But that made a symlink a hole straight
+ * through it: a link named `notes.md` pointing at `.agent/config.yml` is judged
+ * as `notes.md`, and the protected path it resolves to is never considered.
+ * Resolving here, rather than inside `checkScope`, keeps that function lexical
+ * and testable while letting the gate judge both names.
+ *
+ * The target is resolved lexically against the link's own directory: it may
+ * point outside the repository, and following it on disk would be the wrong
+ * thing to do with an untrusted path.
+ *
+ * @param {string} root
+ * @param {string} base
+ * @param {string} mode
+ * @returns {Array<{ link: string, target: string }>}
+ */
+export function symlinkChanges(root = process.cwd(), base = "main", mode = "committed") {
+  const SYMLINK_MODE = "120000";
+  const results = [];
+  const seen = new Set();
+
+  for (const entry of parseRawDiff(root, base, mode)) {
+    if (entry.status === "D") continue;
+    if (entry.dstMode !== SYMLINK_MODE) continue;
+    if (seen.has(entry.file)) continue;
+    seen.add(entry.file);
+
+    // A symlink's blob content is its target path.
+    let target = "";
+    if (entry.dstSha && !/^0+$/.test(entry.dstSha)) {
+      target = (git(["cat-file", "blob", entry.dstSha], { cwd: root, ignoreError: true }) || "").trim();
+    }
+    if (!target) {
+      try {
+        target = readlinkSync(join(root, entry.file));
+      } catch (_) {
+        continue;
       }
-      // An unstaged change has an all-zero destination sha; the working file is
-      // the only place its size exists.
-      if (!bytes) {
-        try {
-          bytes = statSync(join(root, file)).size;
-        } catch (_) {
-          bytes = 0;
-        }
+    }
+    if (!target) continue;
+
+    const linkDir = normalizePath(entry.file).split("/").slice(0, -1).join("/");
+    const resolved = normalizePath(target).startsWith("/")
+      ? normalizePath(target)
+      : canonicalizePath(linkDir ? `${linkDir}/${target}` : target);
+
+    results.push({ link: entry.file, target: resolved });
+  }
+
+  return results;
+}
+
+export function binaryDiffEntries(root = process.cwd(), base = "main", mode = "committed") {
+  const entries = new Map();
+  for (const entry of parseRawDiff(root, base, mode)) {
+    if (entry.status === "D") continue;
+    const { file, dstSha } = entry;
+
+    let bytes = 0;
+    if (dstSha && !/^0+$/.test(dstSha)) {
+      const size = git(["cat-file", "-s", dstSha], { cwd: root, ignoreError: true });
+      bytes = Number(size) || 0;
+    }
+    // An unstaged change has an all-zero destination sha; the working file is
+    // the only place its size exists.
+    if (!bytes) {
+      try {
+        bytes = statSync(join(root, file)).size;
+      } catch (_) {
+        bytes = 0;
       }
-      // Keep the largest observation: the same path can appear in both ranges.
-      entries.set(file, Math.max(entries.get(file) || 0, bytes));
     }
+    // Keep the largest observation: the same path can appear in both ranges.
+    entries.set(file, Math.max(entries.get(file) || 0, bytes));
   }
 
   // Only the paths git itself refused to render as text are relevant; a file

package/src/provider.mjs

@@ -673,10 +673,17 @@ export function createProvider(spec = "jules", config = {}) {
     },
 
     async getSession(sessionId, ctx = {}) {
-      if (!sessionId || typeof sessionId !== "string") {
+      if (!ctx || typeof ctx !== "object") ctx = {};
+      // `listSources()` reuses this method purely as an authenticated GET, and
+      // passes `customUrl` with no session to fetch. The guard rejected the
+      // empty id before the url was even looked at, so listing a repository's
+      // connected sources threw a TypeError against the live API every time —
+      // a failure no dry-run or unit test could reach, because both stop
+      // before the request. A session id is required only when the url is
+      // going to be built out of one.
+      if (!ctx.customUrl && (!sessionId || typeof sessionId !== "string")) {
         throw new TypeError("getSession() requires a valid sessionId string");
       }
-      if (!ctx || typeof ctx !== "object") ctx = {};
 
       const pool = ctx.tokenPool || config.tokenPool || TokenPool.fromEnv(config);
       const rawToken = pool.getNextToken() || process.env.JULES_API_KEY || (ctx.allowLegacyKey ? process.env.GEMINI_API_KEY : "") || "";

package/src/security.mjs

@@ -1120,6 +1120,24 @@ export function checkTestTampering(diffOrText = "", options = {}) {
   const ASSERTION_PATTERN = /(?:\b(?:assert(?:\.[a-zA-Z0-9_$]+)?|expect|t\.(?:assert|expect|is|equal|true|false|Errorf|Fatalf)|require\.[a-zA-Z0-9_$]+)\b|assert!|assert_eq!|assert_ne!)/i;
   const isCommentLine = (str) => /^\s*(?:\/\/|\/\*|\*|#|--|;)/.test(str);
 
+  // An assertion that states a *specific* expected value. Counting assertions
+  // alone let a test be gutted while looking untouched: swapping
+  // `assert.strictEqual(add(2,3), 5)` for `assert.ok(add(2,3) !== undefined)`
+  // removes one and adds one, so `removed > added` stayed false and the guard
+  // said nothing — while the suite stopped checking the answer.
+  const SPECIFIC_ASSERTION = new RegExp(
+    [
+      "\\bassert(?:\\.strict)?\\.?(?:strictEqual|deepStrictEqual|deepEqual|notStrictEqual|notDeepStrictEqual|equal|notEqual|match|doesNotMatch|throws|rejects|doesNotThrow)\\s*\\(",
+      "\\bexpect\\s*\\([^)]*\\)\\s*\\.(?:toBe|toEqual|toStrictEqual|toMatch|toMatchObject|toContain|toHaveBeenCalledWith|toThrow|toHaveLength|toBeCloseTo)\\s*\\(",
+      "\\bassert\\.(?:equals|deepEquals|include|lengthOf)\\s*\\(",
+      "assert_eq!|assert_ne!",
+      "\\bt\\.(?:Errorf|Fatalf)\\s*\\(",
+      "\\brequire\\.(?:Equal|NotEqual|Len|Contains|Error|NoError)\\s*\\(",
+    ].join("|"),
+    "i"
+  );
+  const isSpecificAssertion = (str) => SPECIFIC_ASSERTION.test(str);
+
   const fileAssertions = new Map();
 
   for (let i = 0; i < lines.length; i++) {
@@ -1151,7 +1169,7 @@ export function checkTestTampering(diffOrText = "", options = {}) {
     }
 
     if (!fileAssertions.has(currentFile)) {
-      fileAssertions.set(currentFile, { removed: [], added: 0 });
+      fileAssertions.set(currentFile, { removed: [], added: 0, removedSpecific: [], addedSpecific: 0 });
     }
     const fileStats = fileAssertions.get(currentFile);
 
@@ -1159,6 +1177,9 @@ export function checkTestTampering(diffOrText = "", options = {}) {
       const deletedText = line.slice(1);
       if (!isCommentLine(deletedText) && ASSERTION_PATTERN.test(deletedText)) {
         fileStats.removed.push({ line: currentOldLineNo, text: deletedText });
+        if (isSpecificAssertion(deletedText)) {
+          fileStats.removedSpecific.push({ line: currentOldLineNo, text: deletedText });
+        }
       }
       if (currentOldLineNo !== null) currentOldLineNo++;
     } else if (line.startsWith("+") && !line.startsWith("+++")) {
@@ -1205,6 +1226,7 @@ export function checkTestTampering(diffOrText = "", options = {}) {
       // If valid non-vacuous, non-commented assertion is added, increment added count
       if (!isVacuous && !isCommented && !isCommentLine(addedText) && ASSERTION_PATTERN.test(addedText)) {
         fileStats.added++;
+        if (isSpecificAssertion(addedText)) fileStats.addedSpecific++;
       }
 
       if (currentNewLineNo !== null) currentNewLineNo++;
@@ -1226,6 +1248,31 @@ export function checkTestTampering(diffOrText = "", options = {}) {
         });
       }
     }
+
+    // Replacing an assertion is not the same as keeping one. Counting totals
+    // let a specific expectation be swapped for a vague one at no cost — one
+    // out, one in, guard silent, suite no longer checking the answer. What must
+    // not fall is the number of assertions that name an expected value.
+    //
+    // Only the *replaced* ones are reported here. An assertion deleted outright
+    // is already an ASSERTION_REMOVAL above, and emitting both would report the
+    // same line twice under two names.
+    const alreadyReportedSpecific = stats.removed
+      .slice(stats.added)
+      .filter((item) => isSpecificAssertion(item.text)).length;
+    const specificLost = Math.max(0, stats.removedSpecific.length - stats.addedSpecific);
+    const weakenedCount = Math.max(0, specificLost - alreadyReportedSpecific);
+
+    if (weakenedCount > 0) {
+      for (const item of stats.removedSpecific.slice(stats.addedSpecific, stats.addedSpecific + weakenedCount)) {
+        violations.push({
+          file,
+          line: item.line,
+          type: "ASSERTION_WEAKENED",
+          reason: `Test Tamper Guard: Assertion weakened in ${file}${item.line ? `:${item.line}` : ""} — an assertion naming an expected value was replaced by one that does not: "${item.text.trim()}"`,
+        });
+      }
+    }
   }
 
   return {

package/src/session-ops.mjs

@@ -160,6 +160,18 @@ export async function applySessionPatch(sessionId, opts = {}) {
 
   // 2. If apply requested, execute git apply
   if (opts.apply) {
+    // Writing an agent's patch into the working tree is the other moment a
+    // rollback target has to exist. The hosted provider works server-side, so
+    // dispatch never touched this tree — this is the first time it changes.
+    if (opts.checkpoint !== false) {
+      try {
+        const { createCheckpoint } = await import("./ops/checkpoint.mjs");
+        createCheckpoint(`patch-${String(sessionId).replace(/[^A-Za-z0-9_.-]/g, "-")}`, { root });
+      } catch (err) {
+        console.warn(`⚠️  Could not snapshot before applying the patch (${err.message}); \`agentctl rollback\` will not cover it.`);
+      }
+    }
+
     const applyRes = spawnSync("git", ["apply", "-"], {
       cwd: root,
       input: res.patch,

package/src/state.mjs

@@ -560,6 +560,40 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
     }
   }
 
+  // The lock file is named after the task, so `existsSync(lockFile)` above only
+  // ever asked "is this same task already running?". The `files` argument — the
+  // whole point of the call — was stored as metadata and never compared against
+  // anything, so two agents could hold locks on the same file at the same time
+  // and each be told it had exclusive access. Check the paths, not just the id.
+  const requested = new Set(
+    (Array.isArray(files) ? files : [])
+      .filter((f) => typeof f === "string" && f)
+      .map((f) => normalizePath(f))
+  );
+  if (requested.size > 0) {
+    for (const held of lockStatus(root)) {
+      if (!held || held.taskId === taskId) continue;
+      const recordedStart = held.processStartTime ?? held.starttime ?? null;
+      const stillHeld =
+        isPidAlive(held.pid, recordedStart) &&
+        !(held.acquiredAt && Date.now() - new Date(held.acquiredAt).getTime() > 7200000);
+      if (!stillHeld) continue;
+
+      const overlap = (Array.isArray(held.files) ? held.files : [])
+        .map((f) => normalizePath(f))
+        .filter((f) => requested.has(f));
+      if (overlap.length > 0) {
+        return {
+          ok: false,
+          holder: held.agent,
+          taskId: held.taskId,
+          pid: held.pid,
+          conflictingFiles: overlap,
+        };
+      }
+    }
+  }
+
   const startTime = getProcessStartTime(process.pid);
   const concurrencyGroup = String(opts?.concurrencyGroup || opts?.concurrency_group || "").trim();
   const payload = {

package/src/wizard-init.mjs

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { parseYaml, TIER_PRESETS, VENDOR_TIERS, FALLBACK_TIER } from "./config.mjs";
 import { suggestProvider, detectAvailableProviders } from "./provider-readiness.mjs";
 import { detectDefaultBranch } from "./git.mjs";
+import { resolveWorkspaceBoundary } from "./stack-detector.mjs";
 import { PROFILE_NAMES, PROFILE_DESCRIPTIONS } from "./profiles.mjs";
 import { detectStackOracles, runVerificationProbe } from "./wizard-oracle.mjs";
 import { select, multiSelect, input, confirm, spinner, isTTY } from "./tui.mjs";
@@ -180,6 +181,21 @@ export function planInit(root = process.cwd(), options = {}) {
   // whose git chose `master`, or whose team standardised on `develop`.
   const baseBranch = options.baseBranch || existingConfig.base_branch || detectDefaultBranch(root);
 
+  // A monorepo that runs every package's suite for a one-package change is the
+  // complaint the boundary resolver was written to answer, so a repository
+  // detected as one starts with it on. Existing repositories keep whatever they
+  // already stated; nobody's gate changes meaning because they upgraded.
+  const detectedMonorepo = (() => {
+    if (options.verifyScope) return options.verifyScope === "affected";
+    if (existingConfig.verify?.scope) return existingConfig.verify.scope === "affected";
+    try {
+      return Boolean(resolveWorkspaceBoundary([], root).isMonorepo);
+    } catch (_) {
+      return false;
+    }
+  })();
+  const verifyScope = detectedMonorepo ? "affected" : "global";
+
   const limitsBlock = isCustomLimits
     ? `\nlimits:\n  concurrency: ${limits.concurrency}\n  daily_tasks: ${limits.daily_tasks}\n  stagger_ms: ${limits.stagger_ms}\n  diff_kb: ${limits.diff_kb}\n`
     : "";
@@ -195,6 +211,9 @@ ${limitsBlock}
 verify:
   # minimal | standard | max  — see: agentctl profile --list
   profile: ${profile}
+  # global runs the repository's own commands; affected resolves changed files
+  # to their sub-projects and runs only those suites (monorepos)
+  scope: ${verifyScope}
   test: "${verify.test}"
   build: "${verify.build}"
   lint: "${verify.lint}"
@@ -236,6 +255,7 @@ allow_paths: ${allowPaths.length > 0 ? "\n" + allowPaths.map((p) => `  - "${p}"`
     provider,
     profile,
     baseBranch,
+    verifyScope,
     verify,
     limits,
     presets: selectedPresets,