jules-orchestrator-kit 0.72.3 → 0.73.1

package/bin/agentctl.mjs

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
 
 import { parseArgs } from "node:util";
-import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { readFileSync, existsSync, readdirSync, statSync, renameSync, mkdirSync } 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";
+import { parseEnvelopeHeader } from "../src/envelope.mjs";
 import { worktreePrune } from "../src/git.mjs";
 import { reapOrphanedIntents, reapStaleMutexDirs } from "../src/journal.mjs";
 import { KIT_VERSION } from "../src/version.mjs";
 import { budgetStatus, listOpenReservations, releaseOpenReservations, resolveConcurrency } from "../src/budget.mjs";
+import { COMMAND_REGISTRY } from "../src/ops/command-registry.mjs";
 
 // Vendor-neutral env spellings are filled in before any module reads
 // process.env, so `AGENT_API_KEY` works everywhere `JULES_API_KEY` does. A
@@ -42,78 +44,52 @@ export function formatBudgetLine(b) {
 }
 
 export function printHelp() {
-  console.log(`
-agentctl v${VERSION} — Universal Agent Orchestrator & Safety Gatekeeper
-
-Usage: agentctl <command> [options]
-
-Commands:
-  dispatch | create     Dispatch a single task to an AI agent (--role <name>, --tier fast|complex, --check-premise)
-  check                 Run all-in-one CI security, rules, and stack verification gate
-  gate | audit          Run CI security and verification gate against current branch
-  mutate | mutation     Run zero-dependency diff mutation testing harness (--min-score, --max-mutants)
-  coverage              Run native zero-dependency V8 diff coverage check (--min, --cmd)
-  probe | stability     Run test flakiness stability probe across N repetitions (--repeat, --cmd)
-  perf | event-loop     Monitor Node.js event loop delay and Big-O lag (--max-ms, --cmd)
-  fix                   Auto-repair from piped terminal logs or error trace (npm test 2>&1 | agentctl fix)
-  rules <action>        Audit rule token budgets or compile rule sentinels (check | compile)
-  queue                 Run pending task queue (--dag, --concurrency <n>)
-  swarm                 Run parallel task swarm
-  mcp                   Start stdio Model Context Protocol (MCP) server
-  clean                 Clean stale branches, worktrees, locks, and ledgers
-  lock <action>         Manage mutex locks (acquire [--ttl <min>] [--pid <n>] | release | status)
-  doctor                Run system diagnostics and stack resolution checks
-  providers             List agent providers and whether this machine can reach them (--json)
-  provider set <name>   Switch the active provider in .agent/config.yml
-  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
-  review-repair         Parse PR review comments and synthesize OODA repair tasks
-  dashboard             Start local HTTP telemetry and audit dashboard
-  init                  Scaffold .agent/ config and run onboarding wizard
-  task create           Interactively author and scope a Jules task envelope (--template <name>, --role <name>, --tier fast|complex)
-  task optimize         Linter & optimizer for Jules task prompts (--fix, --json, --web)
-  task template         List and generate task templates (--list, --json)
-  test-gen              Scaffold & run automated TDD Red-to-Green test cycle (--run)
-  mcp init              Scaffold IDE integration config (cursor | vscode | claude | all)
-  rollback              Restore git state & working tree to atomic pre-flight checkpoint
-  handover              Inspect or generate Baton Pass session handover envelopes (list | show | create | prune)
-  resume                Resume warm session with human response (--response "<text>")
-  plan approve <id>     Approve pending plan for a Jules session (:approvePlan)
-  session get <id>      Retrieve remote session status from provider API
-  patch <id>            Extract and test/apply git patch from a Jules session (--apply, --save)
-  retry <id>            Retry failed session with automated failure-trace injection (--role)
-  prune                 Batch-archive or delete stale sessions via Jules API (--age 7d, --yes)
-  pr harvest            Triage, verify CI, and auto-merge low-risk agent PRs (--auto, --tier r0,r1)
-  escalate              Dispatch or manage webhook escalation incidents (--flush, --status, --clear)
-  flaky                 Manage Wilson-quarantined tests and dispatch healing swarm (status | heal | reset)
-  status                Display queue and system status summary
-  budget                Show the 24h task budget, worker slots and their provenance (reset --yes)
-  scan                  Scan codebase for TODO/FIXME task candidates
-  hydrate [prompt]      Prepend active system learnings and baton-pass state to a prompt
-  harvest               Harvest failure traces and record/quarantine resolution rules
-  learning add          Record a system learning rule into .agent/knowledge/
-  evidence <action>     Manage cryptographic audit evidence (generate | verify | show)
-  assert                Run declarative zero-dependency verification assertion primitives
-  version               Output agentctl version
-
-Options:
-  --prompt, -p          Task prompt text — dispatch, task create and task optimize
-                        also accept it as a positional argument
-  --prompt-file, -f     Read the prompt from a file (-f is --fix on task optimize)
-  --role, -r            Specify specialist agent role (overseer | bolt | sentinel | janitor)
-  --tier                Force routing tier when router.enabled (fast | complex) — see .agent/config.yml router:
-  --check-premise       Verify task goal/oracle passes locally before burning API budget
-  --dag                 Execute queue tasks via DAG dependency resolution
-  --dry-run, -d         Simulate action without making API calls or modifying git
-  --mode, -m            Gate evaluation mode (working-tree | committed | staged)
-  --repoless            Dispatch task in repoless execution mode
-  --source, -s          Specify Jules repository source name
-  --branch, -b          Specify target starting branch
-  --json, -j            Emit machine-readable JSON output
-  --json-report <path>  Write structured machine-readable JSON diagnostics report
-  --help, -h            Show command help
-`);
+  // Single source of truth: the command list is generated from
+  // COMMAND_REGISTRY, so adding a descriptor automatically updates --help,
+  // `help <command>` (via formatCommandHelp) and docs/COMMAND_REFERENCE.md.
+  const CATEGORY_ORDER = ["Create", "Inspect", "Operate", "Repair", "Configure"];
+  const lines = [];
+  lines.push("");
+  lines.push(`agentctl v${VERSION} — Universal Agent Orchestrator & Safety Gatekeeper`);
+  lines.push("");
+  lines.push("Usage: agentctl <command> [options]");
+  lines.push("");
+  lines.push("Commands:");
+  for (const category of CATEGORY_ORDER) {
+    const cmds = COMMAND_REGISTRY.filter((c) => c.category === category);
+    if (cmds.length === 0) continue;
+    lines.push(`  --- ${category} ---`);
+    for (const cmd of cmds) {
+      const name = cmd.path.join(" ");
+      const flagHint =
+        cmd.flags.length > 0
+          ? ` (${cmd.flags.slice(0, 3).map((f) => `--${f.name}`).join(", ")}${cmd.flags.length > 3 ? ", ..." : ""})`
+          : "";
+      lines.push(`  ${name.padEnd(20)} ${cmd.description}${flagHint}`);
+    }
+  }
+  lines.push("  version               Output agentctl version");
+  lines.push("");
+  lines.push("Run `agentctl help <command>` or `agentctl <command> --help` for full flag documentation.");
+  lines.push("");
+  lines.push("Options:");
+  lines.push("  --prompt, -p          Task prompt text — dispatch, task create and task optimize");
+  lines.push("                        also accept it as a positional argument");
+  lines.push("  --prompt-file, -f     Read the prompt from a file (-f is --fix on task optimize)");
+  lines.push("  --role, -r            Specify specialist agent role (auditor | performance | security | hygiene | resilience | types | debugger | testing | e2e | database | docs | a11y)");
+  lines.push("  --tier                Force routing tier when router.enabled (fast | complex) — see .agent/config.yml router:");
+  lines.push("  --check-premise       Verify task goal/oracle passes locally before burning API budget");
+  lines.push("  --dag                 Execute queue tasks via DAG dependency resolution");
+  lines.push("  --dry-run, -d         Simulate action without making API calls or modifying git");
+  lines.push("  --mode, -m            Gate evaluation mode (working-tree | committed | staged)");
+  lines.push("  --repoless            Dispatch task in repoless execution mode");
+  lines.push("  --source, -s          Specify Jules repository source name");
+  lines.push("  --branch, -b          Specify target starting branch");
+  lines.push("  --json, -j            Emit machine-readable JSON output");
+  lines.push("  --json-report <path>  Write structured machine-readable JSON diagnostics report");
+  lines.push("  --help, -h            Show command help");
+  lines.push("");
+  console.log(lines.join("\n"));
 }
 
 /**
@@ -130,17 +106,65 @@ Options:
  * @param {string[]} [positionals] Remaining free arguments.
  * @returns {string} The prompt, or "" when none was supplied.
  */
-function resolvePromptInput(values, positionals = []) {
+/**
+ * Resolve the prompt text and source path a command was given.
+ *
+ * @param {Record<string, unknown>} values Parsed flags.
+ * @param {string[]} [positionals] Remaining free arguments.
+ * @param {string} [root] Repository root.
+ * @returns {{ content: string, sourceFile: string | null }}
+ */
+function resolvePromptDetails(values, positionals = [], root = process.cwd()) {
   const file = values["prompt-file"] || values.file;
   if (file) {
     if (!existsSync(file)) {
       console.error(`Error: prompt file not found: ${file}`);
       process.exit(1);
     }
-    return readFileSync(file, "utf-8");
+    return { content: readFileSync(file, "utf-8"), sourceFile: file };
   }
-  if (values.prompt) return String(values.prompt);
-  return positionals.join(" ").trim();
+  if (values.prompt) return { content: String(values.prompt), sourceFile: null };
+
+  if (positionals.length === 1) {
+    const raw = String(positionals[0]).trim();
+    const candidateFiles = [
+      raw,
+      resolve(root, raw),
+      join(root, ".agent", "jules-queue", raw),
+      join(root, ".agent", "jules-queue", `${raw}.md`),
+    ];
+    for (const cand of candidateFiles) {
+      if (cand && existsSync(cand)) {
+        try {
+          if (statSync(cand).isFile()) {
+            return { content: readFileSync(cand, "utf-8"), sourceFile: cand };
+          }
+        } catch (_) {}
+      }
+    }
+  }
+
+  if (positionals.length === 0) {
+    const queueDir = getQueueDir(root);
+    if (existsSync(queueDir)) {
+      const candidates = readdirSync(queueDir)
+        .filter((f) => f.endsWith(".md") && !f.startsWith(".") && f !== "README.md" && isTaskFile(f, queueDir))
+        .sort();
+      if (candidates.length > 0) {
+        const selected = join(queueDir, candidates[0]);
+        if (!values?.json) {
+          console.log(`Auto-selected pending queue task: .agent/jules-queue/${candidates[0]}`);
+        }
+        return { content: readFileSync(selected, "utf-8"), sourceFile: selected };
+      }
+    }
+  }
+
+  return { content: positionals.join(" ").trim(), sourceFile: null };
+}
+
+function resolvePromptInput(values, positionals = [], root = process.cwd()) {
+  return resolvePromptDetails(values, positionals, root).content;
 }
 
 /**
@@ -275,8 +299,7 @@ async function main() {
   const config = loadConfig(root);
 
   switch (command) {
-    case "dispatch":
-    case "create": {
+    case "dispatch": {
       const { values, positionals } = parseArgs({
         args: args.slice(1),
         options: {
@@ -290,6 +313,8 @@ async function main() {
           repoless: { type: "boolean" },
           "auto-pr": { type: "boolean" },
           "require-plan-approval": { type: "boolean" },
+          "auto-approve-plans": { type: "boolean" },
+          "auto-approve": { type: "boolean" },
           "check-premise": { type: "boolean" },
           idempotent: { type: "boolean" },
           author: { type: "string" },
@@ -301,12 +326,30 @@ async function main() {
         allowPositionals: true,
       });
 
-      const promptContent = resolvePromptInput(values, positionals);
+      const { content: promptContent, sourceFile } = resolvePromptDetails(values, positionals, root);
       if (!promptContent) {
-        console.error("Error: a prompt is required — pass it as --prompt, --prompt-file, or a positional argument.");
+        console.error("Error: a prompt is required — pass it as --prompt, --prompt-file, a task file path, or create one in .agent/jules-queue/.");
         process.exit(1);
       }
 
+      // If promptContent has an envelope header, inherit defaults
+      const envelopeMeta = parseEnvelopeHeader(promptContent);
+      if (envelopeMeta) {
+        values.title = values.title || envelopeMeta.title;
+        values.role = values.role || envelopeMeta.role;
+        values.tier = values.tier || envelopeMeta.tier;
+        values["verify-cmd"] = values["verify-cmd"] || values.verify || envelopeMeta.verifyCmd;
+        if (values["auto-pr"] === undefined && envelopeMeta.flags?.autoPr !== undefined) {
+          values["auto-pr"] = envelopeMeta.flags.autoPr;
+        }
+        if (values["require-plan-approval"] === undefined && envelopeMeta.flags?.requirePlanApproval !== undefined) {
+          values["require-plan-approval"] = envelopeMeta.flags.requirePlanApproval;
+        }
+        if (values.repoless === undefined && envelopeMeta.flags?.repoless !== undefined) {
+          values.repoless = envelopeMeta.flags.repoless;
+        }
+      }
+
       // `task create --role` has always rejected a role it cannot resolve;
       // `dispatch --role` used to drop it without a word and hand the work to a
       // generic agent, so the two commands disagreed about what the same flag
@@ -316,13 +359,14 @@ async function main() {
         const { resolveRolePrompt } = await import("../src/role-resolver.mjs");
         if (!resolveRolePrompt(root, values.role, { config })) {
           console.error(
-            `Error: Unknown agent role '${values.role}'. Expected matching prompt file in .agent/prompts/ (e.g. Overseer, Bolt, Sentinel, Janitor).`
+            `Error: Unknown agent role '${values.role}'. Expected matching prompt file in .agent/prompts/ (e.g. Auditor, Performance, Security, Hygiene, Testing).`
           );
           console.error(`   Run 'agentctl init' to scaffold the shipped role prompts.`);
           process.exit(1);
         }
       }
 
+      const autoApprove = Boolean(values["auto-approve-plans"] || values["auto-approve"]);
       const task = {
         title: values.title || "CLI Dispatch Task",
         prompt: promptContent,
@@ -332,7 +376,7 @@ async function main() {
         branch: values.branch,
         repoless: values.repoless,
         autoPr: values["auto-pr"],
-        requirePlanApproval: values["require-plan-approval"],
+        requirePlanApproval: autoApprove ? false : values["require-plan-approval"],
         checkPremise: values["check-premise"] || values.idempotent,
         author: values.author,
         verifyCmd: values["verify-cmd"] || values.verify,
@@ -377,6 +421,19 @@ async function main() {
             }
           }
         }
+        if (session && session.ok !== false && !values["dry-run"] && sourceFile) {
+          const queueDir = getQueueDir(root);
+          const resolvedSrc = resolve(root, sourceFile);
+          if (resolvedSrc.startsWith(queueDir) && existsSync(resolvedSrc)) {
+            const completedDir = join(queueDir, "completed");
+            if (!existsSync(completedDir)) mkdirSync(completedDir, { recursive: true });
+            const baseName = resolvedSrc.slice(queueDir.length).replace(/^[/\\]+/, "");
+            const dstPath = join(completedDir, baseName);
+            if (!existsSync(dstPath)) {
+              renameSync(resolvedSrc, dstPath);
+            }
+          }
+        }
         process.exit(0);
       } catch (err) {
         const exitCode = typeof err.code === "number" ? err.code : 1;
@@ -821,6 +878,10 @@ async function main() {
           min: { type: "string", short: "m" },
           "min-pass-rate": { type: "string" },
           cmd: { type: "string", short: "c" },
+          "test-cmd": { type: "string", short: "t" },
+          "verify-cmd": { type: "string" },
+          record: { type: "boolean" },
+          "no-record": { type: "boolean" },
           json: { type: "boolean", short: "j" },
         },
         allowPositionals: true,
@@ -829,8 +890,10 @@ async function main() {
       const root = resolveRoot();
       const repeat = values.repeat ? parseInt(values.repeat, 10) : (values.iterations ? parseInt(values.iterations, 10) : 5);
       const minPassRate = values.min ? parseFloat(values.min) : (values["min-pass-rate"] ? parseFloat(values["min-pass-rate"]) : 1.0);
+      const targetCmd = values["test-cmd"] || values["verify-cmd"] || values.cmd;
+      const record = values["no-record"] ? false : values.record !== false;
 
-      const report = runStabilityProbe(values.cmd, { root, repeat, minPassRate });
+      const report = runStabilityProbe(targetCmd, { root, repeat, minPassRate, record });
 
       if (values.json) {
         console.log(JSON.stringify(report, null, 2));
@@ -849,6 +912,11 @@ async function main() {
           }
         }
 
+        if (record && !report.ok) {
+          console.log(`\n  Recorded probe results to .agent/state/flaky.jsonl.`);
+          console.log(`  Check status or trigger auto-healing: agentctl flaky status | agentctl flaky heal`);
+        }
+
         console.log(`------------------------------------------------------------------`);
         console.log(`Overall Result: ${report.ok ? "APPROVED (Deterministic 100% Pass — Exit 0)" : "REJECTED (Flaky / Intermittent Failures — Exit 1)"}\n`);
       }
@@ -920,10 +988,11 @@ async function main() {
         errorInput = readFileSync(values.file, "utf-8");
       } else if (values.input) {
         errorInput = values.input;
-      } else if (positionals.slice(1).length > 0) {
-        errorInput = positionals.slice(1).join(" ");
+      } else if (positionals.length > 0) {
+        errorInput = positionals.join(" ");
       } else if (!process.stdin.isTTY) {
-        errorInput = readFileSync(0, "utf-8");
+        const { text } = await import("node:stream/consumers");
+        errorInput = await text(process.stdin);
       }
 
       if (!errorInput.trim()) {
@@ -939,6 +1008,7 @@ async function main() {
           prompt: `Fix the following test/build failure:\n\n${cleanTrace.slice(0, 4000)}`,
           title: "Automated Failure Repair",
           verifyCmd: values.cmd || "npm test",
+          allowHighEntropy: true,
         });
 
         if (values.json) {
@@ -982,7 +1052,7 @@ async function main() {
         allowPositionals: true,
       });
 
-      const sessionId = values.session || positionals[0] || positionals[1];
+      const sessionId = values.session || positionals[0];
       if (!sessionId) {
         console.error("❌ Error: Missing required session ID. Usage: agentctl patch <session_id> [--apply] [--save <path>]");
         process.exit(1);
@@ -1033,7 +1103,7 @@ async function main() {
         allowPositionals: true,
       });
 
-      const sessionId = values.session || positionals[0] || positionals[1];
+      const sessionId = values.session || positionals[0];
       if (!sessionId) {
         console.error("❌ Error: Missing required session ID. Usage: agentctl retry <session_id> [--role <role>]");
         process.exit(1);
@@ -1315,7 +1385,21 @@ async function main() {
     }
 
     case "budget": {
-      const action = args[1];
+      const { values: budgetValues, positionals: budgetPositionals } = parseArgs({
+        args: args.slice(1),
+        options: {
+          "dry-run": { type: "boolean" },
+          yes: { type: "boolean", short: "y" },
+          all: { type: "boolean" },
+          "by-user": { type: "boolean", short: "u" },
+          json: { type: "boolean" },
+        },
+        allowPositionals: true,
+        // strict:false so `reset` can refuse unknown flags with its own
+        // ledger-aware message instead of a generic parseArgs throw.
+        strict: false,
+      });
+      const action = budgetPositionals[0];
       const b = budgetStatus(config, root);
 
       if (action === "reset") {
@@ -1333,11 +1417,11 @@ async function main() {
           console.error("Accepted: --dry-run, --yes/-y, --all. Nothing was released.");
           process.exit(2);
         }
-        const dryRun = args.includes("--dry-run");
-        const confirmed = args.includes("--yes") || args.includes("-y");
+        const dryRun = Boolean(budgetValues["dry-run"]);
+        const confirmed = Boolean(budgetValues.yes);
         // Committed reservations reached the provider, so releasing them makes
         // the local count understate real usage. That has to be deliberate.
-        const includeCommitted = args.includes("--all");
+        const includeCommitted = Boolean(budgetValues.all);
         if (!dryRun && !confirmed) {
           const open = listOpenReservations(root);
           const committed = open.filter((r) => r.committed).length;
@@ -1364,7 +1448,7 @@ async function main() {
         process.exit(0);
       }
 
-      if (args.includes("--by-user") || args.includes("-u")) {
+      if (budgetValues["by-user"]) {
         console.log("📊 Task Budget Attribution (Rolling 24h Window)");
         console.log(`Daily Limit : ${b.limit} Tasks | Used: ${b.used} | Remaining: ${b.remaining}\n`);
         const users = Object.entries(b.byUser || {});
@@ -1385,7 +1469,7 @@ async function main() {
         process.exit(0);
       }
 
-      if (args.includes("--json")) {
+      if (budgetValues.json) {
         console.log(JSON.stringify({ ok: true, budget: { ...b, scope: "this-repository" } }, null, 2));
         process.exit(0);
       }
@@ -1411,7 +1495,16 @@ async function main() {
     }
 
     case "lock": {
-      const action = args[1];
+      const { values: lockValues, positionals: lockPositionals } = parseArgs({
+        args: args.slice(1),
+        options: {
+          ttl: { type: "string" },
+          pid: { type: "string" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+      const action = lockPositionals[0];
       if (action === "acquire") {
         // A lock taken from the command line outlives the command. The process
         // that runs `lock acquire` writes the record and exits; the agent it
@@ -1422,27 +1515,26 @@ async function main() {
         // `--pid` is the escape hatch for a caller that *does* have a durable
         // process to point at: the lock then releases itself when that process
         // dies, exactly as an in-process acquire does.
-        const flagIdx = args.findIndex((a, i) => i >= 2 && a.startsWith("--"));
-        const positional = flagIdx === -1 ? args.slice(2) : args.slice(2, flagIdx);
-        const { values } = parseArgs({
-          args: flagIdx === -1 ? [] : args.slice(flagIdx),
-          options: {
-            ttl: { type: "string" },
-            pid: { type: "string" },
-          },
-          allowPositionals: false,
-        });
-        const agent = positional[0] || "agent";
-        const taskId = positional[1] || "task-1";
+        const positional = lockPositionals.slice(1);
+        if (positional.length < 3) {
+          console.error("Usage: agentctl lock acquire <agent> <task_id> <file_path...> [--ttl <minutes>] [--pid <pid>]");
+          process.exit(1);
+        }
+        const agent = positional[0];
+        const taskId = positional[1];
         const filePaths = positional.slice(2);
-        const ttlMinutes = Number(values.ttl);
-        const ownerPid = Number(values.pid);
+        const ttlMinutes = Number(lockValues.ttl);
+        const ownerPid = Number(lockValues.pid);
         const bindsToProcess = Number.isInteger(ownerPid) && ownerPid > 0;
         const res = acquireLock(agent, taskId, filePaths, root, {
           lease: !bindsToProcess,
           ownerPid: bindsToProcess ? ownerPid : undefined,
           ttlMs: Number.isFinite(ttlMinutes) && ttlMinutes > 0 ? ttlMinutes * 60_000 : undefined,
         });
+        if (lockValues.json) {
+          console.log(JSON.stringify(res, null, 2));
+          process.exit(res.ok ? 0 : 1);
+        }
         if (res.ok) {
           const held = filePaths.length ? ` (${filePaths.length} path${filePaths.length === 1 ? "" : "s"})` : "";
           const until = bindsToProcess ? `bound to pid ${ownerPid}` : `expires ${new Date(Date.now() + (Number.isFinite(ttlMinutes) && ttlMinutes > 0 ? ttlMinutes : 120) * 60_000).toISOString()}`;
@@ -1456,8 +1548,16 @@ async function main() {
           process.exit(1);
         }
       } else if (action === "release") {
-        const taskId = args[2] || "task-1";
+        const taskId = lockPositionals[1];
+        if (!taskId) {
+          console.error("Usage: agentctl lock release <task_id>");
+          process.exit(1);
+        }
         const ok = releaseLock(taskId, root);
+        if (lockValues.json) {
+          console.log(JSON.stringify({ ok, taskId }, null, 2));
+          process.exit(ok ? 0 : 1);
+        }
         if (ok) {
           console.log(`✅ Released lock for ${taskId}`);
         } else {
@@ -1466,7 +1566,21 @@ async function main() {
         }
       } else {
         const locks = lockStatus(root);
-        console.log(`Active Locks (${locks.length}):`, locks);
+        if (lockValues.json) {
+          console.log(JSON.stringify({ ok: true, locks }, null, 2));
+          process.exit(0);
+        }
+        if (locks.length === 0) {
+          console.log("Active Locks: 0 (no held locks)");
+        } else {
+          console.log(`Active Locks (${locks.length}):`);
+          for (const l of locks) {
+            const files = Array.isArray(l.files) ? l.files.join(", ") : (l.files || "");
+            const expires = l.expiresAt ? `expires ${l.expiresAt}` : (l.ownerPid ? `pid ${l.ownerPid}` : "active");
+            console.log(`  • taskId: ${l.taskId || l.id} [${l.agent || "unknown"}] (${expires})`);
+            if (files) console.log(`    Paths: ${files}`);
+          }
+        }
       }
       process.exit(0);
       break;
@@ -1531,11 +1645,16 @@ async function main() {
 
     case "provider":
     case "providers": {
+      const { values, positionals } = parseArgs({
+        args: args.slice(1),
+        options: { json: { type: "boolean", short: "j" } },
+        allowPositionals: true,
+      });
       // `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 (positionals[0] === "set") {
+        const target = positionals[1];
         if (!target) {
           console.error(`❌ Usage: agentctl provider set <name>   (see: agentctl providers)`);
           process.exit(2);
@@ -1555,11 +1674,6 @@ async function main() {
         process.exit(0);
       }
 
-      const { values } = parseArgs({
-        args: args.slice(1),
-        options: { json: { type: "boolean", short: "j" } },
-        allowPositionals: true,
-      });
       const { detectAvailableProviders, probeProvider } = await import("../src/provider-readiness.mjs");
       const probes = detectAvailableProviders();
       const active = config.provider || "jules";
@@ -1707,11 +1821,16 @@ async function main() {
         options: {
           force: { type: "boolean", short: "f" },
           "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
         },
         allowPositionals: true,
       });
 
       const res = bootstrapZeroTestRepo(root, { force: values.force });
+      if (values.json) {
+        console.log(JSON.stringify({ ok: res.bootstrapped, ...res }, null, 2));
+        process.exit(res.bootstrapped ? 0 : 1);
+      }
       if (res.bootstrapped) {
         console.log(`✅ Zero-test repo bootstrapped successfully!`);
         console.log(`   Stack detected : ${res.stack}`);
@@ -1732,7 +1851,12 @@ async function main() {
     }
 
     case "review-repair": {
-      const fileArg = args[1];
+      const { positionals: reviewPositionals } = parseArgs({
+        args: args.slice(1),
+        options: {},
+        allowPositionals: true,
+      });
+      const fileArg = reviewPositionals[0];
       if (!fileArg || !existsSync(fileArg)) {
         console.error("Error: Please provide a valid JSON file containing PR review comments.");
         process.exit(1);
@@ -1750,9 +1874,33 @@ async function main() {
     }
 
     case "dashboard": {
-      const port = Number(args[1] || 4100);
+      // Accepts both `agentctl dashboard 3000` and `agentctl dashboard --port
+      // 3000`. The old code read args[1] raw, so the documented flag form fed
+      // the literal string "--port" into Number() and died with an uncaught
+      // ERR_SOCKET_BAD_PORT instead of a usable error.
+      let dashboardOpts;
+      try {
+        const parsed = parseArgs({
+          args: args.slice(1),
+          options: {
+            port: { type: "string" },
+            host: { type: "string" },
+          },
+          allowPositionals: true,
+        });
+        dashboardOpts = { port: parsed.values.port, host: parsed.values.host, positional: parsed.positionals[0] };
+      } catch (err) {
+        console.error(`Error: Invalid port argument: ${err.message}`);
+        process.exit(1);
+      }
+      const rawPort = dashboardOpts.port ?? dashboardOpts.positional ?? "4100";
+      const port = Number(rawPort);
+      if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+        console.error(`Error: Invalid port "${rawPort}". Expected an integer between 1024 and 65535.`);
+        process.exit(1);
+      }
       const { startDashboardServer } = await import("../src/dashboard.mjs");
-      startDashboardServer(port, root);
+      startDashboardServer(port, root, dashboardOpts.host || "127.0.0.1");
       break;
     }
 
@@ -1774,7 +1922,27 @@ async function main() {
         allowPositionals: true,
       });
 
-      const isInteractive = values.interactive !== false && !values["non-interactive"] && !values["no-interactive"] && !values.yes;
+      if (values.tier) {
+        const validTiers = ["free", "pro", "ultra", "enterprise"];
+        const lowerTier = values.tier.toLowerCase();
+        if (!validTiers.includes(lowerTier)) {
+          if (["minimal", "standard", "max"].includes(lowerTier)) {
+            console.error(`❌ Invalid tier "${values.tier}". Valid tiers: ${validTiers.join(", ")}. Did you mean '--profile ${values.tier}'?`);
+          } else {
+            console.error(`❌ Invalid tier "${values.tier}". Valid tiers: ${validTiers.join(", ")}.`);
+          }
+          process.exit(1);
+        }
+      }
+
+      const isInteractive =
+        values.interactive === true ||
+        (values.interactive !== false &&
+          Boolean(process.stdin.isTTY) &&
+          !process.env.CI &&
+          !values["non-interactive"] &&
+          !values["no-interactive"] &&
+          !values.yes);
 
       const { runInitWizard } = await import("../src/wizard-init.mjs");
       const res = await runInitWizard(root, {
@@ -1833,7 +2001,15 @@ async function main() {
         // tree for files init had just written, which reads as the tool
         // catching the user cheating on step three.
         const rootContracts = ["SPEC.md", "CONSTRAINTS.md", "DESIGN.md"].filter((f) => existsSync(join(root, f)));
-        const filesToAdd = [".agent", "AGENTS.md", ...rootContracts, ".gitignore"].filter((f) => existsSync(join(root, f)));
+        // A fresh `npm install`/`npm init -y` just created package manifests the
+        // scope rules `protect`. Leaving them out of the hint meant the very
+        // first `agentctl gate`/`agentctl task create` still rejected the tree
+        // even after the user committed exactly what this message listed. Fold
+        // the install-produced, currently-addable artifacts in so the suggested
+        // commit actually leaves the tree clean enough for step three.
+        const { addableOnboardingArtifacts } = await import("../src/git.mjs");
+        const filesToAdd = [".agent", "AGENTS.md", ...rootContracts, ...addableOnboardingArtifacts(root), ".gitignore"]
+          .filter((f) => existsSync(join(root, f)));
         console.log(`\n   Commit the manifest and contracts so the gate does not read them as agent edits:`);
         console.log(`     git add ${filesToAdd.join(" ")} && git commit -m "chore: add agent config"`);
 
@@ -1879,6 +2055,8 @@ async function main() {
           interactive: values.interactive,
           nonInteractive: values["non-interactive"] || values["no-interactive"],
           yes: values.yes,
+          ci: Boolean(process.env.CI),
+          isTTY: Boolean(process.stdin.isTTY),
           // 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)),
@@ -2032,14 +2210,32 @@ async function main() {
     }
 
     case "status": {
+      const { values: statusValues } = parseArgs({
+        args: args.slice(1),
+        options: {
+          json: { type: "boolean" },
+        },
+        allowPositionals: true,
+      });
       const queueDir = getQueueDir(root);
       const files = existsSync(queueDir) ? readdirSync(queueDir).filter((f) => isTaskFile(f, queueDir)) : [];
+      const budget = budgetStatus(config, root);
+      if (statusValues.json) {
+        console.log(JSON.stringify({
+          ok: true,
+          version: VERSION,
+          root,
+          pendingTasks: files.length,
+          activeLocks: lockStatus(root).length,
+          budget,
+        }, null, 2));
+        process.exit(0);
+      }
       console.log(`\n📊 agentctl Status Summary (v${VERSION})`);
       console.log(`--------------------------------------------------`);
       console.log(`  Project Root     : ${root}`);
       console.log(`  Pending Tasks    : ${files.length}`);
       console.log(`  Active VFS Locks : ${lockStatus(root).length}`);
-      const budget = budgetStatus(config, root);
       console.log(`  Daily Budget     : ${formatBudgetLine(budget)}`);
       console.log(`--------------------------------------------------\n`);
       process.exit(0);
@@ -2047,7 +2243,7 @@ async function main() {
     }
 
     case "scan": {
-      const { scanCodebaseForTodos } = await import("../scripts/jules-scan-todos.mjs");
+      const { scanCodebaseForTodos } = await import("../src/todo-scanner.mjs");
       const todos = scanCodebaseForTodos(root);
       console.log(`\n🔍 Scanned ${todos.length} TODO/FIXME annotation(s).`);
       for (const t of todos.slice(0, 10)) {
@@ -2235,8 +2431,7 @@ async function main() {
 
     case "resume": {
       const { createProvider } = await import("../src/provider.mjs");
-      const sessionId = args[1];
-      const { values } = parseArgs({
+      const { values, positionals } = parseArgs({
         args: args.slice(1),
         options: {
           response: { type: "string", short: "r" },
@@ -2245,13 +2440,14 @@ async function main() {
         },
         allowPositionals: true,
       });
+      const sessionId = positionals[0];
 
       if (!sessionId || sessionId.startsWith("-")) {
         console.error("Error: Session ID is required for agentctl resume <sessionId>.");
         process.exit(1);
       }
 
-      const responseText = values.response || args.slice(2).join(" ");
+      const responseText = values.response || positionals.slice(1).join(" ");
       if (!responseText) {
         console.error("Error: --response text is required to resume warm session.");
         process.exit(1);
@@ -2278,7 +2474,6 @@ async function main() {
     case "plan": {
       const subAction = args[1];
       if (subAction === "approve") {
-        const sessionId = args[2];
         const { values, positionals } = parseArgs({
           args: args.slice(2),
           options: {
@@ -2287,7 +2482,7 @@ async function main() {
           },
           allowPositionals: true,
         });
-        const targetSessionId = sessionId && !sessionId.startsWith("-") ? sessionId : positionals?.[0];
+        const targetSessionId = positionals?.[0];
         if (!targetSessionId) {
           console.error("Error: Session ID is required for agentctl plan approve <sessionId>.");
           process.exit(1);
@@ -2315,7 +2510,6 @@ async function main() {
     }
 
     case "approve": {
-      const sessionId = args[1];
       const { values, positionals } = parseArgs({
         args: args.slice(1),
         options: {
@@ -2324,7 +2518,7 @@ async function main() {
         },
         allowPositionals: true,
       });
-      const targetSessionId = sessionId && !sessionId.startsWith("-") ? sessionId : positionals?.[0];
+      const targetSessionId = positionals?.[0];
       if (!targetSessionId) {
         console.error("Error: Session ID is required for agentctl approve <sessionId>.");
         process.exit(1);
@@ -2351,7 +2545,6 @@ async function main() {
     case "session": {
       const subAction = args[1];
       if (subAction === "get" || subAction === "status") {
-        const sessionId = args[2];
         const { values, positionals } = parseArgs({
           args: args.slice(2),
           options: {
@@ -2360,7 +2553,7 @@ async function main() {
           },
           allowPositionals: true,
         });
-        const targetSessionId = sessionId && !sessionId.startsWith("-") ? sessionId : positionals?.[0];
+        const targetSessionId = positionals?.[0];
         if (!targetSessionId) {
           console.error("Error: Session ID is required for agentctl session get <sessionId>.");
           process.exit(1);
@@ -2382,7 +2575,103 @@ async function main() {
           process.exit(1);
         }
       }
-      console.error(`Error: Unknown session subcommand '${subAction}'. Use get.`);
+
+      if (subAction === "list" || subAction === "ls") {
+        const { values } = parseArgs({
+          args: args.slice(2),
+          options: {
+            limit: { type: "string", short: "l" },
+            "page-size": { type: "string" },
+            remote: { type: "boolean" },
+            "dry-run": { type: "boolean", short: "d" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+
+        const limit = Number(values.limit || values["page-size"]) || 20;
+        const { createProvider } = await import("../src/provider.mjs");
+        const provider = createProvider(config.provider || "jules", config);
+
+        try {
+          const res = await provider.listSessions({
+            root,
+            pageSize: limit,
+            dryRun: values["dry-run"],
+          });
+          const remoteSessions = Array.isArray(res?.sessions) ? res.sessions : [];
+
+          const localSessions = [];
+          try {
+            const { getStateDir } = await import("../src/state.mjs");
+            const { readdirSync, readFileSync, existsSync } = await import("node:fs");
+            const stateDir = getStateDir(root);
+            if (existsSync(stateDir)) {
+              const files = readdirSync(stateDir).filter((f) => f.startsWith("ledger-") && f.endsWith(".jsonl"));
+              for (const file of files) {
+                const lines = readFileSync(join(stateDir, file), "utf-8").split("\n").filter(Boolean);
+                for (const line of lines) {
+                  try {
+                    const parsed = JSON.parse(line);
+                    if (parsed.sessionId) {
+                      localSessions.push({
+                        id: parsed.sessionId,
+                        status: parsed.status || "DISPATCHED",
+                        timestamp: parsed.timestamp,
+                        title: parsed.task || parsed.title || "",
+                        source: "local-ledger",
+                      });
+                    }
+                  } catch (_) {}
+                }
+              }
+            }
+          } catch (_) {}
+
+          const sessionMap = new Map();
+          for (const s of localSessions) {
+            sessionMap.set(s.id, s);
+          }
+          for (const s of remoteSessions) {
+            const sid = s.id || s.name;
+            if (sid) {
+              sessionMap.set(sid, {
+                id: sid,
+                status: s.state || s.status || "UNKNOWN",
+                createTime: s.createTime || s.created_at,
+                title: s.title || s.prompt?.slice(0, 60) || "",
+                source: "remote",
+              });
+            }
+          }
+
+          const combined = Array.from(sessionMap.values()).slice(0, limit);
+
+          if (values.json) {
+            console.log(JSON.stringify({ ok: true, sessions: combined, count: combined.length, nextPageToken: res?.nextPageToken }, null, 2));
+          } else {
+            console.log(`\n📋 Jules Sessions List (${combined.length} found):`);
+            console.log("--------------------------------------------------");
+            if (combined.length === 0) {
+              console.log("   No active or recent sessions found.");
+            } else {
+              for (const s of combined) {
+                const sid = (s.id || "unknown").slice(0, 24).padEnd(26);
+                const st = (s.status || "UNKNOWN").padEnd(14);
+                const desc = s.title || s.source || "";
+                console.log(`  • ${sid} [${st}] ${desc}`);
+              }
+            }
+            console.log("--------------------------------------------------\n");
+          }
+          process.exit(0);
+        } catch (err) {
+          console.error(`❌ Session List Failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+
+      console.error(`Error: Unknown session subcommand '${subAction}'. Use get or list.`);
       process.exit(1);
       break;
     }
@@ -2572,7 +2861,7 @@ async function main() {
         args: args.slice(2),
         options: {
           dispatch: { type: "boolean" },
-          role: { type: "string", short: "r", default: "janitor" },
+          role: { type: "string", short: "r", default: "hygiene" },
           "test-cmd": { type: "string", short: "t" },
           "dry-run": { type: "boolean", short: "d" },
           json: { type: "boolean", short: "j" },
@@ -2677,7 +2966,7 @@ async function main() {
 
     case "test-gen": {
       const { scaffoldTddTest, runTddCycle } = await import("../src/ops/tdd-generator.mjs");
-      const { values } = parseArgs({
+      const { values, positionals } = parseArgs({
         args: args.slice(1),
         options: {
           title: { type: "string", short: "t" },
@@ -2689,8 +2978,8 @@ async function main() {
         allowPositionals: true,
       });
 
-      const title = values.title || args[1] || "feature-spec";
-      const specText = values.spec || args.slice(2).join(" ") || "TDD requirement specification.";
+      const title = values.title || positionals[0] || "feature-spec";
+      const specText = values.spec || positionals.slice(1).join(" ") || "TDD requirement specification.";
 
       try {
         if (values.run) {
@@ -2819,11 +3108,16 @@ async function main() {
     }
 
     case "learning": {
-      const subcmd = args[1];
+      const { positionals: learningPositionals } = parseArgs({
+        args: args.slice(1),
+        options: {},
+        allowPositionals: true,
+      });
+      const subcmd = learningPositionals[0];
       if (subcmd === "add") {
         const { recordLearning } = await import("../src/memory.mjs");
-        const trigger = args[2];
-        const solution = args[3];
+        const trigger = learningPositionals[1];
+        const solution = learningPositionals[2];
         if (!trigger || !solution) {
           console.error('Usage: agentctl learning add "<trigger/symptom>" "<solution>"');
           process.exit(1);