tascan-mcp 3.11.0 → 3.13.0

package/README.md

@@ -268,6 +268,15 @@ API keys are scoped to your organization and support rate limiting (60 requests/
 
 ## Changelog
 
+### v3.13.0 — 2026-09-14
+- **Authorization scopes.** Every key and OAuth grant now carries a tier — `read`, `write`, or `full` — plus two additive permissions: `agent:dispatch` (hand PLAN/RESEARCH/WRITE/REVIEW/DEFAULT tasks to an AI agent inbox) and `agent:dispatch:code` (CODE/SHELL tasks, which run on the org's own machine). Tools are classified in `scopes.cjs`; a call outside the grant returns an `isError` result naming the scope to reconnect with. Existing OAuth connections must reconnect and tick the dispatch boxes on the consent page to dispatch again.
+- **`tascan_get_receipt` (new, 70 tools).** Fetches the signed Action Receipt (Ed25519 JWS, TaScan Protocol v0.1) for one completion: what was done, by whom, evidence hashes, verification, ledger chain head — with per-field provenance. Verify offline against `https://app.tascan.io/.well-known/tascan-receipt-keys.json` or online via `POST /api/v1/receipts/verify`. Spec: https://app.tascan.io/docs/protocol/TASCAN-PROTOCOL-v0.1.md
+- `tascan_get_task` reports an `agent` block (execution attempts: state, attempts, runner, trace id, error) for tasks dispatched to an agent — the only place agent failures are surfaced.
+- `tascan_dispatch_to_agent` keeps the full instruction in the task description; the urgent marker no longer breaks routing.
+
+### v3.12.0 — 2026-09-12
+- `tascan_send_task_email` and `tascan_assess_condition` now send the caller's API key (the TaScan functions behind them require it after the S99 security sweep). No tool additions — still 69 tools.
+
 ### v3.11.0 — 2026-09-11
 - **Signed photo URLs in every completion payload.** Photo evidence was invisible to AI agents: `photo_url` was a bare private-bucket path with no host or token. Every read path that returns a completion now also returns `photo_signed_url` (short-lived, default 1h, tunable via `TASCAN_PHOTO_URL_TTL`), `null` when there is no photo. Covered: `tascan_get_task` (task + subtask completions), `tascan_get_report` (new per-task `photos[]` when `include_responses` is true, replacing the bare `[+photo]` marker), `tascan_list_subtasks`, `tascan_query_responses`, `tascan_list_issues` / issue analysis (issue + injury photos), `tascan_zone_compliance` (PPE checkpoint photos), `tascan_condition_history` (assessment + baseline photos).
 - One batched storage signing call per response (a 40-task list fires one request, not 40). Signing failures log and degrade to `photo_signed_url: null` with the raw path intact; the tool call never fails.

package/index.js

@@ -43,9 +43,10 @@ async function api(method, path, body) {
   }
   return data;
 }
+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.11.0' },
+  { name: 'tascan', version: '3.13.0' },
   { capabilities: { tools: {} } }
 );
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "tascan-mcp",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "mcpName": "io.github.snowbikemike/tascan-mcp",
-  "description": "TaScan MCP Server — Closed-loop autonomous operations protocol. 69 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), cross-entity search, duplicate-worker detection, worker identity merge, AI issue analysis, and autonomous remediation dispatch. 15 patents filed (470+ claims). Task. Scan. Done.",
+  "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",
   "main": "index.js",
   "bin": {
@@ -14,6 +14,7 @@
   "files": [
     "index.js",
     "tools.cjs",
+    "scopes.cjs",
     "README.md",
     "LICENSE"
   ],

package/scopes.cjs

@@ -0,0 +1,314 @@
+// ============================================================
+// TaScan authorization scopes — ONE classification for MCP tools
+// and REST routes (S100 W1, 2026-09-14).
+// ============================================================
+// Consumed by:
+//   live-event/netlify/functions/mcp-endpoint.js   (per tool call)
+//   live-event/netlify/functions/api-v1.js         (per route)
+//   live-event/netlify/functions/mcp-oauth.js      (consent + token)
+//   live-event/netlify/functions/send-task-email.js (raw lane)
+//   live-event/netlify/functions/assess-condition.js (raw lane)
+//   live-event/admin.js mirrors the labels only.
+//
+// Tiers are cumulative:  read < write < full.
+// Two ADDITIVE dispatch permissions (never implied by a tier):
+//   agent:dispatch        — hand PLAN/RESEARCH/WRITE/REVIEW/DEFAULT tasks to an agent inbox
+//   agent:dispatch:code   — hand CODE/SHELL tasks to an agent inbox (touches Mike's PC);
+//                           requires agent:dispatch as well.
+//
+// Storage: api_keys.scopes TEXT[] is CANONICAL (migration 150 constrains it to
+// SCOPE_VALUES); oauth_grants.scope is a display mirror.  Enforcement reads
+// api_keys.scopes only.  'all' / '*' survive here solely for the service key
+// sentinel (api-v1-helpers.js authenticateApiKey returns ['*']) and for the
+// deploy window before 150 rewrites legacy rows.
+//
+// CommonJS, zero dependencies (bundled into Netlify functions via the same
+// relative require mcp-endpoint.js already uses for tools.cjs).
+// ============================================================
+
+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];
+const ALL_SCOPES = SCOPE_VALUES.slice();
+
+// Seed agent inbox (tools.cjs AGENT_REGISTRY, agent-execute, agent.js, migrations 046/137/151).
+// REST additionally consults agent_registry.inbox_id (org-scoped) — see api-v1.js isAgentInbox.
+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 CLOUD_TASK_TYPES = ['RESEARCH', 'WRITE', 'REVIEW', 'DEFAULT'];
+const LOCAL_ONLY_TASK_TYPES = ['CODE', 'SHELL', 'PLAN', 'MCP'];   // the cloud runner refuses these; DEFAULT goes either way
+const CODE_TASK_TYPES = ['CODE', 'SHELL'];
+const TASK_PREFIX_RE = new RegExp('^(' + TASK_TYPES.join('|') + '):');
+
+function taskType(title) {
+  const t = String(title == null ? '' : title).replace(/^[^A-Za-z]+/, '').toUpperCase();
+  const m = t.match(TASK_PREFIX_RE);
+  return m ? m[1] : 'DEFAULT';
+}
+// Which dispatch permission a task title needs when it lands in an agent inbox.
+function dispatchScopeFor(title) {
+  return CODE_TASK_TYPES.includes(taskType(title)) ? DISPATCH_CODE : DISPATCH;
+}
+// For a batch of titles: 'code' when any is CODE/SHELL, else true (plain dispatch).
+function dispatchKind(titles) {
+  const arr = Array.isArray(titles) ? titles : [titles];
+  return arr.some(t => dispatchScopeFor(t) === DISPATCH_CODE) ? 'code' : true;
+}
+
+// ─── 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)
+function normalize(v) {
+  if (v == null) return { tier: 'read', dispatch: false, code: 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 };
+  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 };
+}
+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);
+  return out;
+}
+function toScopeString(n) { return toArray(n).join(' '); }
+
+// OAuth `scope` request parameter (RFC 6749 §3.3).  Absent/blank = everything requested
+// (that is what a scope-less request meant before 150).  Unknown tokens are dropped and reported.
+// A scope string with NO known token (a vendor's fixed 'openid' / 'mcp' / account-linking scope —
+// nobody has recorded what Gemini / ChatGPT / custom clients send) FAILS OPEN: it is treated exactly
+// like an absent scope (`fallback: true`, unknown tokens listed for the log).  Unknown tokens carry no
+// security value: the consent page decides the grant regardless of what was requested, and refusing
+// would only lock those clients out at deploy.  `requested` is never null.
+// The AS decides the grant — the consent page always offers every option; `requested` only
+// picks the preselected tier.
+const SCOPE_PARAM_MAX = 1024;   // longer than this is not a scope list; ignore it rather than echo it
+const EVERYTHING = () => ({ tier: 'full', dispatch: true, code: true, legacy: false });
+function parseRequested(str) {
+  if (str == null || !String(str).trim()) {
+    return { requested: EVERYTHING(), unknown: [], absent: true, fallback: false };
+  }
+  if (String(str).length > SCOPE_PARAM_MAX) {
+    return { requested: EVERYTHING(), unknown: ['(scope parameter longer than ' + SCOPE_PARAM_MAX + ' chars)'], absent: false, fallback: true };
+  }
+  const toks = String(str).split(/[\s+,]+/).filter(Boolean);
+  const known = toks.filter(t => SCOPE_VALUES.includes(t));
+  const unknown = toks.filter(t => !SCOPE_VALUES.includes(t));
+  if (!known.length) return { requested: EVERYTHING(), unknown, absent: false, fallback: true };
+  return { requested: normalize(known), unknown, absent: false, fallback: false };
+}
+// What the consent form echoes back as its hidden `scope` field (so the POST re-parses the same request
+// and the consent log records it).  An over-long value is dropped rather than round-tripped.
+function echoScope(str) {
+  if (str == null) return '';
+  const s = String(str);
+  return s.length > SCOPE_PARAM_MAX ? '' : s;
+}
+
+// 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) {
+  const t = TIERS.includes(tier) ? tier : 'read';
+  const owner = role === 'owner';
+  const clamped = [];
+  let gt = t;
+  if (gt === 'full' && !owner) { gt = 'write'; clamped.push('full'); }
+  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 };
+}
+
+// POST /api/v1/keys body.scopes → canonical array or null (rejects 'all', '*', junk, empty,
+// and code-without-dispatch).
+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;
+  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.
+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 ((RANK[g.tier] || 0) < (RANK[need.tier] || 99)) return deny(need.tier);
+  if (need.dispatch === 'code' && !g.code) return deny(DISPATCH_CODE);
+  if (need.dispatch === true && !g.dispatch) return deny(DISPATCH);
+  return null;
+}
+
+// ─── Tool map: EVERY tool in tools.cjs.  Unknown name → null → deny. ─────────
+const R = { tier: 'read' }, W = { tier: 'write' }, F = { tier: 'full' };
+const WD = { tier: 'write', dispatch: true };
+// Writers into a list: dispatch decided by the target.  Seed inbox is known here; other
+// registered inboxes are only known to REST (agent_registry, org-scoped).
+const listWrite = titles => a => {
+  const id = String((a && a.list_id) || '');
+  return { tier: 'write', dispatch: AGENT_INBOX_IDS.includes(id) ? dispatchKind(titles(a)) : 'if_inbox' };
+};
+
+const TOOL_SCOPES = {
+  // read (31)
+  tascan_list_projects: R, tascan_get_project: R, tascan_list_events: R, tascan_get_event: R,
+  tascan_list_agents: R, tascan_list_tasks: R, tascan_get_task: R, tascan_list_subtasks: R,
+  tascan_list_workers: R, tascan_list_templates: R, tascan_get_report: R, tascan_query_responses: R,
+  tascan_list_issues: R, tascan_get_sms_status: R, tascan_list_tags: R, tascan_get_scan_history: R,
+  tascan_search_marketplace: R, tascan_list_invites: R, tascan_list_zones: R, tascan_zone_compliance: R,
+  tascan_condition_history: R, tascan_list_assets: R, tascan_list_reports: R, tascan_list_invoices: R,
+  tascan_list_payments: R, tascan_get_worker_passport: R, tascan_server_info: R, tascan_find: R,
+  tascan_get_worker: R, tascan_find_duplicate_workers: R,
+  tascan_get_receipt: R,                       // W3 receipt.js (GET /api/v1/receipts/:id — read tier there too)
+  // 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,
+  tascan_add_subtasks: W, tascan_update_subtask: W, tascan_complete_subtask: W, tascan_delete_subtask: W,
+  tascan_delete_task: W, tascan_complete_task: W, tascan_create_worker: W, tascan_update_worker: W,
+  tascan_generate_qr: W, tascan_recommend_fix: W, tascan_register_tag: W, tascan_create_zone: W,
+  tascan_update_zone: W, tascan_register_asset: W, tascan_create_invoice: W, tascan_update_invoice: W,
+  tascan_merge_workers: W, tascan_delete_worker: W,
+  // write + dispatch: defining a dispatch target IS a dispatch permission
+  tascan_register_agent: WD,
+  // write + inbox rule
+  tascan_add_tasks: listWrite(a => (Array.isArray(a.tasks) ? a.tasks : []).map(t => t && t.title)),
+  tascan_apply_template: listWrite(() => []),
+  // dispatch: the task text decides plain vs code
+  tascan_dispatch_to_agent: a => ({ tier: 'write', dispatch: dispatchKind(a.task) }),
+  // full (7): sends to a human, spends AI credits, or pledges money
+  tascan_dispatch_instruction: F, tascan_auto_resolve: F, tascan_send_sms: F, tascan_send_task_email: F,
+  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 })
+};
+// 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.
+const PENDING_TOOLS = [];
+
+function requiredForTool(name, args) {
+  const v = TOOL_SCOPES[name];
+  if (!v) return null;
+  return typeof v === 'function' ? v(args || {}) : { ...v };
+}
+
+// ─── Route map: EVERY handler name in api-v1-helpers.js parsePath × accepted methods. ─────
+// (handler, method) not listed → null → 403 unclassified.  'admin' = admin-JWT routes (gate skipped).
+const INBOX_WRITE = () => ({ tier: 'write', dispatch: 'if_inbox' });
+const ROUTE_SCOPES = {
+  projects:            { GET: R, POST: W },
+  project:             { GET: R, PUT: W, DELETE: W },
+  project_lists:       { GET: R, POST: W },
+  project_responses:   { GET: R },
+  list:                { GET: R, PUT: W, DELETE: W },
+  list_tasks:          { GET: R, POST: INBOX_WRITE },
+  list_qr:             { POST: W },
+  apply_template:      { POST: INBOX_WRITE },
+  list_report:         { GET: R },
+  task:                { GET: R, PUT: W, DELETE: W },       // ANY PUT on an inbox task re-checked in handleTask (dispatch / code by existing+new title); DELETE stays write (kill switch)
+  task_complete:       { POST: W },
+  task_subtasks:       { GET: R, POST: W },
+  subtask:             { GET: R, PUT: W, DELETE: W },
+  subtask_complete:    { POST: W },
+  workers:             { GET: R, POST: W },
+  worker:              { GET: R, PUT: W, DELETE: W },
+  worker_duplicates:   { GET: R },
+  worker_merge:        { POST: W },
+  worker_passport:     { GET: R },
+  agents:              { GET: R, POST: WD },
+  zones:               { GET: R, POST: W },
+  zone:                { GET: R, PUT: W, DELETE: W },
+  zone_events:         { GET: R },
+  zone_compliance:     { GET: R },
+  assets:              { GET: R, POST: W },
+  asset:               { GET: R },
+  payments:            { GET: R, POST: F },
+  invoices:            { GET: R, POST: W },
+  invoice:             { GET: R, PUT: W, PATCH: W, DELETE: W },
+  reports:             { GET: R, POST: b => (b && b.send_to_phone ? { ...F } : { ...W }) },
+  meta:                { GET: R },
+  find:                { GET: R },
+  scans:               { GET: R },
+  sms:                 { POST: F },
+  sms_status:          { GET: R },
+  marketplace:         { GET: R },
+  marketplace_invite:  { POST: F },
+  marketplace_invites: { GET: R },
+  templates:           { GET: R },
+  issue:               { GET: R, PUT: W },
+  list_issues:         { GET: R },
+  issue_recommend:     { POST: W },
+  issue_dispatch:      { POST: F },
+  issue_analyze:       { POST: F },
+  issue_auto_resolve:  { POST: F },
+  analytics_platform:  { GET: R },
+  analytics_org:       { GET: R },
+  analytics_resolutions: { GET: R },
+  tags:                { GET: R, POST: W },
+  tag:                 { GET: R, PUT: W, DELETE: W },
+  tag_scans:           { GET: R },
+  keys: 'admin', key: 'admin'
+};
+
+function requiredForRoute(handler, method, body) {
+  const h = ROUTE_SCOPES[handler];
+  if (!h || h === 'admin') return null;
+  const v = h[method];
+  if (!v) return null;
+  return typeof v === 'function' ? v(body || {}) : { ...v };
+}
+
+// ─── Error formatters ─────────────────────────────────────────
+const SCOPE_LABEL = {
+  read: 'the "read" access level',
+  write: 'the "write" access level',
+  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")',
+  unclassified: 'a classification (this tool is not in the scope map)'
+};
+function reconnectHint(required) {
+  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")';
+  s += '.  If you connect with a tsk_ API key instead, generate a new key with that access at app.tascan.io → Team → API Keys (owner only).';
+  return s;
+}
+function mcpDenialText(toolName, d) {
+  return `insufficient_scope: ${toolName} needs ${SCOPE_LABEL[d.required] || d.required}; this connection was granted "${d.granted_scope}".\n\n${reconnectHint(d.required)}`;
+}
+function restDenialBody(d) {
+  return {
+    error: 'insufficient_scope',
+    required_scope: d.required,
+    granted_scope: d.granted_scope,
+    error_description: `This credential was granted "${d.granted_scope}"; this request requires "${d.required}".  Generate a key with more access at app.tascan.io → Team → API Keys, or reconnect your MCP client and choose a higher access level${d.required.startsWith('agent:') ? ' and the agent-dispatch checkbox' : ''}.`
+  };
+}
+function restDenialHeaders(d) {
+  return { 'WWW-Authenticate': `Bearer error="insufficient_scope", scope="${d.required}"` };
+}
+
+module.exports = {
+  SCOPE_VALUES, ALL_SCOPES, TIERS, RANK, DISPATCH, DISPATCH_CODE, AGENT_INBOX_IDS,
+  TASK_TYPES, LOCAL_TASK_TYPES, CLOUD_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,
+  mcpDenialText, restDenialBody, restDenialHeaders
+};

package/tools.cjs

@@ -41,6 +41,13 @@ function fmtResponse(responseValue, notes) {
   return { value: value == null || value === '' ? null : String(value), note };
 }
 
+// Authorization scopes + task-type routing (S100 W1).  ONE routing rule: scopes.cjs taskType() mirrors
+// SQL agent_task_type() (migration 151) — prefix-only, no keyword heuristics.
+const { taskType, LOCAL_ONLY_TASK_TYPES, AGENT_INBOX_IDS } = require('./scopes.cjs');
+
+// Capabilities advertised here MUST match what each runner actually accepts (migration 151 seeds the same
+// rows): local = CODE/SHELL/PLAN/DEFAULT/MCP; cloud = RESEARCH/WRITE/REVIEW/DEFAULT (text only — it
+// refuses CODE/SHELL/PLAN/MCP).  DEFAULT goes local while the PC agent heartbeats, else cloud.
 const AGENT_REGISTRY = [
   {
     id: 'claude-code-local',
@@ -48,11 +55,11 @@ const AGENT_REGISTRY = [
     type: 'local',
     model: 'claude-opus-4-6',
     worker_id: '9d194a8e-0c38-4cba-ba62-8560e497a0c3',
-    inbox_id: 'f745d0fa-421a-42e5-85be-0a3f9acd28e8',
-    capabilities: ['CODE', 'SHELL', 'PLAN', 'WRITE', 'RESEARCH', 'DEFAULT'],
+    inbox_id: AGENT_INBOX_IDS[0],
+    capabilities: ['CODE', 'SHELL', 'PLAN', 'DEFAULT', 'MCP'],
     location: 'Las Vegas, NV (Mike\'s PC)',
     status: 'active',
-    description: 'Local Claude Code agent on Mike\'s PC. Spawns claude -p for code/shell tasks. Full filesystem + tool access. Picks up tasks from AI Inbox via Supabase Realtime.'
+    description: 'Local Claude Code agent on Mike\'s PC. Spawns an isolated claude -p (own settings, no desktop-control tools) for CODE/SHELL/PLAN/MCP tasks. Picks up tasks from the AI Inbox via Supabase Realtime. Dispatching here needs agent:dispatch (CODE/SHELL: agent:dispatch:code).'
   },
   {
     id: 'cloud-agent',
@@ -60,11 +67,11 @@ const AGENT_REGISTRY = [
     type: 'cloud',
     model: 'claude-haiku-4-5-20251001',
     worker_id: '9d194a8e-0c38-4cba-ba62-8560e497a0c3',
-    inbox_id: 'f745d0fa-421a-42e5-85be-0a3f9acd28e8',
-    capabilities: ['RESEARCH', 'WRITE', 'REVIEW', 'MCP', 'DEFAULT'],
+    inbox_id: AGENT_INBOX_IDS[0],
+    capabilities: ['RESEARCH', 'WRITE', 'REVIEW', 'DEFAULT'],
     location: 'Netlify (cloud)',
     status: 'active',
-    description: 'Cloud agent via Netlify function (agent-execute.js). Uses Anthropic API for RESEARCH/WRITE tasks. Triggered by Supabase pg_net webhook on task insert.'
+    description: 'Cloud agent via Netlify background function (agent-execute-background.js). Text only: RESEARCH/WRITE/REVIEW (and DEFAULT when the local agent is offline). Refuses CODE/SHELL/PLAN/MCP — those run on the local agent.'
   }
 ];
 // Dynamic registry entries (from tascan_register_agent calls within this session)
@@ -252,7 +259,7 @@ const TOOLS = [
   },
   {
     name: 'tascan_add_tasks',
-    description: 'Add one or more tasks to an event (task list). Supports bulk creation. IMPORTANT: Set response_type correctly — use "text" for info collection (names, phones, emails, notes), "photo" for visual verification (inspections, serial numbers, damage checks), "checkbox" only for simple confirmations. NOTE: To dispatch tasks to the Claude Code agent running on Mike\'s PC, use tascan_dispatch_to_agent instead — it routes directly to the agent\'s inbox with zero configuration needed.',
+    description: 'Add one or more tasks to an event (task list). Supports bulk creation. IMPORTANT: Set response_type correctly — use "text" for info collection (names, phones, emails, notes), "photo" for visual verification (inspections, serial numbers, damage checks), "checkbox" only for simple confirmations. NOTE: To dispatch tasks to an AI agent use tascan_dispatch_to_agent instead. Writing into an agent inbox list requires the agent:dispatch permission (agent:dispatch:code for CODE:/SHELL: titles) — without it the call is refused.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -301,13 +308,13 @@ const TOOLS = [
   },
   {
     name: 'tascan_dispatch_to_agent',
-    description: 'PREFERRED tool for sending work to an AI agent. Dispatches a task to the agent\'s inbox — picked up and executed automatically. No list ID needed. Supports prefixes: CODE: SHELL: RESEARCH: WRITE: PLAN: for routing. Use "agent" param to target a specific agent (default: claude-code-local). Use tascan_list_agents to discover available agents.',
+    description: 'PREFERRED tool for sending work to an AI agent. Dispatches a task to the agent\'s inbox — picked up and executed automatically. No list ID needed. REQUIRES the agent:dispatch permission on this connection (CODE:/SHELL: tasks also require agent:dispatch:code) — reconnect and tick the agent checkbox(es) if refused. Routing is by TITLE PREFIX only: CODE: SHELL: PLAN: MCP: → local Claude Code on Mike\'s PC; RESEARCH: WRITE: REVIEW: → cloud; no prefix (DEFAULT) → local while the PC agent is alive, else cloud. The cloud agent refuses CODE/SHELL/PLAN/MCP. Use "agent" param to target a specific agent (default: claude-code-local). Use tascan_list_agents to discover available agents; track progress with tascan_get_task (its "agent" block).',
     inputSchema: {
       type: 'object',
       properties: {
-        task: { type: 'string', description: 'The task description. Prefix with CODE: SHELL: RESEARCH: WRITE: PLAN: for routing, or just plain text.' },
-        agent: { type: 'string', description: 'Agent ID or name to dispatch to (default: claude-code-local). Use tascan_list_agents to see options.' },
-        priority: { type: 'string', enum: ['normal', 'urgent'], description: 'Priority level (default: normal)' }
+        task: { type: 'string', description: 'The full task text. START it with CODE: SHELL: PLAN: MCP: RESEARCH: WRITE: or REVIEW: for routing (prefix-only — nothing may precede it), or leave it unprefixed (DEFAULT). The whole text is stored in the task description; the first 140 chars become the title.' },
+        agent: { type: 'string', description: 'Agent ID or name to dispatch to (default: claude-code-local). Use tascan_list_agents to see options. An unknown agent is an error, never a silent fallback.' },
+        priority: { type: 'string', enum: ['normal', 'urgent'], description: 'Priority level (default: normal). The urgent marker is placed AFTER the routing prefix so it never breaks routing.' }
       },
       required: ['task']
     },
@@ -317,10 +324,28 @@ const TOOLS = [
       try { registered = (await api('GET', '/agents')).data || []; } catch (e) { /* registry unreachable — fall back to seeds */ }
       const allAgents = [...AGENT_REGISTRY, ...dynamicAgents, ...registered.filter(r => !AGENT_REGISTRY.some(s => s.id === r.id))];
       const agentQuery = (args.agent || 'claude-code-local').toLowerCase();
-      const agent = allAgents.find(a => a.id === agentQuery || a.name.toLowerCase() === agentQuery) || allAgents[0];
-      const title = args.priority === 'urgent' ? `🔴 ${args.task}` : args.task;
-      const result = await api('POST', `/lists/${agent.inbox_id}/tasks`, [{ title, response_type: 'text' }]);
-      return `Task dispatched to ${agent.name}!\n\nAgent: ${agent.name} (${agent.id})\nType: ${agent.type}\nLocation: ${agent.location}\nTask: ${title}\nStatus: Queued — agent will pick this up automatically.\n\n${JSON.stringify(result.data, null, 2)}`;
+      const agent = allAgents.find(a => a.id === agentQuery || a.name.toLowerCase() === agentQuery);
+      // A typo must never silently land work on Mike's machine (the old `|| allAgents[0]` did exactly that).
+      if (!agent) throw new Error(`Unknown agent "${args.agent}".  Available: ${allAgents.map(a => a.id).join(', ')}`);
+      const text = String(args.task == null ? '' : args.task).trim();
+      if (!text) throw new Error('task is required');
+      const type = taskType(text);
+      if (agent.type === 'cloud' && LOCAL_ONLY_TASK_TYPES.includes(type)) {
+        return `Refused: the cloud agent cannot run ${type} tasks (text only: RESEARCH/WRITE/REVIEW/DEFAULT).  Dispatch to claude-code-local (or omit "agent").  Nothing was queued.`;
+      }
+      // Title = first 140 chars with the TYPE: prefix intact (runners and the scope gate route on the title
+      // prefix); the FULL text lives in description so nothing past 140 chars is lost.  The urgent marker
+      // goes AFTER the prefix — `🔴 CODE: …` used to defeat startsWith('CODE:') and fall to DEFAULT.
+      let title = text;
+      if (args.priority === 'urgent') {
+        const m = title.match(/^([A-Za-z]+:)\s*/);
+        title = m ? `${m[1]} 🔴 ${title.slice(m[0].length)}` : `🔴 ${title}`;
+      }
+      title = title.slice(0, 140);
+      const result = await api('POST', `/lists/${agent.inbox_id}/tasks`, [{ title, description: text, response_type: 'text' }]);
+      const created = (result.data && result.data[0]) || {};
+      const route = LOCAL_ONLY_TASK_TYPES.includes(type) ? 'local (Claude Code on Mike\'s PC)' : type === 'DEFAULT' ? 'local when the PC agent is alive, else cloud' : 'cloud (text only)';
+      return `Task dispatched (task_id: ${created.id || 'unknown'}) to ${agent.name} (${agent.id}).\nType: ${type} → route: ${route}\nTitle: ${title}\nStatus: queued.  Track it with tascan_get_task(task_id): the "agent" block goes queued → claimed → running → completed | failed; a run that dies is recorded as expired/failed and retried up to 3×.\n\n${JSON.stringify(result.data, null, 2)}`;
     }
   },
   {
@@ -344,7 +369,7 @@ const TOOLS = [
   },
   {
     name: 'tascan_register_agent',
-    description: 'Register a new AI agent in the agent registry. The agent will appear in tascan_list_agents and can receive dispatched tasks. Self-registration for AI agents joining the TaScan network.',
+    description: 'Register a new AI agent in the agent registry. The agent will appear in tascan_list_agents and can receive dispatched tasks. Self-registration for AI agents joining the TaScan network. REQUIRES the agent:dispatch permission (defining a dispatch target is a dispatch permission); inbox_id must be a task list (event) in your organization.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -395,7 +420,7 @@ const TOOLS = [
   },
   {
     name: 'tascan_get_task',
-    description: 'Get details of a specific task including completions and subtasks. Each completion carries photo_url (raw storage path, stable) and photo_signed_url (short-lived fetchable URL, ~1h; null when no photo) so you can actually view the photo evidence.',
+    description: 'Get details of a specific task including completions and subtasks. Each completion carries photo_url (raw storage path, stable) and photo_signed_url (short-lived fetchable URL, ~1h; null when no photo) so you can actually view the photo evidence. Tasks dispatched to an AI agent also carry an "agent" block (state claimed|running|completed|failed|expired|released, attempts, current run with runner/trace_id/error) — the only place agent failures are reported.',
     inputSchema: {
       type: 'object',
       properties: { task_id: { type: 'string', description: 'Task ID' } },
@@ -404,12 +429,59 @@ const TOOLS = [
     annotations: { title: 'Get Task', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args, api) => {
       const result = await api('GET', `/tasks/${args.task_id}`);
-      return JSON.stringify(result.data, null, 2);
+      const d = result.data || {};
+      let text = '';
+      if (d.agent) {
+        const a = d.agent, c = a.current || {};
+        text += `AGENT: state=${a.state} | failed/expired attempts=${a.attempts}/${a.max_attempts}` +
+          (c.runner ? ` | runner=${c.runner}` : '') + (c.trace_id ? ` | trace_id=${c.trace_id}` : '') +
+          (c.error ? `\nLast error: ${c.error}` : '') + (c.outcome ? `\nOutcome: ${String(c.outcome).slice(0, 300)}` : '') + '\n\n';
+      }
+      return text + JSON.stringify(d, null, 2);
+    }
+  },
+  {
+    name: 'tascan_get_receipt',
+    description: 'Fetch the signed Action Receipt (Ed25519 JWS) for one completed task. Takes the completion_id (tascan_get_task -> completions[].id). Returns a human-readable summary (what was done, by whom, verification level, evidence hashes, AI verification result, outcome, ledger chain) plus receipt_id/serial/kid, the compact JWS, and the public verify URL. Anyone can verify the JWS offline against the JWKS or online by POSTing {jws} to the verify URL. 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: 'Get Action Receipt', 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 env = await api('GET', `/receipts/${id}`);   // receipt.js returns the envelope itself (no data wrapper)
+      const r = (env.claims && env.claims.receipt) || {};
+      const v = x => (x && typeof x === 'object' && 'value' in x) ? x.value : x;
+      const a = r.action || {}, ex = r.executor || {}, ts = r.timestamps || {}, ver = r.verification || null, ch = r.chain || {};
+      const vr = ver ? v(ver.result) : null, vf = ver ? v(ver.verifier) : null;   // null Claims stay null (verification block is always present)
+      const verify = env.verify || {};
+      const lines = [
+        '=== TASCAN ACTION RECEIPT ===',
+        `Receipt: ${env.receipt_id}  (serial ${env.serial}, kid ${env.kid}, status ${env.status}, view ${env.view})`,
+        `Subject: ${env.subject}  (the Evidence row; the Action is task ${v(a.task_id)})`,
+        `Action: ${(env.private && env.private.title) || '(title signed as sha256 ' + String(v(a.title_sha256) || '').slice(0, 16) + '…)'}  [task ${v(a.task_id)} in list ${(env.private && env.private.list_name) || v(a.list_id)}]`,
+        `Executor: ${(env.private && env.private.executor_display) || v(ex.id) || 'unknown'} (${v(ex.kind)}, verification_level ${v(ex.verification_level)}${v(ex.runner) ? `, runner ${v(ex.runner)}, trace ${v(ex.trace_id)}, attempt ${v(ex.attempt)}` : ''})`,
+        `Outcome: ${v(r.outcome)}  | completed ${v(ts.completed)} | recorded ${v(ts.recorded)}`,
+        `Evidence: ${(r.evidence || []).map(e => `${v(e.type)} sha256:${String(v(e.sha256) || '').slice(0, 16)}...`).join(', ') || 'none'}`,
+        `Verification: ${vr ? `${vr.verified ? 'VERIFIED' : 'NOT verified'} (confidence ${vr.confidence}) by ${vf && vf.kind}${vf && vf.identity ? ' ' + vf.identity : ''}, policy ${v(ver.policy_id)}@${v(ver.policy_version)}${env.private && env.private.verification_reason ? ' - ' + env.private.verification_reason + ' (unsigned; sha256 signed)' : ''}` : 'none recorded'}`,
+        (() => { const t = v(a.target); return t ? `Target: ${(env.private && env.private.target_label) || '(label signed as sha256)'}${env.private && env.private.target_hardware_id ? ' hw ' + env.private.target_hardware_id : ''} [${t.type} ${t.id}, ${t.correlated_by}] (label + hardware id signed as sha256 only)` : null; })(),
+        `Ledger: ${v(ch.event_count)} events, head ${String(v(ch.ledger_head_hash) || '').slice(0, 16)}..., row matches signed snapshot: ${v(ch.row_matches_snapshot)}${(v(ch.mutated_fields) || []).length ? ' (mutated: ' + v(ch.mutated_fields).join(', ') + ')' : ''}`,
+        env.private && env.private.notes ? `Notes (unsigned; sha256 is in evidence): ${env.private.notes}` : null,
+        '',
+        `Verify online: POST ${verify.url}  body {"jws": "<JWS below>"}`,
+        `JWKS: ${verify.jwks}   Schema: ${verify.schema}   Signed at: ${env.signed_at}`,
+        '',
+        'JWS:', env.jws
+      ].filter(x => x !== null);
+      return lines.join('\n');
     }
   },
   {
     name: 'tascan_update_task',
-    description: 'Update a task (title, description, response_type, flags, sort_order)',
+    description: 'Update a task (title, description, response_type, flags, sort_order). A task that sits in an AI agent inbox is agent input (the runner executes title + description), so ANY edit to it needs the agent:dispatch permission — agent:dispatch:code when the task is or becomes CODE:/SHELL:.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -1079,12 +1151,12 @@ const TOOLS = [
       required: ['to_email', 'list_id']
     },
     annotations: { title: 'Send Task Email', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    handler: async (args) => {
-      // Call the send-task-email function directly via HTTP
+    handler: async (args, api) => {
+      // Call the send-task-email function directly via HTTP (S99: it now requires the caller's tsk_ key)
       const url = 'https://app.tascan.io/.netlify/functions/send-task-email';
       const resp = await fetch(url, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + ((api && api.key) || API_KEY) },
         body: JSON.stringify({
           to_email: args.to_email,
           to_name: args.to_name,
@@ -1444,10 +1516,10 @@ const TOOLS = [
       required: ['asset_id', 'photo_url']
     },
     annotations: { title: 'Assess Asset Condition', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    handler: async (args) => {
+    handler: async (args, api) => {
       const resp = await fetch('https://app.tascan.io/api/assess-condition', {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + ((api && api.key) || API_KEY) },
         body: JSON.stringify({ asset_id: args.asset_id, photo_url: args.photo_url, worker_name: args.worker_name || null, source: 'api' })
       });
       const data = await resp.json();