jules-orchestrator-kit 0.56.0 → 0.58.0

package/README.md

@@ -204,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 **851 unit tests across 115 suites passing in < 14.0s**.
+* **Verified Test Suite:** Tested with **895 unit tests across 128 suites passing in < 15.0s**.
 
 <br/>
 
@@ -237,7 +237,7 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 | `doctor` | `agentctl doctor [--probe] [--json]` | Diagnostic check runner. `--probe` additionally starts the configured provider's CLI to confirm it answers, rather than only finding it on `PATH`. | `0` (Healthy), `1` (Failures) |
 | `queue` | `agentctl queue [--dag] [--concurrency <n>] [--dry-run] [--json]` | Consumes and executes task envelopes in `.agent/jules-queue/` with Kahn's DAG dependency resolution. Non-task files (manifests, `README.md`) are skipped, and `--dry-run` previews without moving anything. | `0` (Complete) |
 | `swarm` | `agentctl swarm [--json]` | Runs parallel multi-agent swarm across worker slots with PID liveness detection. | `0` (Complete) |
-| `check` / `gate` / `audit`| `agentctl check [--mode working-tree] [--fix] [--json] [--json-report <path>]` | Runs security, secret scanning, rules budget audit, and tiered verification gates (with declarative assertion support) against working tree or branch. | `0` (Approved), `1` (Budget/Arg), `3` (Scope), `4` (Verify), `5` (Diff >75K), `6` (Secret), `8` (Flaky) |
+| `check` / `gate` / `audit`| `agentctl check [--mode working-tree] [--fix] [--allow-protected] [--allow-test-modifications] [--json] [--json-report <path>]` | Runs security, secret scanning, rules budget audit, and tiered verification gates (with declarative assertion support) against working tree or branch. | `0` (Approved), `1` (Budget/Arg), `3` (Scope), `4` (Verify), `5` (Diff >75K), `6` (Secret), `8` (Flaky) |
 | `mutate` / `mutation` | `agentctl mutate [--min-score <n>] [--max-mutants <n>] [--cmd <testCmd>] [--json]` | Runs zero-dependency diff mutation testing harness on changed hunks with operator inversion and safety rollback. | `0` (Passed), `1` (Score Low) |
 | `coverage` | `agentctl coverage [--min <pct>] [--cmd <testCmd>] [--base <ref>] [--json]` | Runs native zero-dependency V8 diff coverage check against added diff lines. | `0` (Passed), `1` (Low Coverage) |
 | `probe` / `stability` | `agentctl probe [--repeat <n>] [--min <passRate>] [--cmd <testCmd>] [--json]` | Probes test suite flakiness across N consecutive iterations with oscillation detection. | `0` (Passed), `1` (Flaky) |
@@ -249,7 +249,7 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 | `resume` | `agentctl resume <sessionId> --response "<reply>"` | Streams engineer response back into active Google Jules warm session context window. | `0` (Resumed), `1` (Error) |
 | `test-gen` | `agentctl test-gen --title <t> --spec <s> [--run]` | Scaffolds falsifiable unit tests, verifies RED failure state, and locks test in `scope.deny`. | `0` (Scaffolded/Red) |
 | `dashboard` | `agentctl dashboard [port]` | Starts zero-dependency local HTTP telemetry and audit visualizer dashboard. | `0` (Running) |
-| `evidence` | `agentctl evidence <generate\|verify\|show>` | Generates, verifies, or prints SHA-256 cryptographic evidence manifests with test-tamper locking. | `0` (Verified), `1` (Tamper) |
+| `evidence` | `agentctl evidence <generate\|verify\|show>` | Generates, verifies, or prints SHA-256 evidence manifests (unkeyed digests: tamper-evident, not signed) with test-tamper locking. | `0` (Verified), `1` (Tamper) |
 | `flaky` | `agentctl flaky <status\|heal\|reset>` | Manages Wilson-quarantined tests (Exit Code 8) and dispatches automated anti-flakiness healing swarms. | `0` (Healed/Listed) |
 | `mcp` | `agentctl mcp` | Starts stdio Model Context Protocol (MCP) server for Claude, Cursor, and Antigravity. | `0` / Stdio stream |
 | `mcp init` | `agentctl mcp init [--target cursor\|vscode\|claude\|all]` | 1-click config scaffolding for Cursor (`.cursor/mcp.json`), VS Code tasks (`tasks.json`), and Claude Desktop. | `0` (Scaffolded) |

package/bin/agentctl.mjs

@@ -61,7 +61,7 @@ Commands:
   swarm                 Run parallel task swarm
   mcp                   Start stdio Model Context Protocol (MCP) server
   clean                 Clean stale branches, worktrees, locks, and ledgers
-  lock <action>         Manage mutex locks (acquire | release | status)
+  lock <action>         Manage mutex locks (acquire [--ttl <min>] [--pid <n>] | release | status)
   doctor                Run system diagnostics and stack resolution checks
   providers             List agent providers and whether this machine can reach them (--json)
   provider set <name>   Switch the active provider in .agent/config.yml
@@ -383,6 +383,12 @@ async function main() {
           committed: { type: "boolean" },
           fix: { type: "boolean" },
           "allow-protected": { type: "boolean" },
+          // The tamper guard has always had an override — `allowTestModifications`
+          // — and it was reachable only from JavaScript. So a legitimate change
+          // of spec, which necessarily rewrites what a test expects, hit a
+          // CRITICAL finding at exit 6 with no documented way past it. A guard
+          // with no override is not a guard, it is an outage.
+          "allow-test-modifications": { type: "boolean" },
           json: { type: "boolean", short: "j" },
           "json-report": { type: "string" },
           "dry-run": { type: "boolean", short: "d" },
@@ -402,6 +408,7 @@ async function main() {
         mode: selectedMode,
         fix: values.fix,
         allowProtected: values["allow-protected"],
+        allowTestModifications: values["allow-test-modifications"],
         jsonReport: values["json-report"],
       });
 
@@ -570,8 +577,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 +612,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 +1088,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 +1133,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 +1164,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;
     }
@@ -1216,14 +1285,46 @@ async function main() {
     case "lock": {
       const action = args[1];
       if (action === "acquire") {
-        const agent = args[2] || "agent";
-        const taskId = args[3] || "task-1";
-        const filePaths = args.slice(4);
-        const res = acquireLock(agent, taskId, filePaths, root);
+        // A lock taken from the command line outlives the command. The process
+        // that runs `lock acquire` writes the record and exits; the agent it
+        // speaks for is somewhere else entirely. So this is a time-bounded
+        // lease, not a pid the next acquire can test for liveness — that test
+        // always said "dead" and handed the same files to the next caller.
+        //
+        // `--pid` is the escape hatch for a caller that *does* have a durable
+        // process to point at: the lock then releases itself when that process
+        // dies, exactly as an in-process acquire does.
+        const flagIdx = args.findIndex((a, i) => i >= 2 && a.startsWith("--"));
+        const positional = flagIdx === -1 ? args.slice(2) : args.slice(2, flagIdx);
+        const { values } = parseArgs({
+          args: flagIdx === -1 ? [] : args.slice(flagIdx),
+          options: {
+            ttl: { type: "string" },
+            pid: { type: "string" },
+          },
+          allowPositionals: false,
+        });
+        const agent = positional[0] || "agent";
+        const taskId = positional[1] || "task-1";
+        const filePaths = positional.slice(2);
+        const ttlMinutes = Number(values.ttl);
+        const ownerPid = Number(values.pid);
+        const bindsToProcess = Number.isInteger(ownerPid) && ownerPid > 0;
+        const res = acquireLock(agent, taskId, filePaths, root, {
+          lease: !bindsToProcess,
+          ownerPid: bindsToProcess ? ownerPid : undefined,
+          ttlMs: Number.isFinite(ttlMinutes) && ttlMinutes > 0 ? ttlMinutes * 60_000 : undefined,
+        });
         if (res.ok) {
-          console.log(`✅ Acquired lock for ${taskId}`);
+          const held = filePaths.length ? ` (${filePaths.length} path${filePaths.length === 1 ? "" : "s"})` : "";
+          const until = bindsToProcess ? `bound to pid ${ownerPid}` : `expires ${new Date(Date.now() + (Number.isFinite(ttlMinutes) && ttlMinutes > 0 ? ttlMinutes : 120) * 60_000).toISOString()}`;
+          console.log(`✅ Acquired lock for ${taskId}${held} — ${until}`);
         } else {
-          console.log(`❌ Lock conflict detected: held by ${res.holder}`);
+          const overlap = Array.isArray(res.conflictingFiles) && res.conflictingFiles.length
+            ? `\n   Contested paths: ${res.conflictingFiles.join(", ")}`
+            : "";
+          const until = res.expiresAt ? `\n   Held until ${res.expiresAt} (or until \`agentctl lock release ${res.taskId}\`).` : "";
+          console.log(`❌ Lock conflict detected: held by ${res.holder} (task ${res.taskId})${overlap}${until}`);
           process.exit(1);
         }
       } else if (action === "release") {
@@ -2610,9 +2711,16 @@ async function main() {
         if (values.json) {
           console.log(JSON.stringify(res, null, 2));
         } else {
-          console.log(`\n🛡️ Cryptographic Evidence Manifest Generated!`);
+          // "Signature" was the wrong word and the wrong promise. There is no
+          // key anywhere in this system: the value is a SHA-256 digest of the
+          // manifest, so anyone who can write the file can also recompute it
+          // and have `evidence verify` agree. What it proves is that the
+          // manifest has not been edited *since* it was written — tamper
+          // evidence, not authorship. Calling that a signature invites an
+          // operator to trust it for something it cannot do.
+          console.log(`\n🛡️ Evidence Manifest Generated!`);
           console.log(`   Manifest ID : ${res.manifest.manifestId}`);
-          console.log(`   Signature   : ${res.manifest.evidenceHash}`);
+          console.log(`   Digest      : ${res.manifest.evidenceHash}`);
           console.log(`   Location    : ${res.manifestPath}`);
           console.log(`   Test Files  : ${res.manifest.testIntegrity.testFileCount}`);
           console.log(`   Tampered    : ${res.manifest.testIntegrity.tamperDetected ? "YES (FAILED)" : "NO (VERIFIED)"}\n`);
@@ -2628,7 +2736,7 @@ async function main() {
           if (res.ok) {
             console.log(`\n✅ Evidence Verification PASSED`);
             console.log(`   Manifest ID : ${res.manifestId}`);
-            console.log(`   Signature   : ${res.evidenceHash}\n`);
+            console.log(`   Digest      : ${res.evidenceHash}\n`);
           } else {
             console.error(`\n❌ Evidence Verification FAILED`);
             console.error(`   Reason      : ${res.reason}`);

package/package.json

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

@@ -28,6 +28,34 @@ const DEFAULTS = {
   baseBranch: "main",
 };
 
+// A CI definition is code the forge runs with the repository's own
+// credentials, on the next push, without review. `.github/**` was the only one
+// listed, so the gate's answer depended on which forge the project happened to
+// use: an identical exfiltration job placed in `.gitlab-ci.yml` was approved
+// where `.github/workflows/x.yml` was rejected. A safety gate that is only
+// safe on GitHub is not a safety gate.
+const CI_DEFINITIONS = [
+  ".github/**",
+  ".gitlab-ci.yml",
+  "**/.gitlab-ci.yml",
+  ".gitlab/ci/**",
+  ".circleci/**",
+  "azure-pipelines.yml",
+  "azure-pipelines.yaml",
+  "**/azure-pipelines.yml",
+  "Jenkinsfile",
+  "**/Jenkinsfile",
+  ".travis.yml",
+  ".drone.yml",
+  "bitbucket-pipelines.yml",
+  ".buildkite/**",
+  ".woodpecker.yml",
+  ".woodpecker/**",
+  "appveyor.yml",
+  ".teamcity/**",
+  ".githooks/**",
+];
+
 export const BUILTIN_DENY = [
   ".git/**",
   "**/.env",
@@ -36,7 +64,7 @@ export const BUILTIN_DENY = [
   "**/*.key",
   "**/id_rsa*",
   ".agent/jules-queue/**",
-  ".github/**",
+  ...CI_DEFINITIONS,
 ];
 
 export const BUILTIN_PROTECT = [
@@ -59,6 +87,50 @@ export const BUILTIN_PROTECT = [
   "**/Makefile",
   "**/.npmrc",
   "**/.netrc",
+
+  // Build definitions that execute arbitrary code at install or build time.
+  // The same tier as package.json: legitimately edited, so not denied, but not
+  // edited quietly either.
+  "setup.py",
+  "**/setup.py",
+  "setup.cfg",
+  "**/setup.cfg",
+  "build.rs",
+  "**/build.rs",
+  "pom.xml",
+  "**/pom.xml",
+  "build.gradle",
+  "**/build.gradle",
+  "build.gradle.kts",
+  "**/build.gradle.kts",
+  "CMakeLists.txt",
+  "**/CMakeLists.txt",
+  "Gemfile",
+  "**/Gemfile",
+  "Dockerfile",
+  "**/Dockerfile",
+
+  // Test-runner configuration decides which tests run and what counts as a
+  // pass. Rewriting it is the cheapest way to make a suite green without
+  // touching a single assertion — `--passWithNoTests`, an added ignore
+  // pattern, a conftest.py fixture that stubs the thing under test — and the
+  // tamper guard reads test *files*, so none of it was visible to anything.
+  "conftest.py",
+  "**/conftest.py",
+  "pytest.ini",
+  "**/pytest.ini",
+  "tox.ini",
+  "**/tox.ini",
+  "jest.config.*",
+  "**/jest.config.*",
+  "vitest.config.*",
+  "**/vitest.config.*",
+  "**/.mocharc.*",
+  "karma.conf.*",
+  "**/karma.conf.*",
+  "phpunit.xml",
+  "**/phpunit.xml",
+  "**/.nycrc*",
 ];
 
 const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);

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

@@ -274,7 +274,7 @@ export async function gate(opts = {}) {
   }
 
   // Phase 3: Diff Secret Scanner & Security Checks
-  const secretResult = scanDiff(diffStr, { root });
+  const secretResult = scanDiff(diffStr, { root, allowTestModifications: opts.allowTestModifications === true });
   // A binary file reaches the scanner as one summary line, so its contents were
   // never looked at — a NUL byte in front of a token was enough to hide it.
   // Inspect those files directly and fold the verdict in.

package/src/evidence.mjs

@@ -54,6 +54,30 @@ export function computeFileHash(filePath) {
  * @param {string} [baseDir]
  * @returns {string[]}
  */
+/**
+ * Directories whose contents a build or a test run regenerates.
+ *
+ * These are not hashed. The test-integrity hash is taken before and after the
+ * verification command and any difference is reported as tampering — so a
+ * runner that writes its own cache *inside* the test tree accused itself. That
+ * is exactly what pytest does: it drops `tests/__pycache__/*.pyc` on first
+ * collection, the post-run hash no longer matched the pre-run hash, and every
+ * Python project on earth failed the gate with "test files changed during the
+ * run". A false accusation of tampering is worse than a missed one; it teaches
+ * the user to pass --allow-test-modifications by reflex.
+ */
+const ARTIFACT_DIRS = new Set([
+  ".git", "node_modules", "target", "vendor",
+  "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox",
+  ".venv", "venv", ".gradle", ".nyc_output", "coverage", "htmlcov",
+  ".next", ".nuxt", ".turbo", ".cache", ".parcel-cache",
+]);
+
+/** Compiled output. Regenerated from the sources that are hashed instead. */
+const ARTIFACT_EXTENSIONS = new Set([
+  ".pyc", ".pyo", ".pyd", ".class", ".o", ".obj", ".so", ".dll", ".dylib", ".exe", ".log",
+]);
+
 export function findFilesRecursively(dir, baseDir = dir) {
   if (!existsSync(dir)) return [];
   const results = [];
@@ -61,12 +85,11 @@ export function findFilesRecursively(dir, baseDir = dir) {
     const entries = readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = join(dir, entry.name);
-      if (entry.name === ".git" || entry.name === "node_modules" || entry.name === "target" || entry.name === "vendor") {
-        continue;
-      }
+      if (ARTIFACT_DIRS.has(entry.name)) continue;
       if (entry.isDirectory()) {
         results.push(...findFilesRecursively(fullPath, baseDir));
       } else if (entry.isFile()) {
+        if (ARTIFACT_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue;
         results.push(normalizePath(relative(baseDir, fullPath)));
       }
     }
@@ -579,7 +602,7 @@ export function generateEvidenceMarkdown(manifest) {
   const lines = [
     "### 🛡️ Autonomous Verification & Evidence Proof",
     "",
-    `> **Evidence Manifest**: \`${manifest.manifestId}\` | **Signature**: \`${manifest.evidenceHash?.slice(0, 16)}...\``,
+    `> **Evidence Manifest**: \`${manifest.manifestId}\` | **Digest**: \`${manifest.evidenceHash?.slice(0, 16)}...\``,
     "",
     "| Gate / Policy | Status | Evidence Record |",
     "| :--- | :---: | :--- |",

package/src/git.mjs

@@ -1,5 +1,5 @@
 import { execFileSync, execSync } from "node:child_process";
-import { readFileSync, existsSync, statSync, readlinkSync } from "node:fs";
+import { readFileSync, existsSync, statSync, lstatSync, readlinkSync } from "node:fs";
 import { join, delimiter } from "node:path";
 import { normalizePath, canonicalizePath } from "./config.mjs";
 
@@ -382,10 +382,38 @@ export function diffText(root = process.cwd(), base = "main", mode = "committed"
     for (const file of untrackedFiles) {
       try {
         const fullPath = join(root, file);
+
+        // A symlink is its target *path*, never its target's contents — that is
+        // how git stores one and how `git diff` renders one. Reading through
+        // the link instead pulled whatever it pointed at into the diff, so
+        // `ln -s /etc/passwd notes.md` shipped that file's contents to the
+        // provider as ordinary added lines under an innocent name. Emit the
+        // link the way a committed symlink is emitted, and let checkScope judge
+        // the target it resolves to.
+        let linkStat = null;
+        try {
+          linkStat = lstatSync(fullPath);
+        } catch (_) {}
+        if (linkStat && linkStat.isSymbolicLink()) {
+          const target = readlinkSync(fullPath);
+          untrackedDiff += `\ndiff --git a/${file} b/${file}\nnew file mode 120000\n--- /dev/null\n+++ b/${file}\n`;
+          untrackedDiff += `@@ -0,0 +1 @@\n+${target}\n\\n`;
+          continue;
+        }
+
         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 (_) {}
     }
@@ -493,17 +521,48 @@ export function symlinkChanges(root = process.cwd(), base = "main", mode = "comm
     }
     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: resolveLinkTarget(entry.file, target) });
+  }
 
-    results.push({ link: entry.file, target: resolved });
+  // An untracked symlink appears in no `git diff --raw` at all, so in
+  // working-tree mode — the default for `agentctl check` — the loop above sees
+  // nothing. `ln -s /etc/os-release leak.txt` therefore reached checkScope as
+  // the plain name `leak.txt` and passed; committing the identical link to a
+  // branch and checking that was caught. The gate's answer must not depend on
+  // whether the attacker ran `git add`.
+  if (mode === "working-tree" || mode === "working") {
+    const untrackedRaw =
+      git(["-c", "core.quotePath=false", "ls-files", "-z", "--others", "--exclude-standard"], {
+        cwd: root,
+        raw: true,
+        ignoreError: true,
+      }) || "";
+    for (const rel of untrackedRaw.split("\0").map(normalizePath).filter(Boolean)) {
+      if (seen.has(rel)) continue;
+      let target = "";
+      try {
+        if (!lstatSync(join(root, rel)).isSymbolicLink()) continue;
+        target = readlinkSync(join(root, rel));
+      } catch (_) {
+        continue;
+      }
+      if (!target) continue;
+      seen.add(rel);
+      results.push({ link: rel, target: resolveLinkTarget(rel, target) });
+    }
   }
 
   return results;
 }
 
+/** Where a symlink at `link` pointing at `target` lands, as a repo-relative or absolute path. */
+function resolveLinkTarget(link, target) {
+  const linkDir = normalizePath(link).split("/").slice(0, -1).join("/");
+  return normalizePath(target).startsWith("/")
+    ? normalizePath(target)
+    : canonicalizePath(linkDir ? `${linkDir}/${target}` : target);
+}
+
 export function binaryDiffEntries(root = process.cwd(), base = "main", mode = "committed") {
   const entries = new Map();
   for (const entry of parseRawDiff(root, base, mode)) {

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/security.mjs

@@ -838,9 +838,56 @@ function splitDiffByFile(diffText) {
 
 const CANDIDATE_TOKEN_REGEX = /[A-Za-z0-9_-]{24,}/g;
 
+/** A whole data: URI, base64-encoded or not. Its payload is not a credential. */
+const DATA_URI_TOKEN = /\bdata:[a-z0-9.+-]+\/[a-z0-9.+-]*(?:;[a-z0-9.+=-]+)*,[^\s"'`<>)\]}]*/gi;
+
+/** A subresource-integrity digest. High entropy by construction, public by design. */
+const INTEGRITY_TOKEN = /\bsha(?:256|384|512)-[A-Za-z0-9+/=]+/gi;
+
+/** A URL, from its scheme to the first character that cannot be part of one. */
+const URL_TOKEN = /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'`<>)\]},;]+/gi;
+
+/**
+ * Remove from a line the noise that made URLs worth ignoring, and keep the
+ * parts of a URL that can carry a credential.
+ *
+ * This used to be `if (rawLine.includes("://")) continue;` — one substring
+ * anywhere on the line switched off entropy analysis for the entire line. So
+ * the scanner caught a bare 32-character key and let the identical key through
+ * the moment a comment carrying any http link sat beside it. An agent does not
+ * need to know why that works to stumble into it; a fetch call and its endpoint
+ * on one line is ordinary code.
+ *
+ * What actually justified the skip is narrower: a CDN path segment or an npm
+ * integrity hash looks exactly like a secret and is neither. Those are dropped
+ * here. A URL's userinfo and its query values are the opposite — `?api_key=…`
+ * and `//user:password@host` are where credentials genuinely hide — so they
+ * are carried over and scanned on their own.
+ */
+function stripEntropyNoise(rawLine) {
+  const carried = [];
+  let line = rawLine.replace(DATA_URI_TOKEN, " ").replace(INTEGRITY_TOKEN, " ");
+  line = line.replace(URL_TOKEN, (url) => {
+    const afterScheme = url.slice(url.indexOf("://") + 3);
+    const authority = afterScheme.split(/[/?#]/)[0];
+    const at = authority.lastIndexOf("@");
+    if (at > 0) carried.push(authority.slice(0, at));
+    const q = url.indexOf("?");
+    if (q !== -1) {
+      for (const pair of url.slice(q + 1).split(/[&;#]/)) {
+        const eq = pair.indexOf("=");
+        if (eq !== -1) carried.push(pair.slice(eq + 1));
+      }
+    }
+    return " ";
+  });
+  return carried.length ? `${line} ${carried.join(" ")}` : line;
+}
+
 /**
  * Checks for high-entropy continuous tokens (>= 24 chars, entropy > 4.5) on added lines.
- * Filters out URLs, SRI hashes (sha512-, sha256-, sha384-), and lockfiles to eliminate false positives.
+ * Strips URLs, data: URIs, SRI hashes (sha512-, sha256-, sha384-) and skips lockfiles
+ * to eliminate false positives.
  *
  * @param {string} text - Text to scan
  * @param {string|null} [file=null] - File path associated with the text
@@ -863,19 +910,11 @@ export function hasHighEntropyToken(text = "", file = null) {
 
   const lines = text.split("\n");
   for (const rawLine of lines) {
-    if (
-      rawLine.includes("://") ||
-      rawLine.includes("data:image/") ||
-      rawLine.includes("sha512-") ||
-      rawLine.includes("sha256-") ||
-      rawLine.includes("sha384-")
-    ) {
-      continue;
-    }
+    const line = stripEntropyNoise(rawLine);
 
     CANDIDATE_TOKEN_REGEX.lastIndex = 0;
     let match;
-    while ((match = CANDIDATE_TOKEN_REGEX.exec(rawLine)) !== null) {
+    while ((match = CANDIDATE_TOKEN_REGEX.exec(line)) !== null) {
       const token = match[0];
       if (token.startsWith("sha512-") || token.startsWith("sha256-")) continue;
       if (token.length >= 24) {
@@ -1138,6 +1177,22 @@ export function checkTestTampering(diffOrText = "", options = {}) {
   );
   const isSpecificAssertion = (str) => SPECIFIC_ASSERTION.test(str);
 
+  /**
+   * An assertion with every literal value replaced by a placeholder.
+   *
+   * Two lines that normalize to the same string are the same assertion about
+   * the same expression; whatever differs between them is a value.
+   */
+  const blankLiterals = (str) =>
+    str
+      .replace(/(['"`])(?:\\.|(?!\1)[^\\])*\1/g, "\u0000S")
+      // The sign belongs to the literal: without it `3` and `-1` normalized to
+      // different shapes and the rewritten expectation was never paired.
+      .replace(/(?<![\w$])-?\d+(?:\.\d+)?\b/g, "\u0000N")
+      .replace(/\b(?:true|false|null|undefined|None|True|False|nil)\b/g, "\u0000B")
+      .replace(/\s+/g, " ")
+      .trim();
+
   const fileAssertions = new Map();
 
   for (let i = 0; i < lines.length; i++) {
@@ -1169,7 +1224,7 @@ export function checkTestTampering(diffOrText = "", options = {}) {
     }
 
     if (!fileAssertions.has(currentFile)) {
-      fileAssertions.set(currentFile, { removed: [], added: 0, removedSpecific: [], addedSpecific: 0 });
+      fileAssertions.set(currentFile, { removed: [], added: 0, addedTexts: [], removedSpecific: [], addedSpecific: 0 });
     }
     const fileStats = fileAssertions.get(currentFile);
 
@@ -1226,6 +1281,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++;
+        fileStats.addedTexts.push({ line: currentNewLineNo, text: addedText });
         if (isSpecificAssertion(addedText)) fileStats.addedSpecific++;
       }
 
@@ -1237,6 +1293,58 @@ export function checkTestTampering(diffOrText = "", options = {}) {
   }
 
   for (const [file, stats] of fileAssertions.entries()) {
+    // An expectation that was rewritten rather than removed.
+    //
+    // Counting assertions cannot see this one: `assert.equal(add(1,2), 3)`
+    // becoming `assert.equal(add(1,2), -1)` takes one specific assertion out
+    // and puts one specific assertion back, so every total stayed level and the
+    // guard said nothing — while the suite went from checking that addition
+    // works to certifying that it is broken. It is the single cheapest way to
+    // make a red suite green, and the one this tool exists to refuse.
+    //
+    // The signal is that the two lines are the *same assertion* with different
+    // values in it: identical once every literal is blanked out, different
+    // before. That does not distinguish an attack from a deliberate change of
+    // spec — nothing can, from the diff alone — so this reports rather than
+    // decides, and `--allow-test-modifications` is the answer when the new
+    // expectation is the correct one.
+    // Shapes are computed once per added line, not once per (removed, added)
+    // pair: a large test refactor is O(n²) comparisons and the normalisation is
+    // the expensive half of each one.
+    const unpairedAdded = stats.addedTexts
+      .filter((a) => isSpecificAssertion(a.text))
+      .map((a) => ({ ...a, shape: blankLiterals(a.text) }));
+    for (const removedItem of stats.removed.slice()) {
+      if (!isSpecificAssertion(removedItem.text)) continue;
+      const shape = blankLiterals(removedItem.text);
+      const idx = unpairedAdded.findIndex(
+        (a) => a.shape === shape && a.text.trim() !== removedItem.text.trim()
+      );
+      if (idx === -1) continue;
+      const addedItem = unpairedAdded.splice(idx, 1)[0];
+
+      violations.push({
+        file,
+        line: addedItem.line ?? removedItem.line,
+        type: "ASSERTION_EXPECTATION_CHANGED",
+        reason:
+          `Test Tamper Guard: Expected value rewritten in ${file}${addedItem.line ? `:${addedItem.line}` : ""} — ` +
+          `"${removedItem.text.trim()}" became "${addedItem.text.trim()}". ` +
+          `If the new value is the correct one, re-run with --allow-test-modifications.`,
+      });
+
+      // Both sides are accounted for here, so they must not also feed the
+      // count-based checks below — the same line reported twice under two
+      // names tells the operator nothing extra.
+      stats.removed.splice(stats.removed.indexOf(removedItem), 1);
+      const rsIdx = stats.removedSpecific.indexOf(removedItem);
+      if (rsIdx !== -1) {
+        stats.removedSpecific.splice(rsIdx, 1);
+        stats.addedSpecific--;
+      }
+      stats.added--;
+    }
+
     if (stats.removed.length > stats.added) {
       const unreplaced = stats.removed.slice(stats.added);
       for (const item of unreplaced) {

package/src/stack-detector.mjs

@@ -1,5 +1,42 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from "node:fs";
 import { join, relative } from "node:path";
+import { whichBinary } from "./provider-readiness.mjs";
+
+/**
+ * The Python interpreter to invoke, by whatever name this machine has it under.
+ *
+ * `python3` does not exist on a default Windows install (the launcher is `py`,
+ * the Store package is `python`), so a hardcoded `python3` made every Python
+ * command in the kit unrunnable there.
+ */
+function pythonBin(env = process.env) {
+  for (const name of ["python3", "python", "py"]) {
+    if (whichBinary(name, env)) return name;
+  }
+  return "python3";
+}
+
+/**
+ * The command that runs a pytest suite.
+ *
+ * Not `pytest`. Invoked as a bare console script, pytest does not put the
+ * working directory on `sys.path`; invoked as `-m`, Python does. So the most
+ * ordinary Python layout there is — a module at the root, its test under
+ * `tests/` importing it — collapsed at collection with `ModuleNotFoundError:
+ * No module named 'calc'`, and the gate reported exit 4 on a project whose
+ * suite passes perfectly when the developer types `python3 -m pytest`. A
+ * first-run rejection of correct code is the most expensive failure this tool
+ * can produce: it teaches the user the gate is wrong.
+ *
+ * Falls back to the bare console script only when no interpreter can be found
+ * to host the module.
+ */
+export function pytestCmd(env = process.env) {
+  for (const name of ["python3", "python", "py"]) {
+    if (whichBinary(name, env)) return `${name} -m pytest`;
+  }
+  return "pytest";
+}
 
 /**
  * Generate a zero-dependency smoke test file using node:test for untested JS/Generic repos.
@@ -186,7 +223,7 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
   }
   if (existsSync(join(projectRoot, "pyproject.toml")) || existsSync(join(projectRoot, "requirements.txt")) || existsSync(join(projectRoot, "setup.py"))) {
     const triggerFile = existsSync(join(projectRoot, "pyproject.toml")) ? "pyproject.toml" : existsSync(join(projectRoot, "requirements.txt")) ? "requirements.txt" : "setup.py";
-    return { ...container, stack: "python", testCmd: "pytest", buildCmd: "python3 -m compileall -q .", triggerFile };
+    return { ...container, stack: "python", testCmd: pytestCmd(), buildCmd: `${pythonBin()} -m compileall -q .`, triggerFile };
   }
   if (existsSync(join(projectRoot, "mix.exs"))) {
     return { ...container, stack: "mix", testCmd: "mix test", buildCmd: "mix compile", triggerFile: "mix.exs" };
@@ -270,7 +307,7 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
     }
     const pyFile = rootFiles.find((f) => f.endsWith(".py"));
     if (pyFile) {
-      return { ...container, stack: "python", testCmd: "pytest", buildCmd: "python3 -m compileall -q .", triggerFile: pyFile };
+      return { ...container, stack: "python", testCmd: pytestCmd(), buildCmd: `${pythonBin()} -m compileall -q .`, triggerFile: pyFile };
     }
   } catch (_) {}
 
@@ -699,7 +736,7 @@ export function bootstrapZeroTestRepo(root = process.cwd(), options = {}) {
   if (detected.stack === "php" || detected.stack === "laravel" || detected.stack === "wordpress") {
     testCmd = 'php -l $(find . -name "*.php" -not -path "./vendor/*" -not -path "./node_modules/*")';
   } else if (detected.stack === "python") {
-    testCmd = "python3 -m compileall -q -x '^\\./(\\.\\venv|venv|node_modules|\\.git)/' .";
+    testCmd = `${pythonBin()} -m compileall -q -x '^\\./(\\.\\venv|venv|node_modules|\\.git)/' .`;
   } else if (detected.stack === "dotnet") {
     testCmd = "dotnet build --no-incremental --nologo";
   } else if (detected.stack === "cargo") {

package/src/state.mjs

@@ -530,6 +530,54 @@ export function isPidAlive(pid, expectedStartTime = null) {
   return true;
 }
 
+export const LOCK_TTL_MS = 7200000;
+
+/**
+ * The epoch-ms instant a lock record stops holding.
+ *
+ * Records written before leases existed carry only `acquiredAt`, so they keep
+ * the two-hour window they were reaped on before.
+ */
+function lockExpiry(record) {
+  if (!record) return 0;
+  if (record.expiresAt) {
+    const t = new Date(record.expiresAt).getTime();
+    if (Number.isFinite(t)) return t;
+  }
+  if (record.acquiredAt) {
+    const t = new Date(record.acquiredAt).getTime();
+    if (Number.isFinite(t)) return t + LOCK_TTL_MS;
+  }
+  return Infinity;
+}
+
+/**
+ * Is this lock still held?
+ *
+ * There are two kinds of holder and only one of them has a process worth
+ * asking about.
+ *
+ * An in-process caller — the engine, the swarm — holds the lock for as long as
+ * it runs, so its pid is a real witness: if it died the lock is garbage, and
+ * reaping on a dead pid is what stops a crash from wedging the repo for the
+ * full TTL.
+ *
+ * `agentctl lock acquire` is the opposite. That process writes the file and
+ * exits *by design* — the agent it speaks for lives in some other process, on
+ * another machine, or has not started yet. Asking whether the CLI that wrote
+ * the record is alive therefore always answered "no", so the very next acquire
+ * reaped the lock and handed the same files to a second agent, telling both
+ * they had exclusive access. Two holders who each believe they are alone is
+ * worse than no lock at all. A record written that way marks itself `leased`,
+ * and then only its expiry decides.
+ */
+export function isLockLive(record) {
+  if (!record) return false;
+  if (Date.now() >= lockExpiry(record)) return false;
+  if (record.leased === true) return true;
+  return isPidAlive(record.pid, record.processStartTime ?? record.starttime ?? null);
+}
+
 function assertSafeTaskId(taskId) {
   if (typeof taskId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(taskId) || basename(taskId) !== taskId) {
     throw new Error("Invalid task id for lock path");
@@ -546,15 +594,16 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
   if (existsSync(lockFile)) {
     try {
       const existing = JSON.parse(readFileSync(lockFile, "utf-8"));
-      const recordedStartTime = existing.processStartTime ?? existing.starttime ?? null;
-      const isAlive = isPidAlive(existing.pid, recordedStartTime);
-      const isExpired = existing.acquiredAt && Date.now() - new Date(existing.acquiredAt).getTime() > 7200000;
-
-      if (!isAlive || isExpired) {
-        try { unlinkSync(lockFile); } catch (_) {}
-      } else {
-        return { ok: false, holder: existing.agent, taskId, pid: existing.pid };
+      if (isLockLive(existing)) {
+        return {
+          ok: false,
+          holder: existing.agent,
+          taskId,
+          pid: existing.pid,
+          expiresAt: existing.expiresAt || null,
+        };
       }
+      try { unlinkSync(lockFile); } catch (_) {}
     } catch (_) {
       try { unlinkSync(lockFile); } catch (_) {}
     }
@@ -573,11 +622,7 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
   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;
+      if (!isLockLive(held)) continue;
 
       const overlap = (Array.isArray(held.files) ? held.files : [])
         .map((f) => normalizePath(f))
@@ -588,13 +633,22 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
           holder: held.agent,
           taskId: held.taskId,
           pid: held.pid,
+          expiresAt: held.expiresAt || null,
           conflictingFiles: overlap,
         };
       }
     }
   }
 
-  const startTime = getProcessStartTime(process.pid);
+  // `leased` says the holder is not this process. A caller that will stay
+  // alive for the duration (the engine, the swarm) leaves it off and gets pid
+  // liveness; a one-shot CLI sets it and gets a plain time-bounded lease. See
+  // isLockLive.
+  const leased = opts?.lease === true;
+  const ownerPid = Number.isInteger(opts?.ownerPid) && opts.ownerPid > 0 ? opts.ownerPid : process.pid;
+  const ttlMs = Number.isFinite(opts?.ttlMs) && opts.ttlMs > 0 ? opts.ttlMs : LOCK_TTL_MS;
+  const startTime = getProcessStartTime(ownerPid);
+  const acquiredAt = new Date();
   const concurrencyGroup = String(opts?.concurrencyGroup || opts?.concurrency_group || "").trim();
   const payload = {
     agent: agentName,
@@ -602,12 +656,14 @@ export function acquireLock(agentName, taskId, files = [], rootOrOpts = resolveR
     branch,
     files,
     concurrencyGroup,
-    pid: process.pid,
+    pid: ownerPid,
     processStartTime: startTime,
     starttime: startTime,
+    leased,
     nonce: randomUUID(),
     hostname: hostname(),
-    acquiredAt: new Date().toISOString(),
+    acquiredAt: acquiredAt.toISOString(),
+    expiresAt: new Date(acquiredAt.getTime() + ttlMs).toISOString(),
   };
 
   let fd;