@humwick/server 0.130.1 → 0.130.3

package/src/mcp/presentation.ts

@@ -50,7 +50,7 @@ export type PresentationVerbosity = "brief" | "lean" | "default" | "verbose";
 
 type TaskGateSummary = Record<TaskGateStatus, number> & { total: number };
 
-type TaskDetailLeanPresentation = Pick<TaskDetail, "validationItems" | "staleOwnerGone" | "terminalStage" | "completedAt" | "owner"> & {
+type TaskDetailLeanPresentation = Pick<TaskDetail, "validationItems" | "staleOwnerGone" | "terminalStage" | "completedAt" | "owner" | "onDeploy"> & {
   id: number;
   title: string;
   status: string;
@@ -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.",
   };
 }
 
@@ -328,7 +329,7 @@ export function projectTaskList(
     return tasks.map((task) => ({
       id: task.id,
       label: truncateTaskListLabel(task.label),
-      status: task.status, ...taskValidationProjection(task),
+      status: task.status, ...taskValidationProjection(task), ...(task.onDeploy ? { onDeploy: task.onDeploy } : {}),
     }));
   }
   return tasks.map((task) => {
@@ -339,7 +340,7 @@ export function projectTaskList(
       status: task.status,
       deliverableStage: task.deliverableStage ?? null,
       ownerAgentId: task.ownerAgentId ?? null,
-      ...taskValidationProjection(task),
+      ...taskValidationProjection(task), ...(task.onDeploy ? { onDeploy: task.onDeploy } : {}),
       updatedAt: updatedAt.relative,
       ...(crossRepo && task.repo ? { repo: task.repo } : {}),
     };
@@ -368,7 +369,7 @@ export function projectTaskDetail(
     deliverableStage: task.deliverableStage ?? null,
     ownerAgentLabel: task.ownerAgentLabel ?? null,
     ...(task.owner ? { owner: task.owner } : {}),
-    ...taskValidationProjection(task),
+    ...taskValidationProjection(task), ...(task.onDeploy ? { onDeploy: task.onDeploy } : {}),
     issues: task.issues,
     ...(task.waitedOnBy?.length ? { waitedOnByPlans: task.waitedOnBy.length } : {}),
     gates: summarizeTaskGates(task.gates),

package/src/mcp/project-profile-instructions.ts

@@ -0,0 +1,32 @@
+import { ValidationError } from "../db/connection";
+import { authContextFromMcp } from "../services/auth-context";
+import { listProjectProfileInstructions, mutateProjectProfileInstructions, projectProfileInstructionHistory, readProjectProfileInstructions } from "../services/project-profile-instructions";
+import { stringField } from "./validation";
+import type { McpAuthContext, ToolDefinition } from "./types";
+import { hasAnyScope } from "./identity";
+import { McpAuthError } from "../mcp-errors";
+
+export const PROJECT_PROFILE_INSTRUCTION_TOOLS: ToolDefinition[] = [{
+  name: "relay_project_profile_instructions",
+  description: "Project additions to profile instructions. Empty version is 0. Writes need expectedVersion; restore appends history.",
+  requiredScopes: ["agent:read"],
+  inputSchema: { type: "object", properties: {
+    operation: { type: "string", enum: ["list", "get", "set", "history", "restore"] },
+    projectId: { type: "string" }, profile: { type: "string" }, template: { type: "string" },
+    expectedVersion: { type: "integer", minimum: 0 }, version: { type: "integer", minimum: 1 }, reason: { type: "string" },
+  }, required: ["operation"], additionalProperties: false },
+}];
+
+export async function relayProjectProfileInstructions(auth: McpAuthContext, args: Record<string, unknown>) {
+  if (["set", "restore"].includes(String(args.operation)) && !hasAnyScope(auth, ["agent:write"])) throw new McpAuthError("agent:write scope required");
+  const required = args.operation !== "list";
+  const projectId = stringField(args.projectId, "projectId", { required, max: 200 });
+  const profile = stringField(args.profile, "profile", { required, max: 200 });
+  switch (args.operation) {
+    case "list": return listProjectProfileInstructions({ projectId: projectId || undefined, profile: profile || undefined });
+    case "get": return readProjectProfileInstructions(projectId, profile);
+    case "history": return projectProfileInstructionHistory(projectId, profile);
+    case "set": case "restore": return mutateProjectProfileInstructions(authContextFromMcp(auth), projectId, profile, args, args.operation === "restore");
+    default: throw new ValidationError("unknown project profile instructions operation");
+  }
+}

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
@@ -29,7 +30,7 @@ export const RELAY_TOOL_GROUPS: Record<string, readonly string[]> = {
   // #3110 — opt-in: only profiles that list it (plus coordinator/ops-assistant by default) get the
   // tools AND the secrets:write scope; see runtime-tokens.ts.
   secrets: ["relay_service_access", "relay_secret_reader_create", "relay_secret_project_create", "relay_secret_set"],
-  prompts: ["relay_prompt"],
+  prompts: ["relay_prompt", "relay_project_profile_instructions"],
   quota: ["relay_codex_reset_consume", "relay_claude_api_budget"],
   // #3327 — coordinator-only, like decisions: edits the fleet's routing preferences.
   routing: ["relay_routing_policy_get", "relay_routing_policy_set"],
@@ -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-spawn.ts

@@ -16,7 +16,7 @@ import { workflowForBuilderSpawn } from "../services/workflow-auto-start";
 import { optionalEnum } from "../validation";
 import { cleanTaskDispatch } from "../db/task-entity";
 import { DISPATCH_SHAPE_SCHEMA } from "./dispatch-shape-schema";
-import { APPROVAL_MODES, AUTO_MERGE_POLICIES, LAUNCH_MODES, REPORT_VERBOSITIES, SPAWN_PROVIDERS, stringValue, VALID_AGENT_LIFECYCLES, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "@humwick/sdk";
+import { APPROVAL_MODES, AUTO_MERGE_POLICIES, LAUNCH_MODES, REPORT_VERBOSITIES, SPAWN_PROVIDERS, stringValue, VALID_AGENT_LIFECYCLES, VALID_WORKSPACE_MODES } from "@humwick/sdk";
 import type { ProviderEffort } from "@humwick/sdk/provider-catalog";
 import type { AgentCard, AgentLifecycle, Command, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceLandingPolicy, WorkspaceLandMechanism, WorkspaceMode, WorkspaceRecord } from "../types";
 import { projectMyAgent, projectSpawnTargets, type MyAgentFullPresentation, type PresentationVerbosity } from "./presentation";
@@ -43,7 +43,7 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         env: { type: "object", additionalProperties: { type: "string" }, description: "Vault refs: secret:<name>." },
         label: { type: "string" },
         model: { type: "string" },
-        effort: { enum: VALID_EFFORTS },
+        effort: { type: "string" },
         approvalMode: { enum: APPROVAL_MODES, description: "Use open; read-only blocks reports/tests; guarded waits for prompts." },
         prompt: { type: "string" },
         taskId: { oneOf: [{ type: "integer", minimum: 1 }, { type: "string" }], description: "Task id or TNNNN; loads its spec." },
@@ -70,7 +70,7 @@ export const SPAWN_TOOLS: ToolDefinition[] = [
         hostPinned: { type: "boolean" },
         landBlocked: { type: "boolean", description: "Permanent ban; for review use a Task hold." },
         selfEffort: { type: "boolean" },
-        selfEffortCeiling: { enum: VALID_EFFORTS },
+        selfEffortCeiling: { type: "string" },
         profile: { type: "string" },
         role: { type: "string", description: "Default-branch project role; mutually exclusive with profile." },
         tags: { type: "array", items: { type: "string" } },
@@ -229,6 +229,7 @@ export async function relaySpawnAgent(auth: McpAuthContext, args: Record<string,
     ...(result.taskId !== undefined ? { taskId: result.taskId } : {}),
     ...(result.task ? { task: result.task } : {}),
     ...(result.warnings ? { warnings: result.warnings } : {}),
+    ...(result.spawnPolicy ? { spawnPolicy: result.spawnPolicy } : {}),
     ...(result.dispatchDecision ? { dispatchDecision: { target: result.dispatchDecision.target, rationale: result.dispatchDecision.rationale, warnings: result.dispatchDecision.warnings } } : {}),
     ...(workflow.reason ? { workflow: { started: false, reason: workflow.reason } } : {}),
   };

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-agent-action.ts

@@ -1,7 +1,6 @@
 import { REPORT_VERBOSITIES } from "@humwick/sdk";
 import { setAgentReportVerbosity } from "./services/agent-reporting";
 import { INCLUDED_TOOL_SCOPE_NEEDS } from "./mcp/tool-groups";
-import { VALID_EFFORTS } from "@humwick/sdk/provider-catalog";
 import { cleanEnum, cleanString } from "./validation";
 import { AgentActionTargetError, dispatchAgentAction, type AgentAction } from "./services/agent-action";
 import { authContextFromMcp } from "./services/auth-context";
@@ -37,7 +36,7 @@ export const SET_EFFORT_TOOL = {
   inputSchema: {
     type: "object",
     properties: {
-      effort: { type: "string", enum: VALID_EFFORTS },
+      effort: { type: "string" },
       reason: { type: "string" },
       requestId: { type: "string" },
     },

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,9 +1,10 @@
-import { deleteIssueRef, getIssueRef, getIssueRefByExternalKey, issueRefClosedCompleted, issueRefForRefString, listIssueRefs, resolveIssueRefByExternalKey, resolveIssueRefFromString, updateIssueRef, upsertIssueRef } from "./db/issue-refs";
+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";
 import { ValidationError } from "./db";
-import { advanceTerminalPlanRefs } from "./services/plan-terminal-refs";
+import { advanceTerminalPlanRefsAsync } from "./services/plan-terminal-refs";
 
 export const ISSUE_REF_TOOLS = [
   {
@@ -126,11 +127,11 @@ function currentRefFor(args: Record<string, unknown>) {
   return null;
 }
 
-export function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, args: Record<string, unknown>): Record<string, unknown> {
+export async function relayIssueRefTool(_auth: IssueRefToolAuth, 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_ref_upsert") {
     const before = currentRefFor(args);
-    const issueRef = upsertIssueRef({
+    const issueRef = await upsertIssueRefAsync({
       provider: providerArg(args.provider),
       repo: cleanString(args.repo, "repo", { required: true, max: 500 })!,
       externalKey: cleanString(args.externalKey, "externalKey", { required: true, max: 240 })!,
@@ -141,7 +142,7 @@ export function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, args: R
       statusSyncedAt: timestampArg(args.statusSyncedAt),
     });
     // #2520 — the cached ref flipped to a completed close: propagate to bound plan nodes.
-    if (issueRefClosedCompleted(before, issueRef)) advanceTerminalPlanRefs({ issueRefId: issueRef.id, actor: _auth.actor });
+    if (issueRefClosedCompleted(before, issueRef)) await advanceTerminalPlanRefsAsync({ issueRefId: issueRef.id, actor: _auth.actor });
     return issueRef as unknown as Record<string, unknown>;
   }
   if (name === "relay_issue_ref_resolve") {
@@ -153,7 +154,7 @@ export function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, args: R
       ? issueRefForRefString(ref, cleanString(args.defaultRepo ?? args.repo, "defaultRepo", { max: 500 }))
       : currentRefFor(args);
     const issueRef = (ref
-      ? resolveIssueRefFromString({
+      ? await resolveIssueRefFromStringAsync({
         ref,
         defaultRepo: cleanString(args.defaultRepo ?? args.repo, "defaultRepo", { max: 500 }),
         provider: optionalEnum(args.provider, "provider", ISSUE_PROVIDERS, "github") as IssueProvider,
@@ -162,7 +163,7 @@ export function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, args: R
         closeReason: closeReasonArg(args.closeReason),
         statusSyncedAt: timestampArg(args.statusSyncedAt),
       })
-      : resolveIssueRefByExternalKey({
+      : await resolveIssueRefByExternalKeyAsync({
         provider: providerArg(args.provider),
         repo: cleanString(args.repo, "repo", { required: true, max: 500 })!,
         externalKey: cleanString(args.externalKey, "externalKey", { required: true, max: 240 })!,
@@ -172,7 +173,7 @@ export function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, args: R
         closeReason: closeReasonArg(args.closeReason),
         statusSyncedAt: timestampArg(args.statusSyncedAt),
       })) as unknown as IssueRef;
-    if (issueRefClosedCompleted(before, issueRef)) advanceTerminalPlanRefs({ issueRefId: issueRef.id, actor: _auth.actor });
+    if (issueRefClosedCompleted(before, issueRef)) await advanceTerminalPlanRefsAsync({ issueRefId: issueRef.id, actor: _auth.actor });
     return issueRef as unknown as Record<string, unknown>;
   }
   if (name === "relay_issue_ref_get") {
@@ -182,7 +183,7 @@ export function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, args: R
   }
   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),
@@ -192,7 +193,7 @@ export function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, args: R
   }
   if (name === "relay_issue_ref_update") {
     const before = currentRefFor(args);
-    const issueRef = updateIssueRef(cleanString(args.id, "id", { required: true, max: 120 })!, {
+    const issueRef = await updateIssueRefAsync(cleanString(args.id, "id", { required: true, max: 120 })!, {
       url: cleanString(args.url, "url", { max: 2000 }),
       title: cleanString(args.title, "title", { max: 500 }),
       status: statusArg(args.status),
@@ -201,11 +202,11 @@ export function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, args: R
     });
     if (!issueRef) throw new McpNotFoundError("issue ref not found");
     // #2520 — the cached ref flipped to a completed close: propagate to bound plan nodes.
-    if (issueRefClosedCompleted(before, issueRef)) advanceTerminalPlanRefs({ issueRefId: issueRef.id, actor: _auth.actor });
+    if (issueRefClosedCompleted(before, issueRef)) await advanceTerminalPlanRefsAsync({ issueRefId: issueRef.id, actor: _auth.actor });
     return { issueRef };
   }
   if (name === "relay_issue_ref_delete") {
-    const deleted = deleteIssueRef(cleanString(args.id, "id", { required: true, max: 120 })!);
+    const deleted = await deleteIssueRefAsync(cleanString(args.id, "id", { required: true, max: 120 })!);
     if (!deleted) throw new McpNotFoundError("issue ref not found");
     return { deleted };
   }