@humwick/server 0.130.0 → 0.130.2

package/src/managed-policy.ts

@@ -7,14 +7,13 @@ import { getAgent } from "./db/agents";
 import { getOrchestratorAsync } from "./db/orchestrators-async";
 import { composeProfileSpawnInstructions, composeProfileSpawnInstructionsAsync } from "./project-instructions";
 import { getSelfEffortCeiling } from "./db/self-effort-permissions";
-import { runnerRuntimeTokenEnv, type RunnerLaunchAuthority } from "./runtime-tokens";
-import { gatewayBackend } from "./db/gateway";
+import { runnerRuntimeTokenEnv, runnerRuntimeTokenEnvAsync, type RunnerLaunchAuthority, type RunnerRuntimeTokenInput } from "./runtime-tokens";
 import { recordedLaunchMode, resolveHostLaunchMode } from "./launch-mode";
 import { buildSpawnCommand, generateSpawnAgentId, resolveSpawnModelParams, resolveSpawnModelParamsAsync } from "./spawn-command";
 import { applyDefaultSharedMcp } from "./shared-mcp";
 import { AGENT_SYSTEM_TAGS, systemTagsForSpawn } from "./agent-system-tags";
 import { buildWhoamiDefaultForAgent } from "./mcp/identity-projection";
-import { isStewardPolicy, isGenuineStewardPolicy, stewardWorktreeCwdPrefixes } from "./steward-spawn-guard";
+import { isGenuineStewardPolicy, stewardWorktreeCwdPrefixes } from "./steward-spawn-guard";
 // #2033 — from isolated-workspace-placement.ts, NOT ./services/spawn-identity: that module also
 // exports buildProspectiveSpawnIdentity, which imports mcp/identity.ts → self-resume.ts →
 // restart-spawn.ts → managed-policy.ts, and importing it here would close that into a cycle.
@@ -97,7 +96,8 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
   const composed = composeProfileSpawnInstructions(managedInstructionInput(policy, agentProfile, agentRelayIdentity, orchestratorHost, alwaysOnAppend));
 
   return buildManagedCommand({ policy, requestId, ctx, agentId, prompt, agentProfile, orchestrator, extraCwdPrefixes, composed,
-    modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort, { skipDefaultWhenEmpty: !isStewardPolicy(policy) }),
+    modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort),
+    env: runnerRuntimeTokenEnv(managedTokenInput(policy, requestId, ctx, agentId, extraCwdPrefixes)),
   });
 }
 
@@ -147,6 +147,7 @@ function buildManagedCommand(input: {
   extraCwdPrefixes: string[];
   composed: ReturnType<typeof composeProfileSpawnInstructions>;
   modelParams: ReturnType<typeof resolveSpawnModelParams>;
+  env: Record<string, string>;
 }): Record<string, unknown> {
   const { policy, requestId, ctx, agentId, prompt, agentProfile, orchestrator, extraCwdPrefixes, composed, modelParams } = input;
   return buildSpawnCommand({
@@ -177,26 +178,31 @@ function buildManagedCommand(input: {
     headless: true,
     policyName: policy.name,
     spawnRequestId: requestId,
-    env: runnerRuntimeTokenEnv({
-      agentId,
-      orchestratorId: policy.orchestratorId,
-      cwd: policy.cwd,
-      provider: policy.provider,
-      label: policy.label,
-      policyName: policy.name,
-      spawnRequestId: requestId,
-      createdBy: ctx.createdBy,
-      authority: ctx.authority,
-      profile: policy.profile || undefined,
-      // #2245 — the same posture this launch is given above; stamped into the signed constraints.
-      approvalMode: policy.permissionMode,
-      ...(extraCwdPrefixes.length ? { extraCwdPrefixes } : {}),
-    }),
+    env: input.env,
     requestedBy: ctx.createdBy,
     requestedAt: ctx.requestedAt ?? Date.now(),
   });
 }
 
+/** The runner token a managed launch carries; the sync builder and the writer-op builder mint the same input. */
+function managedTokenInput(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext, agentId: string, extraCwdPrefixes: string[]): RunnerRuntimeTokenInput {
+  return {
+    agentId,
+    orchestratorId: policy.orchestratorId,
+    cwd: policy.cwd,
+    provider: policy.provider,
+    label: policy.label,
+    policyName: policy.name,
+    spawnRequestId: requestId,
+    createdBy: ctx.createdBy,
+    authority: ctx.authority,
+    profile: policy.profile || undefined,
+    // #2245 — the same posture this launch is given above; stamped into the signed constraints.
+    approvalMode: policy.permissionMode,
+    ...(extraCwdPrefixes.length ? { extraCwdPrefixes } : {}),
+  };
+}
+
 // #2656 — backstop for every managed launch path (policy start/restart routes, agent restart): no
 // new process starts on a disabled provider. The lifecycle manager parks the policy before this.
 function assertManagedProviderEnabled(message: string | undefined): void {
@@ -205,15 +211,12 @@ function assertManagedProviderEnabled(message: string | undefined): void {
 
 /** Worker-safe counterpart used by every runtime managed launch path.  The synchronous builder
  * remains for in-process unit fixtures; production must never borrow its main-thread connection. */
-export function buildManagedSpawnParamsAsync(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Record<string, unknown> | Promise<Record<string, unknown>> {
+export async function buildManagedSpawnParamsAsync(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Promise<Record<string, unknown>> {
   if (effectiveManagedPolicyWorkspaceMode(policy) === "isolated" && ctx.gitRepoRoot === undefined) {
-    return getOrchestratorAsync(policy.orchestratorId).then(async (host) => buildManagedSpawnParamsAsync(policy, requestId, {
-      ...ctx, gitRepoRoot: host ? await resolveSpawnRepoRoot(host, policy.cwd) : null,
-    }));
+    const host = await getOrchestratorAsync(policy.orchestratorId);
+    ctx = { ...ctx, gitRepoRoot: host ? await resolveSpawnRepoRoot(host, policy.cwd) : null };
   }
-  // Preserve immediate in-process command construction for durable policy wake callers. The worker
-  // backend never enters this synchronous branch, so it cannot reopen the closed-main DB path.
-  return gatewayBackend() === "in-process" ? buildManagedSpawnParams(policy, requestId, ctx) : buildManagedSpawnParamsWorkerAsync(policy, requestId, ctx);
+  return buildManagedSpawnParamsWorkerAsync(policy, requestId, ctx);
 }
 
 async function buildManagedSpawnParamsWorkerAsync(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Promise<Record<string, unknown>> {
@@ -231,6 +234,7 @@ async function buildManagedSpawnParamsWorkerAsync(policy: SpawnPolicy, requestId
   const extraCwdPrefixes = managedCwdPrefixes(policy, requestId, ctx, orchestrator);
   const composed = await composeProfileSpawnInstructionsAsync(managedInstructionInput(policy, agentProfile, agentRelayIdentity, orchestratorHost, alwaysOnAppend));
   return buildManagedCommand({ policy, requestId, ctx, agentId, prompt, agentProfile, orchestrator, extraCwdPrefixes, composed,
-    modelParams: await resolveSpawnModelParamsAsync(policy.provider, policy.model, policy.effort, { skipDefaultWhenEmpty: !isStewardPolicy(policy) }),
+    modelParams: await resolveSpawnModelParamsAsync(policy.provider, policy.model, policy.effort),
+    env: await runnerRuntimeTokenEnvAsync(managedTokenInput(policy, requestId, ctx, agentId, extraCwdPrefixes)),
   });
 }

package/src/mcp/index.ts

@@ -1,5 +1,6 @@
 import { normalizeOutputArgs, outputToolDefinition, presentToolOutput } from "./output-levels";
 import { PROMPT_TOOLS, relayPrompt } from "./prompts";
+import { PROJECT_PROFILE_INSTRUCTION_TOOLS, relayProjectProfileInstructions } from "./project-profile-instructions";
 import { PromptVersionConflictError } from "../prompt-version-errors";
 import { memoryRetirementMessage } from "../memory-retirement";
 import { GUIDE_TOOLS, relayGuide } from "./guides";
@@ -60,6 +61,7 @@ const MCP_PROTOCOL_VERSION = "2024-11-05";
 const MCP_BODY_OVERHEAD_BYTES = ARTIFACT_BODY_OVERHEAD_BYTES;
 const TOOLS: ToolDefinition[] = [
   ...PROMPT_TOOLS,
+  ...PROJECT_PROFILE_INSTRUCTION_TOOLS,
   ...WEB_TOOL_CALL_TOOLS,
   ...MESSAGING_TOOLS,
   ...ARTIFACT_TOOLS,
@@ -215,6 +217,7 @@ async function callTool(auth: VerifiedMcpAuthContext, params: unknown, signal?:
     else if (name === "relay_hosts") result = await relayHosts(auth, args);
     else if (name === "relay_host_gate_budget") result = await relayHostGateBudget(auth, args);
     else if (name === "relay_prompt") result = await relayPrompt(auth, args);
+    else if (name === "relay_project_profile_instructions") result = await relayProjectProfileInstructions(auth, args);
     else if (name === "relay_service_access") result = await relayServiceAccess(auth, args);
     else if (name.startsWith("relay_secret_")) result = await relaySecretTool(auth, name, args);
     else if (name === "relay_my_agents") result = await relayMyAgents(auth, args);
@@ -223,7 +226,7 @@ async function callTool(auth: VerifiedMcpAuthContext, params: unknown, signal?:
     else if (name === "relay_agent_keep") result = await relayAgentKeep(auth, args);
     else if (name === "relay_codex_reset_consume") result = await relayCodexResetConsume(args);
     else if (name === "relay_claude_api_budget") result = await relayClaudeApiBudget(args);
-    else if (name === "relay_profile_trust") result = relayProfileTrust(auth, args);
+    else if (name === "relay_profile_trust") result = await relayProfileTrust(auth, args);
     else if (name.startsWith("relay_routing_policy_")) result = await relayRoutingPolicyTool(auth, name, args);
     else if (name === "relay_agent_action") result = await relayAgentAction(auth, args);
     else if (name === "relay_set_effort") result = await relaySetEffort(auth, args);
@@ -253,7 +256,7 @@ async function callTool(auth: VerifiedMcpAuthContext, params: unknown, signal?:
     // #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 = 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 === "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 === "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_delete_channel_binding") result = await relayDeleteChannelBinding(args, auth);

package/src/mcp/output-descriptions.ts

@@ -27,14 +27,14 @@ export const OUTPUT_DESCRIPTIONS: Record<string, string> = {
   relay_kernel_listEntities: "List entities.",
   relay_kernel_listEvents: "List events.",
   relay_kernel_listInstances: "List workflow instances.",
-  relay_list_artifacts: "List artifacts; relay_read_artifact reads bodies.",
+  relay_list_artifacts: "List artifacts (metadata only).",
   relay_list_subscriptions: "Your subscriptions",
   relay_list_timers: "List your scheduled timers.",
   relay_maintenance_jobs: "Job health; jobId reads runbook.",
   relay_maintenance_pauses: "Maintenance pauses.",
   relay_merge_pauses: "Merge holds",
   relay_notification_preview: "Preview notification routing.",
-  relay_plan_get: "Read plan; mode:resume selects the frontier view.",
+  relay_plan_get: "Read plan; mode:resume reads the frontier.",
   relay_plan_list: "List team plans.",
   relay_project_checkout: "Inspect, bind, unbind (keeps files) or remove (deletes files) a checkout.",
   relay_project_get: "Read project and roots.",
@@ -44,7 +44,7 @@ export const OUTPUT_DESCRIPTIONS: Record<string, string> = {
   relay_project_search: "Search memory; read full bodies by returned ids.",
   relay_prompt: "Read/edit prompts; writes need expectedVersion; restore/adopt append.",
   relay_read_artifact: "Page artifact text; binary returns download command.",
-  relay_recall: "Search history; read a returned ref for the segment.",
+  relay_recall: "Search history; read a returned ref.",
   relay_release_readiness: "Read release readiness.",
   relay_routing_policy_get: "Read policy",
   relay_run: "Run shell work. Long work: waitMs:0, END YOUR TURN and await completion; never poll.",
@@ -53,17 +53,17 @@ export const OUTPUT_DESCRIPTIONS: Record<string, string> = {
   relay_task_close_bridge: "Read Task close-bridge state.",
   relay_task_get: "Read Task hydration.",
   relay_task_history: "Read Task history.",
-  relay_task_list: "List your Tasks; mine:false lists all.",
+  relay_task_list: "Tasks.",
   relay_task_memory_read: "Read Task continuation.",
   relay_task_needs_validation: "List Tasks awaiting validation.",
   relay_team_get: "Read team and roster summary.",
   relay_team_template_get: "Read saved",
   relay_team_template_list: "Saved",
-  relay_web_tool_calls: "Page web calls newest first; times are epoch milliseconds.",
+  relay_web_tool_calls: "Page web calls, newest first; epoch ms.",
   relay_why_notified: "Explain delivery.",
-  relay_workflow_cancel: "Cancel run and reap agents.",
-  relay_workflow_get: "Read run status; history and result pages are opt-in.",
-  relay_workflow_resume: "Resume or answer/escalate a decision.",
+  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_start: "Start Task workflow.",
   relay_workspace_deps: "Check or refresh workspace dependencies.",
   relay_workspace_list: "List workspaces.",

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;
@@ -328,7 +328,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 +339,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 +368,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/tool-groups.ts

@@ -29,7 +29,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"],

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-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-host-tools.ts

@@ -35,7 +35,7 @@ export const HOST_TOOLS: ToolDefinition[] = [{
       landSlots: { anyOf: [{ type: "integer", minimum: 1, maximum: 1000 }, { type: "null" }] },
       validationSlots: { anyOf: [{ type: "integer", minimum: 1, maximum: 1000 }, { type: "null" }] },
       runCpus: { anyOf: [{ type: "number", minimum: 0.01, maximum: 1000 }, { type: "null" }] },
-      runMemory: { anyOf: [{ type: "integer", minimum: 1 }, { type: "null" }], description: "Per-run memory cap in bytes" },
+      runMemory: { anyOf: [{ type: "integer", minimum: 1 }, { type: "null" }], description: "Soft per-run memory, bytes" },
       projectGateReservations: { anyOf: [{ type: "object", additionalProperties: { type: "integer", minimum: 1, maximum: 1000 } }, { type: "null" }] },
     },
   },

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, listIssueRefs } from "./db/issue-refs";
+import { deleteIssueRefAsync, 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") {
@@ -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 };
   }

package/src/mcp-maintenance-tools.ts

@@ -11,7 +11,7 @@
 
 import { ValidationError } from "./db";
 import { McpNotFoundError } from "./mcp-errors";
-import { listMaintenanceJobs } from "./maintenance";
+import { listMaintenanceJobsAsync } from "./maintenance";
 import { listPauses, pauseJob, resumeJobAsync } from "./maintenance/pauses";
 import { authContextFromMcp } from "./services/auth-context";
 import { cleanString } from "./validation";
@@ -72,7 +72,7 @@ export async function relayMaintenanceTool(auth: McpAuthLike, name: string, args
   }
 
   if (name === "relay_maintenance_jobs") {
-    const jobs = listMaintenanceJobs();
+    const jobs = await listMaintenanceJobsAsync();
     const jobId = cleanString(args.jobId, "jobId", { max: 120 });
     if (!jobId) return { jobs, count: jobs.length };
     const job = jobs.find(candidate => candidate.id === jobId);

package/src/mcp-profile-trust-tools.ts

@@ -3,7 +3,7 @@ import { INCLUDED_TOOL_SCOPE_NEEDS } from "./mcp/tool-groups";
 import { ValidationError } from "./db";
 import { callerAgentId } from "./mcp/identity";
 import { optionalEnum } from "./validation";
-import { approveProfileProjectTrust, PROJECT_REVIEW_MODES, PROJECT_TRUST_CAPABILITIES, updateProfileProjectTrust } from "./services/profile-trust";
+import { approveProfileProjectTrust, PROJECT_REVIEW_MODES, PROJECT_TRUST_CAPABILITIES, updateProfileProjectTrustAsync } from "./services/profile-trust";
 import type { McpAuthContext, ToolDefinition } from "./mcp/types";
 
 export const PROFILE_TRUST_TOOL: ToolDefinition = {
@@ -31,17 +31,17 @@ function text(args: Record<string, unknown>, field: string): string {
   return value.trim();
 }
 
-export function relayProfileTrust(auth: McpAuthContext, args: Record<string, unknown>): unknown {
+export async function relayProfileTrust(auth: McpAuthContext, args: Record<string, unknown>): Promise<unknown> {
   const name = text(args, "profile");
   const by = callerAgentId(auth) ?? auth.actor;
   if (args.action === "set-review") {
     const review = optionalEnum(args.review, "review", PROJECT_REVIEW_MODES);
     if (!review) throw new ValidationError("review is required");
-    return { trust: updateProfileProjectTrust(name, { review }, by).value.sources?.project?.trust };
+    return { trust: (await updateProfileProjectTrustAsync(name, { review }, by)).value.sources?.project?.trust };
   }
   const capability = optionalEnum(args.capability, "capability", PROJECT_TRUST_CAPABILITIES);
   if (!capability) throw new ValidationError("capability is required");
-  if (args.action === "ack") return { ack: updateProfileProjectTrust(name, { ack: [capability] }, by).value.sources?.project?.[capability]?.ack };
+  if (args.action === "ack") return { ack: (await updateProfileProjectTrustAsync(name, { ack: [capability] }, by)).value.sources?.project?.[capability]?.ack };
   if (args.action === "approve") return { approval: approveProfileProjectTrust({ name, capability, repoKey: text(args, "repoKey"), value: text(args, "value"), by }) };
   throw new ValidationError("action must be set-review, ack or approve");
 }

package/src/mcp-provider-catalog.ts

@@ -1,9 +1,9 @@
-import { VALID_EFFORTS, isRecord } from "@humwick/sdk";
+import { isRecord } from "@humwick/sdk";
 import { effectiveProviderEffortLevelsAsync } from "./db";
 
 export async function providerCatalogToolInputSchema(name: string, inputSchema: Record<string, unknown>): Promise<Record<string, unknown>> {
   if (name !== "relay_spawn_agent") return inputSchema;
   const efforts = await effectiveProviderEffortLevelsAsync();
   const properties = isRecord(inputSchema.properties) ? inputSchema.properties : {};
-  return { ...inputSchema, properties: { ...properties, effort: { type: "string", enum: efforts.length ? efforts : VALID_EFFORTS } } };
+  return { ...inputSchema, properties: { ...properties, effort: { type: "string", enum: efforts }, selfEffortCeiling: { type: "string", enum: efforts } } };
 }

package/src/mcp-task-tools.ts

@@ -74,7 +74,7 @@ const TASK_ID_PROP = { oneOf: [{ type: "integer", minimum: 1 }, { type: "string"
 export const TASK_TOOLS = [
   {
     name: "relay_task_create",
-    description: "Create a durable Task. fromIssue digests GitHub title, body, acceptance, labels and references; explicit fields win.",
+    description: "Create Task; fromIssue imports GitHub content; explicit fields win.",
     requiredScopes: ["task:write"],
     inputSchema: {
       type: "object",
@@ -84,9 +84,11 @@ export const TASK_TOOLS = [
         intent: { type: "string" },
         fromIssue: { type: "string", description: "GitHub URL or owner/repo#number. Fetch once before atomic create." },
         tags: { type: "array", items: { type: "string" } },
+        paths: { type: "array", items: { type: "string" } },
         complexity: { type: "string", enum: TASK_DISPATCH_COMPLEXITIES },
         context: { type: "string" },
-        terminalStage: { type: "string", enum: TASK_TERMINAL_STAGES },
+        terminalStage: { enum: TASK_TERMINAL_STAGES },
+        onDeploy: { type: "string" },
         doneWhen: { type: "string" },
         teamId: { type: "string" },
         projectId: { type: "string" },
@@ -108,8 +110,8 @@ export const TASK_TOOLS = [
     },
   },
   { name: "relay_task_get", description: "Read a lean Task hydration; verbose:true includes full intent, gates and history projections.", requiredScopes: ["task:read"], inputSchema: { type: "object", properties: { taskId: TASK_ID_PROP, verbose: { type: "boolean" } }, required: ["taskId"], additionalProperties: false } },
-  { name: "relay_task_list", description: "List your Tasks by default; mine:false lists all. mode:brief is id/label/status; lean is default.", requiredScopes: ["task:read"], inputSchema: { type: "object", properties: { status: { type: "string", enum: DELIVERABLE_STATUS_ENUM }, deliverableStage: { type: "string", enum: TASK_DELIVERABLE_STAGES }, teamId: { type: "string" }, projectId: { type: "string" }, repo: { type: "string" }, mine: { type: "boolean" }, inFlight: { type: "boolean" }, staleOwnerGone: { type: "boolean" }, limit: { type: "integer", minimum: 1, maximum: 500 }, mode: { type: "string", enum: ["brief", "lean", "full"] }, verbose: { type: "boolean" } }, additionalProperties: false } },
-  { name: "relay_task_update", description: "Update Task intent, steer, criteria or dispatch.", requiredScopes: ["task:write"], inputSchema: { type: "object", properties: { taskId: TASK_ID_PROP, refreshIssue: { type: "object", description: "Explicit source refresh: {expectedRevision, resolutions?: {title|intent|doneWhen|tags: source|local}}. Conflicts require resolution." }, verbose: { type: "boolean" }, title: { type: "string" }, label: { type: "string" }, intent: { type: "string" }, complexity: { type: "string", enum: TASK_DISPATCH_COMPLEXITIES }, context: { type: "string" }, latestSteer: { type: "string" }, doneWhen: { type: "string" }, terminalStage: { anyOf: [{ type: "string", enum: TASK_TERMINAL_STAGES }, { type: "null" }] }, dispatch: DISPATCH_SHAPE_SCHEMA, teamId: { type: "string" }, projectId: { type: "string" }, repo: { type: "string" } }, required: ["taskId"], additionalProperties: false } },
+  { name: "relay_task_list", description: "List your Tasks by default; mine:false lists all. mode:brief is id/label/status; lean is default.", requiredScopes: ["task:read"], inputSchema: { type: "object", properties: { status: { enum: DELIVERABLE_STATUS_ENUM }, deliverableStage: { enum: [...TASK_DELIVERABLE_STAGES, "awaiting-deploy"] }, teamId: { type: "string" }, projectId: { type: "string" }, repo: { type: "string" }, mine: { type: "boolean" }, inFlight: { type: "boolean" }, staleOwnerGone: { type: "boolean" }, limit: { type: "integer", minimum: 1, maximum: 500 }, mode: { type: "string", enum: ["brief", "lean", "full"] }, verbose: { type: "boolean" } }, additionalProperties: false } },
+  { name: "relay_task_update", description: "Update Task intent, steer, criteria or dispatch.", requiredScopes: ["task:write"], inputSchema: { type: "object", properties: { taskId: TASK_ID_PROP, refreshIssue: { type: "object", description: "{expectedRevision, resolutions?: {title|intent|doneWhen|tags: source|local}}." }, verbose: { type: "boolean" }, title: { type: "string" }, label: { type: "string" }, intent: { type: "string" }, complexity: { type: "string", enum: TASK_DISPATCH_COMPLEXITIES }, context: { type: "string" }, latestSteer: { type: "string" }, onDeploy: { type: "string" }, doneWhen: { type: "string" }, terminalStage: { enum: [...TASK_TERMINAL_STAGES, null] }, dispatch: DISPATCH_SHAPE_SCHEMA, teamId: { type: "string" }, projectId: { type: "string" }, repo: { type: "string" }, paths: { type: "array", items: { type: "string" } } }, required: ["taskId"], additionalProperties: false } },
   { name: "relay_task_set_status", description: "Transition Task execution status. done requires met validation; force requires explicit override authority.", requiredScopes: ["task:write"], inputSchema: { type: "object", properties: { taskId: TASK_ID_PROP, status: { type: "string", enum: DELIVERABLE_STATUS_ENUM }, force: { type: "boolean" }, blockedBy: { type: "array", items: BLOCKER_SCHEMA }, note: { type: "string" }, verbose: { type: "boolean" } }, required: ["taskId", "status"], additionalProperties: false } },
   { name: "relay_task_set_stage", description: "Set Task delivery stage/branch/commit; normally maintained by the land/deploy pipeline.", requiredScopes: ["task:write"], inputSchema: { type: "object", properties: { taskId: TASK_ID_PROP, deliverableStage: { type: "string", enum: TASK_DELIVERABLE_STAGES }, branch: { type: "string" }, commit: COMMIT_SCHEMA }, required: ["taskId", "deliverableStage"], additionalProperties: false } },
   { name: "relay_task_confirm_carry", description: "Confirm a protected-tip revert's delivered change was carried to current main; clears only carry-pending.", requiredScopes: ["task:write"], inputSchema: { type: "object", properties: { taskId: TASK_ID_PROP, commit: COMMIT_SCHEMA, branch: { type: "string" }, note: { type: "string" } }, required: ["taskId"], additionalProperties: false } },
@@ -175,6 +177,7 @@ export async function relayTaskTool(auth: McpAuthLike, name: string, args: Recor
       complexity: optionalEnum(args.complexity, "complexity", TASK_DISPATCH_COMPLEXITIES),
       context: cleanString(args.context, "context", { max: 1_000_000 }),
       terminalStage: optionalEnum(args.terminalStage, "terminalStage", TASK_TERMINAL_STAGES),
+      onDeploy: cleanString(args.onDeploy, "onDeploy", { max: 500 }),
       doneWhen: cleanString(args.doneWhen, "doneWhen", { max: 1_000_000 }),
       teamId: cleanString(args.teamId, "teamId", { max: 200 }),
       projectId: cleanString(args.projectId, "projectId", { max: 120 }),
@@ -182,6 +185,7 @@ export async function relayTaskTool(auth: McpAuthLike, name: string, args: Recor
       branch: cleanString(args.branch, "branch", { max: 500 }),
       dispatch: args.dispatch as TaskDispatch | undefined,
       tags: args.tags as string[] | undefined,
+      paths: args.paths as string[] | undefined,
       // Alias-tolerant (#2214): a ref passed as `refs`/`issues`/`externalKey`/… used to be dropped
       // silently, leaving the Task's issues[] empty and its spawn brief without the linked spec.
       issueRefs: issueRefsFromArgs(args),
@@ -218,7 +222,7 @@ export async function relayTaskTool(auth: McpAuthLike, name: string, args: Recor
   if (name === "relay_task_list") {
     const tasks = await listTaskEntitySummariesAsync({
       status: optionalEnum(args.status, "status", DELIVERABLE_STATUS_ENUM),
-      deliverableStage: optionalEnum(args.deliverableStage, "deliverableStage", TASK_DELIVERABLE_STAGES),
+      deliverableStage: optionalEnum(args.deliverableStage, "deliverableStage", [...TASK_DELIVERABLE_STAGES, "awaiting-deploy"] as const),
       teamId: cleanString(args.teamId, "teamId", { max: 200 }),
       projectId: cleanString(args.projectId, "projectId", { max: 120 }),
       repo: cleanString(args.repo, "repo", { max: 500 }),
@@ -246,12 +250,14 @@ export async function relayTaskTool(auth: McpAuthLike, name: string, args: Recor
       ...(args.complexity !== undefined ? { complexity: optionalEnum(args.complexity, "complexity", TASK_DISPATCH_COMPLEXITIES) } : {}),
       ...(args.context !== undefined ? { context: cleanString(args.context, "context", { max: 1_000_000 }) ?? "" } : {}),
       ...(args.latestSteer !== undefined ? { latestSteer: cleanString(args.latestSteer, "latestSteer", { max: 1_000_000 }) ?? "" } : {}),
+      ...(args.onDeploy !== undefined ? { onDeploy: cleanString(args.onDeploy, "onDeploy", { max: 500 }) ?? "" } : {}),
       ...(args.doneWhen !== undefined ? { doneWhen: cleanString(args.doneWhen, "doneWhen", { max: 1_000_000 }) ?? "" } : {}),
       ...(args.terminalStage !== undefined ? { terminalStage: args.terminalStage === null ? null : optionalEnum(args.terminalStage, "terminalStage", TASK_TERMINAL_STAGES) } : {}),
       ...(args.dispatch !== undefined ? { dispatch: args.dispatch as TaskDispatch } : {}),
       ...(args.teamId !== undefined ? { teamId: cleanString(args.teamId, "teamId", { max: 200 }) ?? "" } : {}),
       ...(args.projectId !== undefined ? { projectId: cleanString(args.projectId, "projectId", { max: 120 }) ?? "" } : {}),
       ...(args.repo !== undefined ? { repo: cleanString(args.repo, "repo", { max: 500 }) ?? "" } : {}),
+      ...(args.paths !== undefined ? { paths: args.paths as string[] | null } : {}),
     };
     const task = await updateTaskEntityAsync(taskIdArg(args.taskId), { ...patch, actor });
     if (args.verbose === true) return task as unknown as Record<string, unknown>;

package/src/mcp-team-template-tools.ts

@@ -2,7 +2,7 @@ import { INCLUDED_TOOL_SCOPE_NEEDS } from "./mcp/tool-groups";
 import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_AGENT_LIFECYCLES, VALID_WORKSPACE_MODES } from "@humwick/sdk";
 import { McpAuthError } from "./mcp-errors";
 import { authContextFromMcp } from "./services/auth-context";
-import { deleteTeamTemplate, getTeamTemplate, instantiateTeamTemplate, listTeamTemplates, saveTeamTemplate } from "./services/team-templates";
+import { deleteTeamTemplateAsync, getTeamTemplate, instantiateTeamTemplate, listTeamTemplates, saveTeamTemplateAsync } from "./services/team-templates";
 import { summarizeSpawnCommandForCaller } from "./services/spawn-agent";
 import { ValidationError } from "./db";
 
@@ -111,7 +111,7 @@ function slugArg(args: Record<string, unknown>): string {
 export async function relayTeamTemplateTool(auth: McpAuthLike, name: string, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   if (name === "relay_team_template_save") {
     requireScope(auth, "teams:write");
-    return saveTeamTemplate(args, auth.actor) as unknown as Record<string, unknown>;
+    return await saveTeamTemplateAsync(args, auth.actor) as unknown as Record<string, unknown>;
   }
   if (name === "relay_team_template_list") return { templates: listTeamTemplates() };
   if (name === "relay_team_template_get") {
@@ -121,7 +121,7 @@ export async function relayTeamTemplateTool(auth: McpAuthLike, name: string, arg
   }
   if (name === "relay_team_template_delete") {
     requireScope(auth, "teams:write");
-    return { slug: slugArg(args), deleted: deleteTeamTemplate(slugArg(args), auth.actor) };
+    return { slug: slugArg(args), deleted: await deleteTeamTemplateAsync(slugArg(args), auth.actor) };
   }
   if (name === "relay_team_spawn_from_template") {
     requireScope(auth, "teams:write");