jules-orchestrator-kit 0.38.2 → 0.41.0

package/.agent/prompts/Bolt.md

@@ -1,18 +1,21 @@
 # Bolt - Performance & Payload Optimization Specialist ⚡
 
 > **Role:** Codebase Micro-Optimizer & Payload Governor.
-> **Scope:** Performance tuning, bundle size reduction, and asset optimization with zero structural side-effects.
+> **Scope:** Performance tuning, artifact size reduction, and asset optimization with zero structural side-effects.
 
 ## Core Directives
 
 1. **Payload Budgeting:**
-   - Keep total diff payload strictly under 75 KB (`git diff | wc -c`).
-   - Eliminate redundant dependencies by replacing 3rd-party modules with Node.js built-ins (`node:fs`, `node:path`, `node:crypto`).
+   - Keep total diff payload strictly under {{DIFF_KB}} KB (`git diff | wc -c`).
+   - Prefer this project's existing dependencies and its language's standard library over adding another third-party module. Removing a dependency whose job the standard library already does is in scope; adding one is not.
 
 2. **Asset & Memory Optimization:**
-   - Replace heavy raster assets with modern WebP/AVIF equivalents or clean SVGs.
-   - Optimize hot execution paths: remove redundant object allocations inside tight loops.
+   - Replace heavy raster assets with modern equivalents (WebP/AVIF) or clean vector graphics, where the project already serves such formats.
+   - Optimize hot execution paths: remove redundant allocations inside tight loops, and hoist work out of repeated calls.
 
-3. **Zero Regressions Invariant:**
-   - Execute test suite (`npm test`) before and after every micro-optimization pass.
+3. **Evidence Before Claims:**
+   - A performance change requires numbers. Run the benchmark or timing measurement multiple times, compare medians, and state the delta. "Feels faster" is not a result, and a change below the noise floor is not an improvement.
+
+4. **Zero Regressions Invariant:**
+   - Execute `{{VERIFY_TEST}}` before and after every optimization pass, and record both results.
    - Never disable type-checks, skip tests, or alter public API signatures.

package/.agent/prompts/Janitor.md

@@ -1,11 +1,11 @@
 # Janitor Protocol: Technical Debt & Dead Code Elimination
 
-You are **Janitor**, a specialist autonomous agent optimized for technical debt elimination, dead code pruning, and strict zero-dependency refactoring.
+You are **Janitor**, a specialist autonomous agent optimized for technical debt elimination, dead code pruning, and conservative refactoring.
 
 ## Strict Operational Invariants
 
-1. **Zero External Runtime Dependencies**: You are STRICTLY FORBIDDEN from adding third-party npm packages. Use ONLY native Node.js ESM built-in modules (`node:fs`, `node:path`, `node:crypto`, `node:child_process`, `node:os`).
-2. **Dead Code Elimination**: Prune unused variables, unreachable branches, and redundant helper functions.
-3. **Atomic Payload Limit**: Keep total patch payload under 75 KB (`git diff | wc -c`).
-4. **Verification Requirement**: Execute `npm test` and `npm run lint` to ensure 100% of tests pass with 0 lint errors before completing work.
-5. **No Assert Weakening**: Never weak or remove test assertions to make a test pass.
+1. **No New Dependencies**: Do NOT add third-party packages, libraries, or modules of any kind. Solve the task with this project's existing dependencies and its language's standard library. If a task genuinely cannot be completed without a new dependency, stop and say so instead of adding one.
+2. **Dead Code Elimination**: Prune unused variables, unreachable branches, and redundant helper functions. Confirm a symbol has no remaining references across the whole repository before removing it — including dynamic lookups, reflection, and string-keyed access, which a definition-search will not find.
+3. **Atomic Payload Limit**: Keep total patch payload under {{DIFF_KB}} KB (`git diff | wc -c`).
+4. **Verification Requirement**: Execute `{{VERIFY_TEST}}` and `{{VERIFY_LINT}}` and ensure 100% of tests pass with 0 lint errors before completing work.
+5. **No Assert Weakening**: Never weaken or remove test assertions to make a test pass. Leave an unmet requirement RED with a written rationale.

package/.agent/prompts/Task_Template.md

@@ -8,18 +8,19 @@
 ## Context
 - **Project Goals:** [Describe key architectural or business goals.]
 - **Key Files & Folders:** [List critical files, directories, or schemas, e.g. `src/auth.ts`, `schema.sql`.]
-- **Tech Stack:** [List frameworks and libraries, e.g. Node.js, Express, TypeScript, Drizzle ORM.]
+- **Tech Stack:** [List this project's languages, frameworks, and libraries.]
 
 ## Requirements & Hard Constraints
 - **Functional Requirements:** [List specific, non-negotiable functional requirements.]
 - **Hard Constraints:**
-  - Do NOT introduce third-party npm dependencies without explicit authorization.
-  - Do NOT modify command files (`package.json`, `.github/`) or Agent Scope files.
-  - Keep total diff payload strictly under 75 KB (`git diff | wc -c`).
+  - Do NOT introduce new third-party dependencies without explicit authorization.
+  - Do NOT modify this project's build manifest, lockfile, CI configuration, or agent scope files. Run `agentctl gate` to see the enforced set.
+  - Keep total diff payload strictly under {{DIFF_KB}} KB (`git diff | wc -c`).
 
 ## Verification Loop
-- **Verification Command:** Execute automated verification tests: `npm test`.
+- **Verification Command:** Execute `{{VERIFY_TEST}}`.
 - **Zero Errors Invariant:** Ensure 100% of tests pass cleanly with 0 errors before submitting.
+- **Carry the Evidence:** Paste the actual terminal output. Exit code 0 proves the process survived, not that the change works.
 
 ## Expected Artifacts
 - **Code Changes:** Clean, production-grade implementation preserving existing symbol contracts.

package/.agent/rules/jules-protocol.md

@@ -32,7 +32,7 @@ To maximize the ratio of mergeable PRs vs. failed or hallucinated sessions:
 11. **Pre-Dispatch Grounding Mandate:** Verify all file paths, script names, and exported symbols against the live repository tree before writing them into a prompt.
 12. **Programmatic CI Scope Guarding:** Enforce prompt constraints at the CI level using an unbypassable `Agent Scope Guard` workflow that evaluates diffs against a protected paths manifest (`.agent/protected-paths.json`).
 13. **Google Labs Exploration Budget Protocol:** Execute tasks across 3 discrete phases: (1) Discovery & Symbol Tracing (silent inspection, write NO code), (2) Oracle & Test Formulation, and (3) Surgical Implementation & Verification.
-14. **Critic Agent Steering (Adversarial Pre-Review):** Jules' internal Critic Agent must evaluate proposed patches for edge-case regressions, $O(n^2)$ bottlenecks, unhandled parameters, and layout shifts (CLS) prior to PR submission.
+14. **Critic Agent Steering (Adversarial Pre-Review):** Jules' internal Critic Agent must evaluate proposed patches for edge-case regressions, $O(n^2)$ bottlenecks, unhandled parameters, and layout shifts (CLS) prior to PR submission. When modifying test suites or error handling, the agent must deliberately mutate production code and induce real failure conditions to prove that tests and catch blocks actually fail as intended (preventing tautological tests).
 15. **Web Excellence & Frontend Guardrails:** Enforce quantitative Core Web Vitals (LCP < 1.2s, CLS < 0.05), WCAG 2.2 AA/AAA semantic accessibility, Schema.org JSON-LD compliance, and Playwright multi-viewport responsive testing.
 16. **Airtight Positive Enclosures ("Pink Elephant" Rule):** Replace long negative constraint lists with strict positive operational perimeters (`ONLY modify [Target/Module]`) to prevent attention-drift in deep context windows.
 17. **Sterile / Clinical Vocabulary Mandate:** Eradicate aggressive verbs (`kill`, `amputate`, `sabotage`, `destroy`) from prompts and policies. Use clinical equivalents (`terminate PID`, `prune code`, `mutate test logic`, `purge cache`) to prevent false-positive safety classifier trips in Google Cloud VMs.

package/JULES_RULES_TEMPLATE.md

@@ -58,7 +58,7 @@ Jules automatically infers test and build verification commands via `scripts/com
 - **Minimal Interference**: Preserve existing function signatures, comments, and style conventions.
 - **No Token Bloat**: Exclude lockfiles, minified bundles, and binary assets from diff representations.
 - **Google Labs Exploration Budget Protocol**: Execute complex multi-step tasks across 3 discrete phases: (1) Discovery & Symbol Tracing (silent inspection, write NO code), (2) Oracle & Test Formulation, and (3) Surgical Implementation & Verification.
-- **Critic Agent Steering (Adversarial Pre-Review)**: Jules' internal Critic Agent evaluates proposed patches for edge-case regressions, $O(n^2)$ bottlenecks, unhandled parameters, and layout shifts (CLS) prior to final PR submission.
+- **Critic Agent Steering (Adversarial Pre-Review)**: Jules' internal Critic Agent evaluates proposed patches for edge-case regressions, $O(n^2)$ bottlenecks, unhandled parameters, and layout shifts (CLS) prior to final PR submission. In test modifications, verify deliberate logic mutations turn tests red (mutation falsification).
 - **Airtight Positive Enclosures ("Pink Elephant" Principle)**: Avoid massive negative constraint lists; define explicit positive perimeters (`ONLY modify [Target/Module]`) to eliminate attention distortion and cognitive drag.
 - **Sterile / Clinical Vocabulary Mandate**: Replace aggressive verbs (`kill`, `amputate`, `destroy`) with clinical equivalents (`terminate PID`, `prune code`, `purge state`) to prevent false-positive safety classifier tripwires.
 
@@ -80,8 +80,8 @@ Jules automatically infers test and build verification commands via `scripts/com
 
 ## 6. Local CI Verification with Nektos Act
 
-- **Pre-Push CI Validation**: When `.github/workflows/` exists and Nektos `act` is installed, execute `act push` or `bash scripts/act/run-act.sh` to verify changes pass CI locally inside the VM before opening a PR.
-- **Log Inspection**: If local `act` CI fails, inspect `act_output.log`, resolve errors in code, and re-run verification before pushing.
+- **Pre-Push CI Validation**: When `.github/workflows/` exists and Nektos `act` is installed, execute `act push` to verify changes pass CI locally inside the VM before opening a PR. Skip this step if `act` is not on `PATH` — do not install it and do not invent a wrapper script for it.
+- **Log Inspection**: If local `act` CI fails, inspect its output, resolve errors in code, and re-run verification before pushing.
 - **Diff Payload Governor**: API forcefully truncates diff payloads > 80 KB. Keep total diff payload under 75 KB (`git diff | wc -c`).
 
 ---
@@ -101,7 +101,11 @@ To maximize the ratio of mergeable PRs vs. failed or hallucinated sessions, adhe
 
 ### Standard Jules Guardrails Footer
 
-Append this footer to all Jules dispatches:
+`agentctl task create` appends this automatically, generated from your own
+`.agent/config.yml` scope — so the protected-path line lists *your* build
+manifests (`Cargo.toml`, `go.mod`, `pyproject.toml`, `composer.json`, …) and
+rebases onto *your* base branch. Fill the placeholders only for hand-written
+dispatches; run `agentctl gate` to see the full enforced set.
 
 ```text
 Read AGENTS.md and .agent/rules/jules-protocol.md BEFORE starting.
@@ -110,12 +114,12 @@ Follow all rules strictly.
 TASK: <description>
 
 HARD CONSTRAINTS:
-- Do NOT modify package.json, pnpm-lock.yaml, tsconfig.json, or .github/ files. Enforced in CI by Agent Scope Guard.
+- Do NOT modify these protected paths: <your build manifest, lockfile, CI directory, and agent rules>.
 - Diff Payload Governor: Keep total diff payload under 75 KB (`git diff | wc -c`) to prevent API truncation (~80 KB limit).
 - Falsifiable & Evidence-Based: Attach full terminal verification output to PR. Never weaken assertions or delete failing tests to force a pass.
 - Declare Scope Deviations: If modifying files outside task bounds, explicitly state rationale in PR.
-- Verify before finishing: Run full type-check, lint, and unit test suites.
-- BEFORE opening the PR: Run `git fetch origin main && git rebase origin/main`, then re-verify. If the rebase leaves an empty diff, the work already landed — do NOT submit.
-- Delete ALL temporary files (.py, .sh, .patch, debug logs) before submitting.
+- Verify before finishing: Run the project's full type-check, lint, and test commands.
+- BEFORE opening the PR: Run `git fetch origin <base> && git rebase origin/<base>`, then re-verify. If the rebase leaves an empty diff, the work already landed — do NOT submit.
+- Remove any scratch files you created for debugging before submitting. Do not delete files that are part of the project.
 ```
 

package/README.md

@@ -129,9 +129,9 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **Cross-Platform Parity:** Verified 100% green across Linux, macOS (Darwin), and Windows on Node 20, 22, and 24.
 * **Autonomous Self-Healing Loop:** Captures test stderr/stdout, fingerprints error traces, and feeds structured context back into automated repair turns (up to 3 attempts) before human escalation.
 * **Fail-Closed 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.
+* **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 **572 unit tests across 81 suites passing in < 10.0s**.
+* **Verified Test Suite:** Tested with **671 unit tests across 84 suites passing in < 10.0s**.
 
 <br/>
 
@@ -147,13 +147,18 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 | Command | Usage | Description | Exit Codes |
 | :--- | :--- | :--- | :--- |
 | `init` | `agentctl init [--interactive] [--tier pro]` | Interactive onboarding wizard & stack detector generating `.agent/config.yml`. | `0` (Created) |
+| `budget` | `agentctl budget [--by-user] [--json] [reset]` | Reports rolling 24h task budget, quota headroom, and per-developer task attribution without external auth servers. | `0` (Status), `2` (Arg Error) |
 | `task create` | `agentctl task create [--title <t>] [--prompt <p>] [--template <id>] [--role <name>] [--tier fast\|complex]` | Interactively authors & scopes falsifiable task envelopes with secret scrubbing, preflight gate checks, and DAG dependency wiring. | `0` (Queued), `1` (Secret/Unfalsifiable) |
-| `task template` | `agentctl task template [<id>] [--list] [--json]` | Lists and synthesizes pre-calibrated web task envelopes (`web-cwv`, `web-wcag`, `web-seo`, `web-playwright`, `web-flaky-heal`, `web-i18n`, `web-ai-access`). | `0` (Listed/Synthesized) |
-| `dispatch` | `agentctl dispatch [-p <prompt>] [-f <file>] [-r <role>] [-t <tier>] [--auto-pr] [--repoless] [--dry-run]` | Dispatches autonomous task to the active provider with payload limits and role prompt resolution. | `0` (Dispatched), `1` (Error) |
+| `task template` | `agentctl task template [<id>] [--list] [--json]` | Lists and synthesizes pre-calibrated task envelopes (Web, Deep Think & Agent Hardening: `web-cwv`, `web-wcag`, `web-seo`, `web-playwright`, `agent-dead-code-audit`, `web-flaky-heal`, `web-i18n`, `web-ai-access`, `agent-qa-mutation`, `agent-ci-falsify`, `agent-service-isolate`, `agent-error-paths`, `agent-security-audit`, `deep-debug`, `deep-feature`, `deep-optimize`, `deep-harden`). | `0` (Listed/Synthesized) |
+| `dispatch` | `agentctl dispatch [-p <prompt>] [-f <file>] [-r <role>] [-t <tier>] [--author <name>] [--check-premise] [--auto-pr] [--repoless] [--dry-run]` | Dispatches autonomous task to the active provider with pre-flight idempotency checks, payload limits, and role prompt resolution. | `0` (Dispatched), `1` (Error) |
+| `plan approve` | `agentctl plan approve <sessionId> [--dry-run] [--json]` | Approves pending execution plan for an active Jules session (`:approvePlan`) with automatic 404/503 retry backoff. | `0` (Approved), `1` (Error) |
+| `session get` | `agentctl session get <sessionId> [--dry-run] [--json]` | Retrieves live session lifecycle state from provider REST API with token rotation. | `0` (Fetched), `1` (Error) |
+| `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) |
 | `doctor` | `agentctl doctor [--json]` | Diagnostic DAG check runner & automated transactional self-repair engine. | `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) |
-| `gate` / `audit`| `agentctl gate --mode working-tree [--json]` | Runs security, secret scanning, and verification gates against working tree or branch. | `0` (Approved), `3` (Scope), `5` (Diff >75K), `6` (Secret) |
+| `gate` / `audit`| `agentctl gate --mode working-tree [--json] [--json-report <path>]` | Runs security, secret scanning, and tiered verification gates (with declarative assertion support) against working tree or branch. | `0` (Approved), `3` (Scope), `5` (Diff >75K), `6` (Secret) |
+| `assert` | `agentctl assert [--dir <d>] [--file <f>] [--max-mb <n>] [--gzip] [--targets <g>] [--patterns <p>] [--json] [--json-report <p>]` | Runs declarative zero-dependency verification assertion primitives (`assert:dir-size`, `assert:file-size`, `assert:file-patterns`, `assert:exists`). | `0` (Passed), `1` (Assertion Failed) |
 | `rollback` | `agentctl rollback [sessionId \| --latest]` | Restores exact commit, uncommitted files, and cleans orphan task worktrees from pre-flight checkpoints. | `0` (Restored), `1` (Error) |
 | `resume` | `agentctl resume <sessionId> --response "<reply>"` | Streams engineer response back into active Google Jules warm session context window. | `0` (Resumed), `1` (Error) |
 | `test-gen` | `agentctl test-gen --title <t> --spec <s> [--run]` | Scaffolds falsifiable unit tests, verifies RED failure state, and locks test in `scope.deny`. | `0` (Scaffolded/Red) |
@@ -199,13 +204,28 @@ scope:
     - ".agent/config.yml"
     - "keys/**"
 
-# Operational limits & governors
+# Plan tier. Defaults to `free` when unset — the kit will not assume you are
+# paying for a larger plan than you are. Set this to unlock your real limits.
+tier: "free"             # free | pro | ultra
+
+# Risk model for auto-merge triage. Builtin patterns cover what is dangerous in
+# any repository (CI, lockfiles, migrations, key material, IaC, auth). Add the
+# paths that are sensitive to YOUR domain — these EXTEND the builtins.
+risk:
+  restricted:            # R3 — never auto-merged
+    - "**/pricing/**"
+    - "**/billing/**"
+  consequential:         # R2 — always requires a human read
+    - "packages/api/**"
+  max_routine_diff_lines: 400
+
+# Operational limits & governors (tier defaults shown; any key here overrides)
 limits:
-  diffKb: 75             # 75 KB Diff Payload Governor limit
+  diffKb: 75             # Diff Payload Governor limit
   promptKb: 50           # Maximum prompt payload size
   dailyTasks: 300        # Task quota per rolling 24h window (not per calendar day)
   repairAttempts: 3      # Maximum repair iterations
-  concurrency: 15        # Worker slots (free: 3, pro: 8, ultra: 15)
+  concurrency: 15        # Worker slots (defaults free: 3, pro: 8, ultra: 15)
 
 # Dynamic Complexity & Cost Router — opt-in, disabled by default.
 router:
@@ -308,6 +328,23 @@ const { provider, classification } = resolveRoutedProvider(
 console.log(classification.tier); // "fast" | "complex"
 ```
 
+### Syntax-Verified FAST Tier (`createSyntaxVerifiedProvider`)
+`resolveRoutedProvider()` already wraps the FAST tier with this; use it directly only when composing your own provider cascade.
+```javascript
+import { createProvider, createSyntaxVerifiedProvider, loadConfig } from "jules-orchestrator-kit";
+
+const config = loadConfig(process.cwd());
+const fast = createSyntaxVerifiedProvider(
+  createProvider("gemini-flash", config),
+  createProvider("jules", config),
+  config
+);
+
+// If gemini-flash leaves broken .js/.mjs/.cjs on disk, this transparently
+// re-dispatches through "jules" instead of returning the broken result.
+const result = await fast.dispatch({ prompt: "Fix a typo." }, { root: process.cwd() });
+```
+
 </details>
 
 <br/>

package/bin/agentctl.mjs

@@ -40,7 +40,7 @@ export function printHelp() {
 Usage: agentctl <command> [options]
 
 Commands:
-  dispatch | create     Dispatch a single task to an AI agent (--role <name>, --tier fast|complex)
+  dispatch | create     Dispatch a single task to an AI agent (--role <name>, --tier fast|complex, --check-premise)
   gate | audit          Run CI security and verification gate against current branch
   queue                 Run pending task queue (--dag, --concurrency <n>)
   swarm                 Run parallel task swarm
@@ -54,12 +54,15 @@ Commands:
   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 web development task templates (--list, --json)
+  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
+  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
@@ -69,11 +72,13 @@ Commands:
   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:
   --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)
@@ -81,6 +86,7 @@ Options:
   --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
 `);
 }
@@ -147,6 +153,9 @@ async function main() {
           repoless: { type: "boolean" },
           "auto-pr": { type: "boolean" },
           "require-plan-approval": { type: "boolean" },
+          "check-premise": { type: "boolean" },
+          idempotent: { type: "boolean" },
+          author: { type: "string" },
           "dry-run": { type: "boolean", short: "d" },
           json: { type: "boolean", short: "j" },
         },
@@ -177,6 +186,8 @@ async function main() {
         repoless: values.repoless,
         autoPr: values["auto-pr"],
         requirePlanApproval: values["require-plan-approval"],
+        checkPremise: values["check-premise"] || values.idempotent,
+        author: values.author,
       };
 
       try {
@@ -187,15 +198,21 @@ async function main() {
           repoless: values.repoless,
           source: values.source,
           branch: values.branch,
+          checkPremise: values["check-premise"] || values.idempotent,
         });
         if (values.json) {
           console.log(JSON.stringify({ ok: true, session }, null, 2));
         } else {
-          console.log(`\n✅ Task Dispatched Successfully!`);
-          console.log(`   Session ID  : ${session.id}`);
-          console.log(`   Session URL : ${session.url || "N/A"}`);
-          if (session._routeTier) {
-            console.log(`   Router Tier : ${session._routeTier} (${session._routeReason || "n/a"})`);
+          if (session.status === "ALREADY_SATISFIED" || session.skipped) {
+            console.log(`\n⚡ Task Already Satisfied (skipped dispatch):`);
+            console.log(`   Reason: ${session.reason || "Verification oracle already passing on base branch."}`);
+          } else {
+            console.log(`\n✅ Task Dispatched Successfully!`);
+            console.log(`   Session ID  : ${session.id}`);
+            console.log(`   Session URL : ${session.url || "N/A"}`);
+            if (session._routeTier) {
+              console.log(`   Router Tier : ${session._routeTier} (${session._routeReason || "n/a"})`);
+            }
           }
         }
         process.exit(0);
@@ -224,6 +241,7 @@ async function main() {
           fix: { type: "boolean" },
           "allow-protected": { type: "boolean" },
           json: { type: "boolean", short: "j" },
+          "json-report": { type: "string" },
           "dry-run": { type: "boolean", short: "d" },
         },
         allowPositionals: true,
@@ -241,6 +259,7 @@ async function main() {
         mode: selectedMode,
         fix: values.fix,
         allowProtected: values["allow-protected"],
+        jsonReport: values["json-report"],
       });
 
       if (values.json) {
@@ -285,6 +304,93 @@ async function main() {
       break;
     }
 
+    case "assert": {
+      const { runAssertion, parseYaml } = await import("../index.mjs");
+      const { values } = parseArgs({
+        args: args.slice(1),
+        options: {
+          dir: { type: "string", short: "d" },
+          file: { type: "string", short: "f" },
+          targets: { type: "string", short: "t" },
+          patterns: { type: "string", short: "p" },
+          "patterns-file": { type: "string" },
+          "max-bytes": { type: "string" },
+          "max-kb": { type: "string" },
+          "max-mb": { type: "string" },
+          gzip: { type: "boolean" },
+          config: { type: "string", short: "c" },
+          json: { type: "boolean", short: "j" },
+          "json-report": { type: "string" },
+        },
+        allowPositionals: true,
+      });
+
+      let stageConfig = {};
+      if (values.config && existsSync(values.config)) {
+        const raw = readFileSync(values.config, "utf-8");
+        stageConfig = parseYaml(raw);
+      } else {
+        let assertType = "dir-size";
+        if (values.file) assertType = "file-size";
+        else if (values.patterns || values["patterns-file"] || values.targets) assertType = "file-patterns";
+        else if (values.dir) assertType = "dir-size";
+
+        stageConfig = {
+          assert: assertType,
+          path: values.dir || values.file,
+          targets: values.targets ? values.targets.split(",").map((s) => s.trim()) : undefined,
+          patterns: values.patterns ? values.patterns.split(",").map((s) => s.trim()) : undefined,
+          patternsFile: values["patterns-file"],
+          maxBytes: values["max-bytes"] ? Number(values["max-bytes"]) : undefined,
+          maxKb: values["max-kb"] ? Number(values["max-kb"]) : undefined,
+          maxMb: values["max-mb"] ? Number(values["max-mb"]) : undefined,
+          gzip: values.gzip,
+        };
+      }
+
+      const result = runAssertion(stageConfig, root);
+      if (values["json-report"]) {
+        const { exportJsonReport, generateEvidenceManifest } = await import("../src/evidence.mjs");
+        const dummyManifest = generateEvidenceManifest(root, {
+          taskId: "CLI-ASSERT",
+          title: "Ad-hoc Assertion",
+          executionRecords: [
+            {
+              id: result.assertionType,
+              kind: "assert",
+              assert: result.assertionType,
+              exitCode: result.status,
+              durationMs: result.metrics?.durationMs || 0,
+              diagnostics: result.diagnostics,
+              metrics: result.metrics,
+            },
+          ],
+          diagnostics: result.diagnostics,
+          metrics: result.metrics,
+          ok: result.ok,
+        });
+        exportJsonReport(dummyManifest, values["json-report"]);
+      }
+
+      if (values.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        if (result.ok) {
+          console.log(`\n✅ Assertion [${result.assertionType}] PASSED (${result.metrics?.durationMs || 0}ms)`);
+          if (result.metrics?.measuredBytes !== undefined) {
+            console.log(`   Measured : ${result.metrics.measuredBytes} bytes${result.metrics.gzip ? " (gzipped)" : ""}`);
+          }
+        } else {
+          console.error(`\n❌ Assertion [${result.assertionType}] FAILED (Exit 1)`);
+          for (const d of result.diagnostics) {
+            console.error(`   - ${d}`);
+          }
+        }
+      }
+      process.exit(result.status);
+      break;
+    }
+
     case "queue": {
       const { values } = parseArgs({
         args: args.slice(1),
@@ -396,6 +502,27 @@ async function main() {
         process.exit(0);
       }
 
+      if (args.includes("--by-user") || args.includes("-u")) {
+        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 || {});
+        if (users.length === 0) {
+          console.log("  No user activity recorded in the active 24h window.\n");
+        } else {
+          console.log("  Author               Tasks  Committed  Pending");
+          console.log("  -------------------  -----  ---------  -------");
+          for (const [user, stats] of users.sort(([, a], [, b]) => b.tasks - a.tasks)) {
+            const padUser = user.padEnd(20);
+            const padTasks = String(stats.tasks).padStart(5);
+            const padCommitted = String(stats.committed).padStart(9);
+            const padPending = String(stats.uncommitted).padStart(7);
+            console.log(`  ${padUser} ${padTasks}  ${padCommitted}  ${padPending}`);
+          }
+          console.log("");
+        }
+        process.exit(0);
+      }
+
       if (args.includes("--json")) {
         console.log(JSON.stringify({ ok: true, budget: { ...b, scope: "this-repository" } }, null, 2));
         process.exit(0);
@@ -559,7 +686,12 @@ async function main() {
       const { runInitWizard } = await import("../src/wizard-init.mjs");
       const res = await runInitWizard(root, {
         interactive: values.interactive !== false,
-        tier: values.tier || "pro",
+        // No `|| "pro"`: a hardcoded default here overrode both the tier picked
+        // in the menu and the tier already recorded in .agent/config.yml on a
+        // re-run. Undefined lets the wizard seed the menu from the existing
+        // config and fall back to FALLBACK_TIER when there is nothing to seed.
+        tier: values.tier,
+        allowDefaults: true,
       });
 
       if (values.json) {
@@ -643,7 +775,7 @@ async function main() {
           if (values.json) {
             console.log(JSON.stringify({ ok: true, templates }, null, 2));
           } else {
-            console.log(`\n🌐 Available Web Development Task Templates`);
+            console.log(`\n📋 Available Task Templates & Envelopes`);
             console.log(`--------------------------------------------------`);
             templates.forEach((t) => {
               console.log(`  • ${t.id.padEnd(16)} [${t.category}]`);
@@ -977,6 +1109,162 @@ async function main() {
       break;
     }
 
+    case "plan": {
+      const subAction = args[1];
+      if (subAction === "approve") {
+        const sessionId = args[2];
+        const { values, positionals } = parseArgs({
+          args: args.slice(2),
+          options: {
+            "dry-run": { type: "boolean", short: "d" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+        const targetSessionId = sessionId && !sessionId.startsWith("-") ? sessionId : positionals?.[0];
+        if (!targetSessionId) {
+          console.error("Error: Session ID is required for agentctl plan approve <sessionId>.");
+          process.exit(1);
+        }
+        const { createProvider } = await import("../src/provider.mjs");
+        const provider = createProvider(config.provider || "jules", config);
+        try {
+          const res = await provider.approvePlan(targetSessionId, { root, dryRun: values["dry-run"] });
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(`\n✅ Plan Approved Successfully!`);
+            console.log(`   Session ID : ${res.id}`);
+            console.log(`   Status     : ${res.status}\n`);
+          }
+          process.exit(0);
+        } catch (err) {
+          console.error(`❌ Plan Approval Failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+      console.error(`Error: Unknown plan subcommand '${subAction}'. Use approve.`);
+      process.exit(1);
+      break;
+    }
+
+    case "approve": {
+      const sessionId = args[1];
+      const { values, positionals } = parseArgs({
+        args: args.slice(1),
+        options: {
+          "dry-run": { type: "boolean", short: "d" },
+          json: { type: "boolean", short: "j" },
+        },
+        allowPositionals: true,
+      });
+      const targetSessionId = sessionId && !sessionId.startsWith("-") ? sessionId : positionals?.[0];
+      if (!targetSessionId) {
+        console.error("Error: Session ID is required for agentctl approve <sessionId>.");
+        process.exit(1);
+      }
+      const { createProvider } = await import("../src/provider.mjs");
+      const provider = createProvider(config.provider || "jules", config);
+      try {
+        const res = await provider.approvePlan(targetSessionId, { root, dryRun: values["dry-run"] });
+        if (values.json) {
+          console.log(JSON.stringify(res, null, 2));
+        } else {
+          console.log(`\n✅ Plan Approved Successfully!`);
+          console.log(`   Session ID : ${res.id}`);
+          console.log(`   Status     : ${res.status}\n`);
+        }
+        process.exit(0);
+      } catch (err) {
+        console.error(`❌ Plan Approval Failed: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "session": {
+      const subAction = args[1];
+      if (subAction === "get" || subAction === "status") {
+        const sessionId = args[2];
+        const { values, positionals } = parseArgs({
+          args: args.slice(2),
+          options: {
+            "dry-run": { type: "boolean", short: "d" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+        const targetSessionId = sessionId && !sessionId.startsWith("-") ? sessionId : positionals?.[0];
+        if (!targetSessionId) {
+          console.error("Error: Session ID is required for agentctl session get <sessionId>.");
+          process.exit(1);
+        }
+        const { createProvider } = await import("../src/provider.mjs");
+        const provider = createProvider(config.provider || "jules", config);
+        try {
+          const res = await provider.getSession(targetSessionId, { root, dryRun: values["dry-run"] });
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(`\n📋 Remote Session Status:`);
+            console.log(`   Session ID : ${res.id}`);
+            console.log(`   Status     : ${res.status}\n`);
+          }
+          process.exit(0);
+        } catch (err) {
+          console.error(`❌ Session Retrieval Failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+      console.error(`Error: Unknown session subcommand '${subAction}'. Use get.`);
+      process.exit(1);
+      break;
+    }
+
+    case "pr": {
+      const subAction = args[1];
+      if (subAction === "harvest") {
+        const { harvestPullRequests, formatHarvestTable } = await import("../src/ops/pr-harvest.mjs");
+        const { values } = parseArgs({
+          args: args.slice(2),
+          options: {
+            tier: { type: "string" },
+            limit: { type: "string" },
+            auto: { type: "boolean" },
+            merge: { type: "boolean" },
+            "allow-no-checks": { type: "boolean" },
+            "dry-run": { type: "boolean", short: "d" },
+            json: { type: "boolean", short: "j" },
+          },
+          allowPositionals: true,
+        });
+
+        const limit = values.limit ? parseInt(values.limit, 10) : 50;
+        try {
+          const res = await harvestPullRequests(root, {
+            tier: values.tier,
+            limit,
+            auto: values.auto || values.merge,
+            allowNoChecks: values["allow-no-checks"],
+            dryRun: values["dry-run"],
+          });
+
+          if (values.json) {
+            console.log(JSON.stringify(res, null, 2));
+          } else {
+            console.log(formatHarvestTable(res));
+          }
+          process.exit(0);
+        } catch (err) {
+          console.error(`❌ PR Harvest Failed: ${err.message}`);
+          process.exit(1);
+        }
+      }
+      console.error(`Error: Unknown PR subcommand '${subAction}'. Use harvest.`);
+      process.exit(1);
+      break;
+    }
+
     case "escalate": {
       const {
         dispatchEscalation,