jules-orchestrator-kit 0.39.0 → 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/JULES_RULES_TEMPLATE.md

@@ -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 **602 unit tests across 83 suites passing in < 10.0s**.
+* **Verified Test Suite:** Tested with **671 unit tests across 84 suites passing in < 10.0s**.
 
 <br/>
 
@@ -147,12 +147,13 @@ 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 task envelopes (Web & 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`). | `0` (Listed/Synthesized) |
-| `dispatch` | `agentctl dispatch [-p <prompt>] [-f <file>] [-r <role>] [-t <tier>] [--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) |
+| `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] [--dry-run]` | Discovers open agent PRs, evaluates CI checks & risk tiers, and auto-squashes green low-risk changes autonomously. | `0` (Triaged/Merged), `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) |
@@ -203,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:
@@ -312,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

@@ -155,6 +155,7 @@ async function main() {
           "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" },
         },
@@ -186,6 +187,7 @@ async function main() {
         autoPr: values["auto-pr"],
         requirePlanApproval: values["require-plan-approval"],
         checkPremise: values["check-premise"] || values.idempotent,
+        author: values.author,
       };
 
       try {
@@ -500,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);
@@ -663,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) {
@@ -1204,6 +1232,7 @@ async function main() {
             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" },
           },
@@ -1216,6 +1245,7 @@ async function main() {
             tier: values.tier,
             limit,
             auto: values.auto || values.merge,
+            allowNoChecks: values["allow-no-checks"],
             dryRun: values["dry-run"],
           });
 

package/index.mjs

@@ -23,6 +23,7 @@ export { git, runCmd, resolveBase, changedFiles, diffBytes, diffText } from "./s
 export {
   createProvider,
   createFailoverProvider,
+  createSyntaxVerifiedProvider,
   JULES_PRESET,
   CLAUDE_PRESET,
   CODEX_PRESET,
@@ -97,7 +98,7 @@ export { detectStackOracles, runVerificationProbe } from "./src/wizard-oracle.mj
 export { planInit, loadPresets, runInitWizard, TIER_PROFILES, BUILTIN_PRESETS } from "./src/wizard-init.mjs";
 
 // Guided Task Authoring Subsystem
-export { planTaskCreate, runTaskCreateWizard, GUARDRAIL_FOOTER } from "./src/wizard-task.mjs";
+export { planTaskCreate, runTaskCreateWizard, GUARDRAIL_FOOTER, buildGuardrailFooter } from "./src/wizard-task.mjs";
 
 // Prompt Falsifiability & Task Optimizer Engine
 export { scorePromptFalsifiability, optimizeTaskPrompt, levenshteinDistance, extractPathTokens } from "./src/task-optimizer.mjs";
@@ -173,6 +174,7 @@ export {
   listOpenReservations,
   releaseOpenReservations,
   resolveConcurrency,
+  resolveAmbientIdentity,
   CEILING_FILE,
 } from "./src/budget.mjs";
 export { KIT_VERSION } from "./src/version.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for Google Jules (jules) autonomous agents.",
   "repository": {
     "type": "git",

package/scripts/ci-scope-guard.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * CI Agent Scope Guard.
+ *
+ * Evaluates the files a pull request touches against the protected-paths
+ * manifest and fails the job when an agent has edited one of them.
+ *
+ * This exists as a Node entry point rather than inline shell because the shell
+ * version had to reimplement glob matching, and its glob-to-regex `sed`
+ * expression was invalid (`s/\*​/[^/]*​/g` — the `/` inside the character class
+ * closes the substitution). Under `bash -e` that aborted the step on the first
+ * modified file, so the guard never actually evaluated anything. Reusing
+ * `checkScope` removes the second implementation entirely: deny/protect
+ * matching now behaves identically in CI and locally, including the deliberate
+ * case-folding that a hand-rolled bash regex did not have.
+ */
+import { execFileSync } from "node:child_process";
+import { checkScope } from "../src/security.mjs";
+import { normalizePath } from "../src/config.mjs";
+
+/** Exit code 3 in the kit's registry: scope violation. */
+const EXIT_SCOPE_VIOLATION = 3;
+const EXIT_ERROR = 1;
+
+/** Label that lets a human consciously land a protected-path change. */
+export const BYPASS_LABEL = "allow-protected-paths";
+
+function gitShow(ref, path, cwd) {
+  return execFileSync("git", ["show", `${ref}:${path}`], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+/**
+ * Reads the protected-paths manifest from the PR's *base* commit.
+ *
+ * Reading it from the head would let a pull request delete its own guard in the
+ * same diff it uses to edit a protected file, so the base commit is the only
+ * safe source. `baseSha` is preferred over `origin/<branch>` because the branch
+ * ref can advance mid-run while the SHA is pinned to what this PR targets.
+ *
+ * @param {{ baseSha?: string, baseRef?: string, root?: string }} opts
+ * @returns {string[]}
+ */
+export function loadProtectedPatterns(opts = {}) {
+  const root = opts.root || process.cwd();
+  const manifestPath = ".agent/protected-paths.json";
+  const refs = [opts.baseSha, opts.baseRef ? `origin/${opts.baseRef}` : "", opts.baseRef].filter(Boolean);
+
+  let lastErr = null;
+  for (const ref of refs) {
+    try {
+      const parsed = JSON.parse(gitShow(ref, manifestPath, root));
+      const patterns = Array.isArray(parsed.protected) ? parsed.protected.filter((p) => typeof p === "string" && p) : [];
+      if (patterns.length === 0) {
+        throw new Error(`${manifestPath} at ${ref} lists no protected patterns`);
+      }
+      return patterns;
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+
+  // Fail closed: an unreadable manifest means the guard cannot make a decision,
+  // and "cannot decide" must never render as "approved".
+  throw new Error(
+    `Unable to read ${manifestPath} from any of [${refs.join(", ")}]: ${lastErr ? lastErr.message : "no refs supplied"}`
+  );
+}
+
+/**
+ * Lists the paths a pull request changes.
+ *
+ * `-z` and `core.quotePath=false` matter here: without them git splits on
+ * whitespace and octal-escapes non-ASCII names, so `docs/min plan.md` and
+ * `säkerhet/nyckel.pem` arrive as tokens that match no pattern — a protected
+ * file walking past the guard because of how it is spelled.
+ *
+ * @param {{ baseSha: string, headSha: string, root?: string }} opts
+ * @returns {string[]}
+ */
+export function listChangedFiles(opts = {}) {
+  const root = opts.root || process.cwd();
+  const raw = execFileSync(
+    "git",
+    ["-c", "core.quotePath=false", "diff", "-z", "--name-only", opts.baseSha, opts.headSha],
+    { cwd: root, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 10 * 1024 * 1024 }
+  );
+  return raw.split("\0").map(normalizePath).filter(Boolean);
+}
+
+/**
+ * Pure evaluation core, so the decision is testable without a git repository.
+ *
+ * @param {string[]} files
+ * @param {string[]} patterns
+ * @param {{ labels?: string[] }} [opts]
+ * @returns {{ ok: boolean, bypassed: boolean, violations: Array<object> }}
+ */
+export function evaluateScopeGuard(files = [], patterns = [], opts = {}) {
+  const labels = (opts.labels || []).map((l) => String(l).toLowerCase().trim());
+  const bypassed = labels.includes(BYPASS_LABEL);
+
+  // Matching always runs at full strength; the label only decides whether a
+  // match blocks. Passing `allowProtected` into checkScope instead would make
+  // a bypassed run report zero violations, and the job log is the record of
+  // what a human waved through.
+  const res = checkScope(files, { protect: patterns }, { allowProtected: false });
+  return { ok: bypassed || res.ok, bypassed, violations: res.violations };
+}
+
+/**
+ * Parses the labels payload GitHub Actions exposes for a pull request.
+ * Accepts the raw `toJSON(...labels)` array or a plain comma-separated string.
+ *
+ * @param {string} raw
+ * @returns {string[]}
+ */
+export function parseLabels(raw = "") {
+  const text = String(raw || "").trim();
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed)) {
+      return parsed.map((l) => (typeof l === "string" ? l : l && l.name) || "").filter(Boolean);
+    }
+  } catch (_) {}
+  return text.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+function main() {
+  const root = process.cwd();
+  const baseSha = (process.env.BASE_SHA || "").trim();
+  const headSha = (process.env.HEAD_SHA || "").trim();
+  const baseRef = (process.env.BASE_REF || "").trim();
+
+  if (!baseSha || !headSha) {
+    console.error("::error::BASE_SHA and HEAD_SHA must be set. This guard only runs on pull_request events.");
+    process.exit(EXIT_ERROR);
+  }
+
+  let patterns;
+  let files;
+  try {
+    patterns = loadProtectedPatterns({ baseSha, baseRef, root });
+    files = listChangedFiles({ baseSha, headSha, root });
+  } catch (err) {
+    console.error(`::error::Agent Scope Guard could not evaluate this pull request: ${err.message}`);
+    process.exit(EXIT_ERROR);
+  }
+
+  const labels = parseLabels(process.env.PR_LABELS);
+  const result = evaluateScopeGuard(files, patterns, { labels });
+
+  console.log(`Protected patterns (${patterns.length}): ${patterns.join(", ")}`);
+  console.log(`Changed files (${files.length}):`);
+  for (const f of files) console.log(`  ${f}`);
+
+  if (result.bypassed && result.violations.length > 0) {
+    for (const v of result.violations) {
+      console.log(`::warning file=${v.file}::Protected path modified under "${BYPASS_LABEL}": ${v.reason}`);
+    }
+    console.log(`\nLabel "${BYPASS_LABEL}" is present — ${result.violations.length} protected-path match(es) allowed by human review.`);
+    process.exit(0);
+  }
+
+  if (result.ok) {
+    console.log("\nScope check passed. No protected files were modified.");
+    process.exit(0);
+  }
+
+  for (const v of result.violations) {
+    console.error(`::error file=${v.file}::Protected path violation: ${v.reason}`);
+  }
+  console.error(
+    `::error::PR modifies ${result.violations.length} protected file(s). ` +
+      `Apply the "${BYPASS_LABEL}" label after human review to land this intentionally.`
+  );
+  process.exit(EXIT_SCOPE_VIOLATION);
+}
+
+if (process.argv[1] && process.argv[1].endsWith("ci-scope-guard.mjs")) {
+  main();
+}

package/scripts/jules-merge-swarm.mjs

@@ -11,7 +11,7 @@ import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { classifyRiskTier, RISK_TIERS } from "../src/risk.mjs";
 import { git, resolveBase } from "../src/git.mjs";
-import { normalizePath } from "../src/config.mjs";
+import { normalizePath, loadConfig } from "../src/config.mjs";
 
 export const EXIT = Object.freeze({
   SUCCESS: 0,
@@ -155,7 +155,7 @@ export function attemptCodeMergeFile(repoRoot, relPath, oursContent, baseContent
 /**
  * Checks safety gate against active worker locks and risk tiers.
  */
-export function checkSafetyGate(branchName = "", projectRoot = process.cwd()) {
+export function checkSafetyGate(branchName = "", projectRoot = process.cwd(), opts = {}) {
   const locksDir = join(projectRoot, ".agent/state/locks");
   if (existsSync(locksDir)) {
     try {
@@ -179,7 +179,17 @@ export function checkSafetyGate(branchName = "", projectRoot = process.cwd()) {
       const raw = git(["-c", "core.quotePath=false", "diff", "-z", "--name-only", `${resolvedBase}...${branchName}`], { cwd: projectRoot, raw: true, ignoreError: true }) || "";
       const files = raw.split("\0").map(normalizePath).filter(Boolean);
       if (files.length > 0) {
-        const tier = classifyRiskTier(files);
+        // The repository's own risk paths must apply here too, or the gate and
+        // the harvester classify the same branch differently.
+        let config = opts.config;
+        if (!config) {
+          try {
+            config = loadConfig(projectRoot);
+          } catch (_) {
+            config = {};
+          }
+        }
+        const tier = classifyRiskTier(files, { config });
         if (tier.tier === RISK_TIERS.R3) {
           return { safe: false, reason: `R3 Restricted Path violation: ${tier.reason}` };
         }

package/src/budget.mjs

@@ -1,15 +1,56 @@
 import { existsSync, readFileSync, writeFileSync, openSync, fsyncSync, closeSync, renameSync } from "node:fs";
 import { join } from "node:path";
+import { execSync } from "node:child_process";
+import { userInfo } from "node:os";
 import { resolveRoot } from "./config.mjs";
 import {
   getStateDir,
   ensureDir,
   appendLedger,
-  checkDailyBudget,
   scanBudgetWindow,
   ROLLING_WINDOW_MS,
 } from "./state.mjs";
 
+/**
+ * Resolves ambient developer identity with zero dependencies and strict PII protection.
+ * Hierarchy: CLI flag -> GITHUB_ACTOR -> Git config user.email (stripped of domain) -> OS username -> anonymous-local
+ * @param {string|null} [cliOverride]
+ * @returns {string}
+ */
+export function resolveAmbientIdentity(cliOverride = null) {
+  const sanitize = (str) =>
+    (str || "")
+      .toString()
+      .trim()
+      .toLowerCase()
+      .split("@")[0] // Strip email domain to prevent PII leakage
+      .replace(/[^a-z0-9_.-]/g, ""); // Remove unsafe injection/special chars
+
+  if (cliOverride) {
+    const cleaned = sanitize(cliOverride);
+    if (cleaned) return cleaned;
+  }
+
+  if (process.env.GITHUB_ACTOR) {
+    const actor = sanitize(process.env.GITHUB_ACTOR);
+    if (actor) return `ci-${actor}`;
+  }
+
+  try {
+    const gitEmail = execSync("git config user.email", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const cleaned = sanitize(gitEmail);
+    if (cleaned) return cleaned;
+  } catch (_) {}
+
+  try {
+    const osUser = process.env.USER || process.env.USERNAME || userInfo().username;
+    const cleaned = sanitize(osUser);
+    if (cleaned) return `${cleaned}-local`;
+  } catch (_) {}
+
+  return "anonymous-local";
+}
+
 /**
  * Where the observed quota ceiling lives, outside the ledger so it survives
  * rotation.
@@ -347,21 +388,22 @@ export function releaseOpenReservations(opts = {}) {
  */
 export function budgetStatus(config, root = resolveRoot()) {
   const resolved = resolveDailyLimit(config, root);
-  const check = checkDailyBudget(root, resolved.limit);
+  const scan = scanBudgetWindow(root);
   return {
-    used: check.used,
+    used: scan.used,
     limit: resolved.limit,
-    remaining: check.remaining,
+    remaining: Math.max(0, resolved.limit - scan.used),
+    byUser: scan.byUser || {},
     tier: config?.tier || "unknown",
     source: resolved.source,
     certain: resolved.certain,
     note: resolved.note,
     // The count is a rolling 24h window, not a calendar day — surfaced so a
     // caller reporting "used today" cannot quietly mean something else.
-    windowStart: check.windowStart || "",
+    windowStart: scan.windowStart || "",
     windowHours: ROLLING_WINDOW_MS / 3600000,
     // Only a limit we actually know may stop a dispatch.
     enforced: resolved.certain,
-    exhausted: check.used >= resolved.limit,
+    exhausted: scan.used >= resolved.limit,
   };
 }