tascan-mcp 3.17.0 → 3.19.0

package/README.md

@@ -288,6 +288,12 @@ API keys are scoped to your organization and support rate limiting (60 requests/
 
 ## Changelog
 
+### v3.19.0 — 2026-09-28
+- **Quickstart (105 tools).** `tascan_quickstart` (`POST /api/v1/quickstart`, write tier) takes a new user from nothing to a receipt whose `verification.result.value` is true in one action: it reuses-or-creates the project "TaScan Quickstart", its list "Quickstart" and the worker "Quickstart executor", adds a new task "Reply with the exact text: <expected>" (`expected` defaults to `VERIFIED`), completes it with your key, has the new `exact_output` policy `quickstart_exact_output` v1 (migration 237) record `verified` or `refuted` (pass a different `response` to see the refutation), and publishes the receipt's public profile. It returns the receipt URL and the public verify URL. Completed means someone said it was done; verified means a named policy checked it and signed the result.
+
+### v3.18.0 — 2026-09-28
+- **Fan-out (phase 2, item 1: subagent seats), 104 tools.** A fan-out seat may now name `runner: 'local'` (`tascan_create_fanout` `seats[i].runner`, default `research`) — a seat claimable ONLY by its own registered local/subagent instance, never webhook-fired from the cloud. Three new tools over the seat's own run lifecycle (`/runs/claim`, `/runs/:id/heartbeat`, `/runs/:id/finish`, migration 229): `tascan_claim_run` (claims as `"<agent_id>:<anything>"`; a foreign instance is refused `seat_not_yours`, before routing is even evaluated), `tascan_heartbeat_run` (extends the lease; `{ok:false, reason:'not_live'}` means stop), `tascan_finish_run` (stores `document`[/`verification`] as the seat's own build artifacts, hashes `build_ref`, and finishes the run — a real signed completion, exactly like a research seat's or a CODE build's; zero changes to `coord_fanout_settle` / the barrier / the roll-up). All three require `agent:dispatch:code`; a run or task outside your org is 404, never 403.
+
 ### v3.17.0 — 2026-09-28
 - **Fan-out (phase 1b), 101 tools.** Three new tools over the phase 1a REST surface (`/coord/fanouts`, migration 224): `tascan_create_fanout` (1-30 RESEARCH seats plus one synthesizer under ONE cycle root T_F — zero Decision cards, zero Parked cards, zero pages per seat; requires `agent:dispatch:code`; fails closed `fanout_ceiling_unset` until the org owner sets a spending ceiling), `tascan_get_fanout` (`view=status|report|rollup|verify`, read tier), `tascan_control_fanout` (`pause|resume|cancel|close_barrier` — no `amend`, no `answer` in phase 1; requires `agent:dispatch:code`). `dry_run` on create is forwarded to the route as-is; the route has no server-side preflight for this path yet, so it does not yet prevent a real create — see the tool description.
 

package/package.json

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

package/scopes.cjs

@@ -224,6 +224,11 @@ const TOOL_SCOPES = {
   tascan_create_fanout: { tier: 'write', dispatch: 'code' },
   tascan_get_fanout: R,
   tascan_control_fanout: { tier: 'write', dispatch: 'code' },
+  // Fan-out phase 2 item 1 (2026-09-28): three tools over coord-run-lib.js's REST routes -- same shapes as
+  // ROUTE_SCOPES' runs_claim / run_heartbeat / run_finish above.
+  tascan_claim_run: { tier: 'write', dispatch: 'code' },
+  tascan_heartbeat_run: { tier: 'write', dispatch: 'code' },
+  tascan_finish_run: { 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
@@ -270,6 +275,8 @@ const TOOL_SCOPES = {
   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,
+  // Quickstart (migration 237): creates rows and a completion under the caller's org -- write tier, like tascan_complete_task.
+  tascan_quickstart: W,
   // B2 (migration 221): per-key budgets + delegated child keys. tascan_get_budget is the caller's own row (read
   // tier, same idiom as tascan_get_usage). tascan_delegate_to_agent mints (NOT destructiveHint — see tools.cjs);
   // tascan_revoke_delegation is destructive+idempotent. Both need write + delegate (owner-only to grant, I-6).
@@ -312,6 +319,7 @@ const ROUTE_SCOPES = {
   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 },
+  quickstart:          { POST: W },                         // POST /quickstart (migration 237): project+list+worker+task+completion+verdict+publish in one call
   task_subtasks:       { GET: R, POST: W },
   subtask:             { GET: R, PUT: W, DELETE: W },
   subtask_complete:    { POST: W },
@@ -368,6 +376,12 @@ const ROUTE_SCOPES = {
   coord_fanouts:       { GET: R, POST: { tier: 'write', dispatch: 'code' } },   // GET /coord/fanouts (list) / POST (create, T_F = CODE:/SHELL:-equivalent dispatch)
   coord_fanout:        { GET: R },                              // GET /coord/fanouts/:id[?view=status|report|rollup|verify]
   coord_fanout_control: { POST: { tier: 'write', dispatch: 'code' } },   // POST /coord/fanouts/:id/control (pause|resume|cancel|close_barrier)
+  // Fan-out phase 2 item 1 (2026-09-28): matched in coord-run-lib.js's own matchRunRoute, same D6/D8 idiom as the
+  // fan-out routes above -- a LOCAL fan-out seat's own run lifecycle (migration 229). coordRunLib's three handlers
+  // self-gate with these exact shapes too (belt-and-suspenders, same reason coord-fanout-lib.js documents).
+  runs_claim:          { POST: { tier: 'write', dispatch: 'code' } },    // POST /runs/claim -- claim_agent_run(p_runner='local') for a subagent seat
+  run_heartbeat:       { POST: { tier: 'write', dispatch: 'code' } },    // POST /runs/:id/heartbeat
+  run_finish:          { POST: { tier: 'write', dispatch: 'code' } },    // POST /runs/:id/finish -- stores document[/verification], finish_agent_run
   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

package/tools-fanout.cjs

@@ -7,25 +7,26 @@
 // over_ceiling, cap_below_plan, idempotency_body_mismatch, fanout_open_limit, seats_invalid, reserve_floor_unset,
 // no_authority, key_required) reaches the caller VERBATIM: api() (tascan-mcp/index.js / mcp-endpoint.js) throws
 // Error(data.error) on a non-2xx response and the transport prints "Error: <message>" unchanged -- this file adds
-// no try/catch around that path on purpose.  dry_run is forwarded to the route as-is (literal passthrough, the
-// brief's own word); the route built in 1a-ii has NO server-side preflight mode for this path (unlike
-// tascan_create_cycle's dry_run, which /coord/cycles DOES implement) -- a create call with dry_run true still
-// creates a REAL fan-out today.  Documented here, in the tool description and at runtime, rather than silently
-// guessed: fixing that gap means touching coord-fanout-lib.js, which is out of this brief's six deliverables.
+// no try/catch around that path on purpose.  dry_run is forwarded to the route as-is; coord-fanout-lib.js's
+// handleCreateFanout (229) honors it as a REAL preflight -- validation plus the ceiling/cap pre-check, no replay
+// lookup, no budget consumption, no coord_create_fanout call -- and returns {dry_run:true, plan_sha256, seats,
+// problems:[]} instead of a fanout_id.  Every seats[] entry also forwards runner ('research' default, 'local'
+// names a registered local/subagent seat) so a local-seat plan is never silently turned into an all-research plan.
 //
 // tascan_get_fanout: GET /coord/fanouts/:id?view=.  tascan_control_fanout: POST /coord/fanouts/:id/control, action
 // enum WITHOUT amend and WITHOUT answer (master: no such actions in phase 1) -- exactly coord-fanout-lib.js's own
-// CONTROL_ACTIONS.
+// CONTROL_ACTIONS.  'retry_synth' (migration 232) added alongside pause/resume/cancel/close_barrier: mints a synth
+// revision when the current synth's every failed run is input_ref_mismatch.
 'use strict';
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const VIEWS = ['status', 'report', 'rollup', 'verify'];
-const CONTROL_ACTIONS = ['pause', 'resume', 'cancel', 'close_barrier'];
+const CONTROL_ACTIONS = ['pause', 'resume', 'cancel', 'close_barrier', 'retry_synth'];
 
 module.exports = [
   {
     name: 'tascan_create_fanout',
-    description: 'Create a fan-out: 1-30 RESEARCH seats plus one synthesizer under ONE cycle root T_F (POST /coord/fanouts). Zero Decision cards, zero Parked cards, zero pages per seat -- only a control action or the closing roll-up reaches a human. Requires an API key with agent:dispatch:code -- an admin session has no dispatch budget (key_required). Consumes seats.length + 1 dispatch units BEFORE the authoritative create; a refusal only the RPC can see (cap_below_plan, fanout_open_limit, bad agent_id, reserve_floor_unset) still consumes them, by design. Fails closed fanout_ceiling_unset until the owner sets a ceiling; over_ceiling when cap exceeds it. idempotency_key replays duplicate within 24h on the same plan, else idempotency_body_mismatch. dry_run is forwarded as-is; the route has no preflight mode yet, so dry_run true still creates for real -- never a way to avoid creating. Leaves fanout_created; every seat, the synth and the roll-up leave their own signed completion. Track with tascan_get_fanout.',
+    description: 'Create a fan-out: 1-30 seats (RESEARCH by default, or LOCAL subagent seats) plus one synthesizer under ONE cycle root T_F (POST /coord/fanouts). Zero Decision cards, zero Parked cards, zero pages per seat -- only a control action or the closing roll-up reaches a human. Requires an API key with agent:dispatch:code -- an admin session has no dispatch budget (key_required). dry_run true runs the same validation plus the ceiling/cap pre-check and returns {dry_run:true, plan_sha256, seats, problems:[]} WITHOUT consuming budget or creating anything -- a real preflight, not a real create. Otherwise consumes seats.length + 1 dispatch units BEFORE the authoritative create; a refusal only the RPC can see (cap_below_plan, fanout_open_limit, bad agent_id, reserve_floor_unset) still consumes them, by design. Fails closed fanout_ceiling_unset until the owner sets a ceiling; over_ceiling when cap exceeds it. idempotency_key replays duplicate within 24h on the same plan, else idempotency_body_mismatch. Leaves fanout_created; every seat, the synth and the roll-up leave their own signed completion. Track with tascan_get_fanout.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -39,7 +40,8 @@ module.exports = [
             properties: {
               agent_id: { type: 'string', description: 'A registered agent_registry id in this org, matching ^[a-z][a-z0-9-]{0,39}$. Never a system-* worker.' },
               brief: { type: 'string', description: 'This seat\'s own prompt (1-40000 chars). Falls back to seat_defaults.brief when omitted -- one of the two is required.' },
-              role: { type: 'string', description: 'Optional label for this seat (1-100 chars), e.g. "topic A".' }
+              role: { type: 'string', description: 'Optional label for this seat (1-100 chars), e.g. "topic A".' },
+              runner: { type: 'string', enum: ['research', 'local'], description: 'Default "research" (the cloud runner claims it). "local" names a registered local/subagent agent_id -- only that agent, claiming as itself (tascan_claim_run instance starting with "<agent_id>:"), can claim the seat; it is never webhook-fired.' }
             },
             required: ['agent_id']
           }
@@ -70,7 +72,7 @@ module.exports = [
         seat_review: { type: 'string', enum: ['per_seat', 'none'], description: 'per_seat mints one review per seat (allowed for at most 10 seats); none skips seat review. Default per_seat for <=10 seats, none above that.' },
         cap: { type: 'integer', description: 'This fan-out\'s total micro-USD budget, synth reserve included. Refused over_ceiling if it exceeds the org\'s fan-out spending ceiling.' },
         idempotency_key: { type: 'string', description: 'Optional replay key (<= 200 chars). The same key within 24h on the same plan returns duplicate:true with the existing fanout_id; on a different plan it is refused idempotency_body_mismatch.' },
-        dry_run: { type: 'boolean', description: 'Forwarded to POST /coord/fanouts as given. The route has no server-side preflight for this path today, so true still performs a REAL create -- do not rely on it to avoid creating a fan-out.' }
+        dry_run: { type: 'boolean', description: 'true runs the same validation plus the ceiling/cap pre-check and returns {dry_run:true, plan_sha256, seats, problems:[]} WITHOUT consuming budget or creating a fan-out -- a real preflight, not a real create.' }
       },
       required: ['project_id', 'title', 'seats', 'synth', 'cap']
     },
@@ -89,7 +91,8 @@ module.exports = [
         seats: args.seats.map(s => ({
           agent_id: s && s.agent_id,
           ...(s && s.brief != null ? { brief: s.brief } : {}),
-          ...(s && s.role != null ? { role: s.role } : {})
+          ...(s && s.role != null ? { role: s.role } : {}),
+          ...(s && s.runner != null ? { runner: s.runner } : {})
         })),
         synth: { brief: args.synth.brief, max_cost_micro_usd: args.synth.max_cost_micro_usd },
         cap: args.cap
@@ -103,17 +106,16 @@ module.exports = [
 
       const result = await api('POST', '/coord/fanouts', body, args.idempotency_key);
       const d = result.data || {};
+      if (d.dry_run) {
+        return `DRY RUN — nothing was created, no budget consumed.\nplan_sha256: ${d.plan_sha256}\nseats: ${d.seats}\nproblems: ${JSON.stringify(d.problems || [])}`;
+      }
       if (d.duplicate) {
         return `DUPLICATE — nothing was created.  A fan-out with the same idempotency_key and plan exists from the last 24h.\nfanout_id: ${d.fanout_id}\n\nRead it: tascan_get_fanout fanout_id=${d.fanout_id}`;
       }
       const seatLines = Array.isArray(d.seats)
         ? d.seats.map(s => `  seat-${String(s.seat_no).padStart(2, '0')}: ${s.seat_id} (${s.released ? 'released' : 'held on T_F'}, ${s.status})`).join('\n')
         : '  (none returned)';
-      let text = `Fan-out created.\nfanout_id (T_F): ${d.fanout_id}\nplan_sha256: ${d.plan_sha256}\nstatus: ${d.status}\nsynth_task_id: ${d.synth_task_id}\npoll_after_s: ${d.poll_after_s}\nseats:\n${seatLines}\n\nFollow with tascan_get_fanout fanout_id=${d.fanout_id} (view=status).`;
-      if (dryRun) {
-        text = 'NOTE: dry_run has no server-side preflight on this route yet — the fan-out below was created for REAL, not simulated.\n\n' + text;
-      }
-      return text;
+      return `Fan-out created.\nfanout_id (T_F): ${d.fanout_id}\nplan_sha256: ${d.plan_sha256}\nstatus: ${d.status}\nsynth_task_id: ${d.synth_task_id}\npoll_after_s: ${d.poll_after_s}\nseats:\n${seatLines}\n\nFollow with tascan_get_fanout fanout_id=${d.fanout_id} (view=status).`;
     }
   },
   {
@@ -140,12 +142,12 @@ module.exports = [
   },
   {
     name: 'tascan_control_fanout',
-    description: 'Control a running fan-out (POST /coord/fanouts/:id/control). pause holds every unclaimed seat and stops the orphan pass from re-firing them; resume releases them again; cancel supersedes every unclaimed task and closes once quiescent; close_barrier drops unsettled or named exclude_seats and forces the synth barrier now instead of waiting for more seats. No amend and no answer in phase 1. Every action mints a signed control-child completion FIRST, as the org\'s own system worker (coord_fanout_control_receipt) — never coord_dispatcher_action, so a control action can never sign into another org\'s Chief of Staff identity. idempotency_key replays the prior outcome (replayed:true) and applies nothing twice; a replayed resume after a later pause leaves the fan-out paused. Refused fanout_closed once the roll-up has closed. Requires agent:dispatch:code.',
+    description: 'Control a running fan-out (POST /coord/fanouts/:id/control). pause holds every unclaimed seat and stops the orphan pass from re-firing them; resume releases them again; cancel supersedes every unclaimed task and closes once quiescent; close_barrier drops unsettled or named exclude_seats and forces the synth barrier now instead of waiting for more seats; retry_synth (migration 232) mints a new synth revision from the current synth\'s own stored inputs, correctly ordered, when every one of its failed runs is input_ref_mismatch -- refused otherwise (not_synthesizing, no_synth_task, no_failed_runs, not_input_ref_mismatch). No amend and no answer in phase 1. Every action mints a signed control-child completion FIRST, as the org\'s own system worker (coord_fanout_control_receipt) — never coord_dispatcher_action, so a control action can never sign into another org\'s Chief of Staff identity. idempotency_key replays the prior outcome (replayed:true) and applies nothing twice; a replayed resume after a later pause leaves the fan-out paused. Refused fanout_closed once the roll-up has closed. Requires agent:dispatch:code.',
     inputSchema: {
       type: 'object',
       properties: {
         fanout_id: { type: 'string', description: 'Fan-out id (UUID) — the T_F root.' },
-        action: { type: 'string', enum: CONTROL_ACTIONS, description: 'pause, resume, cancel or close_barrier. No amend, no answer (phase 1).' },
+        action: { type: 'string', enum: CONTROL_ACTIONS, description: 'pause, resume, cancel, close_barrier or retry_synth. No amend, no answer (phase 1).' },
         reason: { type: 'string', description: 'Optional free-text reason (<= 4000 chars), recorded on the control child\'s completion.' },
         exclude_seats: { type: 'array', items: { type: 'integer' }, description: 'close_barrier only: 1-based seat numbers to drop from the barrier instead of waiting for them to settle.' },
         idempotency_key: { type: 'string', description: 'Optional replay key (<= 200 chars). The same key returns the prior outcome (replayed:true) and applies nothing a second time.' }

package/tools-runs.cjs

@@ -0,0 +1,110 @@
+// Fan-out phase 2, item 1 (2026-09-28, briefs/2026-09-28-fanout-phase2-subagent-seats.md): three MCP tools over
+// coord-run-lib.js's REST surface (POST /runs/claim, POST /runs/:id/heartbeat, POST /runs/:id/finish) -- never
+// Supabase directly, same split-file pattern as tools-devices.cjs / tools-fanout.cjs (spread into TOOLS by one
+// line there).
+//
+// The Workflow: a fan-out seat named with runner:'local' (tascan_create_fanout, seats[i].runner) is claimable ONLY
+// by its own registered agent -- p_instance ("<agent_id>:<anything>") must start with the seat's own coord.agent_id
+// (migration 229's claim_agent_run gate). A subagent that is new registers itself first (tascan_register_agent,
+// type 'local' or 'subagent'), then: tascan_claim_run -> works -> tascan_finish_run with its document. The seat's
+// completion is a normal, signed TaScan receipt (tascan_get_receipt), exactly like a research seat's or a CODE
+// build's -- coord_fanout_settle / the barrier / the roll-up need no awareness that the seat was local at all
+// (migration 229's own header note: "prove it, do not re-implement it").
+'use strict';
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+module.exports = [
+  {
+    name: 'tascan_claim_run',
+    description: 'Claim a fan-out seat task as a LOCAL subagent run (POST /runs/claim -> claim_agent_run(p_runner=\'local\')). Only admitted when instance starts with "<your registered agent_id>:" -- the seat\'s own coord.agent_id, set when the fan-out was created (tascan_create_fanout seats[i].runner=\'local\'). Any other instance is refused, claimed false with reason seat_not_yours -- this tool never claims a seat that is not yours, and never claims a cloud (research) seat at all (refused not_routable). Never mints a completion or a receipt by itself -- claiming only opens the run; work happens after, and tascan_finish_run is what leaves the signed receipt. Requires agent:dispatch:code. A foreign or unknown task_id is 404, never 403 (S2: another org\'s task never even appears to exist).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The seat task ID (UUID) -- from tascan_create_fanout\'s seats[] or tascan_get_fanout (view=status/report).' },
+        instance: { type: 'string', description: 'Your claim identity, "<agent_id>:<anything>" -- e.g. "researcher-07:host-1234". Must start with the seat\'s own registered agent_id or the claim is refused seat_not_yours.' },
+        ttl_seconds: { type: 'integer', description: 'Optional lease length in seconds (60-86400, default 1800). Extend it later with tascan_heartbeat_run instead of claiming a longer one up front.' }
+      },
+      required: ['task_id', 'instance']
+    },
+    annotations: { title: 'Claim Run', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    handler: async (args, api) => {
+      const taskId = String(args.task_id || '').trim();
+      if (!UUID_RE.test(taskId)) throw new Error('task_id must be a UUID');
+      const instance = typeof args.instance === 'string' ? args.instance.trim() : '';
+      if (!instance) throw new Error('instance is required, "<agent_id>:<anything>"');
+      const body = { task_id: taskId, instance };
+      if (args.ttl_seconds != null) body.ttl_seconds = args.ttl_seconds;
+      const result = await api('POST', '/runs/claim', body);
+      const d = result.data || {};
+      if (d.claimed !== true) {
+        return `NOT claimed -- reason: ${d.reason}\n\n${JSON.stringify(d, null, 2)}`;
+      }
+      return `Claimed. run_id: ${d.run_id}\nroute: ${d.route}\nattempt: ${d.attempt} / max_attempts: ${d.max_attempts}\nexpires_at: ${d.expires_at}\ncycle_root: ${d.cycle_root}\nbuild_ref (the cycle's own binding, if any): ${d.build_ref}\n\nNext: work, optionally tascan_heartbeat_run before the lease expires, then tascan_finish_run with your document.`;
+    }
+  },
+  {
+    name: 'tascan_heartbeat_run',
+    description: 'Extend a claimed local run\'s lease and mark it running (POST /runs/:run_id/heartbeat -> heartbeat_agent_run). ok false with reason not_live means the run is no longer yours -- the sweep expired it, or it was never yours to begin with -- STOP, do not finish it. Never mints a completion or a receipt. Requires agent:dispatch:code. A run outside your org is 404, never 403.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        run_id: { type: 'string', description: 'The run ID from tascan_claim_run\'s response.' },
+        instance: { type: 'string', description: 'The SAME instance string you claimed with -- a mismatch answers not_live.' },
+        extend_seconds: { type: 'integer', description: 'Optional: push expires_at out to now + this many seconds (60-86400) if that is later than the current lease -- never shortens it.' }
+      },
+      required: ['run_id', 'instance']
+    },
+    annotations: { title: 'Heartbeat Run', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (args, api) => {
+      const runId = String(args.run_id || '').trim();
+      if (!UUID_RE.test(runId)) throw new Error('run_id must be a UUID');
+      const instance = typeof args.instance === 'string' ? args.instance.trim() : '';
+      if (!instance) throw new Error('instance is required (the same one you claimed with)');
+      const body = { instance };
+      if (args.extend_seconds != null) body.extend_seconds = args.extend_seconds;
+      const result = await api('POST', `/runs/${runId}/heartbeat`, body);
+      const d = result.data || {};
+      return d.ok ? `Alive. state: ${d.state}, expires_at: ${d.expires_at}, attempt: ${d.attempt}` : `NOT live -- reason: ${d.reason}, state: ${d.state}. Stop; do not finish this run.`;
+    }
+  },
+  {
+    name: 'tascan_finish_run',
+    description: 'Finish a claimed local run (POST /runs/:run_id/finish). outcome=\'completed\' stores `document` (and optional `verification`) as the seat\'s own build artifacts under EXACTLY the artifact_paths the fan-out named for this seat, hashes them into build_ref, and finishes the run -- this mints a real task_completions row and a SIGNED TASCAN RECEIPT for your work (tascan_get_receipt), the same as any other build; `document` is your deliverable and IS what gets hashed, so send the real content, not a summary. Zero changes to coord_fanout_settle / the barrier / the roll-up -- your completion releases the next held seat and, once every seat settles, feeds the fan-out\'s own synthesizer and rollup exactly like a cloud research seat\'s would. outcome=\'failed\' finishes the run failed with your `error` text and stores nothing. Requires agent:dispatch:code. A run outside your org, or already finished, is refused (404 / the RPC\'s own not_live).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        run_id: { type: 'string', description: 'The run ID from tascan_claim_run\'s response.' },
+        instance: { type: 'string', description: 'The SAME instance string you claimed with.' },
+        outcome: { type: 'string', enum: ['completed', 'failed'], description: '\'completed\' stores your document and mints a signed completion; \'failed\' stores nothing.' },
+        document: { type: 'string', description: 'Required when outcome is completed. The seat\'s deliverable -- hashed as build_ref, stored verbatim under the seat\'s own artifact_paths.' },
+        verification: { type: 'string', description: 'Optional second document (a short verification/self-check note) -- stored as the seat\'s second artifact_path when the fan-out named two.' },
+        error: { type: 'string', description: 'Required when outcome is failed -- why (up to 4000 chars).' },
+        cost_micro_usd: { type: 'integer', description: 'Optional micro-USD cost to record against the cycle\'s own budget (default 0 -- a Claude Code subscription seat has no per-call API cost to report).' }
+      },
+      required: ['run_id', 'instance', 'outcome']
+    },
+    annotations: { title: 'Finish Run', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    handler: async (args, api) => {
+      const runId = String(args.run_id || '').trim();
+      if (!UUID_RE.test(runId)) throw new Error('run_id must be a UUID');
+      const instance = typeof args.instance === 'string' ? args.instance.trim() : '';
+      if (!instance) throw new Error('instance is required (the same one you claimed with)');
+      const outcome = String(args.outcome || '');
+      if (!['completed', 'failed'].includes(outcome)) throw new Error('outcome must be "completed" or "failed"');
+      if (outcome === 'completed' && (typeof args.document !== 'string' || !args.document.trim())) {
+        throw new Error('document is required when outcome is "completed"');
+      }
+      const body = { instance, outcome };
+      if (args.document != null) body.document = args.document;
+      if (args.verification != null) body.verification = args.verification;
+      if (args.error != null) body.error = args.error;
+      if (args.cost_micro_usd != null) body.cost_micro_usd = args.cost_micro_usd;
+      const result = await api('POST', `/runs/${runId}/finish`, body);
+      const d = result.data || {};
+      if (outcome === 'failed') return `Finished failed. ok: ${d.ok}, state: ${d.state}.`;
+      if (d.ok === false) return `NOT accepted -- reason: ${d.reason}, state: ${d.state}. The seat is still unfinished; nothing was released.`;
+      return `Finished completed. completion_id: ${result.completion_id}\nbuild_ref: ${result.build_ref}\nrun state: ${d.state}${d.advance ? '\nadvance: ' + JSON.stringify(d.advance) : ''}\n\nThis is a signed receipt -- tascan_get_receipt completion_id=${result.completion_id} to fetch it.`;
+    }
+  }
+];

package/tools.cjs

@@ -2823,10 +2823,44 @@ const TOOLS = [
       return d.already_revoked ? `Key ${args.key_id} was already revoked.` : `Key ${args.key_id} revoked.`;
     }
   },
+  // Quickstart (migration 237): one action to a verified receipt.
+  {
+    name: 'tascan_quickstart',
+    description: 'One action to a genuinely verified receipt (POST /quickstart). Under your org it reuses-or-creates the project "TaScan Quickstart", its list "Quickstart" and the worker "Quickstart executor", adds a NEW task "Reply with the exact text: <expected>", completes it with your key, has the named policy quickstart_exact_output v1 compare the response to the expected text (verified or refuted, signed into the receipt), and publishes the receipt\'s public profile. expected defaults to "VERIFIED" (max 200 chars); response defaults to expected — pass a different response to see a refuted receipt. Returns the receipt URL and the public verify URL. Write tier.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        expected: { type: 'string', description: 'The exact text the task asks for (default "VERIFIED", max 200 chars).' },
+        response: { type: 'string', description: 'The response to submit (default: the expected text). A different value is refuted.' }
+      }
+    },
+    annotations: { title: 'Quickstart: First Verified Receipt', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    handler: async (args, api) => {
+      const body = {};
+      if (args.expected != null) body.expected = args.expected;
+      if (args.response != null) body.response = args.response;
+      const result = await api('POST', '/quickstart', body);
+      const d = result.data || {};
+      const pol = d.policy || {};
+      const lines = [
+        `Created (or reused by name): project "TaScan Quickstart" ${d.project_id}, list "Quickstart" ${d.list_id}, worker "Quickstart executor" ${d.worker_id}, and a new task ${d.task_id}.`,
+        'Completed: yes (by your key)',
+        d.verified
+          ? `Verified: yes — policy ${pol.id} v${pol.version} compared the response to the expected text`
+          : 'Verified: NO — the response did not match; the receipt records the refutation',
+        `Receipt: ${d.receipt_url}`,
+        `Public verify page: ${d.verify_url}` + (d.published ? '' : ` (not public yet — publish failed: ${d.publish_error || 'unknown'})`),
+        'Completed means someone said it was done. Verified means a named policy checked it and signed the result.'
+      ];
+      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'),
   // Fan-out phase 1b (2026-09-28): three tools over the 1a-ii REST surface — split out, same reason.
-  ...require('./tools-fanout.cjs')
+  ...require('./tools-fanout.cjs'),
+  // Fan-out phase 2 item 1 (2026-09-28): three tools over a LOCAL seat's own run lifecycle — split out, same reason.
+  ...require('./tools-runs.cjs')
 ];
 
 module.exports = { TOOLS, AGENT_REGISTRY, dynamicAgents };