jules-orchestrator-kit 0.53.0 → 0.54.0

package/README.md

@@ -200,7 +200,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 **797 unit tests across 98 suites passing in < 12.0s**.
+* **Verified Test Suite:** Tested with **827 unit tests across 107 suites passing in < 14.0s**.
 
 <br/>
 
@@ -226,10 +226,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.`);
@@ -446,9 +489,38 @@ async function main() {
             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 +626,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 +638,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 +1237,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 +1252,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 +1272,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 +1289,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 +1342,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 +1367,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 +1626,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 +1649,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 +2475,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.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/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/git.mjs

@@ -454,6 +454,85 @@ export function parseGitHubRepo(remoteUrl) {
  * @param {string} [root=process.cwd()]
  * @returns {string}
  */
+/**
+ * Work out which branch this repository actually treats as its base.
+ *
+ * `main` was hardcoded as the scaffolded default, which is wrong the moment
+ * `git init` picks `master` (still the default on many installed gits) or the
+ * project standardised on `develop`. The failure was not graceful: the first
+ * `agentctl check` could not resolve the base ref and rejected with exit 1.
+ *
+ * Resolution order, strongest evidence first:
+ *   1. `origin/HEAD` — the remote states its own default branch.
+ *   2. A local `main`, then `master` — the conventional names, preferred over
+ *      the checked-out branch so running `init` from a feature branch does not
+ *      record that feature branch as the base for everything after.
+ *   3. The current branch — covers a fresh `git init` with no commits, where
+ *      HEAD points at an unborn branch that `--show-current` still names.
+ *   4. `main`, when there is no git information at all to go on.
+ *
+ * @param {string} [root=process.cwd()]
+ * @returns {string}
+ */
+/**
+ * Split a list of repo-relative paths into the ones git already tracks and the
+ * ones it does not.
+ *
+ * Used to tell an onboarding mistake apart from an agent overstepping. Both
+ * arrive as the same exit-3 scope violation on the same protected paths, but
+ * "the files `init` just wrote are not committed yet" and "something edited the
+ * rules it is governed by" need opposite advice, and the operator who has just
+ * met the tool gets the wrong half if the two are not distinguished.
+ *
+ * @param {string} root
+ * @param {string[]} files - repo-relative paths
+ * @returns {{ tracked: string[], untracked: string[] }}
+ */
+export function partitionTracked(root = process.cwd(), files = []) {
+  const list = files.filter((f) => typeof f === "string" && f && !f.startsWith("-"));
+  if (list.length === 0) return { tracked: [], untracked: [] };
+  let out = "";
+  try {
+    out = git(["ls-files", "--", ...list], { cwd: root, ignoreError: true }) || "";
+  } catch (_) {
+    // Without an answer, claim nothing is tracked-or-not: callers fall back to
+    // the generic advice rather than to a guess.
+    return { tracked: [], untracked: [] };
+  }
+  const tracked = new Set(out.split("\n").map((l) => l.trim()).filter(Boolean));
+  return {
+    tracked: list.filter((f) => tracked.has(f)),
+    untracked: list.filter((f) => !tracked.has(f)),
+  };
+}
+
+export function detectDefaultBranch(root = process.cwd()) {
+  // `git()` returns trimmed stdout, and "" for a non-zero exit under
+  // ignoreError — there is no status field to read.
+  const ask = (args) => {
+    try {
+      return git(args, { cwd: root, ignoreError: true }) || "";
+    } catch (_) {
+      return "";
+    }
+  };
+
+  const remoteHead = ask(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+  if (remoteHead.startsWith("origin/")) {
+    const name = remoteHead.slice("origin/".length).trim();
+    if (name) return name;
+  }
+
+  for (const candidate of ["main", "master"]) {
+    if (ask(["rev-parse", "--verify", "--quiet", `refs/heads/${candidate}`])) return candidate;
+  }
+
+  const current = ask(["branch", "--show-current"]);
+  if (current) return current;
+
+  return "main";
+}
+
 export function resolveGitRemoteOrigin(root = process.cwd()) {
   try {
     const raw = git(["config", "--get", "remote.origin.url"], { cwd: root, ignoreError: true });

package/src/ops/cli-intent.mjs

@@ -0,0 +1,29 @@
+/**
+ * Whether a command invocation is asking to be walked through a wizard, or has
+ * already said everything the wizard would ask.
+ *
+ * `agentctl task create --title X --prompt Y` states the whole task and then
+ * opened the interactive wizard anyway, which re-asked for the title and the
+ * prompt in a terminal and hung a CI job that had no terminal to answer with.
+ * Neither `--yes` nor `--non-interactive` was passed, so the CLI concluded
+ * "interactive" from the absence of a flag rather than from the presence of the
+ * answers.
+ *
+ * Kept as a pure function, out of the CLI script, because that script executes
+ * on import and so cannot be exercised from a test.
+ *
+ * @param {object} input
+ * @param {boolean} [input.interactive] - `--interactive` was passed explicitly
+ * @param {boolean} [input.nonInteractive] - `--non-interactive` / `--no-interactive`
+ * @param {boolean} [input.yes] - `--yes`
+ * @param {boolean} [input.fullySpecified] - every field the wizard would ask for is present
+ * @returns {boolean|undefined} true/false to force a mode, undefined to let the
+ *   callee decide from whether stdin is a TTY
+ */
+export function resolveWizardInteractivity(input = {}) {
+  // An explicit `--interactive` always wins: the flags may be intended as seeds
+  // to edit rather than as a complete invocation.
+  if (input.interactive === true) return true;
+  if (input.nonInteractive || input.yes || input.fullySpecified) return false;
+  return undefined;
+}

package/src/ops/command-registry.mjs

@@ -70,35 +70,44 @@ export const COMMAND_REGISTRY = [
     shortcuts: ["d", "doc"],
     examples: [
       "agentctl doctor",
-      "agentctl doctor --interactive",
-      "agentctl doctor --fix safe --yes",
+      "agentctl doctor --probe",
       "agentctl doctor --json",
     ],
+    // `--interactive`, `--fix` and `--yes` were listed here and implemented
+    // nowhere: the report carries remediation entries, but nothing applies
+    // them. Advertising a flag the command silently ignores is the same defect
+    // as documenting `queue` as a read-only browser. They come back to this
+    // list when an apply step exists.
     flags: [
-      { name: "interactive", type: "boolean", description: "Open full-screen diagnostic matrix" },
-      { name: "fix", type: "string", description: "Apply fix classes (e.g. 'safe' or check IDs)" },
-      { name: "probe", type: "boolean", description: "Enable active network/execution probes" },
+      { name: "probe", type: "boolean", description: "Actively start the provider CLI to check it answers, rather than only finding it on PATH" },
       { name: "json", type: "boolean", description: "Output structured JSON doctor report" },
-      { name: "yes", type: "boolean", description: "Bypass interactive confirmation for safe fixes" },
     ],
   },
   {
     id: "queue",
+    // This described a passive viewer — "Browse and manage", `mutates: false`,
+    // `risk: low` — while the handler runs the queue: it dispatches every task
+    // to the provider and spends budget. Someone reading `--help` before their
+    // first run was told the opposite of what the command does.
     path: ["queue"],
     title: "queue",
-    description: "Browse and manage canonical task queue",
+    description: "Execute pending task envelopes: dispatches each to the provider and moves it out of the queue",
     category: "Operate",
-    mutates: false,
-    risk: "low",
+    mutates: true,
+    risk: "moderate",
     interactive: "optional",
     requiresRepository: true,
     shortcuts: ["q"],
     examples: [
+      "agentctl queue --dry-run",
       "agentctl queue",
-      "agentctl queue --interactive",
+      "agentctl queue --dag --concurrency 3",
       "agentctl queue --json",
     ],
     flags: [
+      { name: "dag", type: "boolean", description: "Resolve depends-on order via Kahn's algorithm before running" },
+      { name: "concurrency", type: "string", description: "Parallel worker slots (defaults to limits.concurrency)" },
+      { name: "dry-run", type: "boolean", description: "Report what would run without dispatching or moving anything" },
       { name: "interactive", type: "boolean", description: "Open full-screen queue dashboard" },
       { name: "json", type: "boolean", description: "Output structured JSON queue snapshot" },
       { name: "limit", type: "string", description: "Maximum tasks to include in snapshot" },

package/src/ops/doctor-registry.mjs

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { execFileSync, spawnSync } from "node:child_process";
 import { loadConfig } from "../config.mjs";
-import { probeProvider, detectAvailableProviders } from "../provider-readiness.mjs";
+import { probeProvider, detectAvailableProviders, probeProviderLiveness } from "../provider-readiness.mjs";
 import { resolveConcurrency } from "../budget.mjs";
 
 /**
@@ -443,31 +443,53 @@ export async function runDoctorChecks(options = {}) {
     // Fall back to the default; config.present already reports a broken config.
   }
   const providerProbe = probeProvider(configuredProvider);
+  // A green row here used to read as "the provider works", when all it ever
+  // checked was a name on PATH or a variable in the environment. An installed
+  // CLI whose account has no entitlement passes both and then fails on the
+  // first dispatch, so the row has to say what it actually verified.
+  const liveness = activeProbe ? probeProviderLiveness(configuredProvider) : null;
+  const scopeNote =
+    providerProbe.kind === "exec"
+      ? "Checked: the binary is on PATH. Not checked: whether the CLI is signed in — only a dispatch can show that."
+      : "Checked: a credential is present in the environment. Not checked: whether the provider accepts it.";
+  const livenessFailed = Boolean(liveness && liveness.attempted && !liveness.ok);
+
   addResult({
     id: "provider.key",
     category: "Provider",
     title: `Provider Readiness (${providerProbe.name})`,
-    status: providerProbe.ready ? "pass" : "warn",
-    severity: providerProbe.ready ? "info" : "high",
+    alwaysShowSummary: true,
+    status: providerProbe.ready && !livenessFailed ? "pass" : "warn",
+    severity: providerProbe.ready && !livenessFailed ? "info" : "high",
     // Naming the variable, not the value: an operator who wonders which key a
     // dispatch will use should not have to echo a secret to find out.
-    summary: `${providerProbe.label} — ${providerProbe.reason}`,
-    remediation: providerProbe.ready
-      ? []
-      : [
-          {
-            summary: providerProbe.remedy,
-            risk: "low",
-            automatic: false,
-            requiresProbe: false,
-          },
-        ],
+    summary: [
+      `${providerProbe.label} — ${providerProbe.reason}`,
+      liveness && liveness.attempted ? liveness.detail : null,
+      providerProbe.ready ? scopeNote : null,
+      !activeProbe && providerProbe.kind === "exec" ? "Run `agentctl doctor --probe` to start the CLI and confirm it answers." : null,
+    ]
+      .filter(Boolean)
+      .join(" "),
+    remediation:
+      providerProbe.ready && !livenessFailed
+        ? []
+        : [
+            {
+              summary: livenessFailed ? `The CLI is installed but did not run cleanly: ${liveness.detail}` : providerProbe.remedy,
+              risk: "low",
+              automatic: false,
+              requiresProbe: !providerProbe.ready ? false : true,
+            },
+          ],
     evidence: [
       { label: "provider", value: providerProbe.name, sensitive: false },
       { label: "providerKind", value: providerProbe.kind, sensitive: false },
       { label: "ready", value: providerProbe.ready, sensitive: false },
       { label: "keySource", value: providerProbe.keySource || "", sensitive: false },
       { label: "binaryFound", value: Boolean(providerProbe.binPath), sensitive: false },
+      { label: "livenessProbed", value: Boolean(liveness && liveness.attempted), sensitive: false },
+      { label: "livenessOk", value: liveness ? liveness.ok : null, sensitive: false },
     ],
   });
 

package/src/ops/ide-scaffold.mjs

@@ -11,14 +11,32 @@ export class IdeScaffoldError extends Error {
 
 /**
  * Scaffolds IDE integration configuration files for Cursor, VS Code, and Claude Desktop.
+ *
+ * These files land in directories a project may already be using (`.cursor/`,
+ * `.vscode/`), and the merge logic preserves what is there — but `--dry-run`
+ * was accepted by the CLI and never reached here, so the only way to find out
+ * what would be touched was to let it happen.
+ *
  * @param {string} target - 'cursor' | 'vscode' | 'claude' | 'all'
  * @param {object} [options]
+ * @param {string} [options.root]
+ * @param {boolean} [options.dryRun] - report the files without writing them
  * @returns {object} Summary of scaffolded files
  */
 export function scaffoldIdeConfig(target = "all", options = {}) {
   const root = options.root || resolveRoot();
+  const dryRun = Boolean(options.dryRun);
   const validTargets = new Set(["cursor", "vscode", "claude", "all"]);
 
+  /** Write unless this is a rehearsal; the directory is only made when writing. */
+  const writeUnlessRehearsing = (dir, file, contents) => {
+    if (dryRun) return;
+    try {
+      mkdirSync(dir, { recursive: true });
+    } catch (_) {}
+    writeFileSync(file, contents, "utf-8");
+  };
+
   const normTarget = (target || "all").toLowerCase();
   if (!validTargets.has(normTarget)) {
     throw new IdeScaffoldError(`Invalid target '${target}'. Allowed targets: cursor, vscode, claude, all`);
@@ -29,10 +47,6 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
   // Target: Cursor (.cursor/mcp.json)
   if (normTarget === "cursor" || normTarget === "all") {
     const cursorDir = join(root, ".cursor");
-    try {
-      mkdirSync(cursorDir, { recursive: true });
-    } catch (_) {}
-
     const cursorConfigPath = join(cursorDir, "mcp.json");
     let existingConfig = {};
     if (existsSync(cursorConfigPath)) {
@@ -52,17 +66,13 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
       },
     };
 
-    writeFileSync(cursorConfigPath, JSON.stringify(updatedCursorConfig, null, 2), "utf-8");
+    writeUnlessRehearsing(cursorDir, cursorConfigPath, JSON.stringify(updatedCursorConfig, null, 2));
     results.push({ target: "cursor", file: ".cursor/mcp.json", ok: true });
   }
 
   // Target: VS Code (.vscode/tasks.json)
   if (normTarget === "vscode" || normTarget === "all") {
     const vscodeDir = join(root, ".vscode");
-    try {
-      mkdirSync(vscodeDir, { recursive: true });
-    } catch (_) {}
-
     const vscodeTasksPath = join(vscodeDir, "tasks.json");
     let existingConfig = { version: "2.0.0", tasks: [] };
     if (existsSync(vscodeTasksPath)) {
@@ -110,17 +120,13 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
       tasks: updatedTasks,
     };
 
-    writeFileSync(vscodeTasksPath, JSON.stringify(updatedVsCodeConfig, null, 2), "utf-8");
+    writeUnlessRehearsing(vscodeDir, vscodeTasksPath, JSON.stringify(updatedVsCodeConfig, null, 2));
     results.push({ target: "vscode", file: ".vscode/tasks.json", ok: true });
   }
 
   // Target: Claude Desktop (claude_desktop_config.json snippet helper)
   if (normTarget === "claude" || normTarget === "all") {
     const agentDir = join(root, ".agent");
-    try {
-      mkdirSync(agentDir, { recursive: true });
-    } catch (_) {}
-
     const snippetPath = join(agentDir, "claude_desktop_config.snippet.json");
     const claudeSnippet = {
       mcpServers: {
@@ -131,9 +137,9 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
       },
     };
 
-    writeFileSync(snippetPath, JSON.stringify(claudeSnippet, null, 2), "utf-8");
+    writeUnlessRehearsing(agentDir, snippetPath, JSON.stringify(claudeSnippet, null, 2));
     results.push({ target: "claude", file: ".agent/claude_desktop_config.snippet.json", ok: true });
   }
 
-  return { ok: true, target: normTarget, results };
+  return { ok: true, target: normTarget, dryRun, results };
 }

package/src/ops/verify-output.mjs

@@ -0,0 +1,38 @@
+/**
+ * Choose what to show the operator from a failed stage's captured streams.
+ *
+ * stderr is where a failing suite says what it expected; stdout is where
+ * several runners (node:test among them) put the whole report — assertion text
+ * and stack included.
+ *
+ * Preferring stderr outright discarded all of that whenever stderr held so much
+ * as the spawn wrapper's own "Command failed: npm test", which it always does.
+ * The operator was shown a line naming the command they had just typed, and
+ * nothing about which test failed or why. A wrapper line is not diagnostic
+ * output: when that is all stderr has, stdout is the report.
+ *
+ * Lives in src/ rather than in the CLI script so it can be imported and tested
+ * without executing the CLI, which runs on import.
+ *
+ * @param {{ stdout?: string, stderr?: string }} failure
+ * @returns {string}
+ */
+export function selectFailureOutput(failure = {}) {
+  const rawStderr = (failure.stderr || "").trim();
+  const rawStdout = (failure.stdout || "").trim();
+  if (!rawStderr) return rawStdout;
+
+  const stderrIsWrapperOnly = rawStderr
+    .split("\n")
+    .every((line) => line.trim() === "" || /^(command failed|error: command failed|npm err!?)/i.test(line.trim()));
+
+  if (stderrIsWrapperOnly && rawStdout) return rawStdout;
+  if (rawStdout && rawStdout !== rawStderr) {
+    // Both carry something real, so show both rather than guessing which runner
+    // this is. stderr goes last on purpose: the caller keeps only the tail, and
+    // when stderr has real content it is nearly always the failure itself —
+    // putting the runner's banner after it would spend the cap on noise.
+    return `${rawStdout}\n${rawStderr}`;
+  }
+  return rawStderr;
+}

package/src/provider-readiness.mjs

@@ -1,5 +1,7 @@
 import { existsSync, statSync } from "node:fs";
 import { join, delimiter } from "node:path";
+import { spawnSync } from "node:child_process";
+import { resolveWindowsSpawn } from "./git.mjs";
 
 /**
  * What each provider actually needs before a dispatch can succeed.
@@ -172,6 +174,7 @@ export function probeProvider(name, opts = {}) {
   return {
     name: descriptor.name,
     kind: descriptor.kind,
+    bin: descriptor.bin,
     label: descriptor.label,
     ready,
     known: true,
@@ -182,6 +185,72 @@ export function probeProvider(name, opts = {}) {
   };
 }
 
+/**
+ * Actually run the provider's CLI, rather than only finding it on PATH.
+ *
+ * `probeProvider` deliberately spawns nothing — it is called from a bare
+ * `agentctl` invocation and from `doctor`, both of which must stay instant. But
+ * a binary on PATH is a weak claim: a `gemini` that is installed and whose
+ * account has no access still reports ready, `doctor` still says 11 passed, and
+ * the first thing that disagrees is a dispatch that dies. This is the check
+ * that can disagree earlier, so it is opt-in (`agentctl doctor --probe`).
+ *
+ * It proves the binary starts and answers, not that the account is entitled —
+ * no CLI exposes "am I authorised" without doing work — but the common failures
+ * (broken install, wrong architecture, a CLI that refuses to start unauthenticated)
+ * surface here instead of mid-repair.
+ *
+ * @param {string} name
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env=process.env]
+ * @param {number} [opts.timeoutMs=8000]
+ * @returns {{ name: string, attempted: boolean, ok: boolean, detail: string }}
+ */
+export function probeProviderLiveness(name, opts = {}) {
+  const env = opts.env || process.env;
+  const base = probeProvider(name, { env });
+  if (base.kind !== "exec" || !base.binPath) {
+    return {
+      name: base.name,
+      attempted: false,
+      ok: base.ready,
+      detail: base.kind === "http" ? "Hosted provider — a credential cannot be validated without spending a request." : base.reason,
+    };
+  }
+
+  try {
+    // A global npm install puts a `.cmd` shim on PATH, and since the fix for
+    // CVE-2024-27980 Node refuses to spawn one directly — it comes back EINVAL,
+    // which would report every Windows CLI as broken. `resolveWindowsSpawn` is
+    // the same routing `runCmd` already uses: native .exe direct, everything
+    // else through cmd.exe with the argv quoted the way cmd.exe parses it back.
+    const win = resolveWindowsSpawn(base.binPath, ["--version"], env);
+    const res = win
+      ? spawnSync(win.file, win.args, {
+          encoding: "utf-8",
+          timeout: Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 8000,
+          env,
+          windowsVerbatimArguments: win.verbatim,
+        })
+      : spawnSync(base.binPath, ["--version"], {
+          encoding: "utf-8",
+          timeout: Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 8000,
+          env,
+        });
+    if (res.error) {
+      return { name: base.name, attempted: true, ok: false, detail: `\`${base.bin || base.name} --version\` could not run: ${res.error.message}` };
+    }
+    if (res.status !== 0) {
+      const why = ((res.stderr || res.stdout || "").trim().split("\n")[0] || `exit ${res.status}`).slice(0, 200);
+      return { name: base.name, attempted: true, ok: false, detail: `\`--version\` exited ${res.status}: ${why}` };
+    }
+    const version = (res.stdout || "").trim().split("\n")[0].slice(0, 80);
+    return { name: base.name, attempted: true, ok: true, detail: version ? `CLI responds: ${version}` : "CLI responds." };
+  } catch (err) {
+    return { name: base.name, attempted: true, ok: false, detail: `Probe failed: ${err.message}` };
+  }
+}
+
 /**
  * Probe every built-in provider, ready ones first, in preference order.
  *

package/src/wizard-init.mjs

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync, writeFileSync, openSync, fsyncSync, closeSync, renameSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { parseYaml, TIER_PRESETS, VENDOR_TIERS, FALLBACK_TIER } from "./config.mjs";
-import { suggestProvider } from "./provider-readiness.mjs";
-import { PROFILE_NAMES } from "./profiles.mjs";
+import { suggestProvider, detectAvailableProviders } from "./provider-readiness.mjs";
+import { detectDefaultBranch } from "./git.mjs";
+import { PROFILE_NAMES, PROFILE_DESCRIPTIONS } from "./profiles.mjs";
 import { detectStackOracles, runVerificationProbe } from "./wizard-oracle.mjs";
 import { select, multiSelect, input, confirm, spinner, isTTY } from "./tui.mjs";
 import { KIT_VERSION } from "./version.mjs";
@@ -174,6 +175,11 @@ export function planInit(root = process.cwd(), options = {}) {
   const requestedProfile = String(options.profile || existingConfig.verify?.profile || "standard").toLowerCase();
   const profile = PROFILE_NAMES.includes(requestedProfile) ? requestedProfile : "standard";
 
+  // Detected, not assumed. A hardcoded `main` made the very first
+  // `agentctl check` fail with an unresolvable base ref in every repository
+  // whose git chose `master`, or whose team standardised on `develop`.
+  const baseBranch = options.baseBranch || existingConfig.base_branch || detectDefaultBranch(root);
+
   const limitsBlock = isCustomLimits
     ? `\nlimits:\n  concurrency: ${limits.concurrency}\n  daily_tasks: ${limits.daily_tasks}\n  stagger_ms: ${limits.stagger_ms}\n  diff_kb: ${limits.diff_kb}\n`
     : "";
@@ -183,7 +189,7 @@ export function planInit(root = process.cwd(), options = {}) {
 version: 1
 provider: ${provider}
 tier: ${tierName}
-base_branch: ${options.baseBranch || existingConfig.base_branch || "main"}
+base_branch: ${baseBranch}
 branch_prefix: ${existingConfig.branch_prefix || "agent/"}
 ${limitsBlock}
 verify:
@@ -229,6 +235,7 @@ allow_paths: ${allowPaths.length > 0 ? "\n" + allowPaths.map((p) => `  - "${p}"`
     tier: tierName,
     provider,
     profile,
+    baseBranch,
     verify,
     limits,
     presets: selectedPresets,
@@ -292,6 +299,8 @@ export async function runInitWizard(root = process.cwd(), options = {}) {
   }
 
   let selectedTier = options.tier || existingConfig.tier || FALLBACK_TIER;
+  let selectedProvider = options.provider || existingConfig.provider;
+  let selectedProfile = options.profile || existingConfig.verify?.profile;
   let testCmd = options.testCmd;
   let buildCmd = options.buildCmd;
   let selectedPresets = options.presets;
@@ -302,14 +311,51 @@ export async function runInitWizard(root = process.cwd(), options = {}) {
     await new Promise((resolve) => setTimeout(resolve, 300));
     sp.stop(`Detected Stack: ${oracle.stack}`);
 
-    const optionsList = tierOptions();
-    const defaultTierIdx = Math.max(0, optionsList.findIndex((t) => t.value === selectedTier));
-
-    selectedTier = await select(
-      optionsList,
-      "Which plan does your Jules account use? (limits are adjustable later)",
-      { ...options, defaultIdx: defaultTierIdx }
+    // Which agent, before anything about one vendor's plans.
+    //
+    // The wizard's first question used to be "Which plan does your Jules
+    // account use?", asked of everyone — including people who came to drive
+    // Claude Code or Codex and were now left guessing whether a Jules
+    // subscription was a prerequisite. Ask what the repository is for first,
+    // and ask the plan question only of the provider it belongs to.
+    const probes = detectAvailableProviders({ env: options.env || process.env });
+    const providerOptions = probes.map((pr) => ({
+      label: `${pr.name}${pr.ready ? "" : "  (not available here)"}`,
+      value: pr.name,
+      hint: pr.ready ? pr.label : `${pr.label} — ${pr.remedy}`,
+    }));
+    const defaultProviderIdx = Math.max(
+      0,
+      providerOptions.findIndex((o) => o.value === (selectedProvider || probes.find((pr) => pr.ready)?.name))
     );
+    selectedProvider = await select(providerOptions, "Which agent should run the tasks?", {
+      ...options,
+      defaultIdx: defaultProviderIdx,
+    });
+
+    // Only the hosted provider meters work against an account plan; asking a
+    // local-CLI user about tiers is asking about something that does not exist
+    // for them.
+    if (selectedProvider === "jules") {
+      const optionsList = tierOptions();
+      const defaultTierIdx = Math.max(0, optionsList.findIndex((t) => t.value === selectedTier));
+      selectedTier = await select(
+        optionsList,
+        "Which plan does your Jules account use? (limits are adjustable later)",
+        { ...options, defaultIdx: defaultTierIdx }
+      );
+    }
+
+    const profileOptions = PROFILE_NAMES.map((n) => ({
+      label: n,
+      value: n,
+      hint: PROFILE_DESCRIPTIONS[n],
+    }));
+    const defaultProfileIdx = Math.max(0, profileOptions.findIndex((o) => o.value === (selectedProfile || "standard")));
+    selectedProfile = await select(profileOptions, "How hard should the gate verify agent work?", {
+      ...options,
+      defaultIdx: defaultProfileIdx,
+    });
 
     testCmd = await input("Verification Test Command", {
       defaultValue: testCmd || existingConfig.verify?.test || oracle.candidates.testCmd || "npm test",
@@ -357,6 +403,8 @@ export async function runInitWizard(root = process.cwd(), options = {}) {
   const plan = planInit(root, {
     ...options,
     tier: selectedTier,
+    provider: selectedProvider,
+    profile: selectedProfile,
     testCmd,
     buildCmd,
     presets: selectedPresets,

package/src/wizard-task.mjs

@@ -257,7 +257,8 @@ ${fullPrompt}
  * Run interactive or headless task creation wizard.
  * @param {string} [root=process.cwd()]
  * @param {object} [options]
- * @returns {Promise<{ ok: boolean, taskFile: string, plan: object }>}
+ * @param {boolean} [options.dryRun] - synthesize and validate the envelope without writing it
+ * @returns {Promise<{ ok: boolean, dryRun: boolean, taskFile: string, written: boolean, plan: object }>}
  */
 export async function runTaskCreateWizard(root = process.cwd(), options = {}) {
   const interactive = options.interactive !== false && isTTY(options.stdin || process.stdin);
@@ -338,20 +339,36 @@ export async function runTaskCreateWizard(root = process.cwd(), options = {}) {
 
   // Write Task File to canonical queue directory (getQueueDir)
   const queueDir = getQueueDir(root);
-  if (!existsSync(queueDir)) {
-    mkdirSync(queueDir, { recursive: true });
-  }
-
   const taskFile = resolve(queueDir, `${plan.taskId}.md`);
   if (!taskFile.startsWith(resolve(queueDir))) {
     throw new Error("Task ID path traversal blocked.");
   }
 
+  // `--dry-run` was accepted by the CLI parser and then dropped on the floor:
+  // the envelope was written to the queue either way, so a rehearsal queued
+  // real work. A rehearsal returns the same plan and touches nothing — not even
+  // the queue directory, which would otherwise be created as a side effect.
+  if (options.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      taskFile,
+      written: false,
+      plan,
+    };
+  }
+
+  if (!existsSync(queueDir)) {
+    mkdirSync(queueDir, { recursive: true });
+  }
+
   writeFileSync(taskFile, plan.taskFileContent, "utf-8");
 
   return {
     ok: true,
+    dryRun: false,
     taskFile,
+    written: true,
     plan,
   };
 }

package/src/profiles-io.mjs

@@ -1,77 +0,0 @@
-import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
-import { join } from "node:path";
-import { PROFILE_NAMES } from "./profiles.mjs";
-
-/**
- * Set `verify.profile` in the repository's manifest, in place.
- *
- * A surgical text edit rather than a 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.
- *
- * @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 candidates = [join(root, ".agent", "config.yml"), join(root, ".agent", "jules.yml")];
-  const file = candidates.find((f) => existsSync(f));
-  if (!file) {
-    return { ok: false, error: "No .agent/config.yml found. Run `agentctl init` first." };
-  }
-
-  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 = text.split(/\r?\n/);
-
-  // 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}`, "");
-  }
-
-  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 };
-}