@piagent/platform 1.4.0 → 1.4.1

package/packages/piagent-core/extensions/shell-reach.ts

@@ -0,0 +1,250 @@
+// What a shell command can reach, and how to say so.
+//
+// These checks used to live inside the guard entrypoint, which imports the Pi
+// host runtime and therefore cannot be loaded anywhere else. `piagent explain`
+// needs the same answers the guard gives, and a second implementation of "does
+// this command reach a protected path" is exactly the defect this project keeps
+// closing: one segment, many readers, each with its own view. So the readers
+// live here and both the guard and the CLI take this one.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  extractShellGlobCandidates,
+  extractShellPathCandidates,
+  matchesProtectedPath,
+  normalizePathCandidate
+} from "./policy-core.js";
+
+export function normalizeRelative(cwd: string, candidate: unknown): string | undefined {
+  if (typeof candidate !== "string" || candidate.trim().length === 0) return undefined;
+  let raw = candidate.trim();
+  try {
+    raw = decodeURIComponent(raw);
+  } catch {
+    return undefined;
+  }
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw)) {
+    if (!raw.toLowerCase().startsWith("file://")) return undefined;
+    try {
+      raw = fileURLToPath(raw);
+    } catch {
+      return undefined;
+    }
+  }
+  const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+  return path.relative(cwd, absolute).split(path.sep).join("/");
+}
+
+export function resolveRepositoryPathCandidate(cwd: string, candidate: string): string | undefined {
+  const normalized = normalizePathCandidate(candidate);
+  if (normalized === ".." || normalized.startsWith("../")) return undefined;
+
+  const relative = path.posix.isAbsolute(normalized)
+    ? path.relative(cwd, normalized).split(path.sep).join("/")
+    : normalized;
+  if (relative === ".." || relative.startsWith("../")) return undefined;
+
+  const pending = relative.split("/").filter((item) => item && item !== ".");
+  let current = cwd;
+  let resolvedDepth = 0;
+  for (let index = 0; index < pending.length; index += 1) {
+    const next = path.join(current, pending[index]);
+    try {
+      fs.lstatSync(next);
+      current = next;
+      resolvedDepth = index + 1;
+    } catch (error) {
+      const code = error && typeof error === "object" && "code" in error ? String((error as { code?: unknown }).code) : "";
+      if (code !== "ENOENT") return undefined;
+      break;
+    }
+  }
+
+  let canonicalBase: string;
+  try {
+    canonicalBase = fs.realpathSync.native(current);
+  } catch {
+    return undefined;
+  }
+  const canonical = path.resolve(canonicalBase, ...pending.slice(resolvedDepth));
+  const canonicalRoot = fs.realpathSync.native(cwd);
+  const canonicalRelative = path.relative(canonicalRoot, canonical).split(path.sep).join("/");
+  if (canonicalRelative === ".." || canonicalRelative.startsWith("../") || path.isAbsolute(canonicalRelative)) return undefined;
+  return canonicalRelative || ".";
+}
+
+export function findResolvedProtectedPathInCommand(
+  cwd: string,
+  command: string,
+  protectedPatterns: string[]
+): { candidate: string; resolved: string; pattern: string } | undefined {
+  for (const candidate of extractShellPathCandidates(command)) {
+    const relative = normalizeRelative(cwd, candidate);
+    if (!relative) continue;
+    const resolved = resolveRepositoryPathCandidate(cwd, relative);
+    if (!resolved || resolved === relative) continue;
+    const pattern = matchesProtectedPath(resolved, protectedPatterns);
+    if (pattern) return { candidate, resolved, pattern };
+  }
+  return undefined;
+}
+
+export function expandSimpleGlobAlternatives(pattern: string, max = 24): { values: string[]; complete: boolean } {
+  let results = [pattern];
+  let changed = true;
+  let complete = true;
+
+  while (changed) {
+    changed = false;
+    const expanded: string[] = [];
+    for (const item of results) {
+      const match = item.match(/\{([^{}]+)\}/);
+      if (!match) {
+        expanded.push(item);
+        continue;
+      }
+      changed = true;
+      const options = match[1].split(",").map((option) => option.trim());
+      for (const option of options) {
+        expanded.push(`${item.slice(0, match.index)}${option}${item.slice((match.index ?? 0) + match[0].length)}`);
+        if (expanded.length >= max) {
+          complete = false;
+          break;
+        }
+      }
+      if (expanded.length >= max) break;
+    }
+    results = expanded.slice(0, max);
+  }
+
+  return { values: results, complete };
+}
+
+export function shellGlobSegmentMatches(patternSegment: string, candidateSegment: string): boolean {
+  if (candidateSegment.startsWith(".") && !patternSegment.startsWith(".")) return false;
+  let source = "";
+  for (let index = 0; index < patternSegment.length; index += 1) {
+    const char = patternSegment[index];
+    if (char === "*") {
+      source += "[^/]*";
+      continue;
+    }
+    if (char === "?") {
+      source += "[^/]";
+      continue;
+    }
+    if (char === "[") {
+      const end = patternSegment.indexOf("]", index + 1);
+      const body = end > index + 1 ? patternSegment.slice(index + 1, end) : "";
+      if (body && /^[!^A-Za-z0-9_-]+$/.test(body)) {
+        const negated = body.startsWith("!") ? `^${body.slice(1)}` : body;
+        source += `[${negated}]`;
+        index = end;
+        continue;
+      }
+    }
+    source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`, "i").test(candidateSegment);
+}
+
+export function shellGlobMatchesPath(pattern: string, candidate: string): boolean {
+  const patternSegments = normalizePathCandidate(pattern).split("/").filter(Boolean);
+  const candidateSegments = normalizePathCandidate(candidate).split("/").filter(Boolean);
+
+  function match(patternIndex: number, candidateIndex: number): boolean {
+    if (patternIndex === patternSegments.length) return candidateIndex === candidateSegments.length;
+    const patternSegment = patternSegments[patternIndex];
+    if (patternSegment === "**") {
+      if (match(patternIndex + 1, candidateIndex)) return true;
+      for (let next = candidateIndex; next < candidateSegments.length; next += 1) {
+        if (match(patternIndex + 1, next + 1)) return true;
+      }
+      return false;
+    }
+    if (candidateIndex >= candidateSegments.length) return false;
+    return shellGlobSegmentMatches(patternSegment, candidateSegments[candidateIndex])
+      && match(patternIndex + 1, candidateIndex + 1);
+  }
+
+  return patternSegments.length > 0 && candidateSegments.length > 0 && match(0, 0);
+}
+
+export function protectedPatternExamples(pattern: string): string[] {
+  const normalized = normalizePathCandidate(pattern);
+  if (!normalized) return [];
+
+  const examples = new Set<string>();
+  const add = (value: string | undefined) => {
+    const normalizedValue = normalizePathCandidate(value ?? "");
+    if (normalizedValue) examples.add(normalizedValue);
+  };
+
+  add(normalized);
+
+  if (normalized.endsWith("/**")) {
+    const base = normalized.slice(0, -3);
+    add(base);
+    add(`${base}/probe`);
+  }
+
+  if (normalized.startsWith("**/")) {
+    const tail = normalized.slice(3);
+    const concreteTail = tail
+      .replace(/\*\*/g, "nested")
+      .replace(/\*/g, tail.includes(".env.") ? "local" : "probe");
+    add(tail);
+    add(concreteTail);
+    add(`nested/${concreteTail}`);
+  }
+
+  const concrete = normalized
+    .replace(/^\*\*\//, "")
+    .replace(/\/\*\*$/, "/probe")
+    .replace(/\*\*/g, "nested")
+    .replace(/\*/g, normalized.includes(".env.") ? "local" : "probe");
+  add(concrete);
+
+  for (const example of [...examples]) {
+    const base = path.posix.basename(example);
+    if (base && base !== "probe") examples.add(base);
+  }
+
+  return [...examples];
+}
+
+export function shellGlobTargetsProtectedPath(
+  command: string,
+  protectedPatterns: string[]
+): { glob: string; pattern: string; example: string } | undefined {
+  for (const candidate of extractShellGlobCandidates(command)) {
+    if (!/[*?{\[]/.test(candidate)) continue;
+    const expanded = expandSimpleGlobAlternatives(candidate);
+    if (!expanded.complete) return { glob: candidate, pattern: "bounded glob expansion", example: "a protected path" };
+    for (const candidateGlob of expanded.values) {
+      for (const pattern of protectedPatterns) {
+        for (const example of protectedPatternExamples(pattern)) {
+          if (/[*?{\[\]]/.test(example)) continue;
+          if (
+            shellGlobMatchesPath(candidateGlob, example)
+            || shellGlobMatchesPath(`**/${candidateGlob}`, example)
+            || shellGlobMatchesPath(candidateGlob, path.posix.basename(example))
+          ) {
+            return { glob: candidate, pattern, example };
+          }
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+export function unresolvedExpansionReason(subject: string, words: string[]): string {
+  const listed = words.map((word) => `\`${word}\``).join(", ");
+  return `${subject} builds a filename this guard cannot resolve: ${listed}. `
+    + "The literal text around the expansion makes it a path, but its value is only known at run time, "
+    + "so it cannot be checked against the protected paths. Write the path out, or put the expansion in its own argument.";
+}

package/packages/piagent-core/mcp/mcp-command-actions.js

@@ -37,7 +37,7 @@ export const SERVER_ACTIONS = new Set(["get", "approve", "reject", "reset", "ena
 export const TERMINAL_ONLY = new Map([
   ["add", "piagent-mcp add <name> [--scope <scope>] --url <url> | -- <command> [args...]"],
   ["remove", "piagent-mcp remove <name> --scope <scope>"],
-  ["preset", "piagent-mcp --preset <core|popular|design> --scope <scope>"]
+  ["preset", "piagent-mcp --preset <core|popular|documents|google|design> --scope <scope>"]
 ]);
 
 export const HELP_LINES = [

package/packages/piagent-core/mcp/mcp-server-catalog.js

@@ -6,7 +6,7 @@
 // Nothing here is a secret. Every credential is referenced as an environment
 // variable, so the config can be read, diffed and committed without leaking one.
 
-/** @typedef {{description: string, config: Record<string, unknown>}} CatalogServer */
+/** @typedef {{description: string, maturity?: "stable"|"experimental", config: Record<string, unknown>}} CatalogServer */
 
 /** @type {Record<string, CatalogServer>} */
 export const CATALOG_SERVERS = {
@@ -83,6 +83,85 @@ export const CATALOG_SERVERS = {
       lifecycle: "lazy",
       directTools: false
     }
+  },
+  // Google's own remote servers, one per product, rather than a community server
+  // holding every scope at once: a session that only needs to read a document
+  // should not be one OAuth grant away from the mailbox.
+  //
+  // These carry no version pin because there is nothing local to pin -- the
+  // endpoint is operated by Google and changes under the same URL. That is a
+  // real difference from every command-based server above, where the pin is what
+  // stops a floating tag becoming a supply-chain decision each session.
+  // Scopes are declared read-only. Write access is one word longer to ask for
+  // and cannot be taken back once an agent has used it, so the default grant is
+  // the one that cannot lose anything. `clientId` is deliberately absent: every
+  // operator registers their own OAuth client, and a client id baked in here
+  // would be someone else's project answering for their consent screen.
+  "google-drive": {
+    description: "EXPERIMENTAL Developer Preview: Google Drive remote MCP server. Read-only by default.",
+    maturity: "experimental",
+    config: {
+      url: "https://drivemcp.googleapis.com/mcp/v1",
+      auth: "oauth",
+      oauth: { scopes: ["https://www.googleapis.com/auth/drive.readonly"] },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  gmail: {
+    description: "EXPERIMENTAL Developer Preview: Gmail remote MCP server. Read-only by default.",
+    maturity: "experimental",
+    config: {
+      url: "https://gmailmcp.googleapis.com/mcp/v1",
+      auth: "oauth",
+      oauth: { scopes: ["https://www.googleapis.com/auth/gmail.readonly"] },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "google-docs": {
+    description: "EXPERIMENTAL Developer Preview: Google Docs remote MCP server. Read-only by default.",
+    maturity: "experimental",
+    config: {
+      url: "https://docsmcp.googleapis.com/mcp/v1",
+      auth: "oauth",
+      oauth: {
+        scopes: [
+          "https://www.googleapis.com/auth/documents.readonly",
+          "https://www.googleapis.com/auth/drive.readonly"
+        ]
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "google-sheets": {
+    description: "EXPERIMENTAL Developer Preview: Google Sheets remote MCP server. Read-only by default.",
+    maturity: "experimental",
+    config: {
+      url: "https://sheetsmcp.googleapis.com/mcp/v1",
+      auth: "oauth",
+      oauth: {
+        scopes: [
+          "https://www.googleapis.com/auth/spreadsheets.readonly",
+          "https://www.googleapis.com/auth/drive.readonly"
+        ]
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  // Converts .docx, .xlsx, .pptx and .pdf to Markdown locally. Local matters:
+  // the alternative to this is uploading a document somewhere to read it, and a
+  // document worth converting is usually one worth not uploading.
+  markitdown: {
+    description: "MarkItDown MCP. Converts local docx, xlsx, pptx, pdf and html files to Markdown. Runs offline for file: URIs.",
+    config: {
+      command: "uvx",
+      args: ["markitdown-mcp@0.0.1a4"],
+      lifecycle: "lazy",
+      directTools: false
+    }
   }
 };
 
@@ -100,7 +179,33 @@ export const CATALOG_PREREQUISITES = {
   ],
   playwright: ["browsers installed on first use (npx playwright install)"],
   figma: ["Piagent approved in the Figma MCP Catalog before remote OAuth can register"],
-  "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"]
+  "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"],
+  "google-drive": [
+    "a Google Cloud project with drive.googleapis.com and drivemcp.googleapis.com enabled",
+    "Developer Preview: no Pi OAuth end-to-end release proof exists yet",
+    "Google's supported client guides use an OAuth client id and secret; Pi's public-client/PKCE compatibility is unverified",
+    "piagent-mcp add google-drive --url https://drivemcp.googleapis.com/mcp/v1 --oauth-client-id <id> --scope user"
+  ],
+  gmail: [
+    "a Google Cloud project with gmail.googleapis.com and gmailmcp.googleapis.com enabled",
+    "Developer Preview: no Pi OAuth end-to-end release proof exists yet",
+    "Google's supported client guides use an OAuth client id and secret; Pi's public-client/PKCE compatibility is unverified",
+    "read the warning in docs/mcp-and-tools.md first: mail is untrusted input reaching an agent that can act"
+  ],
+  "google-docs": [
+    "a Google Cloud project with docs.googleapis.com and docsmcp.googleapis.com enabled",
+    "Developer Preview: no Pi OAuth end-to-end release proof exists yet",
+    "Google's supported client guides use an OAuth client id and secret; Pi's public-client/PKCE compatibility is unverified"
+  ],
+  "google-sheets": [
+    "a Google Cloud project with sheets.googleapis.com and sheetsmcp.googleapis.com enabled",
+    "Developer Preview: no Pi OAuth end-to-end release proof exists yet",
+    "Google's supported client guides use an OAuth client id and secret; Pi's public-client/PKCE compatibility is unverified"
+  ],
+  markitdown: [
+    "uv on PATH (https://docs.astral.sh/uv); the first run downloads a Python runtime and roughly 120 MB of dependencies",
+    "note: markitdown-mcp is published as an alpha, so pin changes deliberately"
+  ]
 };
 
 // Variables a pinned server references but works without. Context7 answers
@@ -113,6 +218,11 @@ export const CATALOG_OPTIONAL_ENV = {
   context7: ["CONTEXT7_API_KEY"]
 };
 
+// `core` is what an install writes when nobody names a preset, and `popular` is
+// what somebody picks without reading the list. Neither may reach a mailbox or a
+// Drive: an install that quietly grants those is a decision the operator never
+// made. The Google servers are therefore only in presets somebody has to type,
+// and in `all`, which means what it says.
 /** @type {Record<string, string[]>} */
 export const CATALOG_PRESETS = {
   minimal: [],
@@ -122,9 +232,24 @@ export const CATALOG_PRESETS = {
   design: ["figma-desktop"],
   "design-local": ["figma-desktop"],
   web: ["context7", "chrome-devtools", "playwright"],
+  // The generic documents preset stays local. Google Workspace is Developer
+  // Preview and must be selected through an explicitly named Google preset.
+  documents: ["markitdown"],
+  // One preset per product, because that is why Google ships four servers
+  // instead of one. Bundling them back together would mean reading a
+  // spreadsheet costs a grant over Drive and every document in it.
+  "google-drive": ["google-drive"],
+  "google-docs": ["google-docs"],
+  "google-sheets": ["google-sheets"],
+  "google-mail": ["gmail"],
+  google: ["google-drive", "google-docs", "google-sheets"],
+  "google-all": ["google-drive", "gmail", "google-docs", "google-sheets"],
   core: ["context7", "chrome-devtools", "github"],
   popular: ["context7", "chrome-devtools", "playwright", "github", "figma-desktop"],
-  all: ["context7", "chrome-devtools", "playwright", "github", "figma-desktop", "figma"]
+  all: [
+    "context7", "chrome-devtools", "playwright", "github", "figma-desktop", "figma",
+    "markitdown", "google-drive", "gmail", "google-docs", "google-sheets"
+  ]
 };
 
 /** @param {string} name @returns {boolean} */
@@ -136,7 +261,7 @@ export function isCatalogPreset(name) {
  * The servers a preset installs, with their definitions resolved. Throws on an
  * unknown preset so a typo is refused before anything is written.
  * @param {string} name
- * @returns {{name: string, config: Record<string, unknown>, requires: string[]}[]}
+ * @returns {{name: string, maturity: "stable"|"experimental", config: Record<string, unknown>, requires: string[]}[]}
  */
 export function resolvePreset(name) {
   if (!isCatalogPreset(name)) {
@@ -145,6 +270,11 @@ export function resolvePreset(name) {
   return CATALOG_PRESETS[name].map((serverName) => {
     const server = CATALOG_SERVERS[serverName];
     if (!server) throw new Error(`preset ${name} references missing server ${serverName}`);
-    return { name: serverName, config: server.config, requires: CATALOG_PREREQUISITES[serverName] ?? [] };
+    return {
+      name: serverName,
+      maturity: server.maturity ?? "stable",
+      config: server.config,
+      requires: CATALOG_PREREQUISITES[serverName] ?? []
+    };
   });
 }

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "type": "module",
   "private": true,
   "license": "MIT",

package/packages/piagent-core/runtime/hooks/tool-call-hook.ts

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { toolResultFingerprint } from "../../extensions/context-engine.js";
+import { withRemedy } from "../policy/block-remedy.ts";
 import { observeTrajectorySync } from "../trajectory/trajectory-observability.ts";
 import type { TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
 
@@ -75,7 +76,13 @@ export function registerToolCallHook(pi: ExtensionAPI, dependencies: ToolCallHoo
       : dependencies.reviewBudgetDecision?.(resolvedEvent, ctx);
     const startDecision = !(decision && typeof decision === "object" && decision.block) ? dependencies.beforeStart?.(resolvedEvent, ctx) : undefined;
     const finalDecision = startDecision && typeof startDecision === "object" && startDecision.block ? startDecision : decision;
-    const blockedDecision = finalDecision && typeof finalDecision === "object" ? finalDecision : undefined;
+    // Every refusal leaves through here, so this is where it is answered. A
+    // remedy attached at the 29 sites that build one is a remedy the next site
+    // will forget.
+    const answered = finalDecision && typeof finalDecision === "object" && finalDecision.block
+      ? withRemedy(finalDecision)
+      : finalDecision;
+    const blockedDecision = answered && typeof answered === "object" ? answered : undefined;
     record(ctx, {
       activityId: `decision:${toolCallId}`,
       event: "tool_decision",
@@ -91,6 +98,6 @@ export function registerToolCallHook(pi: ExtensionAPI, dependencies: ToolCallHoo
       observeTrajectorySync(ctx, dependencies.afterAuthorized?.(resolvedEvent, ctx, { toolCallId }), dependencies.telemetry);
     }
     dependencies.afterDecision?.(resolvedEvent, ctx, { toolCallId, allowed: !blockedDecision?.block, reason: blockedDecision?.reason });
-    return finalDecision;
+    return answered;
   });
 }

package/packages/piagent-core/runtime/orchestration/owned-work-budget.ts

@@ -7,6 +7,9 @@ import type { HelperRequest, HelperRole } from "./role-policy.ts";
 import { validateHelperRequest } from "./role-policy.ts";
 
 export const OWNED_WORK_BUDGET_VERSION = "owned-work-budget-v1" as const;
+// `maxRepairPasses` is declared for the repair lane, which reserves no helper
+// role here, so this mechanism never reads it. It is named rather than removed
+// because the repair lane is bounded elsewhere; nothing in this file enforces it.
 export type OwnedWorkCeilings = Readonly<{ maxConcurrentHelpers: number; maxTotalHelpers: number; maxScoutPasses: number; maxPlannerPasses: number; maxReviewPasses: number; maxOracleCalls: number; maxRepairPasses: number; maxWriters: number }>;
 export const DEFAULT_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ maxConcurrentHelpers: 2, maxTotalHelpers: 3, maxScoutPasses: 1, maxPlannerPasses: 1, maxReviewPasses: 1, maxOracleCalls: 1, maxRepairPasses: 1, maxWriters: 1 });
 export const AUTOMATIC_OWNED_WORK_CEILINGS: OwnedWorkCeilings = Object.freeze({ ...DEFAULT_OWNED_WORK_CEILINGS, maxConcurrentHelpers: 1, maxTotalHelpers: 1 });
@@ -26,7 +29,27 @@ function statePath(cwd: string, taskRunId: string): string { return path.join(cw
 function lockPath(cwd: string, taskRunId: string): string { return `${statePath(cwd, taskRunId)}.lock`; }
 function empty(request: HelperRequest, now: string): BudgetState { return { version: OWNED_WORK_BUDGET_VERSION, taskId: request.taskId, taskRunId: request.taskRunId, terminal: false, reservations: [], updatedAt: now }; }
 function active(state: BudgetState): OwnedWorkReservation[] { return state.reservations.filter((item) => item.status === "active"); }
-function roleLimit(role: HelperRole): number { return role === "scout" || role === "retriever" || role === "researcher" ? 1 : role === "planner" ? 1 : role === "reviewer" ? 1 : role === "oracle" ? 1 : role === "worker" ? 1 : 0; }
+// The per-role ceiling, read from the ceilings the caller passed rather than
+// from constants written here. These limits were real but fixed at one apiece,
+// so `OwnedWorkCeilings` advertised six numbers that nothing ever read: a
+// profile could raise `maxScoutPasses` and be silently ignored, while the two
+// neighbouring fields in the same object did take effect. Half-honoured
+// configuration is worse than none, because the half that works teaches the
+// reader to trust the half that does not.
+//
+// Every default is one, so this changes no behaviour under the shipped
+// ceilings; it makes the object mean what it says.
+function roleLimit(role: HelperRole, ceilings: OwnedWorkCeilings): number {
+  switch (role) {
+    case "scout": case "retriever": case "researcher": return ceilings.maxScoutPasses;
+    case "planner": return ceilings.maxPlannerPasses;
+    case "reviewer": return ceilings.maxReviewPasses;
+    case "oracle": return ceilings.maxOracleCalls;
+    case "worker": return ceilings.maxWriters;
+    // An unknown role reserves nothing rather than defaulting to a limit.
+    default: return 0;
+  }
+}
 
 function read(cwd: string, request: HelperRequest, now: string): BudgetState {
   const target = statePath(cwd, request.taskRunId); if (!fs.existsSync(target)) return empty(request, now);
@@ -136,7 +159,7 @@ export class OwnedWorkBudgetController {
       const duplicate = state.reservations.find((item) => item.deduplicationKey === request.deduplicationKey && ["active", "succeeded"].includes(item.status));
       if (duplicate) return { decision: "duplicate", reason: "equivalent-helper-already-owned", reservationId: duplicate.id, recoveredOrphans };
       if (active(state).length >= ceilings.maxConcurrentHelpers || state.reservations.length >= ceilings.maxTotalHelpers) return { decision: "blocked", reason: "helper-budget-exhausted", reservationId: null, recoveredOrphans };
-      if (state.reservations.filter((item) => item.role === request.role).length >= roleLimit(request.role)) return { decision: "blocked", reason: `${request.role}-ceiling-reached`, reservationId: null, recoveredOrphans };
+      if (state.reservations.filter((item) => item.role === request.role).length >= roleLimit(request.role, ceilings)) return { decision: "blocked", reason: `${request.role}-ceiling-reached`, reservationId: null, recoveredOrphans };
       if (request.authority === "single-writer" && active(state).some((item) => item.authority === "single-writer")) return { decision: "blocked", reason: "single-writer-already-owned", reservationId: null, recoveredOrphans };
       const id = digest(`${request.taskRunId}:${request.deduplicationKey}:${state.reservations.length}`).slice(0, 32);
       state.reservations.push({ id, deduplicationKey: request.deduplicationKey, role: request.role, authority: request.authority, status: "active", reservedAt: now, expiresAt: new Date(Date.parse(now) + request.ceilings.timeSeconds * 1000).toISOString(), completedAt: null, usageRef: null });