jules-orchestrator-kit 0.55.0 → 0.57.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` |
@@ -203,7 +204,7 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **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 **842 unit tests across 112 suites passing in < 14.0s**.
+* **Verified Test Suite:** Tested with **864 unit tests across 121 suites passing in < 15.0s**.
 
 <br/>
 

package/bin/agentctl.mjs

@@ -570,8 +570,16 @@ async function main() {
       if (values.committed) selectedMode = "committed";
       if (values["working-tree"]) selectedMode = "working-tree";
 
-      const minScore = Number(values["min-score"]) || 80;
-      const maxMutants = Number(values["max-mutants"]) || 20;
+      // `Number(x) || default` swallows a legitimate zero: `--min-score 0`,
+      // the way to run the harness for its report without a threshold, silently
+      // enforced 80. Both flags already carry a parseArgs default, so the only
+      // thing left to guard against is a value that is not a number at all.
+      const parseNumericFlag = (raw, fallback) => {
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : fallback;
+      };
+      const minScore = parseNumericFlag(values["min-score"], 80);
+      const maxMutants = parseNumericFlag(values["max-mutants"], 20);
       const testCmd = values.cmd || config.verify?.test || "npm test";
 
       if (!values.json) {
@@ -597,7 +605,11 @@ async function main() {
         console.log(`  • Mutants Killed (Fail)   : ${report.killedMutants} ✅`);
         console.log(`  • Mutants Survived (Pass) : ${report.survivedMutants} ${report.survivedMutants > 0 ? "⚠️" : ""}`);
         console.log(`  • Errors / Timeouts       : ${report.errorMutants}`);
-        console.log(`  • Mutation Score          : ${report.mutationScore}% (Required: ${report.minScore}%)`);
+        console.log(
+          report.scored === false
+            ? `  • Mutation Score          : n/a — ${report.reason}`
+            : `  • Mutation Score          : ${report.mutationScore}% (Required: ${report.minScore}%)`
+        );
         console.log(`  • Duration                : ${report.durationMs}ms\n`);
 
         if (report.survivors.length > 0) {
@@ -1069,7 +1081,29 @@ async function main() {
       });
 
       const queueDir = getQueueDir(root);
-      const files = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
+      // The DAG runner accepts `.json` and `.task` envelopes as well as
+      // Markdown, and does its own discovery — but this count gated whether it
+      // was ever called, using the Markdown-only filter. A queue holding only
+      // JSON envelopes reported "0 queued task(s)" and did nothing, with no
+      // indication that the files were there and understood.
+      const queueEntries = readdirSync(queueDir);
+      let files;
+      if (values.dag) {
+        const { isDagTaskFile } = await import("../src/dag-engine.mjs");
+        files = queueEntries.filter((f) => {
+          if (f === "completed" || f.startsWith(".")) return false;
+          if (!/\.(md|json|task)$/.test(f)) return false;
+          let content = "";
+          try {
+            content = readFileSync(join(queueDir, f), "utf-8");
+          } catch (_) {
+            return false;
+          }
+          return isDagTaskFile(f, content, isTaskFile);
+        });
+      } 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;
@@ -1092,11 +1126,30 @@ async function main() {
     }
 
     case "swarm": {
-      console.log("🚀 Running Swarm Orchestrator...");
+      // This case had no parseArgs at all: `--json` and `--dry-run` were
+      // accepted by the shell, documented in the registry, and silently
+      // discarded — so a rehearsal dispatched for real and a script asking for
+      // JSON got decorated prose.
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          concurrency: { type: "string", short: "c" },
+          "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+        strict: false,
+      });
+
       const queueDir = getQueueDir(root);
       const files = readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir));
+      if (!values.json) console.log("🚀 Running Swarm Orchestrator...");
       if (files.length === 0) {
-        console.log("No pending tasks found for swarm.");
+        if (values.json) {
+          console.log(JSON.stringify({ ok: true, processed: 0, results: [], dryRun: Boolean(values["dry-run"]) }, null, 2));
+        } else {
+          console.log("No pending tasks found for swarm.");
+        }
         process.exit(0);
       }
       const tasks = files.map((f) => ({
@@ -1104,7 +1157,16 @@ async function main() {
         title: f.replace(/\.md$/, ""),
         prompt: readFileSync(join(queueDir, f), "utf-8"),
       }));
-      const results = await run(tasks, { root, config, concurrency: config.limits.concurrency || 3 });
+      const results = await run(tasks, {
+        root,
+        config,
+        concurrency: values.concurrency ? Number(values.concurrency) : config.limits.concurrency || 3,
+        dryRun: values["dry-run"],
+      });
+      if (values.json) {
+        console.log(JSON.stringify({ ok: true, dryRun: Boolean(values["dry-run"]), ...results }, null, 2));
+        process.exit((results.results || []).some((r) => r && r.ok === false) ? 1 : 0);
+      }
       process.exit(reportRunOutcome(results));
       break;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.55.0",
+  "version": "0.57.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/assertions.mjs

@@ -513,6 +513,11 @@ export function assertMutation(config = {}, root = process.cwd()) {
   });
 
   const diagnostics = [];
+  if (report.scored === false) {
+    // Not a failure, but not a pass worth trusting either: say so, so a green
+    // stage cannot be read as "the diff survived mutation testing".
+    diagnostics.push(report.reason || "No mutants could be generated from the added lines.");
+  }
   if (!report.ok) {
     diagnostics.push(
       `Mutation score ${report.mutationScore}% below required threshold of ${minScore}% (${report.killedMutants}/${report.totalMutants} killed, ${report.survivedMutants} survived).`

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/dag-engine.mjs

@@ -431,7 +431,7 @@ export function resolveAffectedTests(modifiedFiles = [], options = {}) {
  * @param {Function} isTaskFile - `isTaskFile` from engine.mjs, passed in to avoid a circular import.
  * @returns {boolean}
  */
-function isDagTaskFile(fileName, content, isTaskFile) {
+export function isDagTaskFile(fileName, content, isTaskFile) {
   if (fileName.endsWith(".task")) return true;
   if (fileName.endsWith(".md")) return isTaskFile(fileName, content);
   if (fileName.endsWith(".json")) {

package/src/engine.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,
         };
       }
@@ -319,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) {
@@ -994,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/git.mjs

@@ -384,8 +384,17 @@ export function diffText(root = process.cwd(), base = "main", mode = "committed"
         const fullPath = join(root, file);
         if (existsSync(fullPath)) {
           const content = readFileSync(fullPath, "utf-8");
+          const addedLines = content.split(/\r?\n/);
+          // The `@@` header is not decoration. Every consumer that needs to know
+          // *which* line an addition is on parses it — the mutation harness and
+          // the V8 diff-coverage mapper both walk hunks — so a synthetic diff
+          // without one made untracked files invisible to them. Both silently
+          // reported nothing to do for a brand-new file, which is precisely
+          // where untested code arrives. The secret scanner never noticed
+          // because it only reads `+` lines.
           untrackedDiff += `\ndiff --git a/${file} b/${file}\nnew file mode 100644\n--- /dev/null\n+++ b/${file}\n`;
-          untrackedDiff += content.split(/\r?\n/).map((line) => `+${line}`).join("\n") + "\n";
+          untrackedDiff += `@@ -0,0 +1,${addedLines.length} @@\n`;
+          untrackedDiff += addedLines.map((line) => `+${line}`).join("\n") + "\n";
         }
       } catch (_) {}
     }

package/src/mutation.mjs

@@ -676,13 +676,23 @@ export function runMutationTest(options = {}) {
   const selectedMutants = candidates.slice(0, maxMutants);
 
   if (selectedMutants.length === 0) {
+    // A diff with no mutable operators yields no mutants, and reporting that as
+    // "100%" told operators their untested code had a perfect score — the exact
+    // false confidence the harness exists to remove. There is no score to
+    // report, so there is none: `mutationScore` is null and `reason` says why.
+    //
+    // `ok` stays true. Nothing was falsifiable, so nothing failed to be
+    // falsified; failing here would block every diff that only adds imports,
+    // constants or markdown, and a gate that cries wolf gets switched off.
     return {
       ok: true,
       totalMutants: 0,
       killedMutants: 0,
       survivedMutants: 0,
       errorMutants: 0,
-      mutationScore: 100,
+      mutationScore: null,
+      scored: false,
+      reason: "No mutable operators in the added lines — nothing to falsify, so no score was computed.",
       minScore,
       results: [],
       survivors: [],

package/src/ops/command-registry.mjs

@@ -115,23 +115,27 @@ export const COMMAND_REGISTRY = [
   },
   {
     id: "swarm",
+    // Described as an inspector — `mutates: false`, `risk: low` — while the
+    // handler dispatches every queued task in parallel and spends budget.
+    // `--interactive` was advertised and implemented nowhere.
     path: ["swarm"],
     title: "swarm",
-    description: "Inspect active worker slots and concurrency scheduler",
+    description: "Dispatch every queued task in parallel across worker slots",
     category: "Operate",
-    mutates: false,
-    risk: "low",
-    interactive: "optional",
+    mutates: true,
+    risk: "moderate",
+    interactive: "never",
     requiresRepository: true,
     shortcuts: ["s"],
     examples: [
+      "agentctl swarm --dry-run",
       "agentctl swarm",
-      "agentctl swarm --interactive",
-      "agentctl swarm --json",
+      "agentctl swarm --concurrency 3 --json",
     ],
     flags: [
-      { name: "interactive", type: "boolean", description: "Open full-screen swarm dashboard" },
-      { name: "json", type: "boolean", description: "Output structured JSON swarm snapshot" },
+      { name: "concurrency", type: "string", description: "Parallel worker slots (defaults to limits.concurrency)" },
+      { name: "dry-run", type: "boolean", description: "Report what would run without dispatching" },
+      { name: "json", type: "boolean", description: "Output structured JSON swarm result" },
     ],
   },
   {

package/src/ops/tdd-generator.mjs

@@ -1,5 +1,5 @@
 import { writeFileSync, mkdirSync } from "node:fs";
-import { join, basename } from "node:path";
+import { join } from "node:path";
 import { detectPolyglotStack } from "../stack-detector.mjs";
 import { resolveRoot } from "../config.mjs";
 import { runCmd } from "../git.mjs";
@@ -26,45 +26,100 @@ export function scaffoldTddTest(spec = {}, options = {}) {
   const details = spec.spec || "Feature requirement specification assertion.";
 
   const stack = detectPolyglotStack(root);
-  const testDir = join(root, "test");
-  try {
-    mkdirSync(testDir, { recursive: true });
-  } catch (_) {}
 
-  const fileName = `generated-${title}.test.mjs`;
-  const filePath = join(testDir, fileName);
+  // The generated oracle has to be written in the language its runner speaks.
+  //
+  // This used to emit a Node test file for every stack and then, in a Python
+  // project, run `pytest generated-x.test.mjs`. pytest exits 4 on a file it
+  // cannot collect, and the cycle read any non-zero exit as RED — so it
+  // reported a verified failing test, and locked an uncollectable file into
+  // scope.deny, having proven nothing at all.
+  const identifier = title.replace(/-/g, "_");
+
+  // The one string that must appear in the runner's output for the failure to
+  // be the *assertion* failing rather than the file never being collected.
+  const redMarker = `TDD Assertion Failed: Requirement '${title}' is not yet implemented.`;
+  const comment = (prefix) => details.split("\n").map((line) => `${prefix} ${line}`).join("\n");
+
+  let relDir = "test";
+  let fileName = `generated-${title}.test.mjs`;
+  let codeContent;
+  let testCmdParts;
+  let testCmdStr;
+
+  if (stack.stack === "python" || stack.stack === "django") {
+    fileName = `test_generated_${identifier}.py`;
+    codeContent = `def test_tdd_oracle_${identifier}():
+    # REQUIREMENT SPECIFICATION:
+${comment("    #")}
+    is_implemented = False
+    assert is_implemented, "${redMarker}"
+`;
+    testCmdParts = ["pytest", `${relDir}/${fileName}`];
+    testCmdStr = `pytest ${relDir}/${fileName}`;
+  } else if (stack.stack === "cargo") {
+    // Cargo discovers integration tests in tests/, not test/.
+    relDir = "tests";
+    fileName = `generated_${identifier}.rs`;
+    codeContent = `#[test]
+fn tdd_oracle_${identifier}() {
+    // REQUIREMENT SPECIFICATION:
+${comment("    //")}
+    let is_implemented = false;
+    assert!(is_implemented, "${redMarker}");
+}
+`;
+    testCmdParts = ["cargo", "test", "--test", `generated_${identifier}`];
+    testCmdStr = `cargo test --test generated_${identifier}`;
+  } else if (stack.stack === "go") {
+    fileName = `generated_${identifier}_test.go`;
+    codeContent = `package ${relDir}
 
-  const codeContent = `import test from "node:test";
+import "testing"
+
+func TestTddOracle${identifier.replace(/_/g, "")}(t *testing.T) {
+	// REQUIREMENT SPECIFICATION:
+${comment("\t//")}
+	isImplemented := false
+	if !isImplemented {
+		t.Fatalf("${redMarker}")
+	}
+}
+`;
+    testCmdParts = ["go", "test", `./${relDir}/`];
+    testCmdStr = `go test ./${relDir}/`;
+  } else {
+    codeContent = `import test from "node:test";
 import assert from "node:assert/strict";
 
 test("TDD Oracle: ${title}", () => {
   // REQUIREMENT SPECIFICATION:
-  // ${details.replace(/\n/g, "\n  // ")}
+${comment("  //")}
 
   const isImplemented = false;
-  assert.equal(isImplemented, true, "TDD Assertion Failed: Requirement '${title}' is not yet implemented.");
+  assert.equal(isImplemented, true, "${redMarker}");
 });
 `;
+    testCmdParts = ["node", "--test", join(root, relDir, fileName)];
+    testCmdStr = `node --test ${relDir}/${fileName}`;
+  }
 
-  writeFileSync(filePath, codeContent, "utf-8");
+  const testDir = join(root, relDir);
+  try {
+    mkdirSync(testDir, { recursive: true });
+  } catch (_) {}
 
-  const relativePath = `test/${fileName}`;
-  let testCmd = ["node", "--test", filePath];
-  let testCmdStr = `node --test ${relativePath}`;
-  if (stack.stack === "python") {
-    testCmd = ["pytest", filePath];
-    testCmdStr = `pytest ${relativePath}`;
-  } else if (stack.stack === "cargo") {
-    testCmd = ["cargo", "test", "--test", title];
-    testCmdStr = `cargo test --test ${title}`;
-  }
+  const filePath = join(testDir, fileName);
+  writeFileSync(filePath, codeContent, "utf-8");
 
   return {
     filePath,
-    relativePath,
+    relativePath: `${relDir}/${fileName}`,
     codeContent,
-    testCmd,
+    testCmd: testCmdParts,
     testCmdStr,
+    stack: stack.stack,
+    redMarker,
   };
 }
 
@@ -98,7 +153,21 @@ export async function runTddCycle(spec = {}, options = {}) {
 
   if (redOutput.status === 0) {
     throw new TddError(
-      `TDD RED check failed: Test 'test/${basename(scaffolded.filePath)}' passed initially! TDD tests must be falsifiable and fail before implementation.`
+      `TDD RED check failed: Test '${scaffolded.relativePath}' passed initially! TDD tests must be falsifiable and fail before implementation.`
+    );
+  }
+
+  // A non-zero exit is not proof the assertion ran. `pytest` exits 4 on a file
+  // it cannot collect and 5 when it collects nothing; a runner pointed at a
+  // file it does not understand exits non-zero for that reason alone. Reading
+  // either as RED is how a Node test file in a Python project came to be
+  // reported as a verified failing oracle. The generated assertion carries a
+  // marker; if the runner never reached it, the marker is not in the output.
+  const redText = `${redOutput.stdout || ""}\n${redOutput.stderr || ""}`;
+  if (scaffolded.redMarker && !redText.includes(scaffolded.redMarker)) {
+    throw new TddError(
+      `TDD RED check inconclusive: '${scaffolded.testCmdStr}' exited ${redOutput.status} without reaching the generated assertion, so nothing was proven falsifiable. ` +
+        `The runner most likely could not collect '${scaffolded.relativePath}' (detected stack: ${scaffolded.stack}). Output:\n${redText.trim().slice(0, 500)}`
     );
   }
 

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/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,