@volter/supercode-orchestrator 0.4.4

package/mcp/bridge.mjs

@@ -0,0 +1,133 @@
+// The loop side of the model-facing door (docs/ORCHESTRATOR-IR.md §7).
+//
+// One local Unix socket per running orchestrator, at `<root>/orchestrator.sock`,
+// opened by `Orchestrator.start()` and closed by `stop()`. Every per-session
+// MCP server (`mcp/server.mjs`) is a client of it: one JSON line in, one JSON
+// line out, one request per connection.
+//
+// TWO families share the one line protocol, told apart by which key the line
+// carries — `verb` (the model's tools) or `op` (the operator's verbs, ORC-13):
+//
+//   MODEL (§7, one per published MCP tool; the binding comes from the loop)
+//   in   {"verb":"cronjob_create","args":{…},"profile":"coder","surface":"loopback|group|coder-room||"}
+//   out  {"ok":true,"result":{"ran":"created cron job …", …}}
+//        {"ok":false,"error":"…"}
+//
+//   OPERATOR (§4.6, the write door `supercode <noun> <verb> --harness
+//   orchestrator` drives; `profile` defaults to `default`, no surface)
+//   in   {"op":"jobs.create","args":{…},"profile":"coder"}
+//   out  {"ok":true,"result":{"ran":"created cron job …","job":{…}}}
+//        {"ok":false,"error":"jobs_delete: no job job_x"}
+//
+//   op ∈ jobs.create | jobs.update | jobs.pause | jobs.resume | jobs.run |
+//        jobs.delete | profiles.create | profiles.delete | sessions.new |
+//        sessions.reset | access.pair_approve
+//
+// Both families dispatch `events.operator(...)` on the LOOP'S OWN QUEUE, so an
+// operator write is ordered against inbound messages and ticks like anything
+// else, and `save()` inside this package stays the only writer of the folder.
+// The answer's `result` re-reads the affected record out of state after the
+// reducer ran; a verb the reducer refused answers `{ok:false}` carrying the
+// reducer's own log line, never a silent no-op.
+//
+// The socket is the trust boundary: it lives inside the orchestrator root, so
+// its reachability is the root's file permissions. The binding it is told
+// about is the one the loop itself put in the worker's environment.
+
+import { SOCKET_ENV } from './server.mjs';
+import { createServer } from 'node:net';
+import { rmSync } from 'node:fs';
+import { runVerb } from './verbs.mjs';
+import { applyOperator } from '../operator.mjs';
+
+export { socketPathFor } from './server.mjs';
+
+/**
+ * Open the bridge. `orch` is the running Orchestrator; each line is dispatched
+ * through `runVerb`, whose effects are performed on the loop's own queue so a
+ * tool call is ordered against inbound messages and ticks.
+ */
+export function startBridge({ orch, socketPath, log = () => {} }) {
+  // a Unix socket's path is bounded by the kernel (104 bytes on macOS, 108 on Linux); past it listen fails
+  // with a bare EINVAL, so the bound is said by name, with the way around it
+  const limit = process.platform === 'darwin' ? 103 : 107;
+  if (Buffer.byteLength(socketPath) > limit) {
+    return Promise.reject(new Error(`the orchestrator's socket path ${socketPath} is ${Buffer.byteLength(socketPath)} bytes, past this system's ${limit}; set ${SOCKET_ENV} to a shorter path (for example under /tmp), or use a shorter home`));
+  }
+  rmSync(socketPath, { force: true }); // a socket left by a killed daemon
+  const sockets = new Set();
+  const server = createServer((socket) => {
+    sockets.add(socket);
+    socket.setEncoding('utf8');
+    socket.on('close', () => sockets.delete(socket));
+    socket.on('error', () => sockets.delete(socket));
+    let buffer = '';
+    socket.on('data', async (chunk) => {
+      buffer += chunk;
+      const nl = buffer.indexOf('\n');
+      if (nl < 0) return;
+      const line = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + 1);
+      let answer;
+      try {
+        const call = JSON.parse(line);
+        answer = await dispatch(orch, call, log);
+      } catch (error) {
+        answer = { ok: false, error: error.message };
+      }
+      socket.write(`${JSON.stringify(answer)}\n`);
+      socket.end();
+    });
+  });
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(socketPath, () => {
+      server.removeListener('error', reject);
+      resolve({
+        path: socketPath,
+        async close() {
+          for (const socket of sockets) socket.destroy();
+          sockets.clear();
+          await new Promise((done) => server.close(done));
+          rmSync(socketPath, { force: true });
+        },
+      });
+    });
+  });
+}
+
+async function dispatch(orch, call, log) {
+  const { verb, op, args, profile, surface } = call ?? {};
+  if (typeof op === 'string' && op) return dispatchOperator(orch, { op, args, profile }, log);
+  if (typeof verb !== 'string' || !verb) return { ok: false, error: 'verb (a model tool) or op (an operator verb) is required' };
+  if (typeof profile !== 'string' || !profile) return { ok: false, error: 'profile is required' };
+  try {
+    // Mutating verbs dispatch operator events onto the loop's queue themselves
+    // (§4.6): the reducer is the only thing that changes state.
+    const { result, error } = await runVerb(orch, { verb, args: args ?? {}, profile, surface: surface ?? null });
+    if (error) return { ok: false, error };
+    log('info', `mcp ${verb} on ${profile}: ${result.ran}`);
+    return { ok: true, result };
+  } catch (error) {
+    log('warn', `mcp ${verb} on ${profile}: ${error.message}`);
+    return { ok: false, error: error.message };
+  }
+}
+
+/**
+ * The operator family (§4.6). One shared implementation with the cold path
+ * (`operator.mjs`); the only thing the daemon adds is that the events land on
+ * the loop's queue.
+ */
+async function dispatchOperator(orch, { op, args, profile }, log) {
+  const name = typeof profile === 'string' && profile ? profile : 'default';
+  let answer;
+  try {
+    answer = await applyOperator(orch.state, op, args ?? {}, name, orch.clock(), (event) => orch.dispatch(event));
+  } catch (error) {
+    answer = { ok: false, error: error.message };
+  }
+  if (answer.ok) log('info', `operator ${op} on ${name}: ${answer.result.ran}`);
+  else log('warn', `operator ${op} on ${name}: ${answer.error}`);
+  return answer;
+}

package/mcp/hermes-kanban-tools.json

@@ -0,0 +1,477 @@
+[
+  {
+    "name": "kanban_show",
+    "description": "Read a task's full state — title, body, assignee, parent task handoffs, your prior attempts on this task if any, comments, and recent events. Use this to (re)orient yourself before starting work, especially on retries. The response includes a pre-formatted ``worker_context`` string suitable for inclusion verbatim in your reasoning.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "kanban_list",
+    "description": "List Kanban task summaries so an orchestrator profile can discover work to route. Supports the same core filters as the CLI: assignee, status, tenant, include_archived, and limit. Returns compact rows with ids, title, status, assignee, priority, parent/child ids, and counts. Bounded to 50 rows by default, 200 max, with truncation metadata. Also recomputes ready tasks before listing, matching the CLI. Orchestrator-only — dispatcher-spawned task workers never see this tool.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "assignee": {
+          "type": "string",
+          "description": "Optional assignee/profile filter."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "triage",
+            "todo",
+            "ready",
+            "running",
+            "blocked",
+            "done",
+            "archived"
+          ],
+          "description": "Optional task status filter."
+        },
+        "tenant": {
+          "type": "string",
+          "description": "Optional tenant/project namespace filter."
+        },
+        "include_archived": {
+          "type": "boolean",
+          "description": "Include archived tasks. Defaults to false."
+        },
+        "limit": {
+          "type": "integer",
+          "description": "Optional maximum rows to return (default 50, max 200)."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "kanban_complete",
+    "description": "Mark your current task done with a structured handoff for downstream workers and humans. Prefer ``summary`` for a human-readable 1-3 sentence description of what you did; put machine-readable facts in ``metadata`` (changed_files, tests_run, decisions, findings, etc). At least one of ``summary`` or ``result`` is required. If you created new tasks via ``kanban_create`` during this run, list their ids in ``created_cards`` — the kernel verifies them so phantom references are caught before they leak into downstream automation. If you produced deliverable files (charts, PDFs, spreadsheets, generated images), list their absolute paths in ``artifacts`` — the gateway notifier will upload them as native attachments to the human who subscribed to the task, so the deliverable lands in their chat alongside the summary instead of being a path they have to fetch by hand.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
+        },
+        "summary": {
+          "type": "string",
+          "description": "Human-readable handoff, 1-3 sentences. Appears in Run History on the dashboard and in downstream workers' context."
+        },
+        "metadata": {
+          "type": "object",
+          "description": "Free-form dict of structured facts about this attempt — {\"changed_files\": [...], \"tests_run\": 12, \"findings\": [...]}. Surfaced to downstream workers alongside ``summary``."
+        },
+        "result": {
+          "type": "string",
+          "description": "Short result log line (legacy field, maps to task.result). Use ``summary`` instead when possible; this exists for compatibility with callers that still set --result on the CLI."
+        },
+        "created_cards": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional structured manifest of task ids you created via ``kanban_create`` during this run. The kernel verifies each id exists and was created by this worker's profile; any phantom id blocks the completion with an error listing what went wrong (auditable in the task's events). Only list ids you got back from a successful ``kanban_create`` call — do not invent or remember ids from prose. Omit the field if you did not create any cards."
+        },
+        "artifacts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional list of absolute paths to deliverable files you produced during this run — generated charts, PDFs, spreadsheets, images, archives. Examples: [\"/tmp/q3-revenue.png\", \"/tmp/report.pdf\"]. The gateway notifier uploads each path as a native attachment to the subscribed chat (images embed inline, everything else uploads as a file) so the deliverable lands with the completion notification. Skip intermediate scratch files and references that are not the deliverable. The path must exist on disk at completion. Files inside a managed scratch workspace are copied to durable task attachments before cleanup; a missing declared scratch artifact keeps the task in-flight so you can fix the path and retry."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "kanban_block",
+    "description": "Stop work on this task and route it according to WHY you're stuck. Set ``kind`` to say which: 'dependency' (waiting on another task — goes to todo and auto-resumes when that task finishes, no human needed), 'needs_input' (you need a human decision/answer), 'capability' (a hard wall: no access, missing credentials, an action no agent can do), or 'transient' (a flaky failure that may clear). ``reason`` is shown to the human on the board. If a task keeps getting unblocked and re-blocked for the same reason, it is auto-escalated to triage. Use for genuine blockers only — don't block on things you can resolve yourself.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
+        },
+        "reason": {
+          "type": "string",
+          "description": "What you need answered or what stopped you, in one or two sentences. Don't paste the whole conversation; the human has the board and can ask follow-ups via comments."
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "dependency",
+            "needs_input",
+            "capability",
+            "transient"
+          ],
+          "description": "Why you're blocked. 'dependency' waits in todo and resumes automatically; the others surface to a human. Omit only if none apply."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": [
+        "reason"
+      ]
+    }
+  },
+  {
+    "name": "kanban_request_review",
+    "description": "Hand the task off for review: implementation, self-review, and verification are complete and you want a human (or reviewer) to look before it is marked done. Moves the task to the 'review' column and notifies the subscriber. Unlike ``kanban_block`` this is NOT a blocker — it never counts toward unblock-loop detection, so a task can cycle through review across follow-ups without ever being falsely escalated to triage. Use this instead of blocking with a free-form 'review-required:' reason.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
+        },
+        "summary": {
+          "type": "string",
+          "description": "What was implemented and how it was verified, in one or two sentences — shown to the reviewer. Don't paste the whole diff; the reviewer has the board and the PR."
+        },
+        "reviewer": {
+          "type": "string",
+          "description": "Optional reviewer profile. When provided, the task is reassigned to that profile before review dispatch."
+        },
+        "metadata": {
+          "type": "object",
+          "description": "Optional structured handoff facts for the reviewer, such as changed_files, tests_run, commit, or decisions.",
+          "additionalProperties": true
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": [
+        "summary"
+      ]
+    }
+  },
+  {
+    "name": "kanban_request_changes",
+    "description": "Reviewer verdict: return the current review run to the original implementer with concrete required changes. This closes the review run, reapplies parent dependency gating, and requeues the task without using block-loop accounting. Only use from a task claimed from the review column; use kanban_block only for a genuine external blocker.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
+        },
+        "reason": {
+          "type": "string",
+          "description": "Specific, actionable changes the implementer must make before requesting another review."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": [
+        "reason"
+      ]
+    }
+  },
+  {
+    "name": "kanban_heartbeat",
+    "description": "Signal that you're still alive during a long operation (training, encoding, large crawls). Call every few minutes so humans see liveness separately from PID checks. Pure side effect — no work changes.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional short note describing current progress. Shown in the event log."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "kanban_comment",
+    "description": "Append a comment to a task's thread. Use for durable notes that should outlive this run (questions for the next worker, partial findings, rationale). Ephemeral reasoning doesn't belong here — use your normal response instead.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. Required (may be your own task or another's — comment threads are per-task)."
+        },
+        "body": {
+          "type": "string",
+          "description": "Markdown-supported comment body."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": [
+        "task_id",
+        "body"
+      ]
+    }
+  },
+  {
+    "name": "kanban_attach",
+    "description": "Attach a file to a task by passing its bytes inline (base64). Use for genuine file artifacts the next worker or a human should be able to download — generated reports, images, exports. The file is stored as a real attachment (not a comment link) under the task's attachments dir, capped at 25 MB. Prefer kanban_attach_url when you only have a URL.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
+        },
+        "filename": {
+          "type": "string",
+          "description": "File name to store it under (e.g. 'report.pdf'). Directory components are stripped; only the leaf is kept."
+        },
+        "content_base64": {
+          "type": "string",
+          "description": "The file contents, base64-encoded. Max 25 MB decoded."
+        },
+        "content_type": {
+          "type": "string",
+          "description": "Optional MIME type (e.g. 'application/pdf')."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": [
+        "filename",
+        "content_base64"
+      ]
+    }
+  },
+  {
+    "name": "kanban_attach_url",
+    "description": "Attach a file to a task by URL — Hermes downloads it server-side and stores it as a real attachment (capped at 25 MB). Use when you have a link rather than the bytes. Only http/https URLs are accepted.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
+        },
+        "url": {
+          "type": "string",
+          "description": "http(s) URL to fetch and store."
+        },
+        "filename": {
+          "type": "string",
+          "description": "Optional name to store it under. Defaults to the URL path's leaf component."
+        },
+        "content_type": {
+          "type": "string",
+          "description": "Optional MIME type override. Defaults to the Content-Type the server returns."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": [
+        "url"
+      ]
+    }
+  },
+  {
+    "name": "kanban_attachments",
+    "description": "List the files attached to a task: id, filename, content_type, size, who uploaded it, and the absolute on-disk path you can read.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Task id. If omitted, defaults to HERMES_KANBAN_TASK from the env (the task the dispatcher spawned you to work on)."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": []
+    }
+  },
+  {
+    "name": "kanban_create",
+    "description": "Create a new kanban task, optionally as a child of the current one (pass the current task id in ``parents``). Used by orchestrator workers to fan out — decompose work into child tasks with specific assignees, link them into a pipeline, then complete your own task. The dispatcher picks up the new tasks on its next tick and spawns the assigned profiles.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "Short task title (required)."
+        },
+        "assignee": {
+          "type": "string",
+          "description": "Profile name that should execute this task (e.g. 'researcher-a', 'reviewer', 'writer'). Required — tasks without an assignee are never dispatched."
+        },
+        "body": {
+          "type": "string",
+          "description": "Opening post: full spec, acceptance criteria, links. The assigned worker reads this as part of its context."
+        },
+        "parents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Parent task ids. The new task stays in 'todo' until every parent reaches 'done'; then it auto-promotes to 'ready'. Typical fan-in: list all the researcher task ids when creating a synthesizer task."
+        },
+        "tenant": {
+          "type": "string",
+          "description": "Optional namespace for multi-project isolation. Defaults to HERMES_TENANT env if set."
+        },
+        "priority": {
+          "type": "integer",
+          "description": "Dispatcher tiebreaker. Higher = picked sooner when multiple ready tasks share an assignee."
+        },
+        "workspace_kind": {
+          "type": "string",
+          "enum": [
+            "scratch",
+            "dir",
+            "worktree"
+          ],
+          "description": "Workspace flavor: 'scratch' (fresh tmp dir, default), 'dir' (shared directory, requires absolute workspace_path), 'worktree' (git worktree)."
+        },
+        "workspace_path": {
+          "type": "string",
+          "description": "Absolute path for 'dir' or 'worktree' workspace. Relative paths are rejected at dispatch."
+        },
+        "project": {
+          "type": "string",
+          "description": "Optional project id or slug to link the task to. When set, the task becomes a git worktree under the project's primary repo with a deterministic branch (project slug + task id), instead of a random branch."
+        },
+        "triage": {
+          "type": "boolean",
+          "description": "If true, task lands in 'triage' instead of 'todo' — a specifier profile is expected to flesh out the body before work starts."
+        },
+        "idempotency_key": {
+          "type": "string",
+          "description": "If a non-archived task with this key already exists, return that task's id instead of creating a duplicate. Useful for retry-safe automation."
+        },
+        "max_runtime_seconds": {
+          "type": "integer",
+          "description": "Per-task runtime cap. When exceeded, the dispatcher SIGTERMs the worker and re-queues the task with outcome='timed_out'."
+        },
+        "initial_status": {
+          "type": "string",
+          "enum": [
+            "running",
+            "blocked"
+          ],
+          "description": "Initial card status. Use 'blocked' for tasks that require immediate human ops (R3 gate) to skip the brief running-to-blocked transition. Defaults to 'running', which preserves the usual dispatch path."
+        },
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Skill names to force-load into the dispatched worker. The kanban lifecycle is already injected automatically; use this to pin a task to a specialist context — e.g. ['translation'] for a translation task, ['github-code-review'] for a reviewer task. The names must match skills installed on the assignee's profile."
+        },
+        "goal_mode": {
+          "type": "boolean",
+          "description": "Run the dispatched worker in a goal loop. When true, after each turn an auxiliary judge checks the worker's response against this card's title/body; if the work isn't done and budget remains, the worker keeps going in the same session until the judge agrees it's complete (or the goal-turn budget is exhausted, which blocks the task for human review). Use this for open-ended cards where one shot rarely finishes the work. Defaults to false (classic single-shot worker)."
+        },
+        "goal_max_turns": {
+          "type": "integer",
+          "description": "Turn budget for goal_mode workers. Caps how many continuation turns the worker may take before the task is blocked for review. Ignored unless goal_mode is true. Defaults to the goal-engine default (20)."
+        },
+        "model": {
+          "type": "string",
+          "description": "Pin the dispatched worker to this model instead of the assignee profile's configured model. Use the exact model name the target provider expects. Omit to use the profile default."
+        },
+        "provider": {
+          "type": "string",
+          "description": "Provider the 'model' belongs to (e.g. 'openrouter', 'anthropic', 'nous'). Set this whenever the model is not from the assignee profile's configured provider — a model name alone is resolved against the profile's provider and will fail if it belongs to a different one. Requires 'model'."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": [
+        "title",
+        "assignee"
+      ]
+    }
+  },
+  {
+    "name": "kanban_unblock",
+    "description": "Unblock a Kanban task. It moves to ready when all parents are done, or todo while any parent remains open. Orchestrator-only — only profiles with the kanban toolset can unblock routed work; dispatcher-spawned task workers never see this tool.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "task_id": {
+          "type": "string",
+          "description": "Blocked task id to move to ready or parent-gated todo."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": [
+        "task_id"
+      ]
+    }
+  },
+  {
+    "name": "kanban_link",
+    "description": "Add a parent→child dependency edge after both tasks already exist. The child won't promote to 'ready' until all parents are 'done'. Cycles and self-links are rejected.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "parent_id": {
+          "type": "string",
+          "description": "Parent task id."
+        },
+        "child_id": {
+          "type": "string",
+          "description": "Child task id."
+        },
+        "board": {
+          "type": "string",
+          "description": "Kanban board slug to target. When omitted, the call resolves the active board the usual way: HERMES_KANBAN_DB env → HERMES_KANBAN_BOARD env → the 'current' symlink under the kanban home → 'default'. Pass an explicit slug only when the caller (e.g. a Telegram routing layer) needs to override the env-pinned active board for this one call."
+        }
+      },
+      "required": [
+        "parent_id",
+        "child_id"
+      ]
+    }
+  }
+]