jules-orchestrator-kit 0.53.0 → 0.54.1

package/README.md

@@ -197,10 +197,12 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-in modules (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:http`, `node:tty`, `node:test`).
 * **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`.
+* **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 **797 unit tests across 98 suites passing in < 12.0s**.
+* **Verified Test Suite:** Tested with **835 unit tests across 109 suites passing in < 14.0s**.
 
 <br/>
 
@@ -226,10 +228,11 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 | `retry` | `agentctl retry <sessionId> [--role <role>] [--with-failure] [--json]` | Fetches error traces and activity logs from a failed session and synthesizes a targeted OODA retry dispatch. | `0` (Dispatched), `1` (Error) |
 | `prune` | `agentctl prune [--age 7d] [--state <state>] [--delete] [--yes] [--json]` | Queries and batch-archives or deletes stale/completed sessions via Jules v1alpha API to keep workspaces clean. | `0` (Cleaned) |
 | `pr harvest` | `agentctl pr harvest [--tier r0,r1] [--limit <n>] [--auto] [--allow-no-checks] [--dry-run]` | Discovers open agent PRs, evaluates CI checks & risk tiers, and auto-squashes green low-risk changes autonomously. A PR reporting **no** CI checks is skipped unless `--allow-no-checks` is passed, and an unavailable changed-file list blocks rather than classifying as low risk. | `0` (Triaged/Merged), `1` (Error) |
-| `providers` | `agentctl providers [--json]` | Probes every built-in provider and reports which ones this machine can dispatch to, what each one is missing, and which is active. | `0` (Active provider ready), `1` (Not ready) |
+| `providers` | `agentctl providers [--json]` | Probes every built-in provider and reports which ones this machine can dispatch to, what each one is missing, and which is active. For a CLI provider, "ready" means the binary is on `PATH` — it does not prove the CLI is signed in. | `0` (Active provider ready), `1` (Not ready) |
+| `provider set` | `agentctl provider set <name>` | Switches the active provider in `.agent/config.yml` in place, preserving comments. | `0` (Set), `1` (No manifest), `2` (Name missing) |
 | `profile` | `agentctl profile [--list] [--set minimal\|standard\|max] [--json]` | Shows the verification stages the configured profile expands to on this stack, or writes a new profile into `.agent/config.yml` without disturbing comments. | `0` (Shown/Set), `2` (Unknown profile) |
 | `ci init` | `agentctl ci init [--target github\|gitlab] [--force] [--dry-run] [--json]` | Generates a stack-aware CI gate workflow (`.github/workflows/agent-gate.yml` or `.gitlab-ci.agent-gate.yml`) that runs `agentctl check --mode committed`. Refuses to overwrite without `--force`. | `0` (Written/Skipped), `1` (Write error), `2` (Unknown target) |
-| `doctor` | `agentctl doctor [--json]` | Diagnostic DAG check runner & automated transactional self-repair engine. | `0` (Healthy), `1` (Failures) |
+| `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) |

package/bin/agentctl.mjs

@@ -4,6 +4,7 @@ import { parseArgs } from "node:util";
 import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { applyEnvAliases } from "../src/env-aliases.mjs";
+import { selectFailureOutput } from "../src/ops/verify-output.mjs";
 import { loadConfig, resolveRoot, detectStack, bootstrapZeroTestRepo } from "../src/config.mjs";
 import { gate, dispatch, run, isTaskFile } from "../src/engine.mjs";
 import { acquireLock, releaseLock, lockStatus, getQueueDir } from "../src/state.mjs";
@@ -63,6 +64,7 @@ Commands:
   lock <action>         Manage mutex locks (acquire | 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
   profile               Show or set the verification profile (--list, --set <name>, --json)
   ci init               Generate a stack-aware CI gate workflow (--target github|gitlab, --force)
   bootstrap             Bootstrap zero-test repository with verification oracle
@@ -195,9 +197,7 @@ function printVerifyFailure(failure) {
   if (failure.command) console.log(`     - Command: ${failure.command}`);
   for (const d of failure.diagnostics || []) console.log(`     - ${d}`);
 
-  // stderr is where a failing suite says what it expected; stdout is the
-  // fallback for the runners that report everything there.
-  const output = (failure.stderr || "").trim() || (failure.stdout || "").trim();
+  const output = selectFailureOutput(failure);
   if (!output) return;
   const lines = output.split("\n");
   const tail = lines.slice(-VERIFY_OUTPUT_TAIL_LINES);
@@ -419,6 +419,13 @@ async function main() {
           if (p.findings) {
             p.findings.forEach((f) => console.log(`     - [${f.severity}] ${f.type}: ${f.description}`));
           }
+          // `git_resolution` reports its cause in `error` and nothing else.
+          // Never rendering it meant an unresolvable base branch printed a bare
+          // "Phase [GIT_RESOLUTION] : ❌ FAIL" and the operator had to re-run
+          // with --json to find out what the tool had objected to.
+          if (!p.ok && p.error) {
+            console.log(`     - Error: ${p.error}`);
+          }
           if (!p.ok && p.failure) {
             printVerifyFailure(p.failure);
           }
@@ -427,13 +434,49 @@ async function main() {
         console.log(`Overall Result: ${res.ok ? "APPROVED (Exit 0)" : `REJECTED (Exit ${res.code})`}\n`);
         if (!res.ok) {
           const failedPhase = res.phases.find((p) => !p.ok)?.phase;
+          // The secret scanner also carries the integrity findings, so exit 6
+          // alone cannot pick the hint: a weakened assertion and a leaked key
+          // arrive under the same phase and the same code.
+          const secretsPhase = res.phases.find((p) => p.phase === "secrets" && !p.ok);
+          const findingTypes = new Set((secretsPhase?.findings || []).map((f) => f.type));
+          const INTEGRITY_TYPES = new Set([
+            "TEST_TAMPERING_DETECTED",
+            "EDGE_RUNTIME_VIOLATION",
+            "CROSS_PACKAGE_BOUNDARY_VIOLATION",
+          ]);
+          const onlyIntegrityFindings =
+            findingTypes.size > 0 && [...findingTypes].every((t) => INTEGRITY_TYPES.has(t));
+
           // Exit 3 is also what a strictTestLock tamper verdict returns, so the
           // code alone cannot pick the hint — a scope remediation for a rewritten
           // test file sends the operator to the wrong flag entirely.
           if (res.repairs) {
-            console.log(`💡 Remediation Hint (Exit 4 OODA Repair Exhausted):`);
-            console.log(`   • Automated self-repair could not pass tests cleanly.`);
-            console.log(`   • Review error fingerprints via: agentctl doctor\n`);
+            // A repair loop that never reached the agent is not an exhausted
+            // repair loop. Telling someone their tests could not be fixed when
+            // the provider rejected the credential sends them to read test
+            // output that was never produced.
+            const providerFailure =
+              res.repairs.finalStatus === "PROVIDER_INFRASTRUCTURE_FAILURE" ||
+              (res.repairs.attempts || []).every((a) => a && a.ok === false && a.error);
+            const firstError = (res.repairs.attempts || []).find((a) => a && a.error)?.error || res.repairs.error;
+            if (providerFailure && firstError) {
+              console.log(`💡 Remediation Hint (Exit 4 — the repair agent never ran):`);
+              console.log(`   • The provider rejected the dispatch, so no repair was attempted.`);
+              console.log(`   • Provider error: ${firstError}`);
+              console.log(`   • Check the provider is usable: agentctl providers`);
+              console.log(`   • The verification failure above is unchanged — fix it locally, or retry once the provider works.\n`);
+            } else {
+              console.log(`💡 Remediation Hint (Exit 4 OODA Repair Exhausted):`);
+              console.log(`   • Automated self-repair could not pass tests cleanly.`);
+              if (firstError) console.log(`   • Last attempt error: ${firstError}`);
+              console.log(`   • Review error fingerprints via: agentctl doctor\n`);
+            }
+          } else if (onlyIntegrityFindings) {
+            console.log(`💡 Remediation Hint (Exit ${res.code} Test Integrity Violation — no secret was found):`);
+            console.log(`   • The diff weakens or removes verification rather than leaking a credential.`);
+            console.log(`   • Restore the assertion the finding names. A requirement that is not met belongs`);
+            console.log(`     RED with a stated reason, not silenced.`);
+            console.log(`   • Nothing needs rotating: this exit code is shared with the secret scanner.\n`);
           } else if (res.flakyVerdict?.verdict === "QUARANTINED") {
             console.log(`💡 Remediation Hint (Exit 8 Flaky Test Quarantined):`);
             console.log(`   • This command has alternated between pass and fail across recent runs.`);
@@ -441,14 +484,52 @@ async function main() {
             console.log(`💡 Remediation Hint (Exit 188 Offline Network Violation / Infrastructure):`);
             console.log(`   • An unmocked network request was blocked by the preload network guard during verification.`);
             console.log(`   • Ensure dependencies are installed locally (run: npm install) and all network calls in tests are mocked.\n`);
+          } else if (res.phases.find((p) => p.phase === "verify" && !p.ok)?.failure?.stageId === "oracle") {
+            // Nothing exited non-zero here and --fix cannot help: there was no
+            // command to run. Offering the repair loop would send an agent to
+            // fix a failure that does not exist.
+            console.log(`💡 Remediation Hint (Exit ${res.code} No Verification Oracle):`);
+            console.log(`   • Nothing was executed against this change, so the gate cannot approve it.`);
+            console.log(`   • Give it a command:   agentctl bootstrap        (generates one for this stack)`);
+            console.log(`   • Or set it by hand:   verify.test in ${config._file || ".agent/config.yml"}`);
+            console.log(`   • Scope- and secret-scanning only, on purpose? Set verify.required: false there.\n`);
           } else if (failedPhase === "verify" || failedPhase === "evidence") {
             console.log(`💡 Remediation Hint (Exit ${res.code} Verification Failed):`);
             console.log(`   • The stage above exited non-zero. Reproduce it locally, then re-run the gate.`);
             console.log(`   • To let agentctl attempt the repair loop itself, pass: agentctl gate --fix\n`);
           } else if (res.code === 3) {
-            console.log(`💡 Remediation Hint (Exit 3 Scope Violation):`);
-            console.log(`   • To allow protected files in this run, pass: agentctl gate --allow-protected`);
-            console.log(`   • Or remove protected/denied paths from the diff before dispatching.\n`);
+            // The same violation has two very different causes. Right after
+            // `init`, every offending path is a file the tool itself just wrote
+            // and has not committed — advising --allow-protected there teaches
+            // the newcomer to bypass the gate on their first run, when what
+            // they need is `git commit`.
+            const scopeFiles = (res.phases.find((p) => p.phase === "scope")?.violations || [])
+              .map((v) => v.file)
+              .filter(Boolean);
+            const { partitionTracked } = await import("../src/git.mjs");
+            const { tracked, untracked } = partitionTracked(root, scopeFiles);
+            const allNewScaffolding =
+              untracked.length > 0 &&
+              tracked.length === 0 &&
+              untracked.every((f) => /^(\.agent\/|AGENTS\.md$|SPEC\.md$|CONSTRAINTS\.md$|DESIGN\.md$)/.test(f));
+
+            if (allNewScaffolding) {
+              console.log(`💡 Remediation Hint (Exit ${res.code} — these are the files init just wrote):`);
+              console.log(`   • The agent manifest and guardrails are gate-protected on purpose: an agent must`);
+              console.log(`     not edit the rules it is governed by. Uncommitted, they read as exactly that.`);
+              console.log(`   • Commit them once and the gate goes green:`);
+              console.log(`       git add ${untracked.join(" ")} && git commit -m "chore: add agent config"\n`);
+            } else {
+              console.log(`💡 Remediation Hint (Exit ${res.code} Scope Violation):`);
+              console.log(`   • To allow protected files in this run, pass: agentctl gate --allow-protected`);
+              console.log(`   • Or remove protected/denied paths from the diff before dispatching.\n`);
+            }
+          } else if (failedPhase === "git_resolution") {
+            console.log(`💡 Remediation Hint (Exit ${res.code} Base Branch Unresolvable):`);
+            console.log(`   • The gate compares your work against a base branch, and this one is not reachable.`);
+            console.log(`   • This repository's branches: git branch -a`);
+            console.log(`   • Point the gate at the right one: agentctl check --base <branch>`);
+            console.log(`   • Or record it once in .agent/config.yml as: base_branch: <branch>\n`);
           } else if (res.code === 5) {
             console.log(`💡 Remediation Hint (Exit 5 Diff Payload Overflow):`);
             console.log(`   • Total diff exceeds ${config.limits?.diffKb || 75} KB limit.`);
@@ -554,7 +635,11 @@ async function main() {
 
       const root = resolveRoot();
       const minCoverage = values.min ? parseFloat(values.min) : (values["min-coverage"] ? parseFloat(values["min-coverage"]) : 100);
-      const diffStr = diffText(root, values.base || "main", values.mode || "working-tree");
+      // `config.baseBranch` was skipped here while every other gate honoured it,
+      // so `agentctl coverage` alone died on "Cannot resolve base reference
+      // main" in any repository not on `main`.
+      const coverageBase = values.base || config.baseBranch || "main";
+      const diffStr = diffText(root, coverageBase, values.mode || "working-tree");
 
       const covRes = runV8Coverage(values.cmd, { root });
       const report = calculateDiffCoverage(covRes.coverageByFile, diffStr, { root, minCoverage });
@@ -562,7 +647,7 @@ async function main() {
       if (values.json) {
         console.log(JSON.stringify({ ...report, testPass: covRes.ok }, null, 2));
       } else {
-        console.log(`\n📊 V8 Native Diff Coverage Report (Base: ${values.base || "main"})`);
+        console.log(`\n📊 V8 Native Diff Coverage Report (Base: ${coverageBase})`);
         console.log(`------------------------------------------------------------------`);
         console.log(`  Target Min Coverage : ${report.minCoverage}%`);
         console.log(`  Achieved Coverage   : ${report.score}%`);
@@ -1161,7 +1246,13 @@ async function main() {
     case "doctor": {
       const { values } = parseArgs({
         args: args.slice(1),
-        options: { json: { type: "boolean", short: "j" } },
+        options: {
+          json: { type: "boolean", short: "j" },
+          // `--probe` was advertised in the command registry and declared
+          // nowhere, so `runDoctorChecks` never saw `activeProbe` and the flag
+          // was silently inert.
+          probe: { type: "boolean" },
+        },
         allowPositionals: true,
         strict: false,
       });
@@ -1170,7 +1261,7 @@ async function main() {
       // them: this command printed a hand-written summary, so findings like a
       // git-tracked .env were computed, tested, and never shown to anyone.
       const { runDoctorChecks } = await import("../src/ops/doctor-registry.mjs");
-      const report = await runDoctorChecks({ root });
+      const report = await runDoctorChecks({ root, activeProbe: Boolean(values.probe) });
 
       if (values.json) {
         console.log(JSON.stringify(report, null, 2));
@@ -1190,7 +1281,11 @@ async function main() {
       const icon = { pass: "✅", warn: "⚠️ ", fail: "❌", skip: "⏭️ ", unknown: "❔" };
       for (const r of report.results) {
         console.log(`  ${icon[r.status] || "•"} ${r.title}`);
-        if (r.status !== "pass") {
+        // A passing row normally speaks for itself. Provider readiness does
+        // not: green there means "a binary was found", and read as "the
+        // provider works" it sends someone into a dispatch that cannot succeed.
+        // Such a row asks to be spelled out even when it passes.
+        if (r.status !== "pass" || r.alwaysShowSummary) {
           console.log(`       ${r.summary}`);
           for (const fix of r.remediation || []) console.log(`       → ${fix.summary}`);
         }
@@ -1203,7 +1298,32 @@ async function main() {
       break;
     }
 
+    case "provider":
     case "providers": {
+      // `agentctl providers` used to tell the operator to run
+      // `agentctl init --provider <name>` to switch — which restarts the whole
+      // onboarding wizard, plan question included, to change one line.
+      if (args[1] === "set") {
+        const target = args[2];
+        if (!target) {
+          console.error(`❌ Usage: agentctl provider set <name>   (see: agentctl providers)`);
+          process.exit(2);
+        }
+        const { setConfigProvider } = await import("../src/config-edit.mjs");
+        const res = setConfigProvider(root, target);
+        if (!res.ok) {
+          console.error(`❌ ${res.error}`);
+          process.exit(1);
+        }
+        const { probeProvider } = await import("../src/provider-readiness.mjs");
+        const probe = probeProvider(target);
+        console.log(`✅ Provider set to '${target}' in ${res.file}`);
+        console.log(`   ${probe.ready ? "Ready" : `Not ready — ${probe.remedy}`}`);
+        if (!probe.known) console.log(`   Note: '${target}' is not a built-in preset, so its readiness cannot be checked.`);
+        console.log(`   The manifest is gate-protected — commit it so the next check does not read it as an agent edit.`);
+        process.exit(0);
+      }
+
       const { values } = parseArgs({
         args: args.slice(1),
         options: { json: { type: "boolean", short: "j" } },
@@ -1231,7 +1351,9 @@ async function main() {
         console.log(`       ${activeProbe.reason}`);
       }
       console.log(`\n  Active: ${active} (provider: in ${config._file || ".agent/config.yml"})`);
-      console.log(`  Switch: agentctl init --provider <name>   ·   every gate below works with no provider at all\n`);
+      console.log(`  Switch: agentctl provider set <name>   ·   every gate below works with no provider at all`);
+      console.log(`  Note:   for the CLI providers, "ready" means the binary is on PATH — it does not prove`);
+      console.log(`          the CLI is signed in. A dispatch is the first thing that can tell you that.\n`);
       process.exit(activeProbe.ready ? 0 : 1);
       break;
     }
@@ -1254,13 +1376,14 @@ async function main() {
           console.error(`❌ Unknown profile '${values.set}'. Choose one of: ${PROFILE_NAMES.join(", ")}`);
           process.exit(2);
         }
-        const { setVerificationProfile } = await import("../src/profiles-io.mjs");
+        const { setVerificationProfile } = await import("../src/config-edit.mjs");
         const res = setVerificationProfile(root, name);
         if (!res.ok) {
           console.error(`❌ ${res.error}`);
           process.exit(1);
         }
         console.log(`✅ Verification profile set to '${name}' in ${res.file}`);
+        console.log(`   The manifest is gate-protected — commit it so the next check does not read it as an agent edit.`);
         process.exit(0);
       }
 
@@ -1512,8 +1635,15 @@ async function main() {
           allowPositionals: true,
         });
 
-        const isNonInteractive = Boolean(values["non-interactive"] || values["no-interactive"] || values.yes);
-        const isInteractive = values.interactive === true ? true : (isNonInteractive ? false : undefined);
+        const { resolveWizardInteractivity } = await import("../src/ops/cli-intent.mjs");
+        const isInteractive = resolveWizardInteractivity({
+          interactive: values.interactive,
+          nonInteractive: values["non-interactive"] || values["no-interactive"],
+          yes: values.yes,
+          // A title and a prompt together state the whole task; there is
+          // nothing left for the wizard to ask.
+          fullySpecified: Boolean(values.title && resolvePromptInput(values, positionals)),
+        });
 
         const { runTaskCreateWizard } = await import("../src/wizard-task.mjs");
         const res = await runTaskCreateWizard(root, {
@@ -1528,12 +1658,17 @@ async function main() {
           requirePlanApproval: values["require-plan-approval"],
           repoless: values.repoless,
           interactive: isInteractive,
+          dryRun: values["dry-run"],
         });
 
         if (values.json) {
           console.log(JSON.stringify(res, null, 2));
         } else {
-          console.log(`✅ Task synthesized & queued at ${res.taskFile}`);
+          console.log(
+            res.dryRun
+              ? `🧪 Dry run — envelope synthesized and validated, nothing written (would be ${res.taskFile})`
+              : `✅ Task synthesized & queued at ${res.taskFile}`
+          );
           console.log(`   Task ID  : ${res.plan.taskId}`);
           console.log(`   Title    : ${res.plan.title}`);
           if (res.plan.role) console.log(`   Role     : ${res.plan.role}`);
@@ -2349,26 +2484,32 @@ async function main() {
       const subAction = args[1];
       if (subAction === "init") {
         const { scaffoldIdeConfig } = await import("../src/ops/ide-scaffold.mjs");
-        const { values } = parseArgs({
+        const { values, positionals } = parseArgs({
           args: args.slice(2),
           options: {
-            target: { type: "string", short: "t", default: "all" },
+            // No `default: "all"` here. parseArgs sets a default eagerly, so
+            // `values.target` was always truthy and the `|| args[2]` fallback
+            // below could never be reached — `agentctl mcp init cursor`, the
+            // spelling --help advertises, silently scaffolded Cursor, VS Code
+            // and Claude Desktop alike. The default belongs at the end of the
+            // resolution chain, not at the start of it.
+            target: { type: "string", short: "t" },
             json: { type: "boolean", short: "j" },
             "dry-run": { type: "boolean", short: "d" },
           },
           allowPositionals: true,
         });
 
-        const target = values.target || args[2] || "all";
+        const target = values.target || positionals[0] || "all";
         try {
-          const res = scaffoldIdeConfig(target, { root });
+          const res = scaffoldIdeConfig(target, { root, dryRun: values["dry-run"] });
           if (values.json) {
             console.log(JSON.stringify(res, null, 2));
           } else {
-            console.log(`\n🔌 IDE MCP Config Scaffolded Successfully!`);
+            console.log(res.dryRun ? `\n🧪 IDE MCP Config — dry run, nothing written` : `\n🔌 IDE MCP Config Scaffolded Successfully!`);
             console.log(`   Target  : ${res.target}`);
             for (const item of res.results) {
-              console.log(`   - ${item.target.toUpperCase()} : ${item.file}`);
+              console.log(`   - ${item.target.toUpperCase()} : ${item.file}${res.dryRun ? " (would write)" : ""}`);
             }
             console.log("");
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.53.0",
+  "version": "0.54.1",
   "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/config-edit.mjs

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { PROFILE_NAMES } from "./profiles.mjs";
+import { PROVIDER_DESCRIPTORS } from "./provider-readiness.mjs";
+
+/**
+ * In-place edits to the repository's agent manifest.
+ *
+ * Surgical text edits rather than parse-and-reserialise: the kit's YAML reader
+ * is a subset parser, so round-tripping the file through it would drop every
+ * comment the wizard wrote and any key the subset does not model. The manifest
+ * is a file a human maintains; a tool that rewrites it must leave the rest of
+ * it alone.
+ */
+
+/**
+ * The manifest this repository uses, or null when it has none.
+ * @param {string} root
+ * @returns {string|null}
+ */
+function findManifest(root) {
+  return [join(root, ".agent", "config.yml"), join(root, ".agent", "jules.yml")].find((f) => existsSync(f)) || null;
+}
+
+/**
+ * Rewrite the manifest from a line transform, atomically.
+ * @param {string} file
+ * @param {(lines: string[]) => string[]} transform
+ * @returns {{ ok: boolean, file?: string, error?: string }}
+ */
+function editManifest(file, transform) {
+  let text;
+  try {
+    text = readFileSync(file, "utf-8");
+  } catch (err) {
+    return { ok: false, error: `Could not read ${file}: ${err.message}` };
+  }
+
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = transform(text.split(/\r?\n/));
+
+  const tmp = `${file}.tmp-${process.pid}`;
+  try {
+    writeFileSync(tmp, lines.join(eol), "utf-8");
+    renameSync(tmp, file);
+  } catch (err) {
+    return { ok: false, error: `Could not write ${file}: ${err.message}` };
+  }
+  return { ok: true, file };
+}
+
+/**
+ * Set the top-level `provider:` key.
+ *
+ * `agentctl providers` used to point at `agentctl init --provider <name>` to
+ * change providers, which restarts the whole onboarding wizard — plan question
+ * and all — to edit one line. This is that one line.
+ *
+ * @param {string} root
+ * @param {string} provider
+ * @returns {{ ok: boolean, file?: string, error?: string }}
+ */
+export function setConfigProvider(root, provider) {
+  const name = String(provider || "").trim();
+  if (!name) {
+    return { ok: false, error: `Provider name required. Known presets: ${Object.keys(PROVIDER_DESCRIPTORS).join(", ")}` };
+  }
+  if (!/^[\w.-]+$/.test(name)) {
+    return { ok: false, error: `Invalid provider name '${provider}'.` };
+  }
+
+  const file = findManifest(root);
+  if (!file) return { ok: false, error: "No .agent/config.yml found. Run `agentctl init` first." };
+
+  return editManifest(file, (lines) => {
+    const idx = lines.findIndex((l) => /^provider:\s*/.test(l));
+    if (idx >= 0) {
+      lines[idx] = `provider: ${name}`;
+      return lines;
+    }
+    // Keep it near the top where the wizard writes it, after `version:` if
+    // present, so a hand-read manifest still leads with what it is.
+    const versionIdx = lines.findIndex((l) => /^version:\s*/.test(l));
+    lines.splice(versionIdx >= 0 ? versionIdx + 1 : 0, 0, `provider: ${name}`);
+    return lines;
+  });
+}
+
+/**
+ * Set `verify.profile` in the repository's manifest, in place.
+ *
+ * @param {string} root
+ * @param {string} profile - one of {@link PROFILE_NAMES}
+ * @returns {{ ok: boolean, file?: string, error?: string }}
+ */
+export function setVerificationProfile(root, profile) {
+  const name = String(profile || "").toLowerCase();
+  if (!PROFILE_NAMES.includes(name)) {
+    return { ok: false, error: `Unknown profile '${profile}'. Choose one of: ${PROFILE_NAMES.join(", ")}` };
+  }
+
+  const file = findManifest(root);
+  if (!file) {
+    return { ok: false, error: "No .agent/config.yml found. Run `agentctl init` first." };
+  }
+
+  return editManifest(file, (lines) => {
+
+    // Find the `verify:` mapping and the `profile:` key nested directly under it.
+    let verifyIdx = -1;
+    let profileIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (/^verify:\s*$/.test(lines[i])) {
+        verifyIdx = i;
+        for (let j = i + 1; j < lines.length; j++) {
+          // A non-indented, non-blank line ends the block.
+          if (lines[j].trim() !== "" && !/^\s/.test(lines[j])) break;
+          if (/^\s+profile:\s*/.test(lines[j])) {
+            profileIdx = j;
+            break;
+          }
+        }
+        break;
+      }
+    }
+
+    if (profileIdx >= 0) {
+      const indent = lines[profileIdx].match(/^(\s*)/)[1];
+      lines[profileIdx] = `${indent}profile: ${name}`;
+    } else if (verifyIdx >= 0) {
+      lines.splice(verifyIdx + 1, 0, `  profile: ${name}`);
+    } else {
+      if (lines.length && lines[lines.length - 1] !== "") lines.push("");
+      lines.push("verify:", `  profile: ${name}`, "");
+    }
+    return lines;
+  });
+}

package/src/config.mjs

@@ -522,6 +522,11 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     teardown: rawTeardown ?? autoVerify.teardown ?? "",
     build: rawBuild ?? autoVerify.build,
     policy: parsed.verify?.policy ?? autoVerify.policy,
+    // 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
+    // that deliberately uses only the scope and secret phases sets this false.
+    required: parsed.verify?.required !== false,
   };
 
   // A hand-written `verify.stages:` is the operator being explicit and always

package/src/engine.mjs

@@ -1,6 +1,6 @@
 import { loadConfig, parseYaml, normalizeScope } from "./config.mjs";
-import { checkScope, scanDiff, redactSecrets } from "./security.mjs";
-import { changedFiles, diffBytes, diffText, showFromOrigin, runCmd } from "./git.mjs";
+import { checkScope, scanDiff, scanBinaryPayloads, redactSecrets } from "./security.mjs";
+import { changedFiles, diffBytes, diffText, binaryDiffEntries, 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";
@@ -198,6 +198,9 @@ export async function gate(opts = {}) {
           build: parsed.verify?.build || parsed.build_cmd || config.verify.build,
           stages: parsed.verify?.stages || config.verify.stages,
           policy: parsed.verify?.policy || config.verify.policy,
+          // 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,
           timeoutMs: parsed.verify?.timeoutMs || parsed.verify?.timeout_ms || config.verify.timeoutMs,
         };
       }
@@ -242,13 +245,25 @@ export async function gate(opts = {}) {
 
   // Phase 3: Diff Secret Scanner & Security Checks
   const secretResult = scanDiff(diffStr, { root });
-  phases.push({ phase: "secrets", ok: secretResult.ok, findings: secretResult.findings });
-  appendTelemetry(root, "gate_phase", { phase: "secrets", ok: secretResult.ok });
+  // 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.
+  let binaryFindings = [];
+  try {
+    binaryFindings = scanBinaryPayloads(binaryDiffEntries(root, base, mode), root);
+  } catch (_) {
+    // Never let the extra pass break a gate that would otherwise have run; the
+    // text scan above has already been applied.
+  }
+  const allSecretFindings = [...(secretResult.findings || []), ...binaryFindings];
+  const secretsOk = secretResult.ok && binaryFindings.length === 0;
+  phases.push({ phase: "secrets", ok: secretsOk, findings: allSecretFindings });
+  appendTelemetry(root, "gate_phase", { phase: "secrets", ok: secretsOk });
   if (progressBus && progressToken) {
     progressBus.reportProgress(progressToken, 75, 100, "Phase 3/4: Diff Secret Scanner check complete");
   }
 
-  if (!secretResult.ok) {
+  if (!secretsOk) {
     appendTelemetry(root, "gate_finished", { ok: false, code: 6 });
     return { ok: false, code: 6, phases };
   }
@@ -415,7 +430,23 @@ export async function gate(opts = {}) {
     }
   }
 
-  const verifyOk = !failingCmd && !testTampered;
+  // A gate that ran no verification at all must not report APPROVED.
+  //
+  // `testResult` starts optimistic and the stage loop skips a stage with no
+  // command, so a repository with no test oracle produced zero execution
+  // records and a clean bill of health — syntactically broken code included.
+  // That is the product's central claim inverted: the whole point is that a
+  // change is verified before it is approved, and "nothing to run" is not
+  // verification. Repositories that deliberately use only the scope and secret
+  // phases opt out with `verify.required: false`.
+  // Assertions are guards, not oracles: `assert:test-integrity` proves the diff
+  // did not weaken a test, which says nothing about whether the code works. The
+  // question is whether any command was executed against the change at all.
+  const verificationRequired = trustedVerify.required !== false;
+  const ranNoVerification = !executionRecords.some((r) => r && r.kind !== "assert");
+  const missingOracle = verificationRequired && ranNoVerification;
+
+  const verifyOk = !failingCmd && !testTampered && !missingOracle;
 
   // What actually broke. Without this the verify phase reported `ok: false` and
   // nothing else — not the stage, not the exit code, not a line of output — so
@@ -448,7 +479,21 @@ export async function gate(opts = {}) {
           stderr: `Test files changed during the run (${preTestHash.slice(0, 12)} → ${postTestHash.slice(0, 12)}). evidence.strictTestLock treats a passing suite that the diff also rewrote as unproven.`,
           diagnostics: [],
         }
-      : null;
+      : missingOracle
+        ? {
+            stageId: "oracle",
+            command: null,
+            exitCode: null,
+            stdout: "",
+            stderr:
+              "No verification command ran, so nothing about this change was checked. " +
+              "Set verify.test in .agent/config.yml (or run `agentctl bootstrap` to generate one). " +
+              "If this repository intentionally uses only the scope and secret phases, set verify.required: false.",
+            diagnostics: [
+              "The gate approves a change because verification passed. Zero stages executed is not a pass.",
+            ],
+          }
+        : null;
 
   // Generate & persist Evidence Manifest
   const evidenceManifest = generateEvidenceManifest(root, {