tascan-mcp 3.15.0 → 3.16.1

package/README.md

@@ -83,7 +83,7 @@ https://app.tascan.io/mcp
 
 Add as a custom connector in Claude (Settings > Connectors). When you first use a tool, you'll be redirected to sign in with your TaScan email and password — just like connecting GitHub or Netlify. OAuth 2.0 with PKCE handles everything automatically.
 
-## Tools (36)
+## Tools (90)
 
 ### Projects
 | Tool | Description | Type |
@@ -158,6 +158,26 @@ Add as a custom connector in Claude (Settings > Connectors). When you first use
 | `tascan_register_agent` | Register a new AI agent with capabilities | Create |
 | `tascan_dispatch_to_agent` | Route a task to a specific AI agent for execution | Create |
 
+### Protocol Layer — Coordination, Receipts, Evidence, Verification, Analytics
+
+This table lists only the 10 tools M1 (2026-09-23) added; the coordination-cycle tools from earlier milestones
+(`tascan_create_cycle`, `tascan_post_message`, `tascan_record_integration`, `tascan_get_build`,
+`tascan_get_build_file`, `tascan_get_cycle_report`, `tascan_project_digest`, `tascan_get_receipt`) are documented
+inline in their tool descriptions (`tascan_list_tools` / your MCP client's tool browser shows all 90).
+
+| Tool | Description | Type |
+|------|-------------|------|
+| `tascan_list_cycles` | List coordination-cycle roots (id, title, status, build_ref, deploy_id), filterable by project/status | Read |
+| `tascan_get_task_trail` | Read a task's trail messages (question/answer/handoff/note), newest last | Read |
+| `tascan_verify_receipt` | Independently verify an Action Receipt JWS against the reference verifier (works for a foreign issuer too) | None |
+| `tascan_get_build_diff` | Store an already-computed diff for one build-bundle file against a base commit | Write + Dispatch |
+| `tascan_dispatcher_action` | Record a chief-of-staff dispatcher action (approve/revise/park/deploy/decision/...) as a receipt | Write + Dispatch |
+| `tascan_post_evidence` | Post one evidence event (actor did action to object at a time) into the evidence ledger | Write |
+| `tascan_evidence_policy` | Read (action=get) or author/pin (action=set) a task's evidence policy | Read/Write |
+| `tascan_request_verification` | Enqueue an autonomous verification job (http_probe or doc_check) for a completion | Write |
+| `tascan_list_verifications` | Read a completion's verification verdicts and job queue | Read |
+| `tascan_org_analytics` | Read org-wide analytics: the org rollup or paginated AI issue-resolution history | Read |
+
 ## Usage Examples
 
 ### Example 1: Set up a construction site inspection

package/index.js

@@ -15,6 +15,7 @@ import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
 const { TOOLS } = require('./tools.cjs');
+const crypto = require('crypto');   // B1 (migration 220): crypto.randomUUID() is a Node built-in, no new dependency
 
 const API_BASE = process.env.TASCAN_API_URL || 'https://app.tascan.io/api/v1';
 const API_KEY = process.env.TASCAN_API_KEY || '';
@@ -24,8 +25,11 @@ if (!API_KEY) {
   process.exit(1);
 }
 
-// Transport-bound REST call handed to every tool handler
-async function api(method, path, body) {
+// Transport-bound REST call handed to every tool handler.  B1 (migration 220): every POST/PUT sends an
+// Idempotency-Key — a fresh crypto.randomUUID() per call by default, or idemKey verbatim when a tool (e.g.
+// tascan_send_sms, tascan_request_payment, tascan_add_tasks) passes one through so a RETRIED call reuses the
+// same key instead of minting a new reservation (and re-running the handler) every time.
+async function api(method, path, body, idemKey) {
   const opts = {
     method,
     headers: {
@@ -36,6 +40,9 @@ async function api(method, path, body) {
   if (body && (method === 'POST' || method === 'PUT')) {
     opts.body = JSON.stringify(body);
   }
+  if (method === 'POST' || method === 'PUT') {
+    opts.headers['Idempotency-Key'] = idemKey || crypto.randomUUID();
+  }
   const resp = await fetch(API_BASE + path, opts);
   const data = await resp.json();
   if (!resp.ok) {
@@ -46,7 +53,7 @@ async function api(method, path, body) {
 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.15.0' },
+  { name: 'tascan', version: '3.16.1' },
   { capabilities: { tools: {} } }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tascan-mcp",
-  "version": "3.15.0",
+  "version": "3.16.1",
   "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",
@@ -14,6 +14,7 @@
   "files": [
     "index.js",
     "tools.cjs",
+    "tools-devices.cjs",
     "scopes.cjs",
     "README.md",
     "LICENSE"

package/scopes.cjs

@@ -30,7 +30,11 @@ const TIERS = ['read', 'write', 'full'];
 const RANK = { read: 1, write: 2, full: 3 };
 const DISPATCH = 'agent:dispatch';
 const DISPATCH_CODE = 'agent:dispatch:code';
-const SCOPE_VALUES = ['read', 'write', 'full', DISPATCH, DISPATCH_CODE];
+// P0 (migration 216): device control plane. A THIRD additive permission, never implied by a tier — owner-only,
+// 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];
 const ALL_SCOPES = SCOPE_VALUES.slice();
 
 // Seed agent inbox (tools.cjs AGENT_REGISTRY, agent-execute, agent.js, migrations 046/137/151).
@@ -40,11 +44,11 @@ const AGENT_INBOX_IDS = ['f745d0fa-421a-42e5-85be-0a3f9acd28e8'];
 // ─── Task-type routing (mirrors SQL agent_task_type(title), migration 151) ─────
 // Prefix-only: the title must START with TYPE: (after any leading non-letters such
 // as an urgency marker).  No keyword heuristics anywhere.
-const TASK_TYPES = ['CODE', 'SHELL', 'MCP', 'PLAN', 'WRITE', 'RESEARCH', 'REVIEW'];
-const LOCAL_TASK_TYPES = ['CODE', 'SHELL', 'PLAN', 'DEFAULT', 'MCP'];
+const TASK_TYPES = ['CODE', 'SHELL', 'MCP', 'PLAN', 'CAPTURE', 'WRITE', 'RESEARCH', 'REVIEW'];   // CAPTURE (T1 2026-09-24): a review_only cycle's build step — local executor, no model
+const LOCAL_TASK_TYPES = ['CODE', 'SHELL', 'PLAN', 'DEFAULT', 'MCP', 'CAPTURE'];
 const CLOUD_TASK_TYPES = ['RESEARCH', 'WRITE', 'DEFAULT'];
 const REVIEWER_TASK_TYPES = ['REVIEW'];          // agent-review-background.js (155): OpenAI reviewer runner, read-tier key
-const LOCAL_ONLY_TASK_TYPES = ['CODE', 'SHELL', 'PLAN', 'MCP'];   // the cloud runner refuses these; DEFAULT goes either way
+const LOCAL_ONLY_TASK_TYPES = ['CODE', 'SHELL', 'PLAN', 'MCP', 'CAPTURE'];   // the cloud runner refuses these; DEFAULT goes either way.  CAPTURE (T1): agent_route_for('CAPTURE') = 'local' (migration 214)
 const CODE_TASK_TYPES = ['CODE', 'SHELL'];
 const TASK_PREFIX_RE = new RegExp('^(' + TASK_TYPES.join('|') + '):');
 
@@ -64,24 +68,29 @@ function dispatchKind(titles) {
 }
 
 // ─── Normalization ────────────────────────────────────────────
-// api_keys.scopes (array) | oauth_grants.scope (string) | null → { tier, dispatch, code, legacy }
-//   'all' or '*' anywhere → full + dispatch + code (service key sentinel / pre-150 row)
-//   null / undefined / [] → read, no dispatch (FAIL CLOSED)
+// api_keys.scopes (array) | oauth_grants.scope (string) | null → { tier, dispatch, code, device_admin, legacy }
+//   '*' (the service-key sentinel) → full + dispatch + code + device_admin
+//   'all' (the pre-150 legacy row) → full + dispatch + code, but NEVER device_admin — split from '*' on purpose
+//     (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, legacy: false };
+  if (v == null) return { tier: 'read', dispatch: false, code: false, device_admin: false, legacy: false };
   const a = Array.isArray(v) ? v.map(String) : String(v).split(/[\s+,]+/).filter(Boolean);
-  if (a.includes('all') || a.includes('*')) return { tier: 'full', dispatch: true, code: true, legacy: true };
+  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 };
   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);
-  return { tier, dispatch: dispatch || code, code, legacy: false };
+  const deviceAdmin = a.includes(DEVICE_ADMIN);
+  return { tier, dispatch: dispatch || code, code, device_admin: deviceAdmin, 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);
   return out;
 }
 function toScopeString(n) { return toArray(n).join(' '); }
@@ -119,9 +128,12 @@ function echoScope(str) {
 }
 
 // Consent form → granted.  Missing/invalid tier → read (fail closed).  code requires dispatch.
-// role: admin_users.role — only 'owner' may grant full or either dispatch permission.
-// Returns { granted, clamped: [ 'full' | 'agent:dispatch' | 'agent:dispatch:code' ... ] }.
-function clamp({ tier, dispatch, code }, role) {
+// role: admin_users.role — only 'owner' may grant full, either dispatch permission, or device:admin.
+// Returns { granted, clamped: [ 'full' | 'agent:dispatch' | 'agent:dispatch:code' | 'device:admin' ... ] }.
+// 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) {
   const t = TIERS.includes(tier) ? tier : 'read';
   const owner = role === 'owner';
   const clamped = [];
@@ -130,27 +142,35 @@ function clamp({ tier, dispatch, code }, role) {
   let gd = !!dispatch, gc = !!code && gd;
   if (gd && !owner) { gd = false; gc = false; clamped.push(DISPATCH); }
   else if (!!code && !gc) clamped.push(DISPATCH_CODE);   // ticked code without dispatch
-  return { granted: { tier: gt, dispatch: gd, code: gc, legacy: false }, clamped };
+  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 };
 }
 
 // POST /api/v1/keys body.scopes → canonical array or null (rejects 'all', '*', junk, empty,
-// and code-without-dispatch).
+// code-without-dispatch, and device:admin-without-full).
 function validateStored(arr) {
   if (!Array.isArray(arr) || !arr.length || arr.length > SCOPE_VALUES.length) return null;
   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;
   return toArray(normalize(arr));
 }
 
-// granted (normalized) vs need ({ tier, dispatch?: true | 'code' | 'if_inbox' }) → null when allowed,
-// else { code: 'insufficient_scope', required, granted_scope }.
-//   need === null  → unclassified → deny (fail closed)
-//   dispatch 'if_inbox' is not decidable without the DB: MCP lets REST decide; REST resolves it first.
+// granted (normalized) vs need ({ tier, dispatch?: true | 'code' | 'if_inbox' | 'if_cycle', device_admin?: true,
+// human_only?: true }) → null when allowed, else a denial object.
+//   need === null       → unclassified → deny (fail closed)
+//   need.human_only     → denied for EVERY grant (a { code: 'human_session_required' } denial, checked FIRST:
+//                          no tier or permission, including the service-key sentinel, ever satisfies it — P0
+//                          register/rotate are admin-session-only, never a key, per invariant I-3).
+//   dispatch 'if_inbox' / 'if_cycle' is not decidable without the DB: MCP lets REST decide; REST resolves it first.
 function check(granted, need) {
   const g = granted || normalize(null);
   const deny = required => ({ code: 'insufficient_scope', required, granted_scope: toScopeString(g) });
   if (!need) return deny('unclassified');
+  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.dispatch === 'code' && !g.code) return deny(DISPATCH_CODE);
   if (need.dispatch === true && !g.dispatch) return deny(DISPATCH);
   return null;
@@ -185,6 +205,23 @@ 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' },
+  // 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
+  // requires SOME connected key for every tools/call.  tascan_get_build_diff wraps the REAL route (POST
+  // /coord/builds/:ref/diff, coord-dispatch-lib matchBuildDiffRoute/handleBuildDiffRoute, which self-gates
+  // write+dispatch) — the brief's table said GET, but the parser has no GET for this path; see the M1
+  // changes doc.  tascan_dispatcher_action mirrors handleDispatcherActionRoute's own self-gate (write+dispatch).
+  tascan_list_cycles: R, tascan_get_task_trail: R, tascan_verify_receipt: R,
+  tascan_evidence_policy: a => (a && a.action === 'set' ? { ...W } : { ...R }),
+  tascan_list_verifications: R, tascan_org_analytics: R,
+  tascan_post_evidence: W, tascan_request_verification: W,
+  tascan_get_build_diff: WD, tascan_dispatcher_action: WD,
+  // fix (found while wiring M1's coverage check): tascan_record_integration (D4, migration 181) was never
+  // added to this map — an unclassified tool is DENIED (scopes.check fails closed on need === null), so it
+  // was unreachable via MCP despite its route (coord_integrate, below) being classified.  Matches
+  // handleCoordIntegrate's own gate (write + agent:dispatch).
+  tascan_record_integration: WD,
   // write (27)
   tascan_create_project: W, tascan_update_project: W, tascan_delete_project: W, tascan_create_event: W,
   tascan_update_event: W, tascan_delete_event: W, tascan_update_task: W, tascan_reply_with_list: W,
@@ -206,7 +243,14 @@ const TOOL_SCOPES = {
   tascan_invite_worker: F, tascan_assess_condition: F, tascan_request_payment: F,
   // argument-dependent (2)
   tascan_analyze_issue: a => (a.server_side_ai ? { ...F } : { ...R }),
-  tascan_generate_report: a => (a.send_to_phone ? { ...F } : { ...W })
+  tascan_generate_report: a => (a.send_to_phone ? { ...F } : { ...W }),
+  // P0 (migration 216): device control plane. Register and rotate have NO MCP tool at all (C.2, P-15) — each
+  // mints a dev_live_ credential that would land in a model transcript, and each needs a passkey no MCP client
+  // can present. tascan_revoke_device is the kill switch: full + device:admin, no dispatch.
+  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
 };
 // 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.
@@ -225,6 +269,10 @@ const INBOX_WRITE = () => ({ tier: 'write', dispatch: 'if_inbox' });
 // agent:dispatch (agent:dispatch:code when the task — or the asker a question task stands for — is CODE:/SHELL:).
 // Resolved server-side by api-v1.js exactly like if_inbox; an ordinary task stays write tier.  Design §4.4, invariant 18.
 const CYCLE_WRITE = () => ({ tier: 'write', dispatch: 'if_cycle' });
+// P0 (migration 216): register and rotate are admin-session-only — no key, ever, not even full + device:admin
+// (I-3). human_only makes check() deny unconditionally; api-v1.js's main handler answers that denial with
+// 403 human_session_required instead of the ordinary insufficient_scope body.
+const HUMAN = { tier: 'full', device_admin: true, human_only: true };
 const ROUTE_SCOPES = {
   projects:            { GET: R, POST: W },
   project:             { GET: R, PUT: W, DELETE: W },
@@ -278,16 +326,45 @@ const ROUTE_SCOPES = {
   analytics_platform:  { GET: R },
   analytics_org:       { GET: R },
   analytics_resolutions: { GET: R },
+  // B1 (migration 220): GET /usage — a tsk_/service key reads its own org's aggregate usage at read tier; an
+  // admin session of any role reaches the same handler with this gate skipped (api-v1.js's USAGE_HANDLERS, the
+  // same dual-auth idiom as devices/device below) and handleUsage itself refuses `by_key` to a non-owner.
+  usage:               { GET: R },
   tags:                { GET: R, POST: W },
   tag:                 { GET: R, PUT: W, DELETE: W },
   tag_scans:           { GET: R },
   // 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)
+  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
+  // Verification Layer V2 (180): jobs + verdicts on a completion
+  completion_verification_jobs: { POST: W },                    // POST /completions/:id/verification-jobs — enqueue an http_probe (write tier)
+  completion_verifications:     { GET: R },                     // GET  /completions/:id/verifications — V1 rows + jobs (read tier)
   coord_cycle_report:  { GET: R },                              // get_cycle_report (+ summary); an admin Supabase JWT also reaches it (Reports Hub) — api-v1 skips the key lane for that case
   build:               { GET: R },                              // GET /builds/:build_ref  — bundle manifest (build_artifacts)
-  build_file:          { GET: R },                              // GET /builds/:build_ref/file?path=&offset=&limit=  ≤ 12,000 chars per call
+  build_file:          { GET: R },
+  // V9a (203): POST /evidence — a device credential is resolved in api-v1.js's own authenticateEvidenceCredential;
+  // an ordinary worker/agent key needs write.  Production refused every API-key post 403 unclassified from the v229
+  // deploy until 2026-09-22 21:40Z (the V9b harness caught it: 21 of 29 checks 403).  Same lesson as D6 above.
+  evidence:            { POST: W },
+  // 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',
+  // 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',
+  admin_passkeys: 'admin', admin_passkey_options: 'admin', admin_passkey_revoke: 'admin',
+  // P0 (migration 216): device control plane. GET is read tier for both a session and a key. Register (POST
+  // /devices) and rotate need HUMAN (no key, ever). Revoke needs full + device:admin from a key, OR an admin
+  // session — api-v1.js runs a non-key bearer through authenticateAdminSession and skips this gate entirely for
+  // that path (the same skip idiom as keys/key and the H1 admin-JWT handlers above), checking owner/admin role
+  // in the handler instead.
+  devices:             { GET: R, POST: HUMAN },
+  device:              { GET: R },
+  device_rotate:       { POST: HUMAN },
+  device_revoke:       { POST: { tier: 'full', device_admin: true } },
   // receipt.js lanes (a separate function that calls scopes.check itself; classified HERE so there is one map).
   // The anonymous GET /api/v1/receipts/:id/public is credential-free and therefore not classified here.
   receipt:             { GET: R },                 // GET /api/v1/receipts/:id[?profile=public]  (was hard-coded read in receipt.js)
@@ -309,9 +386,13 @@ const SCOPE_LABEL = {
   full: 'the "full" access level',
   [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',
   unclassified: 'a classification (this tool is not in the scope map)'
 };
 function reconnectHint(required) {
+  if (required === DEVICE_ADMIN) {
+    return 'To fix: device:admin is never granted through OAuth — generate a tsk_ key with the device:admin checkbox ticked at app.tascan.io → Team → API Keys (owner only, requires Full).';
+  }
   let s = 'To fix: disconnect TaScan in your MCP client and connect it again — on the TaScan sign-in screen pick a higher access level';
   if (required === DISPATCH) s += ' and tick "Let this app hand tasks to my AI agents"';
   if (required === DISPATCH_CODE) s += ' and tick both agent checkboxes ("...including code and shell tasks on my computer")';
@@ -334,7 +415,7 @@ function restDenialHeaders(d) {
 }
 
 module.exports = {
-  SCOPE_VALUES, ALL_SCOPES, TIERS, RANK, DISPATCH, DISPATCH_CODE, AGENT_INBOX_IDS,
+  SCOPE_VALUES, ALL_SCOPES, TIERS, RANK, DISPATCH, DISPATCH_CODE, DEVICE_ADMIN, 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-devices.cjs

@@ -0,0 +1,69 @@
+// P0 (migration 216): device control plane MCP tools — read the registry and pull the kill switch. Split out
+// of tools.cjs (194 KB already, close to the ~200 KB bundle cap) and spread into TOOLS by one line there.
+//
+// Register and rotate have NO MCP tool at all (roadmap C.2, P-15): each mints a dev_live_ credential that would
+// land in a model transcript, and each needs a fresh passkey assertion (X-Decision-Assertion) that no MCP
+// client can present — POST /devices and POST /devices/:id/rotate stay admin-session-only, reached from
+// admin.js / admin-devices.js, never from here.
+'use strict';
+
+module.exports = [
+  {
+    name: 'tascan_list_devices',
+    description: 'List registered devices (RFID portals, barcode guns, PLCs, cameras, robots, tools, sensors) in the organization. Filter by status (active/revoked) or kind; paginate with an opaque cursor. Never returns a credential hash.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', enum: ['active', 'revoked'], description: 'Filter by device status' },
+        kind: { type: 'string', enum: ['rfid_portal', 'barcode', 'nfc_reader', 'tool', 'plc', 'camera', 'robot', 'sensor', 'other'], description: 'Filter by device kind' },
+        limit: { type: 'number', description: 'Max rows to return (1-200, default 50)' },
+        cursor: { type: 'string', description: 'Opaque cursor from a previous response next_cursor' }
+      }
+    },
+    annotations: { title: 'List Devices', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const qs = [];
+      if (args.status !== undefined) qs.push(`status=${encodeURIComponent(args.status)}`);
+      if (args.kind !== undefined) qs.push(`kind=${encodeURIComponent(args.kind)}`);
+      if (args.limit !== undefined) qs.push(`limit=${encodeURIComponent(args.limit)}`);
+      if (args.cursor !== undefined) qs.push(`cursor=${encodeURIComponent(args.cursor)}`);
+      const result = await api('GET', '/devices' + (qs.length ? '?' + qs.join('&') : ''));
+      const data = result.data || [];
+      const out = `${data.length} device(s)${result.has_more ? ' (more available, pass cursor: ' + result.next_cursor + ')' : ''}\n\n${JSON.stringify(data, null, 2)}`;
+      return out.length > 12000 ? out.slice(0, 12000) + '\n...(truncated at 12000 chars)' : out;
+    }
+  },
+  {
+    name: 'tascan_get_device',
+    description: 'Get one device by id: kind, name, status, location zone, credential rotation timestamps, revocation reason, and the last 20 evidence_events ids it produced. Never returns a credential hash.',
+    inputSchema: {
+      type: 'object',
+      properties: { device_id: { type: 'string', description: 'Device ID' } },
+      required: ['device_id']
+    },
+    annotations: { title: 'Get Device', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      if (!args.device_id) throw new Error('device_id is required');
+      const result = await api('GET', `/devices/${args.device_id}`);
+      return JSON.stringify(result.data, null, 2);
+    }
+  },
+  {
+    name: 'tascan_revoke_device',
+    description: 'Revoke a device credential immediately — the kill switch for a lost, stolen, or decommissioned device (RFID portal, barcode gun, PLC, camera, robot, tool, sensor). Its next evidence post is refused. Idempotent: revoking an already-revoked device reports already_revoked and mints no second receipt. Requires the device:admin permission (owner-only, needs full, never reachable through OAuth).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        device_id: { type: 'string', description: 'Device ID to revoke' },
+        reason: { type: 'string', description: 'Why this device is being revoked (up to 500 characters)' }
+      },
+      required: ['device_id']
+    },
+    annotations: { title: 'Revoke Device', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      if (!args.device_id) throw new Error('device_id is required');
+      const result = await api('POST', `/devices/${args.device_id}/revoke`, { reason: args.reason });
+      return result.already ? `Device ${args.device_id} was already revoked.` : `Device ${args.device_id} revoked.`;
+    }
+  }
+];

package/tools.cjs

@@ -271,7 +271,7 @@ const TOOLS = [
             properties: {
               title: { type: 'string', description: 'Task title' },
               description: { type: 'string', description: 'Task description' },
-              response_type: { type: 'string', enum: ['checkbox', 'photo', 'text', 'number', 'date', 'choice'], description: 'CRITICAL: "text" for names, phones, emails, notes, addresses, any free-form input. "photo" for tasks needing photographic proof (inspections, serial numbers, packed cases). "checkbox" ONLY for simple yes/no confirmations. "number" for numeric values. "date" for dates. "choice" for multiple-choice (needs response_config.options). Most info-collection tasks should be "text", most verification tasks should be "photo".' },
+              response_type: { type: 'string', enum: ['checkbox', 'photo', 'text', 'number', 'date', 'choice', 'link', 'url', 'file'], description: 'CRITICAL: "text" for names, phones, emails, notes, addresses, any free-form input. "photo" for tasks needing photographic proof (inspections, serial numbers, packed cases). "checkbox" ONLY for simple yes/no confirmations. "number" for numeric values. "date" for dates. "choice" for multiple-choice (needs response_config.options). "link" = the worker SUBMITS a URL (auto-verified by an http probe). "url" = the worker VISITS a preset URL and confirms. "file" = the worker uploads a file. Most info-collection tasks should be "text", most verification tasks should be "photo".' },
               response_config: { type: 'object', description: 'Response configuration. For "choice": {options: ["A","B","C"]}. For "text": {placeholder, multiline}. For "number": {placeholder}. For "date": {label, include_text}.' },
               is_safety_checkpoint: { type: 'boolean', description: 'Safety-critical task flag' },
               requires_photo: { type: 'boolean', description: 'Require photo on completion' },
@@ -284,7 +284,7 @@ const TOOLS = [
                   type: 'object',
                   properties: {
                     title: { type: 'string', description: 'Subtask title (e.g. "Set 1")' },
-                    response_type: { type: 'string', enum: ['checkbox', 'number', 'text', 'choice'], description: 'Typed subtask response. "number" for per-set values (reps/weight), "text" for notes, "choice" needs response_config.options. Default checkbox.' },
+                    response_type: { type: 'string', enum: ['checkbox', 'number', 'text', 'choice', 'link', 'url', 'file'], description: 'Typed subtask response. "number" for per-set values (reps/weight), "text" for notes, "choice" needs response_config.options. "link" = the worker submits a URL. "url" = the worker visits a preset URL and confirms. "file" = the worker uploads a file. Default checkbox.' },
                     response_config: { type: 'object', description: 'Same shape as task response_config' },
                     requires_photo: { type: 'boolean' }
                   },
@@ -296,13 +296,14 @@ const TOOLS = [
             required: ['title']
           },
           description: 'Array of tasks to create'
-        }
+        },
+        idempotency_key: { type: 'string', description: 'B1: optional replay key (up to 1024 chars, no braces) sent verbatim as the Idempotency-Key header instead of a fresh one per call — a retried call with the SAME key replays the original response instead of creating the tasks twice.' }
       },
       required: ['list_id', 'tasks']
     },
     annotations: { title: 'Add Tasks', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     handler: async (args, api) => {
-      const result = await api('POST', `/lists/${args.list_id}/tasks`, args.tasks);
+      const result = await api('POST', `/lists/${args.list_id}/tasks`, args.tasks, args.idempotency_key);
       return `${result.count} task(s) created in list ${args.list_id}\n\n${JSON.stringify(result.data, null, 2)}`;
     }
   },
@@ -505,7 +506,7 @@ const TOOLS = [
         task_id: { type: 'string', description: 'Task ID' },
         title: { type: 'string', description: 'New title' },
         description: { type: 'string', description: 'New description' },
-        response_type: { type: 'string', enum: ['checkbox', 'photo', 'text', 'number', 'date', 'choice'], description: 'See tascan_add_tasks for guidance. "text" for info collection, "photo" for visual proof, "checkbox" for yes/no only.' },
+        response_type: { type: 'string', enum: ['checkbox', 'photo', 'text', 'number', 'date', 'choice', 'link', 'url', 'file'], description: 'See tascan_add_tasks for guidance. "text" for info collection, "photo" for visual proof, "checkbox" for yes/no only, "link" for the worker submitting a URL, "url" for the worker visiting a preset URL and confirming, "file" for the worker uploading a file.' },
         response_config: { type: 'object', description: 'Response configuration. For "choice": {options: [...]}. See tascan_add_tasks.' },
         is_safety_checkpoint: { type: 'boolean', description: 'Safety-critical flag' },
         requires_photo: { type: 'boolean', description: 'Require photo' },
@@ -539,7 +540,7 @@ const TOOLS = [
             properties: {
               title: { type: 'string' },
               description: { type: 'string' },
-              response_type: { type: 'string', enum: ['checkbox', 'text', 'number', 'date', 'choice', 'photo'], description: '"date" for scheduling windows, "text" for info requests, "choice" needs response_config.options' },
+              response_type: { type: 'string', enum: ['checkbox', 'text', 'number', 'date', 'choice', 'photo', 'link', 'url', 'file'], description: '"date" for scheduling windows, "text" for info requests, "choice" needs response_config.options. "link" = the worker submits a URL. "url" = the worker visits a preset URL and confirms. "file" = the worker uploads a file.' },
               response_config: { type: 'object' }
             },
             required: ['title']
@@ -580,7 +581,7 @@ const TOOLS = [
             properties: {
               title: { type: 'string', description: 'Subtask title (e.g. "Set 1")' },
               description: { type: 'string', description: 'Optional detail' },
-              response_type: { type: 'string', enum: ['checkbox', 'number', 'text', 'choice'], description: 'Default checkbox. "number" for per-set values. "choice" needs response_config.options.' },
+              response_type: { type: 'string', enum: ['checkbox', 'number', 'text', 'choice', 'link', 'url', 'file'], description: 'Default checkbox. "number" for per-set values. "choice" needs response_config.options. "link" = the worker submits a URL. "url" = the worker visits a preset URL and confirms. "file" = the worker uploads a file.' },
               response_config: { type: 'object', description: 'For "choice": {options: [...]}. For "number"/"text": {placeholder}.' },
               requires_photo: { type: 'boolean', description: 'Require photo on completion' },
               sort_order: { type: 'number', description: 'Explicit position (defaults to end, in array order)' }
@@ -621,7 +622,7 @@ const TOOLS = [
         subtask_id: { type: 'string', description: 'Subtask ID' },
         title: { type: 'string' },
         description: { type: 'string' },
-        response_type: { type: 'string', enum: ['checkbox', 'number', 'text', 'choice'] },
+        response_type: { type: 'string', enum: ['checkbox', 'number', 'text', 'choice', 'link', 'url', 'file'], description: '"link" = the worker submits a URL. "url" = the worker visits a preset URL and confirms. "file" = the worker uploads a file.' },
         response_config: { type: 'object' },
         requires_photo: { type: 'boolean' },
         sort_order: { type: 'number' }
@@ -1112,7 +1113,8 @@ const TOOLS = [
         phone: { type: 'string', description: 'Raw phone number (e.g. "+17025551234") — used when no worker_id given' },
         message: { type: 'string', description: 'Message text. Transactional and work-related only.' },
         list_id: { type: 'string', description: 'Optional task list ID — appends a tap-to-open worker checklist link' },
-        include_link: { type: 'boolean', description: 'When a list_id is given, append the tap-to-open link to the SMS body (default true). Set false to send the message text alone — the link is still returned for you to share another way.' }
+        include_link: { type: 'boolean', description: 'When a list_id is given, append the tap-to-open link to the SMS body (default true). Set false to send the message text alone — the link is still returned for you to share another way.' },
+        idempotency_key: { type: 'string', description: 'B1: optional replay key (up to 1024 chars, no braces) sent verbatim as the Idempotency-Key header instead of a fresh one per call — a retried call with the SAME key replays the original response instead of sending a second text.' }
       },
       required: ['message']
     },
@@ -1124,7 +1126,7 @@ const TOOLS = [
         message: args.message,
         list_id: args.list_id,
         include_link: args.include_link
-      });
+      }, args.idempotency_key);
       const d = result.data;
       let text = `SMS sent!\n`;
       text += `  To: ${d.worker_name ? d.worker_name + ' (' + d.to + ')' : d.to}\n`;
@@ -1441,8 +1443,8 @@ const TOOLS = [
         enforce_on_list: { type: 'boolean', description: 'Zone-lock the task list — it cannot be started from outside the radius' },
         notify_on_enter: { type: 'boolean', description: 'Email the manager when a worker enters this zone (danger areas)' },
         notify_on_exit: { type: 'boolean', description: 'Email the manager when a worker leaves this zone (accountability — sign in then disappear)' },
-        auto_clock_in: { type: 'boolean', description: 'Entering the zone writes a shift_start clock-in event' },
-        auto_clock_out: { type: 'boolean', description: 'Leaving the zone writes a shift_end clock-out event' },
+        auto_clock_in: { type: 'boolean', description: 'Writes a shift_start when the WORKER PAGE, while open, sees the phone enter the zone; detection is pull-based, there is no background geofencing.  For a background-free presence event use a gate NFC/QR scan.' },
+        auto_clock_out: { type: 'boolean', description: 'Writes a shift_end when the WORKER PAGE, while open, sees the phone leave the zone; detection is pull-based, there is no background geofencing.  For a background-free presence event use a gate NFC/QR scan.' },
         notify_email: { type: 'string', description: 'Alert recipient override — defaults to all org admins' },
         polygon: { type: 'array', items: { type: 'array', items: { type: 'number' } }, description: 'Polygon/rectangle zone instead of a circle: vertices as [[lat,lng], ...], at least 3.  lat/lng/radius_m are then computed (centroid + bounding radius) — still pass lat/lng but they are overridden.' },
         description: { type: 'string', description: 'Shown to workers on the Site Gate page' },
@@ -1496,7 +1498,8 @@ const TOOLS = [
         radius_m: { type: 'number' }, task_list_id: { type: 'string' },
         enforce_on_list: { type: 'boolean' }, is_active: { type: 'boolean' },
         notify_on_enter: { type: 'boolean' }, notify_on_exit: { type: 'boolean' },
-        auto_clock_in: { type: 'boolean' }, auto_clock_out: { type: 'boolean' },
+        auto_clock_in: { type: 'boolean', description: 'Writes a shift_start when the WORKER PAGE, while open, sees the phone enter the zone; detection is pull-based, there is no background geofencing.  For a background-free presence event use a gate NFC/QR scan.' },
+        auto_clock_out: { type: 'boolean', description: 'Writes a shift_end when the WORKER PAGE, while open, sees the phone leave the zone; detection is pull-based, there is no background geofencing.  For a background-free presence event use a gate NFC/QR scan.' },
         notify_email: { type: 'string' },
         polygon: { type: 'array', items: { type: 'array', items: { type: 'number' } }, description: 'Replace geometry with a polygon ([[lat,lng],...], ≥3 vertices); pass null to revert to a circle' },
         kind: { type: 'string', enum: ['work_site', 'hazard', 'containment', 'restricted'] },
@@ -1799,13 +1802,15 @@ const TOOLS = [
         amount_cents: { type: 'number', description: 'Amount in cents ($1 min, $10,000 max)' },
         payer_email: { type: 'string', description: 'Who pays — receives the pay link on verification' },
         payer_name: { type: 'string' },
-        memo: { type: 'string', description: 'What the payment is for (shown to the payer)' }
+        memo: { type: 'string', description: 'What the payment is for (shown to the payer)' },
+        idempotency_key: { type: 'string', description: 'B1: optional replay key (up to 1024 chars, no braces) sent verbatim as the Idempotency-Key header instead of a fresh one per call — a retried call with the SAME key replays the original pledge instead of creating a second one.' }
       },
       required: ['task_list_id', 'worker_id', 'amount_cents', 'payer_email']
     },
     annotations: { title: 'Request Verified Payment', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     handler: async (args, api) => {
-      const result = await api('POST', '/payments', args);
+      const { idempotency_key, ...body } = args;
+      const result = await api('POST', '/payments', body, idempotency_key);
       const p = result.data;
       return `Payment pledged: $${(p.amount_cents / 100).toFixed(2)} to worker ${p.worker_id}\n\nID: ${p.id}\nStatus: ${p.status}\nPayer: ${p.payer_email}\n\n${result.note || 'Pay link is issued automatically when the list is verified complete.'}`;
     }
@@ -1992,16 +1997,20 @@ const TOOLS = [
   // SECURITY DEFINER RPCs behind human completions.  The cycle report is the audit surface.
   {
     name: 'tascan_create_cycle',
-    description: 'Start an unattended build-review-decide cycle (protocol v0.2). Queues T1 CODE: (or SHELL:) with your build_brief on the AI Inbox and T2 REVIEW: with your review_brief, born blocked on T1. The local executor builds, stores the exact bytes of artifact_paths as a bundle (build_ref = sha256 over the manifest), the independent reviewer reviews THAT bundle, an approve verdict mints a Decision task for the human authority (one SMS), Approve mints an Integrate task for the deploy id. Revise verdicts spawn revisions (cap max_revisions, default 3); reject, human Reject, scope violations or exhausted revisions PARK the cycle (a Parked task with Resume with notes / Close). REQUIRES agent:dispatch:code. Duplicate protection: the same idempotency_key, or the same briefs + paths, within 24 h returns the existing root instead of queueing again (created=false). Optional `reviews[]` attaches a multi-lens review panel (design item 14a) in place of the single OpenAI review — one review task mints per lens and every blocking lens must approve before the Decision task mints. Track with tascan_get_cycle_report (root_id). Nothing spawns a cycle on its own.',
+    description: 'Start an unattended build-review-decide cycle (protocol v0.2). Queues T1 CODE: (or SHELL:) with your build_brief on the AI Inbox and T2 REVIEW: with your review_brief, born blocked on T1. T1 (2026-09-24 throughput): kind=review_only mints T1 as CAPTURE: instead — the executor stores the bundle from the repo at HEAD without a model call and the review runs on that; dry_run=true runs the dispatch PREFLIGHT only (nothing queued) and prints every problem at once (codes title_too_long, brief_rule, brief_names_unbundled_path, artifact_over_cap, migration_as_context (tascan repo only), idempotency_replay, kind_invalid — bad kind, bad revisable_by, review_only + task_type SHELL/RESEARCH, review_only + max_questions 0), then what the API could NOT check (unchecked[]: artifact_missing_at_head always — only the executor sees the repo, and a CAPTURE naming a missing path fails with "[artifact_missing_at_head]" in its error; artifact_over_cap for any path without a byte count — pass artifact_bytes; idempotency_replay only if its lookup failed) and warnings[] (a build_brief naming a context file outside the bundle); a real create that the API refuses prints the same problems[] list (when the transport hands the tool only the first problem\'s text, the tool re-runs the preflight and prints the whole list). The local executor builds, stores the exact bytes of artifact_paths as a bundle (build_ref = sha256 over the manifest), the independent reviewer reviews THAT bundle, an approve verdict mints a Decision task for the human authority (one SMS), Approve mints an Integrate task for the deploy id. Revise verdicts spawn revisions (cap max_revisions, default 3); reject, human Reject, scope violations or exhausted revisions PARK the cycle (a Parked task with Resume with notes / Close). REQUIRES agent:dispatch:code. Duplicate protection: the same idempotency_key, or (keyless) the same briefs + paths on a live root, within 24 h is refused by the preflight as idempotency_replay (400, nothing queued, the existing root_id in the problem) and printed as DUPLICATE with that root_id; only a replay the preflight could not see (a race) comes back from the RPC as 200 created=false, printed the same way. Optional `reviews[]` attaches a multi-lens review panel (design item 14a) in place of the single OpenAI review — one review task mints per lens and every blocking lens must approve before the Decision task mints. Track with tascan_get_cycle_report (root_id). Nothing spawns a cycle on its own.',
     inputSchema: {
       type: 'object',
       properties: {
         project_id: { type: 'string', description: 'Working project (UUID). Its Decisions and Agent Questions lists are created on the first cycle (coord_ensure_lists). Requires the org human authority to be configured (coord_set_authority) — otherwise 403.' },
-        title: { type: 'string', description: 'Short human title (1-200 chars). T1 becomes "CODE: <title>", T2 "REVIEW: <title>".' },
+        title: { type: 'string', description: 'Short human title (1-200 chars). T1 becomes "CODE: <title>" ("CAPTURE: <title>" when kind=review_only), T2 "REVIEW: <title>".' },
         build_brief: { type: 'string', description: 'The executor prompt (1-40000 chars). Executed verbatim by the local Claude Code runner as a CODE:/SHELL: task — write it as a complete instruction, name the files, forbid nothing the runner already forbids (deploy/commit/push are refused by its context).' },
         review_brief: { type: 'string', description: 'The reviewer prompt (1-40000 chars). The reviewer reads the stored bundle (tascan_get_build / tascan_get_build_file), the task text and the filtered trail; it returns approve, revise, reject or needs_input as strict JSON bound to the build_ref. Still required even when `reviews[]` is given (kept as T2\'s legacy description text).' },
         artifact_paths: { type: 'array', items: { type: 'string' }, description: 'Repo-relative paths the build binds (1-64). Exactly these files are stored as the bundle and hashed into build_ref; files the executor touches OUTSIDE them fail the scope check and park the cycle. No .., not absolute, no drive letter, no backslash.' },
-        task_type: { type: 'string', enum: ['CODE', 'SHELL'], description: 'T1 prefix (default CODE).' },
+        task_type: { type: 'string', enum: ['CODE', 'SHELL', 'RESEARCH'], description: 'T1 prefix (default CODE). CAPTURE is never caller-settable: kind=review_only makes T1 "CAPTURE:" itself. With kind=review_only the value is sent as given — CODE is accepted (T1 is still CAPTURE), SHELL / RESEARCH are refused by the API as kind_invalid.' },
+        kind: { type: 'string', enum: ['build', 'review_only'], description: 'Cycle kind (default build). review_only = no model builds anything: T1 is "CAPTURE: <title>", a local-executor task that stores artifact_paths from the repo at HEAD as the bundle (same build_ref, size cap and scope check as a CODE build) and completes in seconds; T2 REVIEW then reviews that bundle. Use it to get an independent review of documents or of code already committed by hand. Stored as coord.kind_of_cycle on the root.' },
+        revisable_by: { type: 'string', enum: ['dispatcher', 'executor'], description: 'review_only cycles only — who fixes a revise verdict. dispatcher (default): the cycle parks on revise as today and you re-dispatch. executor: a revise spawns a revision CAPTURE task (up to max_revisions) that is born blocked on a question task "Revise the documents, then answer to release" addressed to you — fix the files in the repo, answer that question (tascan_post_message kind=answer), and the capture re-runs on the fixed HEAD. Build cycles always revise through the executor regardless of this field.' },
+        dry_run: { type: 'boolean', description: 'true = PREFLIGHT only: the API validates the whole dispatch and returns every problem at once (code, path, detail) plus the unchecked[] list (what only the executor / the RPC can decide) and warnings[] — nothing is queued, no idempotency key is consumed. Recommended before every real create. Default false.' },
+        artifact_bytes: { type: 'object', additionalProperties: { type: 'integer' }, description: 'Optional {path: bytes} for artifact_paths — the byte length of each file in your checkout. The API cannot read the repo, so artifact_over_cap (262144-byte reviewable cap per file) is only checked for paths you give a byte count; every other path is reported under unchecked (artifact_over_cap, unchecked_at_api) — never guessed from an earlier stored bundle. Same on dry_run and the real create.' },
         max_revisions: { type: 'integer', description: 'Revision cap (default 3): at most max_revisions + 1 builds and reviews.' },
         max_questions: { type: 'integer', description: 'Questions a runner may ask per task before the attempt fails (default 3).' },
         repo: { type: 'string', description: 'Which codebase on the executor the build runs in — an alias from the executor\'s allowlist (tascan-agent/repos.json), e.g. "tascan" (default), "merchskipper", "inkskipper", "rangerlizzy", "cardvault", "take1", "fitcheck", "safegrid", "eternity", "maniacs". artifact_paths are relative to that repo. An unknown alias is refused by the executor (repo_unknown) and the cycle parks.' },
@@ -2027,7 +2036,7 @@ const TOOLS = [
         checkpoint_description: { type: 'string', description: 'Optional description template for the Decision task; the build_ref, preview and findings summary are appended.' },
         integrate_title: { type: 'string', description: 'Optional title template for the Integrate task (default "Integrate: <title>").' },
         integrate_description: { type: 'string', description: 'Optional description template for the Integrate task.' },
-        idempotency_key: { type: 'string', description: 'Optional caller key (≤ 200 chars). The same key within 24 h returns the existing cycle (created=false) instead of a duplicate dispatch.' }
+        idempotency_key: { type: 'string', description: 'Optional caller key (≤ 200 chars). The same key within 24 h is refused as idempotency_replay (nothing queued) and printed as DUPLICATE with the existing root_id — safe to retry after a lost answer.' }
       },
       required: ['project_id', 'title', 'build_brief', 'review_brief', 'artifact_paths']
     },
@@ -2035,9 +2044,21 @@ const TOOLS = [
     handler: async (args, api) => {
       const paths = Array.isArray(args.artifact_paths) ? args.artifact_paths : (typeof args.artifact_paths === 'string' ? [args.artifact_paths] : []);
       if (!paths.length) throw new Error('artifact_paths is required (1-64 repo-relative paths)');
+      // T1 (2026-09-24): cycle kind + revisable_by + dry_run.  Not validated here: an unknown kind / revisable_by is sent
+      // as given and the API's preflight names it kind_invalid in problems[] with everything else wrong (one list, one
+      // round trip — and the same name migration 214 uses).  CAPTURE is the one task_type a caller can never set.
+      const kind = args.kind == null || args.kind === '' ? 'build' : String(args.kind).trim().toLowerCase();
+      let revisableBy = null;
+      if (args.revisable_by != null && args.revisable_by !== '') revisableBy = String(args.revisable_by).trim().toLowerCase();
+      if (args.task_type != null && String(args.task_type).trim().toUpperCase() === 'CAPTURE') throw new Error('task_type must be CODE, SHELL or RESEARCH — CAPTURE is set by kind=review_only, never by the caller');
+      const dryRun = args.dry_run === true || args.dry_run === 'true';
       const options = {};
       if (args.repo) options.repo = String(args.repo);
       for (const k of ['task_type', 'max_revisions', 'max_questions', 'max_cost_micro_usd', 'preview_url']) if (args[k] != null && args[k] !== '') options[k] = args[k];
+      // kind goes on the wire only when it is not the default (a build create keeps the pre-T1 shape); task_type is
+      // forwarded as given even for review_only — the API refuses SHELL / RESEARCH there as kind_invalid.
+      if (kind !== 'build') options.kind = kind;
+      if (revisableBy) options.revisable_by = revisableBy;
       if (Array.isArray(args.reviews) && args.reviews.length) options.reviews = args.reviews;
       const templates = {};
       if (args.checkpoint_title || args.checkpoint_description) templates.checkpoint = { ...(args.checkpoint_title ? { title: args.checkpoint_title } : {}), ...(args.checkpoint_description ? { description: args.checkpoint_description } : {}) };
@@ -2045,7 +2066,88 @@ const TOOLS = [
       if (Object.keys(templates).length) options.templates = templates;
       const body = { project_id: args.project_id, title: args.title, build_brief: args.build_brief, review_brief: args.review_brief, artifact_paths: paths, options };
       if (args.idempotency_key) body.idempotency_key = args.idempotency_key;
-      const result = await api('POST', '/coord/cycles', body);
+      // artifact_bytes {path: bytes}: the only way the API can decide artifact_over_cap for a file it has never stored.
+      // Forwarded verbatim (the API keeps the entries that name an artifact path and are non-negative integers).
+      if (args.artifact_bytes && typeof args.artifact_bytes === 'object' && !Array.isArray(args.artifact_bytes)) {
+        const ab = {};
+        for (const [p, n] of Object.entries(args.artifact_bytes)) if (Number.isInteger(Number(n)) && Number(n) >= 0) ab[p] = Number(n);
+        if (Object.keys(ab).length) body.artifact_bytes = ab;
+      }
+      // Preflight rendering — the API's shape (api-v1 coordCyclePreflight):
+      //   problems  [{code, path?, detail}]                       blocking; the real POST refuses with the FULL list
+      //   warnings  [{code, path, brief, detail}]                 informational (build_brief naming a context file)
+      //   unchecked [{code, status:'unchecked_at_api', paths?, detail}]  what only the executor / the RPC decides
+      // One renderer prints a dry_run answer and a refused real create, so the dispatcher reads one shape either way.
+      const listOf = (r, key) => (r && Array.isArray(r[key])) ? r[key] : (r && r.data && Array.isArray(r.data[key])) ? r.data[key] : [];
+      const renderProblems = (list) => (Array.isArray(list) ? list : []).map((p, i) => {
+        const o = (p && typeof p === 'object') ? p : { code: String(p) };
+        return `${i + 1}. ${o.code || 'unknown'}${o.path ? ` — ${o.path}` : ''}${o.detail ? `: ${o.detail}` : ''}`;
+      }).join('\n');
+      const renderUnchecked = (list) => (Array.isArray(list) && list.length)
+        ? '\n\nUNCHECKED at the API (' + list.length + ') — the executor applies these when it captures / builds; a failure there parks the cycle:\n' + list.map(u => {
+          const o = (u && typeof u === 'object') ? u : { code: String(u) };
+          const where = Array.isArray(o.paths) && o.paths.length ? ` [${o.paths.join(', ')}]` : (o.path ? ` — ${o.path}` : '');
+          return `- ${o.code || 'unknown'}${where}${o.detail ? `: ${o.detail}` : ''}`;
+        }).join('\n')
+        : '';
+      const renderWarnings = (list) => (Array.isArray(list) && list.length)
+        ? '\n\nWARNINGS (' + list.length + ', not refusals):\n' + list.map(w => {
+          const o = (w && typeof w === 'object') ? w : { code: String(w) };
+          return `- ${o.code || 'unknown'}${o.path ? ` — ${o.path}` : ''}${o.brief ? ` (${o.brief})` : ''}${o.detail ? `: ${o.detail}` : ''}`;
+        }).join('\n')
+        : '';
+      const cap = (text) => (text.length > 12000 ? text.slice(0, 12000) + '\n… [truncated at 12000 chars]' : text);
+      // The api() bridge throws on a non-2xx; a refused create (400 {error, problems[]}) reaches the handler as an
+      // Error that may carry the body as .problems / .data / .body (bridge-attached) or as a JSON message.
+      const problemsOfError = (e) => {
+        if (!e) return null;
+        for (const src of [e.problems, e.data && e.data.problems, e.body && e.body.problems, e.response && e.response.problems]) if (Array.isArray(src)) return src;
+        const msg = typeof e.message === 'string' ? e.message.trim() : '';
+        if (msg.startsWith('{')) { try { const j = JSON.parse(msg); if (Array.isArray(j.problems)) return j.problems; } catch (_) { /* not JSON */ } }
+        return null;
+      };
+      const tailLines = `\nkind: ${kind}` + (revisableBy ? `\nrevisable_by: ${revisableBy}` : '') + `\nartifact_paths: ${paths.join(', ')}`;
+      if (dryRun) {
+        const result = await api('POST', '/coord/cycles?dry_run=1', { ...body, dry_run: true });
+        const list = listOf(result, 'problems'), warnings = listOf(result, 'warnings'), unchecked = listOf(result, 'unchecked');
+        const ok = result.ok === true || (result.data && result.data.ok === true) || (list.length === 0 && result.ok !== false);
+        // "0 problem(s)" is never "accepted as written": the API has no repo, so existence at HEAD (and the size of
+        // any path without a byte count) is decided by the executor at capture / build time — printed under UNCHECKED.
+        let text = `PREFLIGHT: ${list.length} problem(s)` + (ok && !list.length ? ' — nothing the API can check is wrong; the items under UNCHECKED are decided by the executor.' : '') + '\nNothing was queued (dry_run).';
+        if (list.length) text += '\n' + renderProblems(list) + '\n\nFix every item above, then call again with dry_run=false.';
+        text += renderUnchecked(unchecked) + renderWarnings(warnings) + tailLines;
+        return cap(text);
+      }
+      let result;
+      try {
+        result = await api('POST', '/coord/cycles', body);
+      } catch (e) {
+        let list = problemsOfError(e), warnings = null, unchecked = null, how = 'the API answered 400 with problems[]';
+        if (!list) {
+          // Both real bridges (tascan-mcp/index.js, mcp-endpoint.js) throw Error(data.error) and drop the rest of
+          // the 400 body — and the API sets error = problems[0].detail, so the dispatcher would see ONE problem per
+          // round trip, the exact cost the preflight exists to remove.  Re-run the preflight (writes nothing, same
+          // scope tier) and print the whole list — but only when the API's error text IS one of the preflight
+          // details, so a refusal from somewhere else (RPC 22023, 403, 503, a post-create failure) is never
+          // re-labelled as a preflight refusal.  Any failure of the re-run falls back to the original error.
+          const msg = typeof e.message === 'string' ? e.message.trim() : '';
+          let pre = null;
+          try { pre = await api('POST', '/coord/cycles?dry_run=1', { ...body, dry_run: true }); } catch (_) { pre = null; }
+          const preList = listOf(pre, 'problems');
+          if (msg && preList.length && preList.some(p => p && typeof p.detail === 'string' && p.detail.trim() === msg)) {
+            list = preList; warnings = listOf(pre, 'warnings'); unchecked = listOf(pre, 'unchecked');
+            how = 'the transport surfaced only the first problem; the list below is the preflight re-run on the same body';
+          }
+        }
+        if (!list) throw e;
+        // A retry after a lost 201 is refused as idempotency_replay with the existing root in the problem: print it as
+        // the DUPLICATE answer (root_id + where to read it), not as a refusal to "fix" — changing the key would dispatch twice.
+        const only = list.length === 1 && list[0] && typeof list[0] === 'object' ? list[0] : null;
+        if (only && only.code === 'idempotency_replay' && only.root_id) {
+          return `DUPLICATE — nothing was queued.  A cycle with the same ${only.by === 'brief_sha256' ? 'briefs and paths' : 'idempotency_key'} exists from the last 24 h (the API refused the replay: idempotency_replay).\nroot_id: ${only.root_id}\n\nRead it: tascan_get_cycle_report root_id=${only.root_id}`;
+        }
+        return cap(`REFUSED — nothing was queued.  PREFLIGHT: ${list.length} problem(s) (${how})\n${renderProblems(list)}\n\nFix every item above and call again (dry_run=true first to confirm).` + renderUnchecked(unchecked) + renderWarnings(warnings));
+      }
       const d = result.data || {};
       if (result.duplicate || d.created === false) {
         return `DUPLICATE — nothing was queued.  A cycle with the same ${args.idempotency_key ? 'idempotency_key' : 'briefs and paths'} exists from the last 24 h (status ${d.status || 'active'}).\nroot_id: ${d.root_id}\nreview_id: ${d.review_id || 'n/a'}\n\nRead it: tascan_get_cycle_report root_id=${d.root_id}`;
@@ -2053,7 +2155,16 @@ const TOOLS = [
       const reviewLine = Array.isArray(d.review_ids) && d.review_ids.length > 0
         ? `review_ids (T2 REVIEW panel, ${d.review_ids.length} lens${d.review_ids.length > 1 ? 'es' : ''}, blocked on T1): ${d.review_ids.join(', ')}`
         : `review_id (T2 REVIEW, blocked on T1): ${d.review_id}`;
-      return `Cycle created.\nroot_id (T1 ${options.task_type || 'CODE'}: build): ${d.root_id}\n${reviewLine}\nbrief_sha256: ${d.brief_sha256}\ndecisions_list_id: ${d.decisions_list_id}\nquestions_list_id: ${d.questions_list_id}\nartifact_paths: ${paths.join(', ')}\n\nNext: the local executor claims T1 on its next poll (≤ 30 s), stores the bundle and finishes with build_ref; T2 is released from that finish.  Follow with tascan_get_cycle_report root_id=${d.root_id} or tascan_get_task task_id=${d.root_id} (agent + trail blocks).  Nobody is texted until the reviewer approves.`;
+      const t1 = kind === 'review_only' ? 'CAPTURE: capture, no model call' : `${options.task_type || 'CODE'}: build`;
+      const next = kind === 'review_only'
+        ? `Next: the local executor claims T1 CAPTURE on its next poll (≤ 30 s), stores artifact_paths from the repo at HEAD as the bundle WITHOUT invoking a model and finishes with build_ref; T2 is released from that finish.  On a revise verdict the cycle ${revisableBy === 'executor' ? 'mints a revision CAPTURE task blocked on a question to you ("Revise the documents, then answer to release") — fix the files, then answer it with tascan_post_message kind=answer' : 'parks (revisable_by=dispatcher) and you re-dispatch after fixing the files'}.`
+        : 'Next: the local executor claims T1 on its next poll (≤ 30 s), stores the bundle and finishes with build_ref; T2 is released from that finish.';
+      // The legacy first three lines are a pinned shape (panel-api-harness P5b): kind / revisable_by print only when
+      // non-default, after the review line, so a plain build cycle's summary is byte-identical to pre-T1.
+      const kindLines = (kind === 'review_only' ? `\nkind: review_only` : '') + (revisableBy ? `\nrevisable_by: ${revisableBy}` : '');
+      // A 201 carries the preflight's warnings[] beside data{} (unchecked[] too, but the executor decides those and a
+      // failure parks the cycle visibly — only the warnings are worth the dispatcher's eyes on a success).
+      return cap(`Cycle created.\nroot_id (T1 ${t1}): ${d.root_id}\n${reviewLine}${kindLines}\nbrief_sha256: ${d.brief_sha256}\ndecisions_list_id: ${d.decisions_list_id}\nquestions_list_id: ${d.questions_list_id}\nartifact_paths: ${paths.join(', ')}\n\n${next}  Follow with tascan_get_cycle_report root_id=${d.root_id} or tascan_get_task task_id=${d.root_id} (agent + trail blocks).  Nobody is texted until the reviewer approves.` + renderWarnings(listOf(result, 'warnings')));
     }
   },
   {
@@ -2086,6 +2197,34 @@ const TOOLS = [
       return text + '\n\n' + JSON.stringify(m, null, 2);
     }
   },
+  {
+    name: 'tascan_record_integration',
+    description: 'D4: the dispatcher records the Netlify deploy id for an authorized cycle — Integrate cards stop landing on Mike for something a key can prove instead (protocol v0.2, migration 181, coord_record_integration). Requires agent:dispatch. The root must be `authorized` (its checkpoint already Approved) with an open Integrate task; deploy_id must be a real Netlify deploy id — 24 lowercase hex, optionally "deployed:<id>" and/or a trailing build-ref hex prefix ("Deploy" and anything else is refused, bad_deploy_id). On success the root flips to `integrated`, the existing "Integrated: deploy …" trail note is posted, and the completion is stamped with your key as the actor (source api:key:<id>) — never as a human on the page. Idempotent: replaying the SAME deploy_id after the root is already integrated returns the same completion (replayed:true); a DIFFERENT deploy_id after integration is refused (409) without changing anything. A human may still complete the Integrate card on the worker page as an ops fallback, but only with a real deploy id too.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root_id: { type: 'string', description: 'The cycle root = the T1 build task id (tascan_get_cycle_report / tascan_create_cycle). Must currently be authorized (checkpoint Approved, Integrate task open).' },
+        deploy_id: { type: 'string', description: 'The Netlify deploy id: 24 lowercase hex, optionally prefixed "deployed:" and/or followed by a space and a ≥12-hex prefix of the build_ref.' },
+        note: { type: 'string', description: 'Optional note (≤ 2000 chars) recorded alongside the completion — e.g. what changed in this deploy.' }
+      },
+      required: ['root_id', 'deploy_id']
+    },
+    annotations: { title: 'Record Integration', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const id = String(args.root_id || '').trim().toLowerCase();
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) throw new Error('root_id must be a UUID');
+      const deployId = String(args.deploy_id || '').trim();
+      if (!deployId) throw new Error('deploy_id is required');
+      const body = { deploy_id: deployId };
+      if (args.note) body.note = args.note;
+      const result = await api('POST', `/coord/cycles/${id}/integrate`, body);
+      const d = result.data || {};
+      let text = `Integration recorded for root ${d.root_id || id}: deploy_id ${d.deploy_id}, build ${d.build_ref}.`;
+      text += d.replayed ? '\n(replay — this deploy id was already recorded; nothing new was written.)' : (d.integrated ? '\nRoot status: integrated.' : '');
+      text += `\ncompletion_id: ${d.completion_id}`;
+      return text + '\n\n' + JSON.stringify(d, null, 2);
+    }
+  },
   {
     name: 'tascan_get_build',
     description: 'Manifest of a stored build bundle by build_ref (protocol v0.2 build_artifacts): the exact files the executor produced for the cycle\'s artifact_paths, each with sha256, byte length and whether text content is stored (binary or over-cap files keep the sha only). build_ref = sha256 over the manifest, computed in the database once; the reviewer reviews THESE bytes, the human approves THIS ref, the integrate task records THIS ref. Read tier. Use tascan_get_build_file to read a file. Truncated at 12000 chars. Reading the manifest is discovery, not a read of any file.',
@@ -2193,7 +2332,426 @@ const TOOLS = [
       const result = await api('GET', `/projects/${id}/digest`);
       return result.markdown || '(no digest returned)';
     }
-  }
+  },
+  // ─── M1 (2026-09-23): MCP catches up with the protocol — ten tools for routes that already existed in
+  // api-v1.js / coord-dispatch-lib.js / receipt.js but had no MCP tool.  See
+  // docs/protocol/briefs/2026-09-23-m1-mcp-protocol-tools.md and the paired changes doc. ───────────────────
+  {
+    name: 'tascan_list_cycles',
+    description: 'List coordination-cycle roots in the organization (protocol v0.2, GET /coord/cycles): root id, title, status, task_type, project, build_ref, deploy_id and the T2 review id, newest first. Filter by project_id and/or status. Read tier — a reviewer\'s read-only key can call this too. Follow up with tascan_get_cycle_report root_id=... for the full audit trail of any row.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'Optional project UUID to filter to one project\'s cycles.' },
+        status: { type: 'string', description: 'Optional cycle status to filter on (e.g. active, parked, authorized, integrated) — lowercase letters and underscores only, 1-20 chars.' },
+        limit: { type: 'integer', description: 'Max rows to return (default 50, max 200).' }
+      }
+    },
+    annotations: { title: 'List Cycles', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const qs = [];
+      if (args.project_id != null && args.project_id !== '') {
+        const pid = String(args.project_id).trim().toLowerCase();
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(pid)) throw new Error('project_id must be a UUID');
+        qs.push(`project_id=${encodeURIComponent(pid)}`);
+      }
+      if (args.status != null && args.status !== '') {
+        const st = String(args.status).trim();
+        if (!/^[a-z_]{1,20}$/.test(st)) throw new Error('status must be 1-20 lowercase letters/underscores');
+        qs.push(`status=${encodeURIComponent(st)}`);
+      }
+      if (args.limit != null) qs.push(`limit=${encodeURIComponent(String(args.limit))}`);
+      const result = await api('GET', `/coord/cycles${qs.length ? '?' + qs.join('&') : ''}`);
+      const rows = result.data || [];
+      const lines = [`${result.count != null ? result.count : rows.length} cycle(s)`, ''];
+      rows.forEach(r => lines.push(`${r.root_id}  [${r.status}]  ${r.title}  (${r.task_type || 'CODE'}, project ${r.project_name || r.project_id}${r.deploy_id ? ', deploy ' + r.deploy_id : ''})`));
+      const out = lines.join('\n') + '\n\n' + JSON.stringify(result.data, null, 2);
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_get_task_trail',
+    description: 'Read a task\'s trail messages (protocol v0.2 trail_messages, GET /tasks/:id/messages): question, answer, handoff and note/discussion entries, last 100, newest last (reading order). Optionally filter to a comma-separated set of kinds. Read tier. Post with tascan_post_message.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task ID (UUID).' },
+        kinds: { type: 'string', description: 'Optional comma-separated kind filter, e.g. question,answer,handoff,note (discussion is stored as note; both names are accepted).' }
+      },
+      required: ['task_id']
+    },
+    annotations: { title: 'Get Task Trail', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const id = String(args.task_id || '').trim().toLowerCase();
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) throw new Error('task_id must be a UUID');
+      const qs = args.kinds ? `?kinds=${encodeURIComponent(String(args.kinds))}` : '';
+      const result = await api('GET', `/tasks/${id}/messages${qs}`);
+      const msgs = result.data || [];
+      const t = result.task || {};
+      const lines = [`TASK TRAIL: ${t.title || id} (${msgs.length} of up to 100, oldest first)`, t.is_cycle_task ? `cycle task — coord.kind ${t.coord && t.coord.kind}${t.coord && t.coord.blocked_by ? ', blocked by ' + t.coord.blocked_by : ''}` : 'ordinary task', ''];
+      msgs.forEach(m => lines.push(`[${m.created_at}] ${m.kind} by ${m.actor_type}:${m.actor_id}${m.addressee ? ' -> ' + m.addressee : ''}: ${String(m.body || '').slice(0, 300)}`));
+      const out = lines.join('\n') + '\n\n' + JSON.stringify(result, null, 2);
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_verify_receipt',
+    description: 'Independently verify a TaScan Action Receipt JWS (protocol 6.8, POST /receipts/verify): size, envelope, signature, issuer origin, key lifecycle, hashing profile, value semantics, schema and chain check, with an online issued/serial check for the reference issuer. Public route: no TaScan scope is required by the API itself, though this MCP connection still needs some valid key to place any tools/call. Works for both the full and the public export profile. Keys come only from the issuer\'s own well-known key document (https://app.tascan.io/.well-known/tascan-receipt-keys.json for the reference issuer, or the equivalent well-known path for a foreign one) — this tool never supplies keys itself. Never verifies locally — always calls the reference verifier.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        jws: { type: 'string', description: 'The compact JWS to verify (from tascan_get_receipt\'s output, or any TaScan-format receipt).' }
+      },
+      required: ['jws']
+    },
+    annotations: { title: 'Verify Receipt', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, api) => {
+      const jws = String(args.jws || '').trim();
+      if (!jws) throw new Error('jws is required');
+      const r = await api('POST', '/receipts/verify', { jws });
+      let receiptId = 'unknown';
+      const sub = r.claims && typeof r.claims.sub === 'string' ? r.claims.sub : null;
+      const m = sub && sub.match(/^tascan:\/\/evidence\/([0-9a-f-]{36})$/);
+      if (m) receiptId = m[1];
+      const lines = [
+        `valid: ${r.valid}`,
+        `reason: ${r.reason || 'none'}`,
+        `kid: ${r.kid || 'unknown'}`,
+        `profile: ${r.profile || 'unknown'}`,
+        `schema_valid: ${r.schema_valid === undefined ? 'not checked' : r.schema_valid}`,
+        `receipt id (from claims.sub): ${receiptId}`,
+        `issuer: ${r.issuer || 'unknown'} (key_source ${r.key_source || 'unknown'})`,
+        `online check: ${r.online ? 'yes' : 'no'} — status ${r.status || 'unknown'}${r.issued != null ? ', issued ' + r.issued : ''}${r.latest_serial != null ? ', latest_serial ' + r.latest_serial : ''}`,
+        r.schema_errors ? `schema_errors: ${JSON.stringify(r.schema_errors)}` : null,
+        r.detail ? `detail: ${r.detail}` : null
+      ].filter(x => x !== null).join('\n');
+      const out = lines + '\n\n' + JSON.stringify(r, null, 2);
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_get_build_diff',
+    description: 'Store an already-computed diff for one file of a build bundle against a base commit (protocol v0.2 item 6, POST /coord/builds/:build_ref/diff — the parser has no GET for this path; a deployed function ships no git object database, so tascan-agent/deployer.js computes the diff text with its own persistent worktree and this route only validates + stores it via coord_set_artifact_diff). build_sha256 must equal the artifact\'s own stored sha256 or the call is refused; storing a diff replaces that file\'s stored full content with the diff going forward. There is currently no REST route that reads a stored diff back (GET /builds/:build_ref and /builds/:build_ref/file do not surface it) — this tool only writes one. Requires agent:dispatch.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        build_ref: { type: 'string', description: 'sha256:<64 hex> (or the bare 64 hex) of the build the diff is about.' },
+        path: { type: 'string', description: 'Repo-relative path from the build manifest (tascan_get_build).' },
+        base_ref: { type: 'string', description: 'The commit-ish the diff was computed against (1-200 chars).' },
+        text: { type: 'string', description: 'The already-computed diff text (up to 262144 characters). This tool never computes a diff itself.' },
+        build_sha256: { type: 'string', description: '64-hex sha256 of the file at build_ref/path — must match the stored artifact\'s own sha256.' },
+        base_sha256: { type: 'string', description: 'Optional 64-hex sha256 of the file at base_ref.' },
+        truncated: { type: 'boolean', description: 'True if text is itself a truncated diff.' }
+      },
+      required: ['build_ref', 'path', 'base_ref', 'text', 'build_sha256']
+    },
+    annotations: { title: 'Submit Build Diff', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const ref = String(args.build_ref || '').trim().toLowerCase();
+      if (!/^(sha256:)?[0-9a-f]{64}$/.test(ref)) throw new Error('build_ref must be sha256:<64 hex>');
+      const path = String(args.path || '').trim();
+      if (!path) throw new Error('path is required');
+      const baseRef = String(args.base_ref || '').trim();
+      if (!baseRef) throw new Error('base_ref is required');
+      const text = args.text;
+      if (typeof text !== 'string') throw new Error('text is required (the already-computed diff)');
+      const buildSha256 = String(args.build_sha256 || '').trim().toLowerCase();
+      if (!/^[0-9a-f]{64}$/.test(buildSha256)) throw new Error('build_sha256 must be a 64-hex sha256');
+      const body = { path, base_ref: baseRef, text, build_sha256: buildSha256 };
+      if (args.base_sha256 != null) {
+        const baseSha256 = String(args.base_sha256).trim().toLowerCase();
+        if (!/^[0-9a-f]{64}$/.test(baseSha256)) throw new Error('base_sha256 must be a 64-hex sha256');
+        body.base_sha256 = baseSha256;
+      }
+      if (args.truncated != null) body.truncated = !!args.truncated;
+      const ref2 = ref.startsWith('sha256:') ? ref : 'sha256:' + ref;
+      const result = await api('POST', `/coord/builds/${encodeURIComponent(ref2)}/diff`, body);
+      const d = result.data || {};
+      const out = `Diff stored for ${d.path || path} (build ${d.build_ref || ref2}).\n\n${JSON.stringify(d, null, 2)}`;
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_dispatcher_action',
+    description: 'Record a chief-of-staff dispatcher action on a coordination cycle as a receipt (protocol v0.2 D6, POST /coord/cycles/:root/dispatcher-actions): hand_review_approve, hand_review_revise, park, bundle_recovery, migration_apply, deploy or decision. Mints a completed task + completion under the Chief of Staff worker and a dispatcher_action ledger event on the root. kind=deploy additionally requires evidence.deploy_id (a Netlify deploy id) and composes the same integrate-as-note every root gets with coord_record_integration when the root is authorized — one call that does both records. Requires agent:dispatch.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        root_id: { type: 'string', description: 'The cycle root task id (tascan_list_cycles / tascan_create_cycle).' },
+        kind: { type: 'string', enum: ['hand_review_approve', 'hand_review_revise', 'park', 'bundle_recovery', 'migration_apply', 'deploy', 'decision'], description: 'Which dispatcher action this is.' },
+        summary: { type: 'string', description: 'Human-readable summary (1-4000 chars) — becomes the recorded completion notes.' },
+        evidence: { type: 'object', description: 'Optional evidence object (serializes to at most 8000 chars). For kind=deploy this must include deploy_id: 24 lowercase hex, optionally prefixed deployed: and/or followed by a build-ref hex prefix.' }
+      },
+      required: ['root_id', 'kind', 'summary']
+    },
+    annotations: { title: 'Dispatcher Action', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    handler: async (args, api) => {
+      const id = String(args.root_id || '').trim().toLowerCase();
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) throw new Error('root_id must be a UUID');
+      const KINDS = ['hand_review_approve', 'hand_review_revise', 'park', 'bundle_recovery', 'migration_apply', 'deploy', 'decision'];
+      const kind = String(args.kind || '');
+      if (!KINDS.includes(kind)) throw new Error(`kind must be one of: ${KINDS.join(', ')}`);
+      const summary = String(args.summary || '').trim();
+      if (!summary) throw new Error('summary is required');
+      if (summary.length > 4000) throw new Error('summary must be 4000 characters or fewer');
+      const body = { kind, summary };
+      if (args.evidence !== undefined && args.evidence !== null) body.evidence = args.evidence;
+      const result = await api('POST', `/coord/cycles/${id}/dispatcher-actions`, body);
+      const d = result.data || {};
+      let text = `Dispatcher action recorded: ${d.kind || kind} on root ${d.root_id || id}.\ntask_id: ${d.task_id}\ncompletion_id: ${d.completion_id}`;
+      if (d.integrate) text += `\nintegrate: ${d.integrate.rpc ? 'coord_record_integration ran (root authorized)' : 'note only (root not yet authorized)'}`;
+      const out = text + '\n\n' + JSON.stringify(d, null, 2);
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_post_evidence',
+    description: 'Post one evidence event into the evidence ledger (protocol v0.2 V9a, POST /evidence): an actor did an action to an object at a point in time, optionally with a location and provenance. idempotency_key is required — the same (org, idempotency_key) always returns the same row, never a second insert. Optionally correlate the event to a task or task list. Write tier; a device credential (structurally different from an API key) is not reachable through this MCP connection, so device_id is never set here.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        actor: {
+          type: 'object',
+          description: 'Who did it.',
+          properties: {
+            kind: { type: 'string', enum: ['worker', 'agent', 'device'], description: 'worker requires an active, unmerged worker id in your organization; agent/device ids are recorded as given.' },
+            id: { type: 'string', description: 'The actor\'s id.' }
+          },
+          required: ['kind', 'id']
+        },
+        action: { type: 'string', description: 'What happened, e.g. inspected, scanned, calibrated.' },
+        object: {
+          type: 'object',
+          description: 'What it happened to.',
+          properties: {
+            kind: { type: 'string', enum: ['asset', 'tag', 'serial', 'url'], description: 'What kind of thing object.ref names.' },
+            ref: { type: 'string', description: 'The object reference (asset id, tag id, serial number, or URL).' }
+          },
+          required: ['kind', 'ref']
+        },
+        occurred_at: { type: 'string', description: 'ISO timestamp for when the event actually happened.' },
+        location: {
+          type: 'object',
+          description: 'Optional location.',
+          properties: {
+            zone_id: { type: 'string', description: 'Optional geofence zone UUID.' },
+            lat: { type: 'number' },
+            lng: { type: 'number' }
+          }
+        },
+        provenance: { type: 'object', description: 'Optional provenance object. provenance.kind first_party_scan is written only by the scan_events trigger and is refused from a caller; provenance.signature triggers device-signature verification.' },
+        correlation: {
+          type: 'object',
+          description: 'Optional correlation hint.',
+          properties: {
+            task_id: { type: 'string', description: 'A task UUID in your organization to correlate this evidence to.' },
+            task_list_id: { type: 'string', description: 'A task list UUID in your organization to correlate this evidence to (used when task_id is absent or does not resolve).' }
+          }
+        },
+        idempotency_key: { type: 'string', description: 'Required, 1-200 chars. The same key on the same org replays the same stored row.' }
+      },
+      required: ['actor', 'action', 'object', 'occurred_at', 'idempotency_key']
+    },
+    annotations: { title: 'Post Evidence', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      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 ACTOR_KINDS = ['worker', 'agent', 'device'], OBJECT_KINDS = ['asset', 'tag', 'serial', 'url'];
+      if (!args.actor || typeof args.actor !== 'object' || !ACTOR_KINDS.includes(args.actor.kind) || !args.actor.id) throw new Error(`actor.kind must be one of ${ACTOR_KINDS.join(', ')} and actor.id is required`);
+      if (args.actor.kind === 'worker' && !UUID_RE.test(String(args.actor.id))) throw new Error('actor.id must be a UUID when actor.kind is worker');
+      if (!args.object || typeof args.object !== 'object' || !OBJECT_KINDS.includes(args.object.kind) || !args.object.ref) throw new Error(`object.kind must be one of ${OBJECT_KINDS.join(', ')} and object.ref is required`);
+      if ((args.object.kind === 'asset' || args.object.kind === 'tag') && !UUID_RE.test(String(args.object.ref))) throw new Error('object.ref must be a UUID when object.kind is asset or tag');
+      const action = String(args.action || '').trim();
+      if (!action) throw new Error('action is required');
+      const occurredAt = args.occurred_at ? new Date(args.occurred_at) : null;
+      if (!occurredAt || Number.isNaN(occurredAt.getTime())) throw new Error('occurred_at must be a valid ISO timestamp');
+      const idem = String(args.idempotency_key || '').trim();
+      if (!idem || idem.length > 200) throw new Error('idempotency_key is required (1-200 characters)');
+      if (args.location != null) {
+        if (typeof args.location !== 'object' || Array.isArray(args.location)) throw new Error('location must be an object');
+        if (args.location.zone_id != null && !UUID_RE.test(String(args.location.zone_id))) throw new Error('location.zone_id must be a UUID');
+      }
+      if (args.correlation != null) {
+        if (typeof args.correlation !== 'object' || Array.isArray(args.correlation)) throw new Error('correlation must be an object');
+        if (args.correlation.task_id != null && !UUID_RE.test(String(args.correlation.task_id))) throw new Error('correlation.task_id must be a UUID');
+        if (args.correlation.task_list_id != null && !UUID_RE.test(String(args.correlation.task_list_id))) throw new Error('correlation.task_list_id must be a UUID');
+      }
+      const body = { actor: { kind: args.actor.kind, id: args.actor.id }, action, object: { kind: args.object.kind, ref: args.object.ref }, occurred_at: occurredAt.toISOString(), idempotency_key: idem };
+      if (args.location) body.location = args.location;
+      if (args.provenance) body.provenance = args.provenance;
+      if (args.correlation) body.correlation = args.correlation;
+      const result = await api('POST', '/evidence', body);
+      const d = result.data || {};
+      const out = `Evidence event ${result.replayed ? '(replay of an existing row)' : 'recorded'}: id ${d.id}, actor ${d.actor_kind}:${d.actor_id}, action ${d.action}, object ${d.object_kind}:${d.object_ref}.\n\n${JSON.stringify(d, null, 2)}`;
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_evidence_policy',
+    description: 'Read or author a task\'s evidence policy (protocol v0.2 V9b, GET|PUT /evidence/policy/:task_id — one route, two methods, so one tool). action=get evaluates the pinned policy against the evidence ledger so far: whether it is usable and satisfied, and its progress (read tier). action=set authors/updates a policy in your org\'s namespace when definition is given (definition.require is a non-empty array of requirement objects; definition.min_count, when set, must be an integer from 1 through definition.require.length) or, when definition is omitted, pins the task to an existing active policy_id (write tier).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['get', 'set'], description: 'get = GET (evaluate, read tier). set = PUT (author/pin, write tier).' },
+        task_id: { type: 'string', description: 'Task ID (UUID) in your organization.' },
+        policy_id: { type: 'string', description: 'action=set only, required: lowercase letters/digits/underscore/dot, starting with a letter, up to 80 chars, e.g. loto_v1.' },
+        version: { type: 'integer', description: 'action=set only: optional version for a new/updated policy definition (default 1). Ignored when only pinning an existing policy.' },
+        definition: { type: 'object', description: 'action=set only, optional: policy definition to create or update — require (array, required), min_count, window, any_of, allow_fallback. Omit to pin the task to the existing active policy_id instead.' }
+      },
+      required: ['action', 'task_id']
+    },
+    annotations: { title: 'Evidence Policy', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const id = String(args.task_id || '').trim().toLowerCase();
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) throw new Error('task_id must be a UUID');
+      if (args.action === 'get') {
+        const result = await api('GET', `/evidence/policy/${id}`);
+        const d = result.data || {};
+        const lines = [`usable: ${d.usable}`, d.reason ? `reason: ${d.reason}` : null, d.policy_id ? `policy_id: ${d.policy_id} v${d.policy_version}` : null, `satisfied: ${d.satisfied}${d.satisfied_via ? ' via ' + d.satisfied_via : ''}`, d.progress ? `progress: ${d.progress}` : null].filter(x => x !== null).join('\n');
+        const out = lines + '\n\n' + JSON.stringify(d, null, 2);
+        return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+      }
+      if (args.action !== 'set') throw new Error("action must be 'get' or 'set'");
+      const policyId = String(args.policy_id || '').trim();
+      if (!/^[a-z][a-z0-9_.]{0,79}$/.test(policyId)) throw new Error('policy_id is required and must match ^[a-z][a-z0-9_.]{0,79}$');
+      const body = { policy_id: policyId };
+      if (args.version != null) body.version = args.version;
+      if (args.definition !== undefined && args.definition !== null) body.definition = args.definition;
+      const result = await api('PUT', `/evidence/policy/${id}`, body);
+      const d = result.data || {};
+      const out = `Evidence policy pinned: ${d.policy_id} on task ${id}${d.evidence_policy_version != null ? ' v' + d.evidence_policy_version : ''}.\n\n${JSON.stringify(d, null, 2)}`;
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_request_verification',
+    description: 'Enqueue an autonomous verification job for a task completion (Verification Layer V2 + V7 doc_check, POST /completions/:completion_id/verification-jobs): http_probe checks a URL (params url, and optionally expect_status, expect_content_type, expect_sha256), doc_check runs a named policy against params.url and params.policy_id. Read the result with tascan_list_verifications once the job runs. Write tier.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        completion_id: { type: 'string', description: 'task_completions.id (UUID) — from tascan_get_task -> completions[].id.' },
+        check_type: { type: 'string', enum: ['http_probe', 'doc_check'], description: 'Which autonomous check to run.' },
+        params: { type: 'object', description: 'For http_probe: url, and optionally expect_status, expect_content_type, expect_sha256. For doc_check: url and policy_id, where policy_id names an active doc_check policy.' },
+        run_at: { type: 'string', description: 'Optional ISO timestamp to schedule the job for (default now).' },
+        idempotency_key: { type: 'string', description: 'Optional replay key (up to 200 chars).' }
+      },
+      required: ['completion_id', 'check_type', 'params']
+    },
+    annotations: { title: 'Request Verification', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, api) => {
+      const id = String(args.completion_id || '').trim().toLowerCase();
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) throw new Error('completion_id must be a UUID');
+      const checkType = String(args.check_type || '');
+      if (checkType !== 'http_probe' && checkType !== 'doc_check') throw new Error("check_type must be 'http_probe' or 'doc_check'");
+      if (!args.params || typeof args.params !== 'object' || Array.isArray(args.params)) throw new Error('params must be an object');
+      if (checkType === 'doc_check' && !args.params.policy_id) throw new Error('params.policy_id is required for check_type doc_check');
+      const body = { check_type: checkType, params: args.params };
+      if (args.run_at) body.run_at = args.run_at;
+      if (args.idempotency_key) body.idempotency_key = args.idempotency_key;
+      const result = await api('POST', `/completions/${id}/verification-jobs`, body);
+      const d = result.data || {};
+      const out = `Verification job queued: ${d.id} (${d.check_type}, state ${d.state}).\n\n${JSON.stringify(d, null, 2)}`;
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_list_verifications',
+    description: 'Read a task completion\'s verification verdicts and job queue (Verification Layer V2, GET /completions/:completion_id/verifications): completion_verifications rows (state, method, verifier, policy, confidence, finding) plus verification_jobs rows (state, attempts, last_error, result). Read tier.',
+    inputSchema: {
+      type: 'object',
+      properties: { completion_id: { type: 'string', description: 'task_completions.id (UUID) — from tascan_get_task -> completions[].id.' } },
+      required: ['completion_id']
+    },
+    annotations: { title: 'List Verifications', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const id = String(args.completion_id || '').trim().toLowerCase();
+      if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) throw new Error('completion_id must be a UUID');
+      const result = await api('GET', `/completions/${id}/verifications`);
+      const d = result.data || {};
+      const vs = d.verifications || [], js = d.jobs || [];
+      const lines = [`${vs.length} verdict(s), ${js.length} job(s) for completion ${d.completion_id || id}`, ''];
+      vs.forEach(v => lines.push(`verdict ${v.state} by ${v.verifier_kind}:${v.verifier_id || ''} policy ${v.policy_id || 'none'} confidence ${v.confidence != null ? v.confidence : 'n/a'} at ${v.observed_at}`));
+      js.forEach(j => lines.push(`job ${j.id} ${j.check_type} state ${j.state} attempts ${j.attempts}/${j.max_attempts}${j.last_error ? ' last_error ' + j.last_error : ''}`));
+      const out = lines.join('\n') + '\n\n' + JSON.stringify(d, null, 2);
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_org_analytics',
+    description: 'Read organization-wide analytics: view org (GET /analytics/org, the get_org_analytics rollup) or view resolutions (GET /analytics/resolutions, paginated AI issue-resolution history, filterable by severity, category, and pattern-detected). Read tier.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        view: { type: 'string', enum: ['org', 'resolutions'], description: 'Which analytics surface to read.' },
+        limit: { type: 'integer', description: 'resolutions only: page size (default 50, max 200).' },
+        offset: { type: 'integer', description: 'resolutions only: page offset.' },
+        severity: { type: 'string', description: 'resolutions only: filter by classification_severity.' },
+        category: { type: 'string', description: 'resolutions only: filter by issue_category.' },
+        pattern: { type: 'boolean', description: 'resolutions only: true to filter to pattern_detected rows only.' }
+      },
+      required: ['view']
+    },
+    annotations: { title: 'Org Analytics', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      if (args.view !== 'org' && args.view !== 'resolutions') throw new Error("view must be 'org' or 'resolutions'");
+      if (args.view === 'org') {
+        const result = await api('GET', '/analytics/org');
+        const d = result.data || {};
+        const ai = d.ai_stats || {};
+        const lines = [
+          `org analytics: ${d.total_projects != null ? d.total_projects : 0} project(s), ${d.total_completions != null ? d.total_completions : 0} completion(s), ${d.total_workers != null ? d.total_workers : 0} worker(s)`,
+          `issues: ${d.total_issues != null ? d.total_issues : 0} total, ${d.total_ai_resolutions != null ? d.total_ai_resolutions : 0} AI-resolved`,
+          `ai_stats: avg_urgency ${ai.avg_urgency != null ? ai.avg_urgency : 'n/a'}, avg_confidence ${ai.avg_confidence != null ? ai.avg_confidence : 'n/a'}, avg_resolution_minutes ${ai.avg_resolution_minutes != null ? ai.avg_resolution_minutes : 'n/a'}, patterns_detected ${ai.patterns_detected != null ? ai.patterns_detected : 0}`
+        ];
+        const out = lines.join('\n') + '\n\n' + JSON.stringify(d, null, 2);
+        return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+      }
+      const qs = [];
+      if (args.limit != null) qs.push(`limit=${encodeURIComponent(String(args.limit))}`);
+      if (args.offset != null) qs.push(`offset=${encodeURIComponent(String(args.offset))}`);
+      if (args.severity) qs.push(`severity=${encodeURIComponent(String(args.severity))}`);
+      if (args.category) qs.push(`category=${encodeURIComponent(String(args.category))}`);
+      if (args.pattern === true) qs.push('pattern=true');
+      const result = await api('GET', `/analytics/resolutions${qs.length ? '?' + qs.join('&') : ''}`);
+      const rows = result.data || [];
+      const out = `${rows.length} resolution(s) (limit ${result.pagination && result.pagination.limit}, offset ${result.pagination && result.pagination.offset})\n\n` + JSON.stringify(result, null, 2);
+      return out.length > 12000 ? out.slice(0, 12000) + '\n…[truncated at 12000 chars]' : out;
+    }
+  },
+  {
+    name: 'tascan_get_usage',
+    description: 'Read your organization\'s usage and quota snapshot for a billing period (GET /usage): SMS, email and AI call counts against their plan limits, the 100-receipt-per-month hard stop (used, allowance, hard_stop), the rate-limit window (60 requests per minute), and coordination-cycle spend in micro-USD for build roots created in that period. period defaults to the current UTC month (YYYY-MM). by_key additionally breaks coordination spend down per dispatch-scoped API key, refused (403 owner_required) to anything but an owner admin session -- a tsk_ key never gets it. Read tier.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        period: { type: 'string', description: 'Billing period as YYYY-MM (default: current UTC month).' },
+        by_key: { type: 'boolean', description: 'Break coordination spend down per dispatch-scoped API key -- owner admin session only.' }
+      }
+    },
+    annotations: { title: 'Get Usage', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const qs = [];
+      if (args.period) qs.push(`period=${encodeURIComponent(String(args.period))}`);
+      if (args.by_key === true) qs.push('by_key=true');
+      const result = await api('GET', `/usage${qs.length ? '?' + qs.join('&') : ''}`);
+      const d = result.data || {};
+      const lines = [
+        `usage for ${d.period || 'this period'} (plan ${d.plan || 'unknown'}):`,
+        `  sms   ${d.sms ? d.sms.used : 0} / ${d.sms ? d.sms.limit : '?'}`,
+        `  email ${d.email ? d.email.used : 0} / ${d.email ? d.email.limit : '?'}`,
+        `  ai    ${d.ai ? d.ai.used : 0} / ${d.ai ? d.ai.limit : '?'}`,
+        `  receipts ${d.receipts ? d.receipts.used : 0} / ${d.receipts && d.receipts.allowance != null ? d.receipts.allowance : '?'}${d.receipts && d.receipts.hard_stop ? ' (HARD STOP)' : ''}`,
+        `  rate limit: ${d.rate_limit ? d.rate_limit.max_requests : 60} requests / ${d.rate_limit ? d.rate_limit.window_minutes : 1} minute(s)`,
+        `  coordination spend: ${d.coordination_spend_micro_usd != null ? d.coordination_spend_micro_usd : 0} micro-USD`
+      ];
+      if (Array.isArray(d.by_key)) {
+        lines.push('  by key:');
+        d.by_key.forEach(k => lines.push(`    ${k.label || k.key_id} (${k.key_id}): ${k.coordination_spend_micro_usd} micro-USD`));
+      }
+      return lines.join('\n');
+    }
+  },
+  // P0 (migration 216): device control plane — split out (194 KB already close to the ~200 KB bundle cap).
+  ...require('./tools-devices.cjs')
 ];
 
 module.exports = { TOOLS, AGENT_REGISTRY, dynamicAgents };