@humwick/server 0.130.1 → 0.130.2

package/src/services/spawn-tree-cleanup.ts

@@ -4,11 +4,11 @@ import { getGateway } from "../db/gateway";
 import { getAgentAsync } from "../db";
 import { shutdownAgent } from "./shutdown-agent";
 import { currentStop } from "./workflow-effects";
-import { invoke, testOptions, type Supervisor } from "./workflow-supervisor-state";
+import { invoke, supervisorNow, type Supervisor } from "./workflow-supervisor-state";
 
 /** Every retry resumes the same outbox effect; only host witnesses release reservations. */
 export async function performSpawnTreeCleanup(sup: Supervisor, effect: WorkflowEffect): Promise<boolean> {
-  const now = (testOptions.now ?? Date.now)();
+  const now = supervisorNow();
   if (typeof effect.result?.nextAttemptAt === "number" && effect.result.nextAttemptAt > now) return false;
   const agentId = String(effect.payload.agentId);
   await getGateway().write("spawnTree.prepareCleanup", { agentId });

package/src/services/task-dispatch.ts

@@ -105,6 +105,7 @@ export interface TaskDispatchSpawnInput {
   /** #3045 — the workflow run dispatching this step; #3091 the base profile its step pins, the run's checkout standing in
    *  for the Task's repo root, and the host its role is read on first. Service-only. */
   workflowRunId?: string;
+  workflowNames?: string[];
   workflowCaller?: SpawnAgentInput["workflowCaller"];
   roleProfile?: string;
   taskRepoCwd?: string;
@@ -139,6 +140,7 @@ export async function spawnTaskDispatch(input: TaskDispatchSpawnInput, ctx: Auth
       role,
       roleSha, roleSnapshot,
       workflowRunId,
+      workflowNames: input.workflowNames,
       workflowCaller: input.workflowCaller,
       roleProfile,
       taskRepoCwd,
@@ -173,6 +175,7 @@ export async function spawnTaskDispatch(input: TaskDispatchSpawnInput, ctx: Auth
     ...(decision ? { decision } : {}),
     ...(reviewTaskId !== undefined ? { reviewTaskId } : {}),
     ...(spawn.warnings ? { warnings: spawn.warnings } : {}),
+    ...(spawn.spawnPolicy ? { spawnPolicy: spawn.spawnPolicy } : {}),
     ...(verbose ? { command: summarizeSpawnCommandForCaller(spawn.command) } : {}),
   };
 }

package/src/services/task-state-reconcile.ts

@@ -4,8 +4,9 @@
 // live in src/db/task-state-reconcile.ts; every change is applied by its conditional writer, which
 // re-checks the rule in the transaction, then audited here with one `task.reconciled` relay event.
 import { errMessage } from "@humwick/sdk";
-import { isSqliteBusyError, withFastFailConnection, writerLockAvailable } from "../db/connection";
-import { getIssueRef, updateIssueRef } from "../db/issue-refs";
+import { writerLockAvailable } from "../db/connection";
+import { getIssueRef } from "../db/issue-refs";
+import { updateIssueRefAsync } from "../db/issue-refs-async";
 import { applyTaskStateReconcileAsync, listTaskStateReconcileCandidatesAsync } from "../db/task-state-reconcile-async";
 import { TASK_RECONCILE_ACTOR, type TaskReconcileRule, type TaskStateReconcileApplied } from "../db/task-state-reconcile";
 import { emitRelayEvent } from "../events";
@@ -104,19 +105,10 @@ async function refreshIssueRefs(refIds: string[], opts: TaskStateReconcileOption
     try {
       const live = await (opts.adapterResolver ?? resolveIssueTrackerAdapter)(ref).getStatus(ref);
       const status = live.status === "open" || live.status === "closed" ? live.status : ref.status;
-      // The tracker read can take long: re-check the lock right before the write, and bound the write itself.
+      // The tracker read can take long: re-check the lock right before the write. The write itself waits on
+      // the writer thread, never on the loop (#1870 S7).
       if (steps.contended()) break;
-      const written = await steps.timed(() => {
-        try {
-          withFastFailConnection(STEP_BUSY_TIMEOUT_MS, () => updateIssueRef(ref.id, { status, title: live.title, closeReason: live.closeReason, statusSyncedAt: Date.now() }));
-          return true;
-        } catch (error) {
-          if (!isSqliteBusyError(error)) throw error;
-          result.moreWork = true;
-          return false;
-        }
-      });
-      if (!written) break;
+      await updateIssueRefAsync(ref.id, { status, title: live.title, closeReason: live.closeReason, statusSyncedAt: Date.now() });
       closedAny ||= status === "closed";
     } catch (error) {
       refreshFailedAt.set(id, now);

package/src/services/team-templates.ts

@@ -1,6 +1,7 @@
 import { isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, APPROVAL_MODES, VALID_AGENT_LIFECYCLES } from "@humwick/sdk";
 import { getTeam, ValidationError } from "../db";
-import { deleteConfig, getConfig, listConfig, setConfig } from "../config-store";
+import { getConfig, listConfig } from "../config-store";
+import { deleteConfigAsync, setConfigAsync } from "../config-store-write";
 import { TEAM_TEMPLATE_NAMESPACE } from "../team-template-config";
 import { cleanString, optionalEnum } from "../validation";
 import type { AuthContext } from "./auth-context";
@@ -47,11 +48,11 @@ function withTimestamps(template: TeamTemplate, existing?: TeamTemplate): TeamTe
   };
 }
 
-export function saveTeamTemplate(input: Record<string, unknown>, updatedBy?: string): TeamTemplate {
+export async function saveTeamTemplateAsync(input: Record<string, unknown>, updatedBy?: string): Promise<TeamTemplate> {
   if (input.teamId !== undefined && input.composition !== undefined) {
     throw new ValidationError("teamId capture and manual composition are mutually exclusive");
   }
-  if (input.teamId !== undefined) return captureTeamTemplateFromTeam(cleanString(input.teamId, "teamId", { required: true, max: 120 })!, input, updatedBy);
+  if (input.teamId !== undefined) return captureTeamTemplateFromTeamAsync(cleanString(input.teamId, "teamId", { required: true, max: 120 })!, input, updatedBy);
   const slug = templateSlug(input);
   const existing = getConfig<TeamTemplate>(TEAM_TEMPLATE_NAMESPACE, slug)?.value;
   const template = withTimestamps({
@@ -64,7 +65,7 @@ export function saveTeamTemplate(input: Record<string, unknown>, updatedBy?: str
     ...(cleanString(input.definitionOfDone, "definitionOfDone", { max: 4000 }) ? { definitionOfDone: cleanString(input.definitionOfDone, "definitionOfDone", { max: 4000 }) } : {}),
     ...(input.planSkeleton !== undefined ? { planSkeleton: input.planSkeleton as TeamTemplate["planSkeleton"] } : {}),
   }, existing);
-  return setConfig(TEAM_TEMPLATE_NAMESPACE, template.slug, template, updatedBy).value as TeamTemplate;
+  return (await setConfigAsync(TEAM_TEMPLATE_NAMESPACE, template.slug, template, updatedBy)).value as TeamTemplate;
 }
 
 export function listTeamTemplates(): TeamTemplate[] {
@@ -75,8 +76,8 @@ export function getTeamTemplate(slug: string): TeamTemplate | null {
   return getConfig<TeamTemplate>(TEAM_TEMPLATE_NAMESPACE, slug)?.value ?? null;
 }
 
-export function deleteTeamTemplate(slug: string, updatedBy?: string): boolean {
-  return deleteConfig(TEAM_TEMPLATE_NAMESPACE, slug, updatedBy);
+export function deleteTeamTemplateAsync(slug: string, updatedBy?: string): Promise<boolean> {
+  return deleteConfigAsync(TEAM_TEMPLATE_NAMESPACE, slug, updatedBy);
 }
 
 function parseFrozenComposition(raw: string): Array<Record<string, unknown>> {
@@ -107,7 +108,7 @@ function compositionFromFrozenSnapshot(raw: string): TeamTemplateCompositionEntr
   return composition;
 }
 
-export function captureTeamTemplateFromTeam(teamId: string, input: Record<string, unknown> = {}, updatedBy?: string): TeamTemplate {
+export async function captureTeamTemplateFromTeamAsync(teamId: string, input: Record<string, unknown> = {}, updatedBy?: string): Promise<TeamTemplate> {
   const team = getTeam(teamId);
   if (!team) throw new ValidationError(`team ${teamId} not found`);
   if (!team.composition) throw new ValidationError("team has no frozen composition snapshot; dissolve it before capture");
@@ -123,7 +124,7 @@ export function captureTeamTemplateFromTeam(teamId: string, input: Record<string
     ...(team.brief ? { brief: team.brief } : {}),
     ...(team.definitionOfDone ? { definitionOfDone: team.definitionOfDone } : {}),
   }, existing);
-  return setConfig(TEAM_TEMPLATE_NAMESPACE, template.slug, template, updatedBy).value as TeamTemplate;
+  return (await setConfigAsync(TEAM_TEMPLATE_NAMESPACE, template.slug, template, updatedBy)).value as TeamTemplate;
 }
 
 function cleanWait(value: unknown): number {

package/src/services/transient-agent-reaper.ts

@@ -15,6 +15,7 @@ import { activeAgentKeep } from "./agent-keep";
 import { automaticDisposalBlocker } from "./automatic-disposal";
 import { agentGenerationKey } from "../db/agent-shutdown-in-flight";
 import { workflowAgentObligation } from "./workflow-agent-obligation";
+import { workflowRunPaused } from "../db/workflow-task-read-ops";
 import type { AgentCard, Command, WorkspaceRecord } from "../types";
 import { emitCommandEvent } from "../command-events";
 
@@ -356,7 +357,8 @@ export async function reapTransientAgents(context: { signal?: AbortSignal } = {}
     if (completedProviderTurns(agent) === 0) { transientTracker.delete(agent.id); waiting.push(agent.id); continue; }
     // #3234 — an empty branch is not completion while the workflow still awaits this agent's delivery.
     const runId = workflowRunIdOf(agent);
-    if (runId && await workflowAgentObligation(runId, agent.id)) { transientTracker.delete(agent.id); waiting.push(agent.id); continue; }
+    // #3757 — a paused run keeps all its step agents.
+    if (runId && (workflowRunPaused(runId) || await workflowAgentObligation(runId, agent.id))) { transientTracker.delete(agent.id); waiting.push(agent.id); continue; }
     const entry = transientTracker.get(agent.id) ?? { firstIdleAt: now };
     transientTracker.set(agent.id, entry);
     const idleForMs = now - entry.firstIdleAt;

package/src/services/workflow-auto-start.ts

@@ -1,14 +1,17 @@
 // #3091 — workflows by default: a builder spawn for a Task that lands code starts the project's build-review
 // workflow instead, and its run spawns the builder. One core behind relay_spawn_agent, relay_task_dispatch and
 // POST /api/agents/spawn; `workflow: false` keeps the manual path. review, research and ops Tasks never start one.
+// #3736 — a project spawn-policy rule matching the Task names the workflow instead, whatever the Task's type.
 import { WORKFLOW_AUTO_START_NAME, workflowAutoStarts, type WorkflowRunAgent, type WorkflowRunView } from "@humwick/sdk";
-import { getTaskDetailAsync, ValidationError } from "../db";
+import { SPAWN_POLICY_FILE } from "@humwick/sdk/spawn-policy";
+import { getAgent, getTaskDetailAsync, resolveProjectForCwd, ValidationError } from "../db";
 import { getAgentProfile } from "../config-store";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { ServiceAuthError } from "./errors";
 import { getWorkflowRun, launchWorkflowRun, prepareWorkflowRun, type PreparedWorkflowRun } from "./workflow-runs";
 import type { WorkflowPins } from "./workflow-pins";
 import type { AuthContext } from "./auth-context";
+import { spawnerKind, spawnPolicyTask, spawnPolicyWorkflowFor } from "./spawn-policy";
 
 /** A builder spawn as its transport received it: the Task, the opt-out, and every other field the caller set (wire names). */
 export interface BuilderSpawn {
@@ -58,18 +61,27 @@ function refused(fields: Record<string, unknown>): string[] {
 export async function workflowForBuilderSpawn(spawn: BuilderSpawn, ctx: AuthContext): Promise<BuilderSpawnOutcome> {
   if (spawn.workflow === false || spawn.taskId === undefined) return { started: false };
   const task = await getTaskDetailAsync(spawn.taskId);
-  const type = task?.kind === "deliverable" ? task.dispatch?.type : undefined;
-  if (!task || !workflowAutoStarts(type)) return { started: false };
-  const subject = `T${task.id} is a ${type} Task, so this spawn starts workflow ${WORKFLOW_AUTO_START_NAME}, whose run spawns the builder`;
-  const optOut = "pass workflow:false to spawn by hand";
+  if (!task || task.kind !== "deliverable") return { started: false };
+  const type = task.dispatch?.type;
+  const { cwd, orchestratorId } = spawn.fields;
+  const caller = ctx.callerAgentId ? getAgent(ctx.callerAgentId) ?? undefined : undefined;
+  const checkout = typeof cwd === "string" && cwd ? { cwd, ...(typeof orchestratorId === "string" && orchestratorId ? { orchestratorId } : {}) } : undefined;
+  const policy = await spawnPolicyWorkflowFor(
+    { projectId: task.projectId ?? (checkout ? resolveProjectForCwd(checkout.cwd)?.id : undefined), ...(checkout ? { checkout } : {}) },
+    { spawner: spawnerKind(ctx, {}, caller), task: spawnPolicyTask(task)! },
+  );
+  if (!policy && !workflowAutoStarts(type)) return { started: false };
+  const workflow = policy?.workflow ?? WORKFLOW_AUTO_START_NAME;
+  const why = policy ? `T${task.id} matches ${SPAWN_POLICY_FILE} rule "${policy.rule}"` : `T${task.id} is a ${type} Task`;
+  const subject = `${why}, so this spawn starts workflow ${workflow}, whose run spawns the builder`;
+  const optOut = policy ? "the project's spawn policy runs this Task only through that workflow" : "pass workflow:false to spawn by hand";
   if (!taskRepos(task).length) return { started: false, reason: `T${task.id} names no repo, so no workflow can run on it` };
   const conflicts = refused(spawn.fields);
-  if (conflicts.length) throw new ValidationError(`${subject}; the run cannot honor ${conflicts.map((key) => `${key}=${JSON.stringify(spawn.fields[key])}`).join(", ")}. Drop ${conflicts.length > 1 ? "them" : "it"}, or ${optOut}`);
+  if (conflicts.length) throw new ValidationError(`${subject}; the run cannot honor ${conflicts.map((key) => `${key}=${JSON.stringify(spawn.fields[key])}`).join(", ")}. Drop ${conflicts.length > 1 ? "them" : "it"}${policy ? "" : `, or ${optOut}`}`);
   try {
     // Located as the spawn itself would be: its cwd and host, else the Task's repo root.
-    const { cwd, orchestratorId } = spawn.fields;
     const prepared = await prepareWorkflowRun({
-      workflow: WORKFLOW_AUTO_START_NAME, taskId: task.id, ...(typeof cwd === "string" && cwd ? { cwd } : {}), ...(typeof orchestratorId === "string" && orchestratorId ? { orchestratorId } : {}),
+      workflow, taskId: task.id, ...(typeof cwd === "string" && cwd ? { cwd } : {}), ...(typeof orchestratorId === "string" && orchestratorId ? { orchestratorId } : {}),
     }, ctx);
     const inputSteps = Object.entries(prepared.read.workflow.definition.steps).filter(([, step]) => step.task === "input");
     const role = spawn.fields.role;
@@ -80,7 +92,7 @@ export async function workflowForBuilderSpawn(spawn: BuilderSpawn, ctx: AuthCont
     const steer = BRIEF_FIELDS.map((key) => spawn.fields[key]).filter((value): value is string => typeof value === "string" && Boolean(value.trim())).join("\n\n");
     // The call answers for the builder's spawn: one the run cannot dispatch fails it, as a spawn by hand would (#3160).
     const started = await launchWorkflowRun(prepared, { ...(pins ? { pins } : {}), ...(steer ? { steer } : {}), refuseUndispatched: true }, ctx) as WorkflowRunView & { existing?: true; warnings?: string[] };
-    return { started: true, receipt: await receiptFor(prepared, started, set(spawn.fields).filter((key) => UNUSED_FIELDS.includes(key)), ctx) };
+    return { started: true, receipt: await receiptFor(prepared, started, set(spawn.fields).filter((key) => UNUSED_FIELDS.includes(key)), { why, policyRule: policy?.rule }, ctx) };
   } catch (error) {
     if (error instanceof ServiceAuthError) throw new McpAuthError(`${subject}: ${error.message}; ${optOut}`);
     if (error instanceof ValidationError || error instanceof McpAuthError || error instanceof McpNotFoundError) error.message = `${subject}: ${error.message}; ${optOut}`;
@@ -99,7 +111,7 @@ function builderPin(fields: Record<string, unknown>): Record<string, string> {
 }
 
 /** The spawn's receipt: the run, and its builder as a spawn receipt names one (the newest agent of the build step). */
-async function receiptFor(prepared: PreparedWorkflowRun, started: WorkflowRunView & { existing?: true; warnings?: string[] }, ignored: string[], ctx: AuthContext): Promise<Record<string, unknown>> {
+async function receiptFor(prepared: PreparedWorkflowRun, started: WorkflowRunView & { existing?: true; warnings?: string[] }, ignored: string[], cause: { why: string; policyRule?: string }, ctx: AuthContext): Promise<Record<string, unknown>> {
   const { task, read } = prepared;
   const run = await getWorkflowRun(started.runId, ctx, { verbose: true }) as WorkflowRunView & { agents: WorkflowRunAgent[] };
   const step = run.steps.find((entry) => read.workflow.definition.steps[entry.name]?.task === "input")!;
@@ -107,8 +119,8 @@ async function receiptFor(prepared: PreparedWorkflowRun, started: WorkflowRunVie
   const profile = step.pin?.profile ?? read.workflow.roles.get(step.role)?.extends;
   const label = `workflow ${run.workflow} (${run.source ?? "project"}) run ${run.runId}`;
   const note = started.existing
-    ? `T${task.id} already runs ${label}, which owns its builder: no builder was spawned. relay_workflow_get shows its agents; pass workflow:false to spawn beside it.`
-    : `T${task.id} is a ${task.dispatch?.type} Task, so Relay started ${label}; its run ${agent ? "spawned" : "is spawning"} the builder (role ${step.role} on profile ${profile}). You hear back on a step spawn failure, an escalation or the result. Pass workflow:false to spawn by hand.`;
+    ? `T${task.id} already runs ${label}, which owns its builder: no builder was spawned. relay_workflow_get shows its agents${cause.policyRule ? "" : "; pass workflow:false to spawn beside it"}.`
+    : `${cause.why}, so Relay started ${label}; its run ${agent ? "spawned" : "is spawning"} the builder (role ${step.role} on profile ${profile}). You hear back on a step spawn failure, an escalation or the result.${cause.policyRule ? "" : " Pass workflow:false to spawn by hand."}`;
   const warnings = [...(started.warnings ?? []), ...(ignored.length ? [`the run sets these for its own agents, so ${ignored.join(", ")} went unused`] : [])];
   return {
     ok: true,
@@ -116,7 +128,7 @@ async function receiptFor(prepared: PreparedWorkflowRun, started: WorkflowRunVie
     taskId: task.id,
     workflowRun: {
       runId: run.runId, workflow: run.workflow, ...(run.source ? { source: run.source } : {}), sha: run.sha, status: run.status, step: run.step,
-      taskType: task.dispatch?.type, ...(started.existing ? { existing: true } : {}),
+      taskType: task.dispatch?.type, ...(cause.policyRule ? { spawnPolicyRule: cause.policyRule } : {}), ...(started.existing ? { existing: true } : {}),
       builder: { step: step.name, role: step.role, ...(profile ? { profile } : {}), ...(step.pin ? { pin: step.pin } : {}) },
     },
     ...(agent ? { spawnRequestId: agent.spawnRequestId, agentId: agent.agentId ?? null, registered: Boolean(agent.agentId), ...(agent.provider ? { provider: agent.provider } : {}) } : {}),

package/src/services/workflow-ci-main.ts

@@ -1,4 +1,4 @@
-import { correlatedCiIncidents } from "./plan-ci-recovery";
+import { correlatedCiIncidents } from "./plan-ci-notice";
 // #3045 H5 — the `ci-main` step after the land: CI on main for the exact landed commit. The CI monitor's
 // existing tick observes every commit a run waits on (ci_sha_observations); this module only reads that
 // evidence. Red alerts the coordinator once while the run keeps waiting; green on every watch ends the run

package/src/services/workflow-deferred-cleanup.ts

@@ -1,3 +1,4 @@
+import { workflowLandVerification } from "./workflow-land-notice";
 import type { WorkflowEffect, WorkflowRunRecord } from "@humwick/kernel/workflow.pilot";
 import { notifySystemMessage } from "../notify";
 import { workflowCoordinatorTarget } from "./workflow-coordinator";
@@ -29,10 +30,11 @@ async function resumeHosts(sup: Supervisor, orchestratorId?: string): Promise<vo
 }
 
 export async function notifyDeferredWorkflowCleanup(run: WorkflowRunRecord, effect: WorkflowEffect): Promise<void> {
+  const proof = run.landed?.sha ? await workflowLandVerification(run, run.landed.sha) : undefined;
   notifySystemMessage(await workflowCoordinatorTarget(run), {
     subject: `Workflow ${run.id}: cleanup deferred`,
-    body: `Workflow ${run.id} landed as ${run.landed?.sha}. Shutdowns on offline hosts are recorded durably and will run when those hosts re-register. The run can finish with its CI result.`,
-    payload: { kind: "workflow.cleanup-deferred", runId: run.id, effectId: effect.id, deferred: effect.result?.deferred },
+    body: `Workflow ${run.id}: ${proof?.verified ? `landed as ${run.landed?.sha}. verified: true.` : proof?.line ?? "No land receipt."} Shutdowns on offline hosts are recorded durably and will run when those hosts re-register. The run can finish with its CI result.`,
+    payload: { ...(proof ? { verified: proof.verified } : {}), kind: "workflow.cleanup-deferred", runId: run.id, effectId: effect.id, deferred: effect.result?.deferred },
     idempotencyKey: `workflow:${run.id}:cleanup-deferred`,
     replyExpected: false,
     maxAgeSeconds: null,

package/src/services/workflow-effect-driver.ts

@@ -156,6 +156,8 @@ export async function drainEffects(sup: Supervisor): Promise<number> {
         continue;
       }
       const run = await invoke<WorkflowRunRecord>(sup, "get", { runId: effect.runId });
+      // #3757 — a paused run spawns, messages, arms and reaps nothing until its unpause; only its pause notices go out.
+      if (run.pause && effect.kind !== "pause-notice") continue;
       if (await settleEffect(sup, run, effect)) settled += 1;
     } catch (error) {
       console.warn(`workflow effect ${effect.id} could not be settled: ${errMessage(error)}`);

package/src/services/workflow-effects.ts

@@ -1,4 +1,4 @@
-import { planCiNotice } from "./plan-ci-recovery";
+import { planCiNotice } from "./plan-ci-notice";
 import { performWorkflowDecision, performWithdrawWorkflowDecision } from "./workflow-decisions";
 import { getCommandAsync } from "../commands-write";
 // #3045 — the src half of a workflow run: the kernel writes effect intents and waits; this module
@@ -23,9 +23,10 @@ import { spawnTaskDispatch } from "./task-dispatch";
 import type { DispatchPin } from "../task-dispatcher";
 import { createTaskEntityAsync } from "./task-entity";
 import { workflowNotice } from "./workflow-notice";
+import { workflowPauseNotice } from "./workflow-pause-text";
 import { planQuietingRunNotice } from "./plan-wake-policy";
 import { workflowOverdueLead } from "./workflow-overdue-notice";
-import { workflowLandNotice } from "./workflow-land-notice";
+import { workflowLandNotice, workflowLandVerification } from "./workflow-land-notice";
 import { ciRedLead, ciResultLine } from "./workflow-ci-main";
 import { stepTaskDispatch } from "./workflow-pins";
 import { workflowDispatchResult } from "./workflow-dispatch-result";
@@ -112,7 +113,7 @@ async function dispatchRole(run: WorkflowRunRecord, effect: WorkflowEffect, agen
   const spawnRequestId = spawnRequestIdFor(effect);
   await call("prepareDispatch", { id: effect.id, taskId, spawnRequestId });
   const spawn = await spawnTaskDispatch({
-    taskId, role, roleSha: run.sha, ...(run.callerAgentId ? { workflowCaller: { agentId: run.callerAgentId, maxLiveAgents: run.maxLiveAgents ?? 2, runId: run.rootRunId ?? run.id } } : {}), ...(run.snapshot?.[run.workflow]?.roles[role] ? { roleSnapshot: run.snapshot[run.workflow]!.roles[role] as unknown as import("../project-roles").ProjectRole } : {}), workflowRunId: run.id, pin: stepDispatchPin(pin, step), pinSources: pin?.from, createReview: false, ...(pin?.orchestratorId ? { orchestratorId: pin.orchestratorId } : {}),
+    taskId, role, roleSha: run.sha, ...(run.callerAgentId ? { workflowCaller: { agentId: run.callerAgentId, maxLiveAgents: run.maxLiveAgents ?? 2, runId: run.rootRunId ?? run.id } } : {}), ...(run.snapshot?.[run.workflow]?.roles[role] ? { roleSnapshot: run.snapshot[run.workflow]!.roles[role] as unknown as import("../project-roles").ProjectRole } : {}), workflowRunId: run.id, workflowNames: [...new Set([run.workflow, ...Object.keys(run.snapshot ?? {})])], pin: stepDispatchPin(pin, step), pinSources: pin?.from, createReview: false, ...(pin?.orchestratorId ? { orchestratorId: pin.orchestratorId } : {}),
     taskRepoCwd: run.cwd, roleHost: run.orchestratorId, ...(pin?.profile ? { roleProfile: pin.profile } : {}),
     spawnRequestId, waitForRegistrationMs: 0, verbose: false, ...(steer ? { steer } : {}), ...avoid,
   }, WORKFLOW_CTX);
@@ -377,6 +378,10 @@ export async function performWorkflowEffect(run: WorkflowRunRecord, effect: Work
       return { messageId: message.id };
     }
     case "landed": return { superseded: "the CI verdict owns the coordinator notice" };
+    case "pause-notice": {
+      const message = notifySystemMessage(await workflowCoordinatorTarget(run), { ...workflowPauseNotice(runLabel(run), run, effect), idempotencyKey: key, replyExpected: false });
+      return { messageId: message.id };
+    }
     case "reap":
       return reapAgents(run, effect, reapTargets(run, effect, agents));
     case "dispatch": {
@@ -451,12 +456,13 @@ export async function performWorkflowEffect(run: WorkflowRunRecord, effect: Work
       }
       if (effect.payload.reason === "ci-red" || effect.payload.reason === "ci-late") {
         const sha = str(effect.payload.landedSha) ?? run.landed?.sha ?? "";
+        const proof = await workflowLandVerification(run, sha);
         const message = notifySystemMessage(await workflowCoordinatorTarget(run), {
-          subject: `${runLabel(run)} landed, CI on main ${effect.payload.reason === "ci-red" ? "red" : "late"}`,
-          body: workflowNotice(run, [`T${run.taskId} landed as ${sha}.`, ...(effect.payload.reason === "ci-red" ? ciRedLead(runLabel(run), effect.payload) : [ciResultLine(effect.payload.ci as WorkflowCiVerdict)!])]),
+          subject: `${runLabel(run)} ${proof.verified ? "landed" : "land verification FAILED"}, CI on main ${effect.payload.reason === "ci-red" ? "red" : "late"}`,
+          body: workflowNotice(run, [proof.verified ? `T${run.taskId} landed as ${sha}. ${proof.line}` : proof.line, ...(effect.payload.reason === "ci-red" ? ciRedLead(runLabel(run), effect.payload) : [ciResultLine(effect.payload.ci as WorkflowCiVerdict)!])]),
           idempotencyKey: `workflow:landed:${run.id}:${sha}:${effect.waitKey ?? effect.id}`,
           replyExpected: false,
-          payload: { kind: "workflow.landed", runId: run.id, taskId: run.taskId, landedSha: sha, reason: effect.payload.reason, ci: effect.payload.ci },
+          payload: { verified: proof.verified, kind: "workflow.landed", runId: run.id, taskId: run.taskId, landedSha: sha, reason: effect.payload.reason, ci: effect.payload.ci },
         });
         return { messageId: message.id };
       }
@@ -494,18 +500,19 @@ export async function performWorkflowEffect(run: WorkflowRunRecord, effect: Work
         const receipt = await planCiNotice(run, effect.payload, true);
         if (receipt) return receipt;
       }
+      const proof = sha ? await workflowLandVerification(run, sha) : undefined;
       const ciLine = ciResultLine(ci);
       const quietFor = await planQuietingRunNotice(run.taskId, "result", ci);
-      if (quietFor) return { quiet: "plan-dispatched", planId: quietFor };
+      if (quietFor && proof?.verified !== false) return { quiet: "plan-dispatched", planId: quietFor };
       const nothingToLand = effect.payload.nothingToLand === true || child?.output?.nothingToLand === true;
       const rounds = typeof effect.payload.rounds === "number" ? effect.payload.rounds : child?.output?.rounds ?? child?.round;
-      const outcome = !sha ? "finished its script steps" : nothingToLand ? `had nothing to land: its reviewed head is already on main as ${sha}` : `landed as ${sha}`;
+      const outcome = !sha ? "finished its script steps" : !proof?.verified ? `has an unverified land receipt for ${sha}` : nothingToLand ? `had nothing to land: its reviewed head is already on main as ${sha}` : `landed as ${sha}`;
       const message = notifySystemMessage(await workflowCoordinatorTarget(run), {
-        subject: `${runLabel(run)} done${nothingToLand ? ", nothing to land" : ""}${ci?.status === "fail" ? ", CI on main red" : ""}`,
-        body: workflowNotice(run, [`${runLabel(run)} is done: T${run.taskId} ${outcome}${rounds === undefined ? "" : ` after ${rounds} round(s)`}.`, ciLine ?? (child || !run.rootRunId ? "CI on main: not configured." : "CI on main: unknown.")], children.items, !!children.cursor),
+        subject: `${runLabel(run)} ${proof?.verified === false ? "land verification FAILED" : "done"}${nothingToLand ? ", nothing to land" : ""}${ci?.status === "fail" ? ", CI on main red" : ""}`,
+        body: workflowNotice(run, [`${runLabel(run)} is done: T${run.taskId} ${outcome}${rounds === undefined ? "" : ` after ${rounds} round(s)`}.${proof ? ` ${proof.line}` : ""}`, ciLine ?? (child || !run.rootRunId ? "CI on main: not configured." : "CI on main: unknown.")], children.items, !!children.cursor),
         idempotencyKey: key,
         replyExpected: false,
-        payload: { kind: "workflow.result", runId: run.id, taskId: run.taskId, landedSha: sha, ...(rounds === undefined ? {} : { rounds }), ...(nothingToLand ? { nothingToLand } : {}), ...(ci ? { ci } : {}) },
+        payload: { ...(proof ? { verified: proof.verified } : {}), kind: "workflow.result", runId: run.id, taskId: run.taskId, landedSha: sha, ...(rounds === undefined ? {} : { rounds }), ...(nothingToLand ? { nothingToLand } : {}), ...(ci ? { ci } : {}) },
       });
       return { messageId: message.id };
     }

package/src/services/workflow-land-notice.ts

@@ -1,3 +1,5 @@
+import { isRecord } from "@humwick/sdk";
+import { verifyPublishedLand } from "./landed-ancestry";
 import type { WorkflowRunRecord } from "@humwick/kernel/workflow.pilot";
 import { landLaneSnapshot } from "../db/commands-land-wait";
 import { formatRelativeTime } from "../mcp/presentation";
@@ -16,3 +18,11 @@ export async function workflowLandNotice(run: WorkflowRunRecord): Promise<string
   const progress = workspace.landProgressAt == null ? "unknown" : formatRelativeTime(workspace.landProgressAt).relative;
   return `Land workspace ${workspace.id}: landState ${state} (${age}); last reported progress: ${progress}; lane position ${position} among waiting lands; merging now: ${active.length ? active.join(", ") : lane ? "none" : "unknown"}; gate host: ${gateHost}.`;
 }
+
+export async function workflowLandVerification(run: WorkflowRunRecord, sha: string): Promise<{ verified: boolean; line: string }> {
+  const workspace = await deliveredWorkspace(run);
+  const hostProof = workspace?.metadata.mergeResult;
+  const verdict = isRecord(hostProof) && hostProof.landVerifiedSha === sha ? "confirmed" : await verifyPublishedLand(workspace?.repoRoot ?? run.cwd, sha, workspace?.baseRef);
+  return verdict === "confirmed" ? { verified: true, line: "verified: true" }
+    : { verified: false, line: `Land NOT verified: ${sha} is ${verdict === "not-ancestor" ? "absent from" : "unresolvable on"} fetched origin. Coordinator action required.` };
+}

package/src/services/workflow-pause-text.ts

@@ -0,0 +1,43 @@
+// #3757 — what a paused run tells its coordinator: a notice on pause and unpause, and one reminder line per paused run
+// of its team in each new context generation (the self-care section of the self-resume continuation).
+import { isRecord, parseJson } from "@humwick/sdk";
+import type { WorkflowEffect, WorkflowRunRecord } from "@humwick/kernel/workflow.pilot";
+import { coordinatedTeamIds } from "../db/coordinator-seat";
+import { taskOwnerRoleTeamId } from "../db/task-owner";
+import { pausedWorkflowRuns } from "../db/workflow-task-read-ops";
+import { workflowText } from "./workflow-notice";
+
+const UNPAUSE = "relay_workflow_resume {runId, pause: false}";
+type Pause = NonNullable<WorkflowRunRecord["pause"]>;
+
+function pauseOf(value: unknown): Pause | undefined {
+  return isRecord(value) && typeof value.reason === "string" && typeof value.by === "string" && typeof value.at === "number"
+    ? { reason: value.reason, by: value.by, at: value.at } : undefined;
+}
+
+function pausedBy(pause: Pause): string {
+  return `paused since ${new Date(pause.at).toISOString()} by ${pause.by}: ${workflowText(pause.reason, 240)}`;
+}
+
+/** The coordinator notice a pause or an unpause sends. */
+export function workflowPauseNotice(label: string, run: WorkflowRunRecord, effect: WorkflowEffect): { subject: string; body: string; payload: Record<string, unknown> } {
+  const pause = pauseOf(effect.payload) ?? { reason: "", by: "unknown", at: effect.createdAt };
+  const kind = effect.payload.action === "unpaused" ? "workflow.unpaused" : "workflow.paused";
+  const body = kind === "workflow.paused"
+    ? `${label} is ${pausedBy(pause)}. A working step agent finishes; the run does not go past its next step, delivery, review or land, and its timers stand still. Continue it: ${UNPAUSE}.`
+    : `${label} was unpaused by ${String(effect.payload.unpausedBy)} after ${Math.round(Number(effect.payload.pausedMs) / 60_000)}m. It was ${pausedBy(pause)}. It goes on from step ${run.step}; its deadlines moved by the paused time.`;
+  return { subject: `${label} ${kind === "workflow.paused" ? "paused" : "unpaused"}`, body, payload: { kind, runId: run.id, taskId: run.taskId, ...pause, ...(kind === "workflow.unpaused" ? { unpausedBy: effect.payload.unpausedBy } : {}) } };
+}
+
+/** The paused runs of the teams this agent coordinates, and the ones it started; "" when none are paused. */
+export function renderPausedRunsSection(agentId: string): string {
+  const teams = new Set(coordinatedTeamIds(agentId));
+  const lines = pausedWorkflowRuns().flatMap((row) => {
+    const teamId = taskOwnerRoleTeamId(row.owner) ?? row.teamId;
+    if (row.coordinator !== agentId && row.callerAgentId !== agentId && !(teamId && teams.has(teamId))) return [];
+    const pause = pauseOf(parseJson<unknown>(row.pause, undefined));
+    if (!pause) return [];
+    return [`- ${row.runId} on T${row.taskId}${row.taskTitle ? ` (${workflowText(row.taskTitle, 80)})` : ""}: ${pausedBy(pause)}`];
+  });
+  return lines.length ? [`Paused workflow runs of your team: they keep their agents and wait. Continue one with ${UNPAUSE}.`, ...lines].join("\n") : "";
+}

package/src/services/workflow-reconcile.ts

@@ -8,7 +8,7 @@ import { workflowDecisionSignal } from "./workflow-decisions";
 import { errMessage, isRecord, stringValue } from "@humwick/sdk";
 
 import { waitTimeoutMs } from "@humwick/kernel/workflow-definition";
-import { workflowEffectId, type WorkflowAgent, type WorkflowEffect, type WorkflowRunRecord, type WorkflowSignal } from "@humwick/kernel/workflow.pilot";
+import { workflowEffectId, workflowRunClock, type WorkflowAgent, type WorkflowEffect, type WorkflowRunRecord, type WorkflowSignal } from "@humwick/kernel/workflow.pilot";
 import { listActivityEventsAsync } from "../db";
 
 import { getGateway } from "../db/gateway";
@@ -21,7 +21,7 @@ import { workflowCleanupDeferred, notifyDeferredWorkflowCleanup } from "./workfl
 
 import { deliveredWorkspace, landedSignal, landStopSignal } from "./workflow-land";
 
-import { invoke, SUPERVISOR, testOptions, type Supervisor } from "./workflow-supervisor-state";
+import { invoke, SUPERVISOR, supervisorNow, testOptions, type Supervisor } from "./workflow-supervisor-state";
 import { workflowWaitAgent } from "./workflow-agent-obligation";
 import { landingProgress } from "../workspace-phase";
 type Json = Record<string, unknown>;
@@ -49,7 +49,7 @@ async function alertStalled(sup: Supervisor, run: WorkflowRunRecord, wait: Await
 /** A wait past its deadline alerts the coordinator once and keeps waiting, like a stopped land (#3045 H1). */
 async function alertTimeout(sup: Supervisor, run: WorkflowRunRecord, wait: Awaiting, taskId: number | undefined): Promise<boolean> {
   const timeoutMs = wait.deadline !== undefined ? wait.deadline - wait.since : waitTimeoutMs(run.definition, run.step);
-  const now = (testOptions.now ?? Date.now)();
+  const now = workflowRunClock(run, supervisorNow());
   if (wait.timedOutAt !== undefined || now < wait.since + timeoutMs) return false;
   if (wait.kind === "landed") {
     const workspace = await deliveredWorkspace(run);
@@ -65,13 +65,15 @@ export async function reconcileRun(sup: Supervisor, run: WorkflowRunRecord, land
   const wait = run.awaiting;
   if (!wait || (await invoke<{ present: boolean }>(sup, "hasSignal", { key: wait.key })).present) return false;
   if (wait.kind === "for-each") return false;
+  // #3757 — a paused run's deadlines stand still: they are read at its pause.
+  const now = workflowRunClock(run, supervisorNow());
   let payload: Json | undefined;
   let kind: WorkflowSignal["kind"] = wait.kind;
   const taskId = wait.taskId ?? await effectTaskId(sup, wait.effectId);
   if (wait.kind === "decision") {
     payload = workflowDecisionSignal(wait.effectId!);
     if (!payload) {
-      if (wait.deadline === undefined || (testOptions.now ?? Date.now)() < wait.deadline) return false;
+      if (wait.deadline === undefined || now < wait.deadline) return false;
       kind = "effect-failed";
       payload = { effect: "decision", error: "DECISION_DEADLINE: operator decision reached its explicit deadline" };
     }
@@ -80,7 +82,7 @@ export async function reconcileRun(sup: Supervisor, run: WorkflowRunRecord, land
     if (!effect?.result?.childRunId) return false;
     const child = await invoke<WorkflowRunRecord>(sup, "get", { runId: effect.result.childRunId });
     if (child.status === "running") {
-      if (wait.deadline !== undefined && (testOptions.now ?? Date.now)() >= wait.deadline) return (await invoke<{ created: boolean }>(sup, "parkChild", { runId: run.id, childRunId: child.id, reason: `CHILD_TIMEOUT: ${child.id} exceeded ${wait.deadline}` })).created;
+      if (wait.deadline !== undefined && now >= wait.deadline) return (await invoke<{ created: boolean }>(sup, "parkChild", { runId: run.id, childRunId: child.id, reason: `CHILD_TIMEOUT: ${child.id} exceeded ${wait.deadline}` })).created;
       return false;
     }
     if (child.status === "escalated") {
@@ -112,19 +114,19 @@ export async function reconcileRun(sup: Supervisor, run: WorkflowRunRecord, land
     payload = taskId === undefined ? undefined : await deliverySignal(run, taskId, wait.afterEventId, wait.since);
     if (!payload) {
       const { effect } = await invoke<{ effect?: WorkflowEffect }>(sup, "getEffect", { id: wait.effectId ?? workflowEffectId(run.id, run.waitSeq, "dispatch") });
-      payload = await spawnFailureSignal(effect, (testOptions.now ?? Date.now)());
+      payload = await spawnFailureSignal(effect, now);
       if (payload) kind = "effect-failed";
     }
     if (!payload) {
-      payload = await exitSignal(sup, run);
+      payload = await exitSignal(sup, run, now);
       if (payload) kind = payload.effect === "dispatch" ? "effect-failed" : "agent-exited";
     }
   } else if (wait.kind === "ci") {
     // A CI wait ends on its verdict, never on a timeout alert: past the deadline it reports CI red or "no CI".
-    const outcome = await ciMainOutcome(run, wait, (testOptions.now ?? Date.now)(), (await deliveredWorkspace(run))?.baseRef);
+    const outcome = await ciMainOutcome(run, wait, now, (await deliveredWorkspace(run))?.baseRef);
     if (outcome.red && (await invoke<{ created: boolean }>(sup, "alert", { runId: run.id, waitKey: wait.key, ...outcome.red })).created) return true;
     if (!outcome.verdict) return false;
-    if (outcome.verdict.status === "none" && wait.deadline !== undefined && (testOptions.now ?? Date.now)() >= wait.deadline
+    if (outcome.verdict.status === "none" && wait.deadline !== undefined && now >= wait.deadline
       && (await invoke<{ created: boolean }>(sup, "alert", { runId: run.id, waitKey: wait.key, key: "ci-late", reason: "ci-late", detail: { ci: outcome.verdict, landedSha: wait.sha } })).created) return true;
     payload = outcome.verdict;
   } else {
@@ -153,10 +155,10 @@ export async function reconcileRun(sup: Supervisor, run: WorkflowRunRecord, land
 }
 
 /** #3166 — the wait's step agent exited without a delivery, has stayed gone past the grace, and is not live again. */
-async function exitSignal(sup: Supervisor, run: WorkflowRunRecord): Promise<Json | undefined> {
+async function exitSignal(sup: Supervisor, run: WorkflowRunRecord, now: number): Promise<Json | undefined> {
   const { agent } = await invoke<{ agent?: WorkflowAgent }>(sup, "exitedWaitAgent", { runId: run.id });
   if (agent?.spawnFailedAt && !agent.readyAt) return { effect: "dispatch", error: `spawn ${agent.spawnRequestId}: ${agent.spawnError ?? "spawn failed"}` };
-  if (!agent?.exitedAt || (testOptions.now ?? Date.now)() - agent.exitedAt < AGENT_EXIT_GRACE_MS) return undefined;
+  if (!agent?.exitedAt || now - agent.exitedAt < AGENT_EXIT_GRACE_MS) return undefined;
   return agentExitSignal(agent);
 }
 

package/src/services/workflow-run-view.ts

@@ -40,6 +40,7 @@ export function runView(run: WorkflowRunRecord): WorkflowRunView {
     ...(run.awaiting ? { awaiting: awaitingView(run.awaiting) } : {}),
     ...(run.overdueAt !== undefined ? { overdueAt: run.overdueAt } : {}),
     ...(run.overdueNotifiedAt !== undefined ? { overdueNotifiedAt: run.overdueNotifiedAt } : {}),
+    ...(run.pause ? { paused: run.pause } : {}),
     ...(run.reason ? { reason: run.reason } : {}),
     ...(run.resumes?.length ? { resumes: run.resumes } : {}),
     ...(run.output ? { output: run.output } : {}),
@@ -57,6 +58,7 @@ export function leanRunView(run: WorkflowRunRecord, agents: WorkflowRunAgent[]):
     ...(run.overdueAt !== undefined ? { overdueAt: run.overdueAt } : {}),
     ...(run.overdueNotifiedAt !== undefined ? { overdueNotifiedAt: run.overdueNotifiedAt } : {}),
     ...(run.awaiting ? { awaiting: awaitingView(run.awaiting) } : {}),
+    ...(run.pause ? { paused: run.pause } : {}),
     ...(run.reason ? { reason: workflowText(run.reason) } : {}),
     ...(run.output ? { output: { ...run.output, ...(run.output.ci ? { ci: { status: run.output.ci.status, ...(run.output.ci.sha ? { sha: run.output.ci.sha } : {}) } } : {}) } } : {}),
     agents: agents.map((agent) => ({

package/src/services/workflow-runs.ts

@@ -43,6 +43,7 @@ import { leanRunView, runView } from "./workflow-run-view";
 import type { AuthContext } from "./auth-context";
 
 import { invoke, live, runAgents, requestPump, serialized, ensureSupervisor, type Supervisor } from "./workflow-supervisor";
+import { supervisorNow } from "./workflow-supervisor-state";
 export { workflowAgentObligation } from "./workflow-agent-obligation";
 import { reconcileRun } from "./workflow-reconcile";
 import { holdWorkflowVerification } from "./workflow-verification";
@@ -198,12 +199,7 @@ export async function readWorkflowRunBudget(runId: string, ctx: AuthContext): Pr
 
 /** #3352 — a coordinator amends a live run's cap; new spawns see it at their next admission. */
 export async function amendWorkflowRunBudget(input: { runId: string; tokenCap: number }, ctx: AuthContext): Promise<Json> {
-  const sup = await ensureSupervisor();
-  const run = await readRun(sup, input.runId);
-  const task = await getTaskDetailAsync(run.taskId);
-  if (!task || !(ctx.callerAgentId === run.callerAgentId || canControlTaskReviewHold(ctx, task))) {
-    throw new ServiceAuthError(`amending the budget of workflow run ${run.id} is coordinator-only — ${COORDINATOR_AUTHORITY_HINT}`);
-  }
+  const { sup, run } = await controlledRun(input.runId, ctx, "amending the budget of");
   const amended = await serialized(sup, () => invoke<WorkflowRunRecord>(sup, "amendTokenBudget", { runId: run.id, tokenCap: input.tokenCap })).catch((error: unknown) => {
     if (error instanceof OpError && error.code === "conflict") throw new ValidationError(error.message);
     throw error;
@@ -270,13 +266,7 @@ export async function resumeWorkflowRun(input: { runId: string; activationId?: s
 /** relay_workflow_cancel (#3166): end a running or escalated run cancelled. A running run ends at once, its step
  *  agents reaped per their `reap`; the Task, its review hold, any delivery and an armed land stay as they are. */
 export async function cancelWorkflowRun(input: { runId: string; reason?: string }, ctx: AuthContext): Promise<Json> {
-  const sup = await ensureSupervisor();
-  const run = await readRun(sup, input.runId);
-  const task = await getTaskDetailAsync(run.taskId);
-  if (!task || !(ctx.callerAgentId === run.callerAgentId || canControlTaskReviewHold(ctx, task))) {
-    throw new ServiceAuthError(`cancelling workflow run ${run.id} is coordinator-only — ${COORDINATOR_AUTHORITY_HINT}`);
-  }
-  const by = ctx.callerAgentId ?? ctx.actor.id;
+  const { sup, run, by } = await controlledRun(input.runId, ctx, "cancelling");
   const reason = `cancelled by ${by}${input.reason ? `: ${input.reason}` : ""}`;
   // Between passes, so the cancel lands before the next routing.
   const { cancelled } = await serialized(sup, () => invoke<{ cancelled: boolean }>(sup, "cancel", { runId: run.id, reason, by })).catch((error: unknown) => {
@@ -287,6 +277,32 @@ export async function cancelWorkflowRun(input: { runId: string; reason?: string
   return { ...runView(await readRun(sup, run.id)), cancelled };
 }
 
+/** The run a coordinator-only control acts on: its caller, the input Task's coordinators and admins may. */
+async function controlledRun(runId: string, ctx: AuthContext, verb: string): Promise<{ sup: Supervisor; run: WorkflowRunRecord; by: string }> {
+  const sup = await ensureSupervisor();
+  const run = await readRun(sup, runId);
+  const task = await getTaskDetailAsync(run.taskId);
+  if (!task || !(ctx.callerAgentId === run.callerAgentId || canControlTaskReviewHold(ctx, task))) {
+    throw new ServiceAuthError(`${verb} workflow run ${run.id} is coordinator-only — ${COORDINATOR_AUTHORITY_HINT}`);
+  }
+  return { sup, run, by: ctx.callerAgentId ?? ctx.actor.id };
+}
+
+/** #3757 — pause a running run at its next seam (reason required) or unpause it; its agents keep working meanwhile. */
+export async function pauseWorkflowRun(input: { runId: string; pause: boolean; reason?: string }, ctx: AuthContext): Promise<Json> {
+  const reason = input.reason?.trim();
+  if (input.pause && !reason) throw new ValidationError("pausing a workflow run needs a reason (MCP: note): say why it waits and for what");
+  const { sup, run, by } = await controlledRun(input.runId, ctx, input.pause ? "pausing" : "unpausing");
+  // Between passes, so no pass routes or performs with a stale view of the pause.
+  await serialized(sup, () => invoke(sup, input.pause ? "pause" : "unpause", { runId: run.id, by, now: supervisorNow(), ...(input.pause ? { reason } : {}) }))
+    .catch((error: unknown) => {
+      if (error instanceof OpError && (error.code === "conflict" || error.code === "invalid_input")) throw new ValidationError(error.message);
+      throw error;
+    });
+  await requestPump(sup);
+  return runView(await readRun(sup, run.id));
+}
+
 /** relay_workflow_get: the run's visible record, after every pass already scheduled. */
 export async function getWorkflowRun(runId: string, ctx: AuthContext, options: WorkflowRunReadOptions = {}): Promise<Json> {
   const sup = await ensureSupervisor();