jules-orchestrator-kit 0.52.8 → 0.54.0

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

@@ -293,6 +293,10 @@ export function detectPackageManager(root = process.cwd(), pkg = {}) {
   return "npm";
 }
 
+import { buildProfileStages, PROFILE_NAMES, PROFILE_DESCRIPTIONS } from "./profiles.mjs";
+
+export { buildProfileStages, PROFILE_NAMES, PROFILE_DESCRIPTIONS };
+
 import {
   detectPolyglotStack,
   resolveWorkspaceBoundary,
@@ -321,6 +325,10 @@ export function detectStack(projectRoot = process.cwd()) {
 export function resolveVerify(root = process.cwd(), userVerify = {}) {
   const s = detectStack(root);
   return {
+    // Carried through so `verify.profile` can gate stack-specific gates (V8
+    // diff coverage only exists where the test command runs on Node) without
+    // every caller re-running stack detection.
+    stack: s.stack || "unknown",
     setup: userVerify.setup ?? s.setupCmd ?? "",
     lint: userVerify.lint ?? s.fmtCmd ?? "",
     test: userVerify.test ?? s.testCmd ?? "",
@@ -501,22 +509,42 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     if (normalizedLimits[k] === undefined) delete normalizedLimits[k];
   }
 
+  // The verification commands, resolved once, so a profile can be expanded
+  // against the same values the gate will actually run.
+  const mergedVerify = {
+    setup: rawSetup ?? autoVerify.setup ?? "",
+    lint: rawLint ?? autoVerify.lint ?? "",
+    test: rawTest ?? autoVerify.test,
+    unit: rawUnit ?? rawTest ?? autoVerify.unit ?? autoVerify.test,
+    fuzz: rawFuzz ?? autoVerify.fuzz ?? "",
+    invariant: rawInvariant ?? autoVerify.invariant ?? "",
+    e2e: rawE2e ?? autoVerify.e2e ?? "",
+    teardown: rawTeardown ?? autoVerify.teardown ?? "",
+    build: rawBuild ?? autoVerify.build,
+    policy: parsed.verify?.policy ?? autoVerify.policy,
+  };
+
+  // A hand-written `verify.stages:` is the operator being explicit and always
+  // wins; `verify.profile:` is the shorthand, expanded here rather than frozen
+  // into the scaffolded YAML so it stays correct when the stack changes.
+  const rawProfile = parsed.verify?.profile ?? parsed.profile ?? null;
+  const explicitStages = parsed.verify?.stages ?? autoVerify.stages ?? null;
+  const profilePlan =
+    !explicitStages && rawProfile
+      ? buildProfileStages(rawProfile, { stack: autoVerify.stack, verify: mergedVerify })
+      : null;
+
   const config = {
     version: parsed.version || DEFAULTS.version,
     provider: parsed.provider || DEFAULTS.provider,
     tier: activeTier,
     verify: {
-      setup: rawSetup ?? autoVerify.setup ?? "",
-      lint: rawLint ?? autoVerify.lint ?? "",
-      test: rawTest ?? autoVerify.test,
-      unit: rawUnit ?? rawTest ?? autoVerify.unit ?? autoVerify.test,
-      fuzz: rawFuzz ?? autoVerify.fuzz ?? "",
-      invariant: rawInvariant ?? autoVerify.invariant ?? "",
-      e2e: rawE2e ?? autoVerify.e2e ?? "",
-      teardown: rawTeardown ?? autoVerify.teardown ?? "",
-      build: rawBuild ?? autoVerify.build,
-      stages: parsed.verify?.stages ?? autoVerify.stages ?? null,
-      policy: parsed.verify?.policy ?? autoVerify.policy,
+      ...mergedVerify,
+      stages: explicitStages ?? profilePlan?.stages ?? null,
+      profile: profilePlan?.profile ?? (rawProfile ? String(rawProfile).toLowerCase() : null),
+      // Named so `doctor` can tell an operator that the gate they enabled is
+      // running one fewer check than they think, and why.
+      profileSkipped: profilePlan?.skipped ?? [],
       timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 60000,
     },
     evidence: {

package/src/engine.mjs

@@ -19,6 +19,7 @@ import { hydratePrompt, harvestFailure } from "./memory.mjs";
 import { resolveRolePrompt } from "./role-resolver.mjs";
 
 import { runAssertion } from "./assertions.mjs";
+import { buildDefaultStages } from "./profiles.mjs";
 import {
   computeDirectoryHash,
   generateEvidenceManifest,
@@ -283,27 +284,7 @@ export async function gate(opts = {}) {
   if (Array.isArray(trustedVerify.stages) && trustedVerify.stages.length > 0) {
     stagesToRun.push(...trustedVerify.stages);
   } else {
-    if (trustedVerify.setup) {
-      stagesToRun.push({ id: "setup", kind: "setup", cmd: trustedVerify.setup, required: true, networkAccess: "allow" });
-    }
-    if (trustedVerify.lint) {
-      stagesToRun.push({ id: "lint", kind: "lint", cmd: trustedVerify.lint, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
-    if (trustedVerify.test || trustedVerify.unit) {
-      stagesToRun.push({ id: "unit", kind: "test", cmd: trustedVerify.test || trustedVerify.unit, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
-    if (trustedVerify.fuzz) {
-      stagesToRun.push({ id: "fuzz", kind: "fuzz", cmd: trustedVerify.fuzz, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
-    if (trustedVerify.invariant) {
-      stagesToRun.push({ id: "invariant", kind: "invariant", cmd: trustedVerify.invariant, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
-    if (trustedVerify.e2e) {
-      stagesToRun.push({ id: "e2e", kind: "e2e", cmd: trustedVerify.e2e, required: true, networkAccess: "allow" });
-    }
-    if (trustedVerify.build) {
-      stagesToRun.push({ id: "build", kind: "build", cmd: trustedVerify.build, required: true, networkAccess: trustedVerify.policy?.networkAccess || "allow" });
-    }
+    stagesToRun.push(...buildDefaultStages(trustedVerify));
   }
 
   try {

package/src/env-aliases.mjs

@@ -0,0 +1,80 @@
+/**
+ * Vendor-neutral spellings for every environment variable the kit reads.
+ *
+ * Every knob in this codebase is spelled `JULES_*`, which is accurate for the
+ * provider it was written against and wrong for every other one: a repository
+ * driving `claude-code` or `codex` still had to export `JULES_SWARM_CONCURRENCY`
+ * to set worker slots, and `JULES_API_KEY` to set a key that never goes to
+ * Jules. Renaming the variables outright would break every existing checkout
+ * and CI job, so both spellings are supported and this table is the only place
+ * that has to know they are the same knob.
+ *
+ * Direction is deliberate: `AGENT_*` is the name to document, `JULES_*` is the
+ * name the code reads, and the alias fills the second from the first. A
+ * `JULES_*` value already in the environment always wins, so adding an
+ * `AGENT_*` export can never change the behaviour of a working setup.
+ *
+ * @type {Record<string, string>}
+ */
+export const ENV_ALIASES = {
+  AGENT_API_KEY: "JULES_API_KEY",
+  AGENT_API_KEYS: "JULES_API_KEYS",
+  AGENT_API_KEY_SECONDARY: "JULES_API_KEY_SECONDARY",
+  AGENT_API_URL: "JULES_API_URL",
+  AGENT_REPO: "JULES_REPO",
+  AGENT_PROJECT_ID: "JULES_PROJECT_ID",
+  AGENT_PROJECT_ROOT: "JULES_PROJECT_ROOT",
+  AGENT_TIER: "JULES_TIER",
+  AGENT_DAILY_BUDGET: "JULES_DAILY_BUDGET",
+  AGENT_MAX_DIFF_KB: "JULES_MAX_DIFF_KB",
+  AGENT_DRY_RUN: "JULES_DRY_RUN",
+  AGENT_REPOLESS: "JULES_REPOLESS",
+  AGENT_SWARM_CONCURRENCY: "JULES_SWARM_CONCURRENCY",
+  AGENT_SWARM_STAGGER_MS: "JULES_SWARM_STAGGER_MS",
+  AGENT_PACE_MS: "JULES_PACE_MS",
+  AGENT_SLOT_INDEX: "JULES_SLOT_INDEX",
+  AGENT_SLOT_TOTAL: "JULES_SLOT_TOTAL",
+  AGENT_USE_WORKTREES: "JULES_USE_WORKTREES",
+  AGENT_ALLOW_COMMAND_FILE_CHANGES: "JULES_ALLOW_COMMAND_FILE_CHANGES",
+  AGENT_ALLOW_AGENT_RULE_CHANGES: "JULES_ALLOW_AGENT_RULE_CHANGES",
+};
+
+/**
+ * Fill the legacy `JULES_*` variables from their `AGENT_*` equivalents.
+ *
+ * Mutates the passed environment object in place — that is the point: every
+ * downstream module reads `process.env` directly, and rewriting hundreds of
+ * call sites to consult an alias table would be a far larger change with far
+ * more places to get it wrong. Called once at process entry.
+ *
+ * An empty-string alias is treated as unset, matching how the rest of the kit
+ * reads keys (`(process.env.X || "").trim()`), so `AGENT_API_KEY=` in a .env
+ * file does not shadow a real `JULES_API_KEY`.
+ *
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string[]} canonical names that were populated from an alias
+ */
+export function applyEnvAliases(env = process.env) {
+  const applied = [];
+  for (const [alias, canonical] of Object.entries(ENV_ALIASES)) {
+    const aliasValue = env[alias];
+    if (aliasValue === undefined || String(aliasValue).trim() === "") continue;
+    const existing = env[canonical];
+    if (existing !== undefined && String(existing).trim() !== "") continue;
+    env[canonical] = aliasValue;
+    applied.push(canonical);
+  }
+  return applied;
+}
+
+/**
+ * Both spellings of one knob, for help text and diagnostics that should name
+ * the vendor-neutral variable first.
+ *
+ * @param {string} canonical - a `JULES_*` name
+ * @returns {{ canonical: string, alias: string|null }}
+ */
+export function describeEnvVar(canonical) {
+  const alias = Object.entries(ENV_ALIASES).find(([, c]) => c === canonical)?.[0] || null;
+  return { canonical, alias };
+}

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

@@ -143,7 +143,7 @@ export const MCP_TOOLS = [
   },
   {
     name: "get_jules_status",
-    description: "Retrieve orchestrator status including daily task budget, active locks, and stack diagnostics.",
+    description: "Retrieve orchestrator status: daily task budget, active locks, stack diagnostics, the configured provider and whether it is reachable, and the verification stages the gate will run.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -439,6 +439,10 @@ export async function handleMcpRequest(request, opts = {}) {
         const stackInfo = detectStack(root);
         const budget = budgetStatus(config, root);
         const locks = lockStatus(root);
+        const { probeProvider } = await import("./provider-readiness.mjs");
+        const { buildDefaultStages } = await import("./profiles.mjs");
+        const providerProbe = probeProvider(config.provider || "jules");
+        const profileStages = config.verify.stages || buildDefaultStages(config.verify);
         const status = {
           version: MCP_SERVER_INFO.version,
           root,
@@ -455,6 +459,20 @@ export async function handleMcpRequest(request, opts = {}) {
           },
           activeLocksCount: locks.length,
           locks,
+          // An IDE agent orienting itself needs to know which agent this repo
+          // dispatches to and how hard its work will be verified before it
+          // starts, not after the gate rejects it.
+          provider: {
+            name: providerProbe.name,
+            kind: providerProbe.kind,
+            ready: providerProbe.ready,
+            reason: providerProbe.reason,
+          },
+          verification: {
+            profile: config.verify.profile,
+            stages: profileStages.map((st) => st.id),
+            skipped: (config.verify.profileSkipped || []).map((sk) => sk.id),
+          },
         };
         return {
           jsonrpc: "2.0",

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" },