@humwick/server 0.130.2 → 0.130.3

package/src/mcp/index.ts

@@ -239,7 +239,7 @@ async function callTool(auth: VerifiedMcpAuthContext, params: unknown, signal?:
     else if (name === "relay_workspace_merge_resume") result = await relayWorkspaceMutation(auth, "resume-merge", args);
     else if (name === "relay_red_main_recover") result = await relayRedMainRecover(auth, args);
     else if (name === "relay_workspace_release") result = await relayWorkspaceMutation(auth, "release-claim", args);
-    else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_maintenance_")) result = await relayMaintenanceTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args); else if (name === "relay_decision") result = relayDecisionTool(auth, args);
+    else if (name.startsWith("relay_merge_")) result = (await relayMergeTool(auth, name, args)); else if (name.startsWith("relay_maintenance_")) result = await relayMaintenanceTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args); else if (name === "relay_decision") result = (await relayDecisionTool(auth, args));
     else if (name.startsWith("relay_plan_")) result = await relayPlanTool(auth, name, args);
     else if (name === "relay_task_deliver") result = await relayTaskDeliverTool(auth, name, args);
     else if (TASK_VALIDATION_TOOLS.some((tool) => tool.name === name)) result = await relayTaskValidationTool(auth, name, args);
@@ -252,16 +252,16 @@ async function callTool(auth: VerifiedMcpAuthContext, params: unknown, signal?:
     else if (name === "relay_task_comment" || name === "relay_task_close_bridge") result = await relayTaskWeaveTool(auth, name, args);
     else if (name === "relay_release_readiness") result = await relayReleaseTool(name, args);
     else if (name.startsWith("relay_task_")) result = await relayTaskTool(auth, name, args);
-    else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
+    else if (name.startsWith("relay_blackboard_")) result = (await relayBlackboardTool(auth, name, args));
     // #2591 — the journal tools must claim their prefix BEFORE the generic relay_project_
     // dispatcher, or they would fall through to relayProjectTool as "unknown tool".
-    else if (name.startsWith("relay_project_journal_")) result = relayProjectJournalTool(auth, name, args);
-    else if (name === "relay_project_ingest_claudemd") result = await relayProjectIngestClaudeMd(auth, args); else if (name.startsWith("relay_project_")) result = await relayProjectTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = await relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = await relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
+    else if (name.startsWith("relay_project_journal_")) result = (await relayProjectJournalTool(auth, name, args));
+    else if (name === "relay_project_ingest_claudemd") result = await relayProjectIngestClaudeMd(auth, args); else if (name.startsWith("relay_project_")) result = await relayProjectTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = await relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = (await relayIssueAssociationTool(auth, name, args)); else if (name.startsWith("relay_issue_activity_")) result = await relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
     else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions" || name === "relay_why_notified" || name === "relay_notification_preview") result = await relayNotificationSubscriptionTool(auth, name, args);
-    else if (name === "relay_notify_ntfy") result = relayNotifyNtfy(args);
+    else if (name === "relay_notify_ntfy") result = (await relayNotifyNtfy(args));
     else if (name === "relay_delete_channel_binding") result = await relayDeleteChannelBinding(args, auth);
     else if (name === "relay_channel_output") result = await relayChannelOutput(args, auth);
-    else if (name === "relay_send_to_channel") result = relayEgressToChannel(args, auth);
+    else if (name === "relay_send_to_channel") result = (await relayEgressToChannel(args, auth));
     else throw new ValidationError(`unknown tool: ${wireName}`);
 
     return toolResult(presentToolOutput(name, result, verbosity, args));
@@ -295,9 +295,9 @@ async function visibleTools(auth: McpAuthContext, generation: ToolGeneration): P
       alwaysOn: auth.component?.role === "provider" && Boolean(constraints.profile || auth.component.sub.startsWith("runner:")),
       allowUnknownGroups: true,
     })
-    : null;
+    : auth.component?.role === "provider" ? resolveRelayTools({}, { alwaysOn: false }) : null;
   if (auth.component?.role === "provider") {
-    for (const name of RELAY_TOOL_GROUPS[SELF_CARE_TOOL_GROUP]!) allowedNames?.add(name);
+    for (const name of resolveRelayTools({ groups: [SELF_CARE_TOOL_GROUP] }, { alwaysOn: false })) allowedNames?.add(name);
   }
   // #1570 — an explicit per-tool allowlist narrows the surface further (still ∩ scopes ∩ groups). This
   // is the Codex-worker provider-split: it trims the always-loaded MCP set the client eager-loads every

package/src/mcp/output-descriptions.ts

@@ -63,7 +63,7 @@ export const OUTPUT_DESCRIPTIONS: Record<string, string> = {
   relay_why_notified: "Explain delivery.",
   relay_workflow_cancel: "Cancel run; reap agents.",
   relay_workflow_get: "Read run status; history opt-in.",
-  relay_workflow_resume: "Resume, pause/unpause, or answer/escalate a decision.",
+  relay_workflow_resume: "Resume, pause/unpause, re-pin, or answer decisions.",
   relay_workflow_start: "Start Task workflow.",
   relay_workspace_deps: "Check or refresh workspace dependencies.",
   relay_workspace_list: "List workspaces.",

package/src/mcp/presentation.ts

@@ -228,6 +228,7 @@ export function projectSpawnTargets(
     },
     baseline: matrix.baseline,
     orchestrators: matrix.orchestrators,
+    ...(matrix.apiBudgets ? { apiBudgets: matrix.apiBudgets } : {}),
     // #2656 — operator-disabled providers are absent from the matrix; name them so callers know why.
     ...(Array.isArray(full.disabledProviders) ? { disabledProviders: full.disabledProviders } : {}),
     // Profile prose stays in verbose; daily discovery needs only the spawnable names (#3594).
@@ -238,7 +239,7 @@ export function projectSpawnTargets(
         target: routingTargetLabel(asRecord(rule.target)),
       })),
     },
-    guidance: "Choose an online host, provider, model, and effort above. Default to isSelf; prefer named profiles and use spawnRequestId for idempotency.",
+    guidance: "Default to isSelf; use named profiles and spawnRequestId for idempotency.",
   };
 }
 

package/src/mcp/runtime-output.ts

@@ -27,7 +27,7 @@ export const RUNTIME_OUTPUT: Record<string, OutputProjection> = {
   relay_spawn_targets: [],
   relay_channel_output: [],
   relay_claude_api_budget: [],
-  relay_routing_policy_get: [],
+  relay_routing_policy_get: [{ path: "diagnostics", brief: null, lean: null }],
   relay_service_access: [],
   relay_list_timers: ["body", "command.stdoutTail", "command.stderrTail"].map(path => ({ path: `timers.*.${path}`, brief: 160 })),
   relay_list_artifacts: [{ path: "artifacts.*.links.*.title", brief: null }],
@@ -74,6 +74,11 @@ function jobSummary(job: MaintenanceJob, verbosity: OutputVerbosity): Record<str
 }
 
 export function projectRuntimeOutput(name: string, result: unknown, verbosity: OutputVerbosity): unknown {
+  // Migration provenance is already exposed by diagnostics; never send the notes twice (#3828).
+  if (name === "relay_routing_policy_get" && isRecord(result) && isRecord(result.policy)) {
+    const { migration, ...policy } = result.policy;
+    return { ...result, policy };
+  }
   if (name !== "relay_maintenance_jobs" || verbosity === "verbose" || !isRecord(result)) return result;
   if (verbosity === "brief" && isRecord(result.job)) return { job: jobSummary(result.job as unknown as MaintenanceJob, verbosity) };
   if (!Array.isArray(result.jobs)) return result;

package/src/mcp/self-care-visibility.ts

@@ -1,7 +1,7 @@
 import { isRecord } from "@humwick/sdk";
 import type { AgentCard, ComponentToken } from "../types";
 import { hasComponentScope } from "../security";
-import { RELAY_TOOL_GROUPS, resolveRelayTools, SELF_CARE_TOOL_GROUP } from "./tool-groups";
+import { resolveRelayTools, SELF_CARE_TOOL_GROUP } from "./tool-groups";
 
 export function supportsSelfResume(agent: AgentCard | null): boolean {
   const context = agent?.providerCapabilities?.context;
@@ -17,7 +17,7 @@ export function canDiscoverSelfResume(agent: AgentCard | null, token: ComponentT
   const constraints = token.constraints;
   const selection = { groups: constraints?.toolGroups, include: constraints?.toolInclude, exclude: constraints?.toolExclude };
   const tools = resolveRelayTools(selection, { alwaysOn: token.role === "provider" && Boolean(constraints?.profile || token.sub.startsWith("runner:")), allowUnknownGroups: true });
-  if (token.role === "provider") for (const name of RELAY_TOOL_GROUPS[SELF_CARE_TOOL_GROUP]!) tools.add(name);
+  if (token.role === "provider") for (const name of resolveRelayTools({ groups: [SELF_CARE_TOOL_GROUP] }, { alwaysOn: false })) tools.add(name);
   if (!tools.has("relay_compact_and_resume")) return false;
   return !constraints?.toolAllowlist || constraints.toolAllowlist.includes("relay_compact_and_resume");
 }

package/src/mcp/spawn-targets-matrix.ts

@@ -31,7 +31,16 @@ export function projectSpawnTargetMatrix(full: Record<string, unknown>, enrich?:
   const baseline = choices.map(({ value }) => value);
   return {
     self: { orchestratorId: stringOrNull(self.orchestratorId), host: stringOrNull(self.host) },
-    ...(Array.isArray(full.apiBudgets) ? { apiBudgets: full.apiBudgets } : {}),
+    ...(Array.isArray(full.apiBudgets) ? { apiBudgets: asRecords(full.apiBudgets).map((budget) => ({
+      budgetId: budget.budgetId, source: budget.source, month: budget.month,
+      headroomMicroUsd: budget.headroomMicroUsd,
+      ...(budget.baselineKnown ? {
+        startsAt: budget.startsAt, endsAt: budget.endsAt,
+        ceilingMicroUsd: budget.ceilingMicroUsd, estimatedSpentMicroUsd: budget.estimatedSpentMicroUsd,
+        enabled: budget.enabled,
+        ...(budget.refusalReason ? { refusalReason: budget.refusalReason } : {}),
+      } : {}),
+    })) } : {}),
     ...(Array.isArray(full.disabledProviders) ? { disabledProviders: full.disabledProviders } : {}),
     baseline: choices.map(({ value, original }) => ({ ...value, ...enrich?.(original) })),
     orchestrators: hosts.map(({ host, providers }) => {

package/src/mcp/tool-groups.ts

@@ -1,5 +1,6 @@
 import { memoryRetirementMessage } from "../memory-retirement";
 import { registryToolName, type AgentProfile } from "@humwick/sdk";
+import { ASSIGNED_RELAY_TOOLS } from "./tool-roles";
 
 // Tool group membership (#551). Each tool belongs to exactly one group; toolGroups in the token
 // constraints lists which groups are enabled (absent = all). This is the surface/eager layer on
@@ -93,11 +94,11 @@ export function resolveRelayTools(selection: AgentProfile["relay"]["tools"] = {}
       if (!RELAY_TOOL_NAMES.has(registryToolName(name))) throw new Error(memoryRetirementMessage(registryToolName(name)) ?? `${field}: unknown Relay tool "${name}"`);
     }
   }
-  const tools = new Set((selection.groups ?? Object.keys(RELAY_TOOL_GROUPS)).flatMap((group) => (RELAY_TOOL_GROUPS[group] ?? [])));
+  const tools = new Set((selection.groups ?? Object.keys(RELAY_TOOL_GROUPS)).flatMap((group) => (RELAY_TOOL_GROUPS[group] ?? [])).filter(name => ASSIGNED_RELAY_TOOLS.has(name)));
   for (const name of selection.include ?? []) tools.add(registryToolName(name));
   for (const name of selection.exclude ?? []) tools.delete(registryToolName(name));
   for (const group of options.alwaysOn !== false ? ["core", SELF_CARE_TOOL_GROUP] : []) {
-    for (const name of RELAY_TOOL_GROUPS[group]!) tools.add(name);
+    for (const name of RELAY_TOOL_GROUPS[group]!) if (ASSIGNED_RELAY_TOOLS.has(name)) tools.add(name);
   }
   return tools;
 }

package/src/mcp/tool-roles.ts

@@ -0,0 +1,81 @@
+import type { AgentProfile } from "@humwick/sdk";
+
+// Explicit names, never registry/group expansion: adding a tool must not grow a role (#3817).
+const COMMON_READ = ["relay_guide", "relay_whoami", "relay_get_message", "relay_get_thread", "relay_find_agents", "relay_task_get", "relay_recall", "web_search"];
+const COMMON_WRITE = ["relay_secret_request", "relay_send_message", "relay_reply", "relay_task_deliver", "relay_compact_and_resume", "relay_run", "relay_schedule_timer"];
+const MEMORY_READ = ["relay_project_read", "relay_project_search"];
+const MEMORY_WRITE = ["relay_project_write_entry", "relay_project_retract"];
+const ARTIFACT_READ = ["relay_list_artifacts", "relay_read_artifact"];
+const ARTIFACT_WRITE = ["relay_upload_artifact", "relay_attach_artifact", "relay_pin_artifact"];
+const TEAM_READ = ["relay_blackboard_get", "relay_blackboard_read", "relay_blackboard_search"];
+const TEAM_WRITE = ["relay_blackboard_write", "relay_blackboard_retract"];
+const TASK_READ = ["relay_task_list", "relay_task_history", "relay_task_memory_read"];
+const PLAN_READ = ["relay_plan_get", "relay_plan_list", "relay_plan_conformance"];
+const WORKSPACE_READ = ["relay_workspace_status", "relay_workspace_deps"];
+const TIMER_READ = ["relay_list_timers"];
+const TIMER_WRITE = ["relay_schedule_timer", "relay_cancel_timer"];
+const WORK_READ = [...MEMORY_READ, ...ARTIFACT_READ, ...TEAM_READ, ...WORKSPACE_READ, ...TASK_READ, ...PLAN_READ, "relay_workflow_get"];
+const WORK_WRITE = [...MEMORY_WRITE, ...ARTIFACT_WRITE, ...TEAM_WRITE];
+const PLAN_WRITE = ["relay_plan_import", "relay_plan_create", "relay_plan_add_node", "relay_plan_update_node", "relay_plan_add_edge", "relay_plan_remove_node", "relay_plan_remove_edge", "relay_plan_archive", "relay_plan_delete", "relay_plan_bind_node", "relay_plan_start"];
+const TASK_WRITE = ["relay_task_set_validation", "relay_task_needs_validation", "relay_task_create", "relay_task_update", "relay_task_set_status", "relay_task_set_stage", "relay_task_set_review_hold", "relay_task_withdraw_land", "relay_task_confirm_carry", "relay_task_record_gate", "relay_task_add_dependency", "relay_task_remove_dependency", "relay_task_add_ref", "relay_task_remove_ref", "relay_task_assign_agent", "relay_task_memory_replace_working_state", "relay_task_memory_append_ruled_out", "relay_task_memory_append_decision", "relay_task_dispatch", "relay_backlog_promote", "relay_task_comment", "relay_task_close_bridge"];
+const SPAWN_READ = ["relay_spawn_targets", "relay_my_agents", "relay_agent_status", "relay_agent_crash_report", "relay_team_get"];
+const SPAWN_WRITE = ["relay_spawn_agent", "relay_shutdown_agent", "relay_interrupt_agent", "relay_agent_keep", "relay_agent_action", "relay_permission_decision", "relay_team_set_spawn_delegation", "relay_team_set_brief", "relay_team_claim", "relay_team_dissolve"];
+const WORKFLOW_WRITE = ["relay_workflow_start", "relay_workflow_resume", "relay_workflow_cancel"];
+
+function role(why: string, read: readonly string[] = [], write: readonly string[] = []) {
+  return { why, read: [...new Set([...COMMON_READ, ...read])].sort(), write: [...new Set([...COMMON_WRITE, ...write])].sort() };
+}
+
+const implementer = role("Implement and deliver the hydrated bound Task. Bounded waits use relay_run.", [...MEMORY_READ, ...ARTIFACT_READ, ...TEAM_READ, ...WORKSPACE_READ], [...WORK_WRITE, "relay_set_effort"]);
+const quality = role("Read Tasks and plans, execute checks and deliver findings; report through the bound Task.", WORK_READ, [...WORK_WRITE, ...TIMER_WRITE]);
+const research = role("Research and report; keep findings and artifacts without workspace or orchestration administration.", [...MEMORY_READ, ...TEAM_READ, ...ARTIFACT_READ, "relay_web_tool_calls"], [...MEMORY_WRITE, ...TEAM_WRITE, ...ARTIFACT_WRITE]);
+
+export const RELAY_TOOL_ROLES: Readonly<Record<string, ReturnType<typeof role>>> = {
+  coordinator: role("Own plan, Task, workflow and team lifecycle; request service access and delegate broker setup and operational work to specialists.",
+    [...WORK_READ, ...SPAWN_READ, ...TIMER_READ, "relay_backlog", "relay_release_readiness", "relay_hosts", "relay_merge_pauses", "relay_routing_policy_get", "relay_project_list", "relay_project_get", "relay_project_journal_get", "relay_team_template_list", "relay_team_template_get"],
+    [...WORK_WRITE, ...PLAN_WRITE, ...TASK_WRITE, ...SPAWN_WRITE, ...WORKFLOW_WRITE, ...TIMER_WRITE, "relay_decision", "relay_set_effort", "relay_service_access", "relay_red_main_recover", "relay_merge_pause", "relay_merge_renew", "relay_merge_resume", "relay_workspace_merge_hold", "relay_workspace_merge_resume", "relay_host_gate_budget", "relay_routing_policy_set", "relay_project_profile_instructions", "relay_prompt", "relay_project_onboard", "relay_project_checkout", "relay_project_add_root", "relay_project_add_edge", "relay_project_remove_edge", "relay_project_archive", "relay_project_promote_entry", "relay_project_ingest_claudemd", "relay_project_journal_update", "relay_team_template_save", "relay_team_template_delete", "relay_team_spawn_from_template"]),
+  "sub-coordinator": role("Coordinate a delegated project and its plan/workflow; parent owns fleet routing and project administration.",
+    [...WORK_READ, ...SPAWN_READ, ...TIMER_READ],
+    [...WORK_WRITE, ...PLAN_WRITE, ...WORKFLOW_WRITE, ...TIMER_WRITE, "relay_decision", "relay_set_effort", "relay_spawn_agent", "relay_shutdown_agent", "relay_interrupt_agent", "relay_agent_keep", "relay_agent_action", "relay_permission_decision", "relay_team_set_brief", "relay_team_dissolve", "relay_task_create", "relay_task_update", "relay_task_set_status", "relay_task_set_review_hold", "relay_task_withdraw_land", "relay_task_record_gate", "relay_task_add_dependency", "relay_task_remove_dependency", "relay_task_add_ref", "relay_task_remove_ref", "relay_task_assign_agent", "relay_task_memory_replace_working_state", "relay_task_memory_append_ruled_out", "relay_task_memory_append_decision", "relay_task_dispatch", "relay_task_comment"]),
+  worker: implementer,
+  "worker-gui": role("Implement GUI work from the hydrated Task and return artifacts; inspect its workspace.", [...MEMORY_READ, ...ARTIFACT_READ, ...WORKSPACE_READ], [...MEMORY_WRITE, ...ARTIFACT_WRITE, "relay_set_effort"]),
+  debugger: implementer,
+  reviewer: quality,
+  QA: quality,
+  "device-qa": quality,
+  "slice-qa": quality,
+  "plan-auditor": quality,
+  probe: role("Run a bounded proof and return its result; no project or workspace administration."),
+  "image-gen": role("Generate and deliver image artifacts for a bound Task.", [...MEMORY_READ, ...ARTIFACT_READ, ...WORKSPACE_READ], [...MEMORY_WRITE, ...ARTIFACT_WRITE]),
+  "software-design": role("Inspect architecture, Tasks and plans and deliver a design; coordinator authors orchestration.", WORK_READ, WORK_WRITE),
+  brainstorm: research,
+  explorer: research,
+  "isolated-research": research,
+  "social-media": role("Research and prepare channel output; no team or Task administration.", [...MEMORY_READ, ...ARTIFACT_READ, "relay_web_tool_calls"], [...MEMORY_WRITE, ...ARTIFACT_WRITE, "relay_channel_output", "relay_send_to_channel"]),
+  "ops-assistant": role("Operate gates, maintenance and delivery; inspect agent health without spawning or planning.",
+    [...MEMORY_READ, ...ARTIFACT_READ, ...WORKSPACE_READ, ...TIMER_READ, "relay_hosts", "relay_agent_status", "relay_agent_crash_report", "relay_maintenance_jobs", "relay_maintenance_pauses", "relay_merge_pauses", "relay_workspace_list", "relay_release_readiness"],
+    [...MEMORY_WRITE, ...ARTIFACT_WRITE, ...TIMER_WRITE, "relay_maintenance_pause", "relay_maintenance_resume", "relay_merge_pause", "relay_merge_renew", "relay_merge_resume", "relay_workspace_claim", "relay_workspace_release", "relay_workspace_merge_hold", "relay_workspace_merge_resume", "relay_red_main_recover", "relay_set_effort"]),
+  "sec-ops": role("Audit security and manage broker access; no orchestration or fleet mutation.",
+    [...MEMORY_READ, ...ARTIFACT_READ, ...WORKSPACE_READ, "relay_hosts", "relay_web_tool_calls"], [...MEMORY_WRITE, ...ARTIFACT_WRITE, "relay_service_access", "relay_secret_reader_create", "relay_secret_project_create", "relay_secret_set", "relay_notify_ntfy"]),
+  // These require admin/control tokens, not provider-agent grants. No hub agent profile is created.
+  operator: role("Operator/control-client tools that cannot be conferred by an agent profile.",
+    ["relay_kernel_listInstances", "relay_kernel_getInstance", "relay_kernel_getJournal", "relay_kernel_listEvents", "relay_kernel_listEntities", "relay_kernel_getEntity", "relay_issue_ref_get", "relay_issue_ref_list", "relay_issue_association_list_issues_for_entity", "relay_issue_association_list_entities_for_issue", "relay_issue_activity_by_issue", "relay_issue_activity_by_agent", "relay_list_subscriptions", "relay_why_notified", "relay_notification_preview"],
+    ["relay_kernel_cancel", "relay_kernel_pause", "relay_kernel_resume", "relay_kernel_retry", "relay_profile_trust", "relay_codex_reset_consume", "relay_claude_api_budget", "relay_delete_channel_binding", "relay_issue_ref_upsert", "relay_issue_ref_resolve", "relay_issue_ref_update", "relay_issue_ref_delete", "relay_issue_association_associate", "relay_issue_association_remove", "relay_issue_activity_record", "relay_issue_lifecycle_reopen", "relay_subscribe", "relay_unsubscribe", "relay_notify_ntfy", "relay_reevaluate_channel_delivery"]),
+};
+
+export const ASSIGNED_RELAY_TOOLS: ReadonlySet<string> = new Set(Object.values(RELAY_TOOL_ROLES).flatMap(role => [...role.read, ...role.write]));
+
+/** Exact includes keep later group additions out of already-curated profiles. */
+export function relayRoleSelection(name: string): NonNullable<AgentProfile["relay"]["tools"]> {
+  const assignment = RELAY_TOOL_ROLES[name];
+  if (!assignment) throw new Error(`No Relay tool role for profile ${name}`);
+  return { groups: [], include: [...new Set([...assignment.read, ...assignment.write])].sort(), exclude: [] };
+}
+
+export function relayToolRoleErrors(registered: readonly string[]): string[] {
+  const names = new Set(registered);
+  return [
+    ...registered.filter(name => !ASSIGNED_RELAY_TOOLS.has(name)).map(name => `${name}: assign this Relay tool to at least one role in src/mcp/tool-roles.ts`),
+    ...[...ASSIGNED_RELAY_TOOLS].filter(name => !names.has(name)).map(name => `${name}: role assignment names an unregistered Relay tool`),
+  ];
+}

package/src/mcp/tools-workspace.ts

@@ -238,7 +238,7 @@ export async function relayWorkspaceMutation(auth: McpAuthContext, action: Works
     payload.guidance = describeWorkspacePhase(result.workspace);
     // Legacy workspace-ready route/CLI path is an explicit, platform-owned completion signal: the caller
     // is declaring its work window closed. Close it, forwarding only the held final group.
-    markAgentWorkFinal(result.workspace.ownerAgentId ?? callerAgentId(auth), "workspace-ready");
+    (await markAgentWorkFinal(result.workspace.ownerAgentId ?? callerAgentId(auth), "workspace-ready"));
   }
   return payload;
 }

package/src/mcp-blackboard-tools.ts

@@ -1,4 +1,5 @@
-import { getAgent, getEntry, getEntryChain, listEntries, retractEntry, searchEntries, ValidationError, writeEntry } from "./db";
+import { writeEntryAsync, retractEntryAsync } from "./db/runtime-tail-async";
+import { getAgent, getEntry, getEntryChain, listEntries, searchEntries, ValidationError } from "./db";
 import { McpNotFoundError } from "./mcp-errors";
 import { authContextFromMcp } from "./services/auth-context";
 import { cleanString, cleanStringArray, optionalEnum } from "./validation";
@@ -92,14 +93,14 @@ function ensureSameTeam(entryId: string, teamId: string): void {
   if (entry.teamId !== teamId) throw new McpNotFoundError("blackboard entry not found");
 }
 
-export function relayBlackboardTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+export async function relayBlackboardTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   const { agentId, teamId } = callerTeam(auth);
   if (name === "relay_blackboard_write") {
     const supersedes = cleanString(args.supersedes, "supersedes", { max: 120 });
     const kind = cleanKind(args.kind);
     if (!kind) throw new ValidationError("kind required");
     if (supersedes) ensureSameTeam(supersedes, teamId);
-    return writeEntry({
+    return (await writeEntryAsync({
       teamId,
       authorId: agentId,
       kind,
@@ -107,7 +108,7 @@ export function relayBlackboardTool(auth: McpAuthLike, name: string, args: Recor
       body: cleanString(args.body, "body", { max: 16_000 }),
       tags: cleanStringArray(args.tags, "tags", { itemMax: 80, maxItems: 32 }),
       supersedes,
-    }) as unknown as Record<string, unknown>;
+    })) as unknown as Record<string, unknown>;
   }
   if (name === "relay_blackboard_get") {
     const id = cleanString(args.id, "id", { required: true, max: 120 })!;
@@ -123,7 +124,7 @@ export function relayBlackboardTool(auth: McpAuthLike, name: string, args: Recor
   if (name === "relay_blackboard_retract") {
     const id = cleanString(args.id, "id", { required: true, max: 120 })!;
     ensureSameTeam(id, teamId);
-    const entry = retractEntry(id);
+    const entry = (await retractEntryAsync(id));
     if (!entry) throw new McpNotFoundError("blackboard entry not found");
     return entry as unknown as Record<string, unknown>;
   }

package/src/mcp-decision-tools.ts

@@ -66,16 +66,16 @@ function requiredId(args: Record<string, unknown>): number {
   return id;
 }
 
-function run(auth: McpAuthLike, args: Record<string, unknown>): Record<string, unknown> {
+async function run(auth: McpAuthLike, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   const ctx = authContextFromMcp(auth);
   const action = cleanEnum(args.action, "action", ACTIONS);
   if (action === "file") {
-    const decision = fileDecision(ctx, args, callerProjectId(ctx));
+    const decision = (await fileDecision(ctx, args, callerProjectId(ctx)));
     return { id: decision.id, kind: decision.kind, status: decision.status, teamId: decision.teamId };
   }
-  if (action === "update") return { id: updateDecision(ctx, requiredId(args), args).id, status: "open" };
-  if (action === "withdraw") return { id: withdrawDecision(ctx, requiredId(args)).id, status: "withdrawn" };
-  const teamId = callerDecisionTeam(ctx, false);
+  if (action === "update") return { id: (await updateDecision(ctx, requiredId(args), args)).id, status: "open" };
+  if (action === "withdraw") return { id: (await withdrawDecision(ctx, requiredId(args))).id, status: "withdrawn" };
+  const teamId = (await callerDecisionTeam(ctx, false));
   const id = optionalPositiveInt(args.id, "id");
   if (id !== undefined) return { decision: teamDecision(teamId, id) };
   const status = optionalEnum(args.status, "status", [...OPERATOR_DECISION_STATUSES, "all"] as const, "open");
@@ -84,9 +84,9 @@ function run(auth: McpAuthLike, args: Record<string, unknown>): Record<string, u
   return { lines: decisions.map((decision) => renderDecisionLine(decision)) };
 }
 
-export function relayDecisionTool(auth: McpAuthLike, args: Record<string, unknown>): Record<string, unknown> {
+export async function relayDecisionTool(auth: McpAuthLike, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   try {
-    return run(auth, args);
+    return (await run(auth, args));
   } catch (error) {
     if (error instanceof ServiceAuthError) throw new McpAuthError(error.message);
     if (error instanceof DecisionNotFoundError) throw new McpNotFoundError(error.message);

package/src/mcp-egress-tools.ts

@@ -1,3 +1,4 @@
+import { sendMessageWithResultAsync } from "./db/message-send";
 // Generic egress MCP tool + relay_notify_ntfy shim (#777).
 //
 // relay_send_to_channel — resolves a registered channel agent by ID, builds a
@@ -15,7 +16,7 @@ import { channelOutputControl, changeChannelOutput } from "./channel-output-cont
 import { McpAuthError } from "./mcp-errors";
 import { isComponentAuthorizedFor, isIntegrationAllowed } from "./security";
 import { MAX_BODY_BYTES } from "./config";
-import { channelObligationAnsweredBy, getChannel, sendMessageWithResult, ValidationError } from "./db";
+import { channelObligationAnsweredBy, getChannel, ValidationError } from "./db";
 import { validateChannelEnvelope } from "./routes/integrations";
 import { emitNewMessage } from "./sse";
 import { optionalEnum } from "./validation";
@@ -91,12 +92,12 @@ function egressBodyForEvent(event: Record<string, unknown>): string {
   return serialized;
 }
 
-function emitChannelEgress(
+async function emitChannelEgress(
   channelId: string,
   event: Record<string, unknown>,
   callerId?: string,
   idempotencyKey?: string,
-): { accepted: boolean; channelId: string; to: string } {
+): Promise<{ accepted: boolean; channelId: string; to: string }> {
   const channel = getChannel(channelId);
   if (!channel) throw new ValidationError(`channel ${channelId} not registered`);
   if (channel.direction === "inbound") {
@@ -123,7 +124,7 @@ function emitChannelEgress(
   // We DON'T route this through sendMessageService: that gate authorizes on message:send, but egress carries only channel:egress, so a component
   // token would 403; the raw path preserves the channel:egress scope model.
   const answeredObligation = callerId ? channelObligationAnsweredBy(callerId, channel.agentId) : null;
-  const { message, created } = sendMessageWithResult({
+  const { message, created } = (await sendMessageWithResultAsync({
     from: callerId ?? "system",
     to: channel.agentId,
     kind: "channel.event",
@@ -132,19 +133,19 @@ function emitChannelEgress(
     replyExpected: false,
     ...(idempotencyKey ? { idempotencyKey } : {}),
     ...(answeredObligation !== null ? { replyTo: answeredObligation } : {}),
-  });
+  }));
   if (created) emitNewMessage(message);
   return { accepted: true, channelId, to: channel.agentId };
 }
 
-export function relayEgressToChannel(args: Record<string, unknown>, auth?: McpAuthContext, idempotencyKey?: string): { accepted: boolean; channelId: string; to: string } {
+export async function relayEgressToChannel(args: Record<string, unknown>, auth?: McpAuthContext, idempotencyKey?: string): Promise<{ accepted: boolean; channelId: string; to: string }> {
   const channelId = stringField(args.channelId, "channelId", { required: true, max: 200 });
   const event = recordField(args.event, "event");
   const callerId = auth ? callerAgentId(auth) : undefined;
-  return emitChannelEgress(channelId, event, callerId, idempotencyKey);
+  return (await emitChannelEgress(channelId, event, callerId, idempotencyKey));
 }
 
-export function relayNotifyNtfy(args: Record<string, unknown>, idempotencyKey?: string): { accepted: boolean; channelId: string } {
+export async function relayNotifyNtfy(args: Record<string, unknown>, idempotencyKey?: string): Promise<{ accepted: boolean; channelId: string }> {
   const title = stringField(args.title, "title", { required: true, max: 200 });
   const body = stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES });
   const priority = optionalEnum(args.priority, "priority", NTFY_PRIORITIES) as NtfyPriority | undefined;
@@ -154,7 +155,7 @@ export function relayNotifyNtfy(args: Record<string, unknown>, idempotencyKey?:
   if (priority !== undefined) event.priority = priority;
   if (tags?.length) event.tags = tags;
   if (click !== undefined) event.click = click;
-  const result = emitChannelEgress(NTFY_CHANNEL_ID, event, undefined, idempotencyKey);
+  const result = (await emitChannelEgress(NTFY_CHANNEL_ID, event, undefined, idempotencyKey));
   return { accepted: result.accepted, channelId: result.channelId };
 }
 

package/src/mcp-issue-activity-tools.ts

@@ -86,7 +86,7 @@ function limitArg(value: unknown): number | undefined {
 
 export async function relayIssueActivityTool(_auth: IssueActivityToolAuth, name: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   if (name === "relay_issue_activity_record") {
-    const event = recordAndEmitIssueActivity({
+    const event = (await recordAndEmitIssueActivity({
       agentId: cleanString(args.agentId, "agentId", { required: true, max: 200 })!,
       action: actionArg(args.action),
       issueRefId: cleanString(args.issueRefId, "issueRefId", { max: 120 }),
@@ -97,7 +97,7 @@ export async function relayIssueActivityTool(_auth: IssueActivityToolAuth, name:
       title: cleanString(args.title, "title", { max: 200 }),
       body: cleanString(args.body, "body", { max: 1000 }),
       metadata: cleanMeta(args.metadata),
-    });
+    }));
     return { event };
   }
   if (name === "relay_issue_activity_by_issue") {

package/src/mcp-issue-association-tools.ts

@@ -83,9 +83,9 @@ function associationInput(args: Record<string, unknown>) {
   };
 }
 
-export function relayIssueAssociationTool(_auth: IssueAssociationToolAuth, name: string, args: Record<string, unknown>): Record<string, unknown> {
+export async function relayIssueAssociationTool(_auth: IssueAssociationToolAuth, name: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   if (!isRecord(args)) throw new ValidationError("arguments must be an object");
-  if (name === "relay_issue_association_associate") return associateIssueRef(associationInput(args)) as unknown as Record<string, unknown>;
+  if (name === "relay_issue_association_associate") return (await associateIssueRef(associationInput(args))) as unknown as Record<string, unknown>;
   if (name === "relay_issue_association_list_issues_for_entity") {
     return {
       issues: listIssueRefsForEntity(
@@ -95,9 +95,9 @@ export function relayIssueAssociationTool(_auth: IssueAssociationToolAuth, name:
     };
   }
   if (name === "relay_issue_association_list_entities_for_issue") {
-    const issueRef = resolveAssociationIssueRef(issueInput(args));
+    const issueRef = (await resolveAssociationIssueRef(issueInput(args)));
     return { issueRef, entities: listIssueEntities(issueRef.id) };
   }
-  if (name === "relay_issue_association_remove") return removeIssueAssociation(associationInput(args));
+  if (name === "relay_issue_association_remove") return (await removeIssueAssociation(associationInput(args)));
   throw new ValidationError(`unknown tool: ${name}`);
 }

package/src/mcp-issue-ref-tools.ts

@@ -1,5 +1,5 @@
-import { getIssueRef, getIssueRefByExternalKey, issueRefClosedCompleted, issueRefForRefString, listIssueRefs } from "./db/issue-refs";
-import { deleteIssueRefAsync, resolveIssueRefByExternalKeyAsync, resolveIssueRefFromStringAsync, updateIssueRefAsync, upsertIssueRefAsync } from "./db/issue-refs-async";
+import { getIssueRef, getIssueRefByExternalKey, issueRefClosedCompleted, issueRefForRefString } from "./db/issue-refs";
+import { deleteIssueRefAsync, listIssueRefsAsync, resolveIssueRefByExternalKeyAsync, resolveIssueRefFromStringAsync, updateIssueRefAsync, upsertIssueRefAsync } from "./db/issue-refs-async";
 import { McpNotFoundError } from "./mcp-errors";
 import { cleanEnum, cleanString, optionalEnum } from "./validation";
 import { ISSUE_REF_CLOSE_REASONS, ISSUE_PROVIDERS, ISSUE_REF_STATUSES, isRecord, type IssueProvider, type IssueRef, type IssueRefCloseReason, type IssueRefStatus } from "./types";
@@ -183,7 +183,7 @@ export async function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, a
   }
   if (name === "relay_issue_ref_list") {
     return {
-      issueRefs: listIssueRefs({
+      issueRefs: await listIssueRefsAsync({
         provider: optionalEnum(args.provider, "provider", ISSUE_PROVIDERS) as IssueProvider | undefined,
         repo: cleanString(args.repo, "repo", { max: 500 }),
         status: statusArg(args.status),

package/src/mcp-merge-tools.ts

@@ -29,24 +29,24 @@ export const MERGE_TOOLS = [
 
 type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
 
-export function relayMergeTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Record<string, unknown> {
+export async function relayMergeTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   const ctx = authContextFromMcp(auth);
   if (name === "relay_merge_pauses") {
     const pauses = listAutoMergePauses();
     return { pauses, count: pauses.length };
   }
   if (name === "relay_merge_pause") {
-    const result = pauseAutoMerge({
+    const result = (await pauseAutoMerge({
       repoRoot: cleanString(args.repoRoot, "repoRoot", { required: true, max: 1024 })!,
       baseRef: cleanString(args.baseRef, "baseRef", { max: 240 }),
       holder: cleanString(args.holder, "holder", { max: 240 }) ?? ctx.callerAgentId ?? ctx.actor.id,
       reason: cleanString(args.reason, "reason", { max: 1000 }),
       ttlMs: optionalPositiveInt(args.ttlMs, "ttlMs"),
-    });
+    }));
     return result.ok ? { ok: true, pause: result.pause } : { ok: false, error: "merge target already paused", pause: result.pause };
   }
   if (name === "relay_merge_renew") {
-    const pause = renewAutoMergePause(cleanString(args.id, "id", { required: true, max: 120 })!, optionalPositiveInt(args.ttlMs, "ttlMs"));
+    const pause = (await renewAutoMergePause(cleanString(args.id, "id", { required: true, max: 120 })!, optionalPositiveInt(args.ttlMs, "ttlMs")));
     if (!pause) throw new McpNotFoundError("merge pause not found or expired");
     return { pause };
   }
@@ -54,7 +54,7 @@ export function relayMergeTool(auth: McpAuthLike, name: string, args: Record<str
     const id = cleanString(args.id, "id", { max: 120 });
     const repoRoot = cleanString(args.repoRoot, "repoRoot", { max: 1024 });
     if (!id && !repoRoot) throw new ValidationError("id or repoRoot required");
-    return { released: resumeAutoMerge({ id, repoRoot, baseRef: cleanString(args.baseRef, "baseRef", { max: 240 }) }) };
+    return { released: (await resumeAutoMerge({ id, repoRoot, baseRef: cleanString(args.baseRef, "baseRef", { max: 240 }) })) };
   }
   throw new ValidationError(`unknown tool: ${name}`);
 }

package/src/mcp-notification-subscription-tools.ts

@@ -1,5 +1,5 @@
+import { addSubscriptionAsync, addSubscriptionsAsync, removeSubscriptionAsync } from "./db/lifecycle-tail-async";
 import {
-  addSubscription,
   childStreamFromSubscriptionType,
   childStreamSubscriptionType,
   cleanChildStream,
@@ -9,7 +9,6 @@ import {
   listSubscriptions,
   NOTIFICATION_SUBSCRIPTION_MODES,
   NOTIFICATION_SUBSCRIPTION_TYPES,
-  removeSubscription,
   type ConfigurableChildStream,
   type ChildStream,
   type NotificationSubscriptionMode,
@@ -112,14 +111,14 @@ export async function relayNotificationSubscriptionTool(
     if (Object.prototype.hasOwnProperty.call(args, "streams")) {
       const scope = cleanChildStreamScope(args, agentId);
       const streams = cleanChildStreams(args.streams);
-      const subscriptions = streams
+      const subscriptions = await addSubscriptionsAsync(streams
         .filter((stream): stream is ConfigurableChildStream => stream !== "responses")
-        .map((stream) => addSubscription({
+        .map((stream) => ({
           agentId,
           type: childStreamSubscriptionType(stream),
           mode: cleanModeOrDefault(args.mode),
           scopeMatch: scope,
-        }));
+        })));
       return {
         subscriptions,
         childStreamFilter: {
@@ -132,21 +131,21 @@ export async function relayNotificationSubscriptionTool(
     if (Object.prototype.hasOwnProperty.call(args, "taskId")) {
       const scope = await taskScope(ctx, args.taskId, args.scope);
       const mode = cleanModeOrDefault(args.mode);
-      const subscriptions = TASK_NOTIFICATION_TYPES.map((type) => addSubscription({
+      const subscriptions = await addSubscriptionsAsync(TASK_NOTIFICATION_TYPES.map((type) => ({
         agentId,
         type,
         mode,
         scopeMatch: scope,
-      }));
+      })));
       return { subscriptions, taskFilter: scope };
     }
     if (args.type === undefined || args.type === null) throw new ValidationError("type or streams required");
-    const subscription = addSubscription({
+    const subscription = (await addSubscriptionAsync({
       agentId,
       type: cleanSubscriptionType(args.type),
       mode: cleanModeOrDefault(args.mode),
       scopeMatch: cleanScope(args.scope),
-    });
+    }));
     return { subscription };
   }
   if (name === "relay_unsubscribe") {
@@ -157,12 +156,12 @@ export async function relayNotificationSubscriptionTool(
       let removed = 0;
       for (const stream of streams) {
         if (stream === "responses") continue;
-        removed += removeSubscription({
+        removed += (await removeSubscriptionAsync({
           agentId,
           type: childStreamSubscriptionType(stream),
           mode: args.mode === undefined || args.mode === null ? undefined : cleanSubscriptionMode(args.mode),
           scopeMatch: scope,
-        });
+        }));
       }
       return { removed, responsesAlwaysOn: true };
     }
@@ -173,24 +172,24 @@ export async function relayNotificationSubscriptionTool(
         : [cleanSubscriptionType(args.type)];
       let removed = 0;
       for (const type of types) {
-        removed += removeSubscription({
+        removed += (await removeSubscriptionAsync({
           agentId,
           type,
           mode: args.mode === undefined || args.mode === null ? undefined : cleanSubscriptionMode(args.mode),
           scopeMatch: scope,
-        });
+        }));
       }
       return { removed };
     }
     const type = args.type === undefined || args.type === null ? undefined : cleanSubscriptionType(args.type);
     if (!id && !type) throw new ValidationError("id or type required");
-    const removed = removeSubscription({
+    const removed = (await removeSubscriptionAsync({
       agentId,
       id,
       type,
       mode: args.mode === undefined || args.mode === null ? undefined : cleanSubscriptionMode(args.mode),
       ...(Object.prototype.hasOwnProperty.call(args, "scope") ? { scopeMatch: cleanScope(args.scope) } : {}),
-    });
+    }));
     return { removed };
   }
   if (name === "relay_list_subscriptions") {

package/src/mcp-output-levels.test-fixture.ts

@@ -58,7 +58,7 @@ export async function seedOutputFixture(database: ReturnType<typeof db.getDb>) {
   await call("relay_decision", { action: "file", title: "Choose output convention", context: OUTPUT_BODY, questions: [{ prompt: "Adopt canonical verbosity?", kind: "text" }] });
   db.upsertWorkspace({ id: "output-ws", repoRoot: process.cwd(), sourceCwd: process.cwd(), worktreePath: process.cwd(), branch: "agent/output", orchestratorId: "output-host", ownerAgentId: caller, mode: "isolated", status: "active", metadata: {} });
   db.recordCrashReport({ agentId: "output-worker-0", parentId: caller, reason: "Provider exited", diagnosis: { cause: "provider-crash", confidence: "high", summary: "Provider exited with nonzero status", evidence: [OUTPUT_BODY], detectedAt: 1000 }, createdAt: 1000 });
-  const notification = routeNotification({ type: "agent.ready", scope: { agentId: "output-worker-0", parent: caller }, recipients: [caller], message: { body: "Worker ready" } })[0]!;
+  const notification = (await routeNotification({ type: "agent.ready", scope: { agentId: "output-worker-0", parent: caller }, recipients: [caller], message: { body: "Worker ready" } }))[0]!;
   const host = createSqliteModuleHost({ db: database, clock: createControllableClock(1000) });
   host.register(timers);
   const timer = await host.invoke(timers, "create", { actor: `runner:${caller}`, grants: ["timers:write"] }, { fireAt: 2000 }) as Timer;