tascan-mcp 3.16.1 → 3.17.0

package/README.md

@@ -288,6 +288,12 @@ API keys are scoped to your organization and support rate limiting (60 requests/
 
 ## Changelog
 
+### v3.17.0 — 2026-09-28
+- **Fan-out (phase 1b), 101 tools.** Three new tools over the phase 1a REST surface (`/coord/fanouts`, migration 224): `tascan_create_fanout` (1-30 RESEARCH seats plus one synthesizer under ONE cycle root T_F — zero Decision cards, zero Parked cards, zero pages per seat; requires `agent:dispatch:code`; fails closed `fanout_ceiling_unset` until the org owner sets a spending ceiling), `tascan_get_fanout` (`view=status|report|rollup|verify`, read tier), `tascan_control_fanout` (`pause|resume|cancel|close_barrier` — no `amend`, no `answer` in phase 1; requires `agent:dispatch:code`). `dry_run` on create is forwarded to the route as-is; the route has no server-side preflight for this path yet, so it does not yet prevent a real create — see the tool description.
+
+### v3.16.2 — 2026-09-28
+- 98 tools.  Rolls up 3.16.0 to 3.16.2: `tascan_get_usage` (GET /usage, per-key daily actions and rate-limit headers, migration 220); the device control plane read/revoke tools (`tascan_list_devices`, `tascan_get_device`, `tascan_revoke_device`; register and rotate stay admin-app only by design); `tascan_delegate_to_agent` (child keys with a TTL of 60 s to 24 h clamped to the parent, non-delegable flags refused, the plaintext returned once) and the per-key action budgets that fail closed (migration 221).  Hosted MCP at https://app.tascan.io/mcp already serves this version; this release brings the stdio package up to it.
+
 ### v3.15.0 — 2026-09-19
 
 - `tascan_create_cycle` gains an optional `reviews[]` array — a multi-lens review panel (design item 14a): 1–8 lenses, each `{lens, brief, provider: openai|anthropic|gemini, model?, blocking? (default true), max_tool_calls? (openai only)}`, forwarded to `POST /coord/cycles`; at least one lens must be blocking.  Omit it for the single OpenAI review.

package/index.js

@@ -53,7 +53,7 @@ async function api(method, path, body, idemKey) {
 api.key = API_KEY;   // raw-fetch tools read the key from here (S99: those functions now require auth)
 
 const server = new Server(
-  { name: 'tascan', version: '3.16.1' },
+  { name: 'tascan', version: '3.16.2' },
   { capabilities: { tools: {} } }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tascan-mcp",
-  "version": "3.16.1",
+  "version": "3.17.0",
   "mcpName": "io.github.snowbikemike/tascan-mcp",
   "description": "TaScan MCP Server — Closed-loop autonomous operations protocol. 70 tools for projects, tasks, workers, QR codes, NFC tags, worker marketplace with consented SMS invites, geofenced zones with rules (work site / hazard + AI-verified PPE checkpoints / containment / restricted, breach alerts, zone compliance audit), AI condition assessment, worker passports, verification-gated gig payments, client invoicing from verified work (overtime / day rate / per diem / expenses), shareable report links (completion, client service report, project, evidence pack), signed Action Receipts (Ed25519 JWS), cross-entity search, duplicate-worker detection, worker identity merge, AI issue analysis, and autonomous remediation dispatch. 15 patents filed (470+ claims). Task. Scan. Done.",
   "type": "module",
@@ -15,6 +15,7 @@
     "index.js",
     "tools.cjs",
     "tools-devices.cjs",
+    "tools-fanout.cjs",
     "scopes.cjs",
     "README.md",
     "LICENSE"

package/scopes.cjs

@@ -34,7 +34,13 @@ const DISPATCH_CODE = 'agent:dispatch:code';
 // requires full, and unreachable through OAuth (mcp-oauth.js's consent flow passes no device flag, so clamp()
 // below never grants it to a connector token even though clamp is capable of granting it to an owner).
 const DEVICE_ADMIN = 'device:admin';
-const SCOPE_VALUES = ['read', 'write', 'full', DISPATCH, DISPATCH_CODE, DEVICE_ADMIN];
+// B2 (migration 221): delegate — a FOURTH additive permission, never implied by a tier — owner-only, requires
+// full (like device:admin), and unreachable through OAuth (mcp-oauth.js's consent flow passes no delegate flag,
+// so clamp() below never grants it to a connector token even though clamp is capable of granting it to an owner).
+// A key holding it may mint time-limited, narrower child keys (coord_delegate_key) — read/write only, never a
+// wider or lateral grant (I-6).
+const DELEGATE = 'delegate';
+const SCOPE_VALUES = ['read', 'write', 'full', DISPATCH, DISPATCH_CODE, DEVICE_ADMIN, DELEGATE];
 const ALL_SCOPES = SCOPE_VALUES.slice();
 
 // Seed agent inbox (tools.cjs AGENT_REGISTRY, agent-execute, agent.js, migrations 046/137/151).
@@ -74,23 +80,25 @@ function dispatchKind(titles) {
 //     (P0 / migration 216): a legacy row minted before this permission existed must not silently gain it.
 //   null / undefined / [] → read, no dispatch, no device_admin (FAIL CLOSED)
 function normalize(v) {
-  if (v == null) return { tier: 'read', dispatch: false, code: false, device_admin: false, legacy: false };
+  if (v == null) return { tier: 'read', dispatch: false, code: false, device_admin: false, delegate: false, legacy: false };
   const a = Array.isArray(v) ? v.map(String) : String(v).split(/[\s+,]+/).filter(Boolean);
-  if (a.includes('*')) return { tier: 'full', dispatch: true, code: true, device_admin: true, legacy: true };
-  if (a.includes('all')) return { tier: 'full', dispatch: true, code: true, device_admin: false, legacy: true };
+  if (a.includes('*')) return { tier: 'full', dispatch: true, code: true, device_admin: true, delegate: true, legacy: true };
+  if (a.includes('all')) return { tier: 'full', dispatch: true, code: true, device_admin: false, delegate: false, legacy: true };
   let tier = 'read';
   for (const t of TIERS) if (a.includes(t) && RANK[t] > RANK[tier]) tier = t;
   const dispatch = a.includes(DISPATCH);
   // code without dispatch is not a state the consent page or key UI can produce; treat as dispatch too
   const code = a.includes(DISPATCH_CODE);
   const deviceAdmin = a.includes(DEVICE_ADMIN);
-  return { tier, dispatch: dispatch || code, code, device_admin: deviceAdmin, legacy: false };
+  const delegate = a.includes(DELEGATE);
+  return { tier, dispatch: dispatch || code, code, device_admin: deviceAdmin, delegate, legacy: false };
 }
 function toArray(n) {
   const out = TIERS.slice(0, RANK[n.tier] || 1);
   if (n.dispatch || n.code) out.push(DISPATCH);
   if (n.code) out.push(DISPATCH_CODE);
   if (n.device_admin) out.push(DEVICE_ADMIN);
+  if (n.delegate) out.push(DELEGATE);
   return out;
 }
 function toScopeString(n) { return toArray(n).join(' '); }
@@ -133,7 +141,7 @@ function echoScope(str) {
 // P0 (migration 216): device_admin is accepted here for completeness and unit-tested (a non-owner clamp drops
 // it), but the ONLY real caller — mcp-oauth.js's OAuth consent flow — never passes a device flag in `pick` at
 // all, so a connector token can never hold device:admin regardless of the granting admin's role.
-function clamp({ tier, dispatch, code, device_admin }, role) {
+function clamp({ tier, dispatch, code, device_admin, delegate }, role) {
   const t = TIERS.includes(tier) ? tier : 'read';
   const owner = role === 'owner';
   const clamped = [];
@@ -144,7 +152,11 @@ function clamp({ tier, dispatch, code, device_admin }, role) {
   else if (!!code && !gc) clamped.push(DISPATCH_CODE);   // ticked code without dispatch
   let gda = !!device_admin && owner;
   if (!!device_admin && !gda) clamped.push(DEVICE_ADMIN);
-  return { granted: { tier: gt, dispatch: gd, code: gc, device_admin: gda, legacy: false }, clamped };
+  // B2 (migration 221): delegate is owner-only AND requires the final (already-clamped) tier to be full — the
+  // same "only an owner-held, full-tier key may ever mint a delegation" rule 221's own CHECK enforces in storage.
+  let gdel = !!delegate && owner && gt === 'full';
+  if (!!delegate && !gdel) clamped.push(DELEGATE);
+  return { granted: { tier: gt, dispatch: gd, code: gc, device_admin: gda, delegate: gdel, legacy: false }, clamped };
 }
 
 // POST /api/v1/keys body.scopes → canonical array or null (rejects 'all', '*', junk, empty,
@@ -154,6 +166,7 @@ function validateStored(arr) {
   if (!arr.every(s => typeof s === 'string' && SCOPE_VALUES.includes(s))) return null;
   if (arr.includes(DISPATCH_CODE) && !arr.includes(DISPATCH)) return null;
   if (arr.includes(DEVICE_ADMIN) && !arr.includes('full')) return null;
+  if (arr.includes(DELEGATE) && !arr.includes('full')) return null;
   return toArray(normalize(arr));
 }
 
@@ -171,6 +184,7 @@ function check(granted, need) {
   if (need.human_only) return { code: 'human_session_required', required: 'human_session_required', granted_scope: toScopeString(g) };
   if ((RANK[g.tier] || 0) < (RANK[need.tier] || 99)) return deny(need.tier);
   if (need.device_admin && !g.device_admin) return deny(DEVICE_ADMIN);
+  if (need.delegate && !g.delegate) return deny(DELEGATE);
   if (need.dispatch === 'code' && !g.code) return deny(DISPATCH_CODE);
   if (need.dispatch === true && !g.dispatch) return deny(DISPATCH);
   return null;
@@ -205,6 +219,11 @@ const TOOL_SCOPES = {
   tascan_post_message: W,
   // creating a cycle queues a CODE:/SHELL: prompt on the AI Inbox → agent:dispatch:code, always
   tascan_create_cycle: { tier: 'write', dispatch: 'code' },
+  // Fan-out phase 1b (2026-09-28): three tools over coord-fanout-lib.js's REST routes — same shapes as
+  // ROUTE_SCOPES' coord_fanouts / coord_fanout / coord_fanout_control below (:363-365).
+  tascan_create_fanout: { tier: 'write', dispatch: 'code' },
+  tascan_get_fanout: R,
+  tascan_control_fanout: { tier: 'write', dispatch: 'code' },
   // M1 (2026-09-23): ten tools wrapping routes that already existed in api-v1.js / coord-dispatch-lib.js /
   // receipt.js but had no MCP tool.  tascan_verify_receipt: receipt.js's POST /receipts/verify is a PUBLIC
   // route (no scope check at all inside receipt.js) — read is the floor because mcp-endpoint.js still
@@ -250,7 +269,14 @@ const TOOL_SCOPES = {
   tascan_list_devices: R, tascan_get_device: R,
   tascan_revoke_device: { tier: 'full', device_admin: true },
   // B1 (migration 220): GET /usage wrapped as a tool — read tier, same as every other read-only usage/analytics tool.
-  tascan_get_usage: R
+  tascan_get_usage: R,
+  // B2 (migration 221): per-key budgets + delegated child keys. tascan_get_budget is the caller's own row (read
+  // tier, same idiom as tascan_get_usage). tascan_delegate_to_agent mints (NOT destructiveHint — see tools.cjs);
+  // tascan_revoke_delegation is destructive+idempotent. Both need write + delegate (owner-only to grant, I-6).
+  tascan_get_budget: R,
+  tascan_delegate_to_agent: { tier: 'write', delegate: true },
+  tascan_list_delegations: R,
+  tascan_revoke_delegation: { tier: 'write', delegate: true }
 };
 // Tools classified here that do not yet exist in tools.cjs (other workstreams' patches).  Empty since
 // tascan_get_receipt landed in tools.cjs (S100 phase 2b); harnesses assert TOOL_SCOPES ⊇ tools.cjs.
@@ -336,6 +362,12 @@ const ROUTE_SCOPES = {
   // coordination layer (api-v1-helpers.js parsePath handlers task_messages / coord_cycles / coord_cycle_report / build / build_file)
   task_messages:       { GET: R, POST: CYCLE_WRITE },          // trail messages; POST answer on a dispatcher question → coord_answer_question
   coord_cycles:        { GET: R, POST: { tier: 'write', dispatch: 'code' } },   // list roots / coord_create_cycle (T1 = CODE:/SHELL: on the AI Inbox)
+  // Fan-out phase 1a-ii (master item 4): matched in coord-fanout-lib.js's own matchFanoutRoute, not
+  // api-v1-helpers.js's parsePath ROUTES table — same D6/D8 idiom as coord_dispatcher_action/coord_build_diff below.
+  // coordFanoutLib.handleFanoutRoute self-gates with these exact shapes too (belt-and-suspenders).
+  coord_fanouts:       { GET: R, POST: { tier: 'write', dispatch: 'code' } },   // GET /coord/fanouts (list) / POST (create, T_F = CODE:/SHELL:-equivalent dispatch)
+  coord_fanout:        { GET: R },                              // GET /coord/fanouts/:id[?view=status|report|rollup|verify]
+  coord_fanout_control: { POST: { tier: 'write', dispatch: 'code' } },   // POST /coord/fanouts/:id/control (pause|resume|cancel|close_barrier)
   coord_integrate:     { POST: WD },                            // D4 (181): POST /coord/cycles/:root/integrate — the dispatcher records the deploy id (agent:dispatch)
   coord_dispatcher_action: { POST: WD },                        // D6 (194): POST /coord/cycles/:root/dispatcher-actions — a chief-of-staff action becomes a receipt (agent:dispatch); the handler self-gates too
   coord_build_diff:    { POST: WD },                            // D8 item 6 (196): POST /coord/builds/:ref/diff — the dispatcher stores an already-computed diff (agent:dispatch); the handler self-gates too
@@ -352,6 +384,16 @@ const ROUTE_SCOPES = {
   // V9b (204): GET/PUT /evidence/policy/:task_id — read a task's evidence-policy progress / author + pin one.
   evidence_policy:     { GET: R, PUT: W },                              // GET /builds/:build_ref/file?path=&offset=&limit=  ≤ 12,000 chars per call
   keys: 'admin', key: 'admin',
+  // B2 (migration 221): key_budget (PUT/GET /keys/:id/budget) joins the admin-JWT-only idiom (api-v1.js's
+  // DECISION_ASSERTION_ADMIN_HANDLERS-style set) — a tsk_/service bearer is refused 403 human_session_required
+  // before this table is ever consulted (I-3: no key, ever, sets or reads ANOTHER key's budget); the whole entry
+  // is the 'admin' marker, same as keys/key above, since the handler self-gates (owner-only for PUT, any admin
+  // role for GET). budget (GET /budget, no :id) is the CALLING key's own row — an ordinary read-tier key route.
+  // delegations/delegation need write + delegate (owner-only to grant, I-6).
+  key_budget: 'admin',
+  budget:      { GET: R },
+  delegations: { POST: { tier: 'write', delegate: true }, GET: R },
+  delegation:  { DELETE: { tier: 'write', delegate: true } },
   // H1 (migration 215): human decision binding — admin-JWT-only, same gate-skip idiom as keys/key (api-v1.js's
   // DECISION_ASSERTION_ADMIN_HANDLERS uses authenticateAdminSession and refuses a tsk_/service key 403 human_session_required).
   decision_assertion_options: 'admin', decision_assertions: 'admin', decision_assertion: 'admin',
@@ -387,6 +429,7 @@ const SCOPE_LABEL = {
   [DISPATCH]: 'the "agent:dispatch" permission ("Let this app hand tasks to my AI agents")',
   [DISPATCH_CODE]: 'the "agent:dispatch:code" permission ("...including code and shell tasks on my computer")',
   [DEVICE_ADMIN]: 'the "device:admin" permission (register/rotate/revoke devices) — owner-only, requires full, and not reachable through OAuth',
+  [DELEGATE]: 'the "delegate" permission (mint time-limited child API keys) — owner-only, requires full, and not reachable through OAuth',
   unclassified: 'a classification (this tool is not in the scope map)'
 };
 function reconnectHint(required) {
@@ -415,7 +458,7 @@ function restDenialHeaders(d) {
 }
 
 module.exports = {
-  SCOPE_VALUES, ALL_SCOPES, TIERS, RANK, DISPATCH, DISPATCH_CODE, DEVICE_ADMIN, AGENT_INBOX_IDS,
+  SCOPE_VALUES, ALL_SCOPES, TIERS, RANK, DISPATCH, DISPATCH_CODE, DEVICE_ADMIN, DELEGATE, AGENT_INBOX_IDS,
   TASK_TYPES, LOCAL_TASK_TYPES, CLOUD_TASK_TYPES, REVIEWER_TASK_TYPES, LOCAL_ONLY_TASK_TYPES, CODE_TASK_TYPES, taskType, dispatchScopeFor, dispatchKind,
   normalize, toArray, toScopeString, parseRequested, echoScope, SCOPE_PARAM_MAX, clamp, validateStored, check,
   TOOL_SCOPES, PENDING_TOOLS, ROUTE_SCOPES, requiredForTool, requiredForRoute,

package/tools-fanout.cjs

@@ -0,0 +1,175 @@
+// Fan-out phase 1b (2026-09-28, briefs/2026-09-28-fanout-phase1b-mcp-tools.md; master
+// briefs/2026-09-27-fanout-phase1.md, r3): three MCP tools over the 1a-ii REST surface
+// (coord-fanout-lib.js's matchFanoutRoute / handleFanoutRoute, wired into api-v1.js) -- never Supabase
+// directly, same split-file pattern as tools-devices.cjs (spread into TOOLS by one line there).
+//
+// tascan_create_fanout: POST /coord/fanouts.  Every preflight problem the route can see (fanout_ceiling_unset,
+// over_ceiling, cap_below_plan, idempotency_body_mismatch, fanout_open_limit, seats_invalid, reserve_floor_unset,
+// no_authority, key_required) reaches the caller VERBATIM: api() (tascan-mcp/index.js / mcp-endpoint.js) throws
+// Error(data.error) on a non-2xx response and the transport prints "Error: <message>" unchanged -- this file adds
+// no try/catch around that path on purpose.  dry_run is forwarded to the route as-is (literal passthrough, the
+// brief's own word); the route built in 1a-ii has NO server-side preflight mode for this path (unlike
+// tascan_create_cycle's dry_run, which /coord/cycles DOES implement) -- a create call with dry_run true still
+// creates a REAL fan-out today.  Documented here, in the tool description and at runtime, rather than silently
+// guessed: fixing that gap means touching coord-fanout-lib.js, which is out of this brief's six deliverables.
+//
+// tascan_get_fanout: GET /coord/fanouts/:id?view=.  tascan_control_fanout: POST /coord/fanouts/:id/control, action
+// enum WITHOUT amend and WITHOUT answer (master: no such actions in phase 1) -- exactly coord-fanout-lib.js's own
+// CONTROL_ACTIONS.
+'use strict';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const VIEWS = ['status', 'report', 'rollup', 'verify'];
+const CONTROL_ACTIONS = ['pause', 'resume', 'cancel', 'close_barrier'];
+
+module.exports = [
+  {
+    name: 'tascan_create_fanout',
+    description: 'Create a fan-out: 1-30 RESEARCH seats plus one synthesizer under ONE cycle root T_F (POST /coord/fanouts). Zero Decision cards, zero Parked cards, zero pages per seat -- only a control action or the closing roll-up reaches a human. Requires an API key with agent:dispatch:code -- an admin session has no dispatch budget (key_required). Consumes seats.length + 1 dispatch units BEFORE the authoritative create; a refusal only the RPC can see (cap_below_plan, fanout_open_limit, bad agent_id, reserve_floor_unset) still consumes them, by design. Fails closed fanout_ceiling_unset until the owner sets a ceiling; over_ceiling when cap exceeds it. idempotency_key replays duplicate within 24h on the same plan, else idempotency_body_mismatch. dry_run is forwarded as-is; the route has no preflight mode yet, so dry_run true still creates for real -- never a way to avoid creating. Leaves fanout_created; every seat, the synth and the roll-up leave their own signed completion. Track with tascan_get_fanout.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'Working project (UUID). The fan-out root T_F is minted on its Questions list (coord_ensure_lists).' },
+        title: { type: 'string', description: 'Short human title (1-200 chars). T_F becomes "FANOUT: <title>"; seats become "RESEARCH: [seat-NN] <title>"; the synth becomes "RESEARCH: [synth] <title>".' },
+        seats: {
+          type: 'array',
+          description: '1-30 seats. Each names the agent that runs it; brief/role fall back to seat_defaults when omitted.',
+          items: {
+            type: 'object',
+            properties: {
+              agent_id: { type: 'string', description: 'A registered agent_registry id in this org, matching ^[a-z][a-z0-9-]{0,39}$. Never a system-* worker.' },
+              brief: { type: 'string', description: 'This seat\'s own prompt (1-40000 chars). Falls back to seat_defaults.brief when omitted -- one of the two is required.' },
+              role: { type: 'string', description: 'Optional label for this seat (1-100 chars), e.g. "topic A".' }
+            },
+            required: ['agent_id']
+          }
+        },
+        seat_defaults: {
+          type: 'object',
+          description: 'Shared defaults applied when a seat names no brief of its own.',
+          properties: {
+            brief: { type: 'string', description: 'Default seat prompt (1-40000 chars), used by any seat that names no brief of its own.' },
+            est_micro_usd: { type: 'integer', description: 'Positive integer micro-USD estimate per seat, used by the RPC\'s cap_below_plan check.' },
+            review_est_micro_usd: { type: 'integer', description: 'Non-negative integer micro-USD estimate per seat review. Must be > 0 when seat_review is per_seat.' }
+          },
+          required: ['est_micro_usd']
+        },
+        synth: {
+          type: 'object',
+          description: 'The synthesizer that runs once the barrier closes, reading every done seat\'s stored output as DATA.',
+          properties: {
+            brief: { type: 'string', description: 'The synthesizer\'s prompt (1-40000 chars).' },
+            max_cost_micro_usd: { type: 'integer', description: 'Positive integer micro-USD reserved for the synth run; reserved out of cap up front, released back into the seat budget only at barrier close.' }
+          },
+          required: ['brief', 'max_cost_micro_usd']
+        },
+        canary: { type: 'integer', description: 'How many seats release immediately; the rest stay held on T_F until the first canary settles done. Default min(2, seats.length).' },
+        min_ok: { type: 'integer', description: 'Minimum seats that must finish done before the synth barrier can close. Default ceil(seats.length / 2).' },
+        breaker_k: { type: 'integer', description: 'Paid (non-infrastructure) seat failures before the breaker pauses the fan-out (2-5, default 2). An expired run never counts.' },
+        deadline_min: { type: 'integer', description: 'Minutes before an idle seat is dropped and the barrier re-evaluated, and before a stuck synthesizing fan-out closes deadline (10-1440, default 240).' },
+        seat_review: { type: 'string', enum: ['per_seat', 'none'], description: 'per_seat mints one review per seat (allowed for at most 10 seats); none skips seat review. Default per_seat for <=10 seats, none above that.' },
+        cap: { type: 'integer', description: 'This fan-out\'s total micro-USD budget, synth reserve included. Refused over_ceiling if it exceeds the org\'s fan-out spending ceiling.' },
+        idempotency_key: { type: 'string', description: 'Optional replay key (<= 200 chars). The same key within 24h on the same plan returns duplicate:true with the existing fanout_id; on a different plan it is refused idempotency_body_mismatch.' },
+        dry_run: { type: 'boolean', description: 'Forwarded to POST /coord/fanouts as given. The route has no server-side preflight for this path today, so true still performs a REAL create -- do not rely on it to avoid creating a fan-out.' }
+      },
+      required: ['project_id', 'title', 'seats', 'synth', 'cap']
+    },
+    annotations: { title: 'Create Fan-out', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, api) => {
+      const projectId = String(args.project_id || '').trim();
+      if (!UUID_RE.test(projectId)) throw new Error('project_id must be a UUID');
+      if (!args.title || typeof args.title !== 'string') throw new Error('title is required');
+      if (!Array.isArray(args.seats) || !args.seats.length) throw new Error('seats is required (1-30 entries)');
+      if (!Number.isInteger(args.cap) || args.cap <= 0) throw new Error('cap is required (a positive integer, this fan-out\'s total micro-USD budget)');
+      if (!args.synth || typeof args.synth !== 'object') throw new Error('synth is required ({brief, max_cost_micro_usd})');
+
+      const body = {
+        project_id: projectId,
+        title: args.title,
+        seats: args.seats.map(s => ({
+          agent_id: s && s.agent_id,
+          ...(s && s.brief != null ? { brief: s.brief } : {}),
+          ...(s && s.role != null ? { role: s.role } : {})
+        })),
+        synth: { brief: args.synth.brief, max_cost_micro_usd: args.synth.max_cost_micro_usd },
+        cap: args.cap
+      };
+      if (args.seat_defaults) body.seat_defaults = args.seat_defaults;
+      for (const k of ['canary', 'min_ok', 'breaker_k', 'deadline_min', 'seat_review', 'idempotency_key']) {
+        if (args[k] != null) body[k] = args[k];
+      }
+      const dryRun = args.dry_run === true || args.dry_run === 'true';
+      if (args.dry_run != null) body.dry_run = dryRun;
+
+      const result = await api('POST', '/coord/fanouts', body, args.idempotency_key);
+      const d = result.data || {};
+      if (d.duplicate) {
+        return `DUPLICATE — nothing was created.  A fan-out with the same idempotency_key and plan exists from the last 24h.\nfanout_id: ${d.fanout_id}\n\nRead it: tascan_get_fanout fanout_id=${d.fanout_id}`;
+      }
+      const seatLines = Array.isArray(d.seats)
+        ? d.seats.map(s => `  seat-${String(s.seat_no).padStart(2, '0')}: ${s.seat_id} (${s.released ? 'released' : 'held on T_F'}, ${s.status})`).join('\n')
+        : '  (none returned)';
+      let text = `Fan-out created.\nfanout_id (T_F): ${d.fanout_id}\nplan_sha256: ${d.plan_sha256}\nstatus: ${d.status}\nsynth_task_id: ${d.synth_task_id}\npoll_after_s: ${d.poll_after_s}\nseats:\n${seatLines}\n\nFollow with tascan_get_fanout fanout_id=${d.fanout_id} (view=status).`;
+      if (dryRun) {
+        text = 'NOTE: dry_run has no server-side preflight on this route yet — the fan-out below was created for REAL, not simulated.\n\n' + text;
+      }
+      return text;
+    }
+  },
+  {
+    name: 'tascan_get_fanout',
+    description: 'Read a fan-out (GET /coord/fanouts/:id?view=). view=status (default): state, seat counts, spend, cap, synth_deadline_at, poll_after_s. view=report: the full cycle report (get_cycle_report) — every seat, review and control step. view=rollup: the exact roll-up response_value plus its leaves (path, sha256, completion_id) once closed. view=verify: the server recomputes rollup_ref over the frozen leaves and returns ok / mismatches — the same check scripts/verify-fanout.js performs independently from another machine, which is the trusted proof; this view is a convenience, not a substitute. A foreign org\'s fanout_id answers 404, never 403, so another org\'s fan-out never even appears to exist. Read tier, no dispatch permission required.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fanout_id: { type: 'string', description: 'Fan-out id (UUID) — the T_F root, from tascan_create_fanout or tascan_list_cycles.' },
+        view: { type: 'string', enum: VIEWS, description: 'status (default), report, rollup or verify.' }
+      },
+      required: ['fanout_id']
+    },
+    annotations: { title: 'Get Fan-out', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const id = String(args.fanout_id || '').trim();
+      if (!UUID_RE.test(id)) throw new Error('fanout_id must be a UUID');
+      const view = args.view != null && args.view !== '' ? String(args.view) : 'status';
+      if (!VIEWS.includes(view)) throw new Error(`view must be one of: ${VIEWS.join(', ')}`);
+      const result = await api('GET', `/coord/fanouts/${id}?view=${view}`);
+      const out = `Fan-out ${id} (view=${view}):\n\n${JSON.stringify(result.data, null, 2)}`;
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_control_fanout',
+    description: 'Control a running fan-out (POST /coord/fanouts/:id/control). pause holds every unclaimed seat and stops the orphan pass from re-firing them; resume releases them again; cancel supersedes every unclaimed task and closes once quiescent; close_barrier drops unsettled or named exclude_seats and forces the synth barrier now instead of waiting for more seats. No amend and no answer in phase 1. Every action mints a signed control-child completion FIRST, as the org\'s own system worker (coord_fanout_control_receipt) — never coord_dispatcher_action, so a control action can never sign into another org\'s Chief of Staff identity. idempotency_key replays the prior outcome (replayed:true) and applies nothing twice; a replayed resume after a later pause leaves the fan-out paused. Refused fanout_closed once the roll-up has closed. Requires agent:dispatch:code.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fanout_id: { type: 'string', description: 'Fan-out id (UUID) — the T_F root.' },
+        action: { type: 'string', enum: CONTROL_ACTIONS, description: 'pause, resume, cancel or close_barrier. No amend, no answer (phase 1).' },
+        reason: { type: 'string', description: 'Optional free-text reason (<= 4000 chars), recorded on the control child\'s completion.' },
+        exclude_seats: { type: 'array', items: { type: 'integer' }, description: 'close_barrier only: 1-based seat numbers to drop from the barrier instead of waiting for them to settle.' },
+        idempotency_key: { type: 'string', description: 'Optional replay key (<= 200 chars). The same key returns the prior outcome (replayed:true) and applies nothing a second time.' }
+      },
+      required: ['fanout_id', 'action']
+    },
+    annotations: { title: 'Control Fan-out', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const id = String(args.fanout_id || '').trim();
+      if (!UUID_RE.test(id)) throw new Error('fanout_id must be a UUID');
+      const action = String(args.action || '');
+      if (!CONTROL_ACTIONS.includes(action)) throw new Error(`action must be one of: ${CONTROL_ACTIONS.join(', ')}`);
+      const body = { action };
+      if (args.reason != null) body.reason = args.reason;
+      if (args.exclude_seats != null) {
+        if (!Array.isArray(args.exclude_seats) || !args.exclude_seats.every(n => Number.isInteger(n) && n > 0)) {
+          throw new Error('exclude_seats must be an array of positive integers');
+        }
+        body.exclude_seats = args.exclude_seats;
+      }
+      if (args.idempotency_key != null) body.idempotency_key = args.idempotency_key;
+      const result = await api('POST', `/coord/fanouts/${id}/control`, body, args.idempotency_key);
+      const d = result.data || {};
+      return `${d.replayed ? 'REPLAYED (idempotent — nothing applied twice)' : 'Applied'}: ${action} on fan-out ${id}.\nfanout_status: ${d.fanout_status}\nreceipt_completion_id: ${d.receipt_completion_id}\n\n${JSON.stringify(d, null, 2)}`;
+    }
+  }
+];

package/tools.cjs

@@ -2750,8 +2750,83 @@ const TOOLS = [
       return lines.join('\n');
     }
   },
+  // B2 (migration 221): per-key action budgets (#10, I-3) + delegated, time-limited child keys (#11, I-6, I-10).
+  {
+    name: 'tascan_get_budget',
+    description: 'Read THIS credential\'s own per-key action budget (GET /budget): daily limits (sms, invites, payment-request cents per day and per request, dispatch, human pages) and today\'s spend against them. A NULL limit (or no budget row at all) means unlimited on that counter. A key can only ever see its OWN budget, never another key\'s (I-3, no tool or key ever reads another key\'s row). Read tier.',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { title: 'Get Budget', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const result = await api('GET', '/budget');
+      const d = result.data || {};
+      const b = d.budget || {}, u = d.usage || {};
+      const rows = [
+        ['sms_per_day', 'sms_count', 'sms/day'], ['invites_per_day', 'invites_count', 'invites/day'],
+        ['payment_request_cents_per_day', 'payment_request_cents_count', 'payment request cents/day'],
+        ['payment_request_cents_max', null, 'payment request cents/request (max)'],
+        ['dispatch_per_day', 'dispatch_count', 'dispatch/day'], ['human_pages_per_day', 'human_pages_count', 'human pages/day']
+      ];
+      const lines = ["this key's budget (null = unlimited):"];
+      for (const [limitKey, usageKey, label] of rows) {
+        const limit = b[limitKey] != null ? b[limitKey] : 'unlimited';
+        const used = usageKey ? (u[usageKey] != null ? u[usageKey] : 0) : null;
+        lines.push(`  ${label}: ${used != null ? used + ' / ' : ''}${limit}`);
+      }
+      return lines.join('\n') + '\n\n' + JSON.stringify(d, null, 2);
+    }
+  },
+  {
+    name: 'tascan_delegate_to_agent',
+    description: 'Mint a time-limited, NARROWER child API key (POST /delegations, roadmap #11) — only read/write scopes may be requested; full, agent:dispatch, agent:dispatch:code, device:admin, delegate and webhooks:manage are always refused by name (I-6). TTL defaults to 1 hour (3600s), clamps to [60 seconds, 24 hours], and clamps further to THIS key\'s own expiry if it has one — a delegated key can never outlive its grantor. The child\'s tier is always a SUBSET of this key\'s own effective tier, never wider or lateral. Requires the delegate permission (owner-only to grant, requires full). The returned raw key is shown to you exactly ONCE — it is never stored server-side and cannot be retrieved again (I-10). Revoking this key (or any ancestor) cascades immediately to every key it delegated.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scopes: { type: 'array', items: { type: 'string', enum: ['read', 'write'] }, description: 'Scopes to request for the child key — read and/or write only.' },
+        ttl_seconds: { type: 'number', description: 'How long the child key lives, in seconds (default 3600 = 1h; clamped to [60, 86400] and to this key\'s own expiry).' },
+        resource_constraints: { type: 'object', description: 'Optional free-form narrowing (e.g. project/list ids) recorded on the child key as metadata.' }
+      },
+      required: ['scopes']
+    },
+    annotations: { title: 'Delegate To Agent', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    handler: async (args, api) => {
+      if (!Array.isArray(args.scopes) || !args.scopes.length) throw new Error('scopes is required (array of "read"/"write")');
+      const result = await api('POST', '/delegations', { scopes: args.scopes, ttl_seconds: args.ttl_seconds, resource_constraints: args.resource_constraints });
+      const d = result.data || {};
+      return `Delegated key ${d.key_id} minted, scopes [${(d.scopes || []).join(', ')}], expires ${d.expires_at}.\nSAVE THIS KEY NOW — it will not be shown again:\n${d.key}`;
+    }
+  },
+  {
+    name: 'tascan_list_delegations',
+    description: 'List delegated child keys (GET /delegations): this key\'s own direct children (id, label, scopes, active/revoked, depth, expires_at) — never the raw credential. An admin session sees every delegated key in the org. Read tier.',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { title: 'List Delegations', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const result = await api('GET', '/delegations');
+      const data = result.data || [];
+      const out = `${data.length} delegated key(s)\n\n${JSON.stringify(data, null, 2)}`;
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_revoke_delegation',
+    description: 'Revoke a delegated child key immediately (DELETE /delegations/:key_id) — self-revoke, revoke by an ancestor key, or by an admin session of the org; any other caller is refused. Revoking cascades to every key IT delegated, in turn (the database trigger, not application code). Idempotent: revoking an already-revoked key reports already_revoked, no error.',
+    inputSchema: {
+      type: 'object',
+      properties: { key_id: { type: 'string', description: 'The delegated key id to revoke (from tascan_list_delegations)' } },
+      required: ['key_id']
+    },
+    annotations: { title: 'Revoke Delegation', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      if (!args.key_id) throw new Error('key_id is required');
+      const result = await api('DELETE', `/delegations/${args.key_id}`);
+      const d = result.data || {};
+      return d.already_revoked ? `Key ${args.key_id} was already revoked.` : `Key ${args.key_id} revoked.`;
+    }
+  },
   // P0 (migration 216): device control plane — split out (194 KB already close to the ~200 KB bundle cap).
-  ...require('./tools-devices.cjs')
+  ...require('./tools-devices.cjs'),
+  // Fan-out phase 1b (2026-09-28): three tools over the 1a-ii REST surface — split out, same reason.
+  ...require('./tools-fanout.cjs')
 ];
 
 module.exports = { TOOLS, AGENT_REGISTRY, dynamicAgents };