@desplega.ai/agent-swarm 2.5.2 → 2.5.3

package/src/workflows/executors/base.ts

@@ -51,6 +51,12 @@ export interface ExecutorResult<TOutput = unknown> {
   output?: TOutput;
   nextPort?: string;
   error?: string;
+  /**
+   * False on a failure no retry can change (a child run that was cancelled,
+   * for example). The engine then skips the node's retry policy. Unset means
+   * retryable.
+   */
+  retryable?: boolean;
 }
 
 export interface AsyncExecutorResult<TOutput = unknown> extends ExecutorResult<TOutput> {

package/src/workflows/executors/human-in-the-loop.ts

@@ -1,4 +1,8 @@
 import { z } from "zod";
+import {
+  ConfigQuestionSettingsSchema,
+  normalizeApprovalQuestions,
+} from "../../be/approval-config-question";
 import type { ExecutorMeta } from "../../types";
 import { scrubSecrets } from "../../utils/secret-scrubber";
 import { dispatchApprovalNotifications } from "../approval-notifications";
@@ -56,6 +60,15 @@ const QuestionSchema = z.discriminatedUnion("type", [
     description: z.string().optional(),
     defaultValue: z.boolean().optional(),
   }),
+  z.object({
+    id: z.string(),
+    type: z.literal("config"),
+    // Defaults to the config key during normalization in `run`.
+    label: z.string().optional(),
+    required: z.boolean().default(true),
+    description: z.string().optional(),
+    config: ConfigQuestionSettingsSchema,
+  }),
 ]);
 
 export const ApproverConfigSchema = z.object({
@@ -207,7 +220,18 @@ export class HumanInTheLoopExecutor extends BaseExecutor<
   override async run(input: ExecutorInput): Promise<ExecutorResult<HITLOutput>> {
     const resolved = resolveHitlQuestions(input.config?.questions);
     if (!resolved.ok) return { status: "failed", error: resolved.error };
-    return super.run({ ...input, config: { ...input.config, questions: resolved.questions } });
+    // Config questions: the same create-time rules as the tool and REST paths.
+    const approvers = input.config?.approvers as { policy?: unknown } | undefined;
+    const normalized = await normalizeApprovalQuestions(resolved.questions, {
+      approvers: { policy: approvers?.policy },
+    });
+    if (!normalized.ok) {
+      return {
+        status: "failed",
+        error: `human-in-the-loop questions are invalid: ${normalized.error}`,
+      };
+    }
+    return super.run({ ...input, config: { ...input.config, questions: normalized.questions } });
   }
 
   protected async execute(

package/src/workflows/executors/sub-workflow.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { getChildWorkflowRunId, getWorkflowRunLineage } from "../../be/db/workflow-runs";
 import type { ExecutorMeta, WorkflowRun } from "../../types";
-import { startWorkflowExecution } from "../engine";
+import { ParentStepNotCurrentError, startWorkflowExecution } from "../engine";
 import type { ExecutorDependencies, ExecutorResult } from "./base";
 import { BaseExecutor } from "./base";
 import type { ExecutorRegistry } from "./registry";
@@ -35,15 +35,21 @@ const NON_NODE_CONTEXT_KEYS = new Set(["trigger", "input", "swarm", "workflow"])
 /**
  * The parent step's outcome for a child run: its result once the child
  * completed, an error once it failed, was cancelled or was skipped, and null
- * while it is still running or waiting.
+ * while it is still running or waiting. Only a failed child is retryable: a
+ * cancel or a skip is a decision, and a node retry must not override it. The
+ * synchronous (executor) and the parked (`resumeFromChildRun`) paths both
+ * apply this, so the same child end gets the same policy whenever it lands.
  */
 export function childRunOutcome(
   child: WorkflowRun,
-): { output: SubWorkflowOutput } | { error: string } | null {
+): { output: SubWorkflowOutput } | { error: string; retryable: boolean } | null {
   if (child.status === "running" || child.status === "waiting") return null;
   if (child.status !== "completed") {
     const reason = child.error ? `: ${child.error}` : "";
-    return { error: `Child workflow run ${child.id} ${child.status}${reason}` };
+    return {
+      error: `Child workflow run ${child.id} ${child.status}${reason}`,
+      retryable: child.status === "failed",
+    };
   }
   const outputs: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(child.context ?? {})) {
@@ -56,8 +62,9 @@ export function childRunOutcome(
 
 /**
  * Runs another workflow as a child run and waits for it. The child run records
- * this step as its parent, so a re-executed step reconnects to it instead of
- * starting a second child. The resume path is `resumeFromChildRun`.
+ * this step and its attempt (`retryCount`) as its parent, so a re-executed or
+ * recovered step reconnects to it instead of starting a second child, while a
+ * retry starts a new one. The resume path is `resumeFromChildRun`.
  */
 export class SubWorkflowExecutor extends BaseExecutor<
   typeof SubWorkflowConfigSchema,
@@ -82,9 +89,12 @@ export class SubWorkflowExecutor extends BaseExecutor<
   ): Promise<ExecutorResult<SubWorkflowOutput>> {
     const { db } = this.deps;
 
-    const existingId = await getChildWorkflowRunId(meta.stepId);
+    // The retry poller re-executes a failed step under the same id with a
+    // higher retryCount; that attempt must not settle on the previous child.
+    const attempt = (await db.getWorkflowRunStep(meta.stepId))?.retryCount ?? 0;
+    const existingId = await getChildWorkflowRunId(meta.stepId, attempt);
     const existing = existingId ? await db.getWorkflowRun(existingId) : null;
-    if (existing) return this.settle(existing);
+    if (existing) return this.settle(existing, config.workflowId);
 
     // Capped at the max depth, so a long chain fails closed instead of
     // hiding a cycle past the end of the scan.
@@ -109,17 +119,34 @@ export class SubWorkflowExecutor extends BaseExecutor<
     }
 
     // Returns once the child run exists; the child walks on its own. A child
-    // that already ended (cooldown, readiness, input failure) settles here.
-    const childRunId = await startWorkflowExecution(workflow, config.inputs ?? {}, this.registry, {
-      requestedByUserId: meta.requestedByUserId,
-      parentStepId: meta.stepId,
-    });
+    // that already ended (cooldown, readiness, input failure) settles here,
+    // and a concurrent execution of this attempt gets the child it created.
+    let childRunId: string;
+    try {
+      childRunId = await startWorkflowExecution(workflow, config.inputs ?? {}, this.registry, {
+        requestedByUserId: meta.requestedByUserId,
+        parentStepId: meta.stepId,
+        parentStepAttempt: attempt,
+      });
+    } catch (err) {
+      if (err instanceof ParentStepNotCurrentError) return { status: "failed", error: err.message };
+      throw err;
+    }
     const child = await db.getWorkflowRun(childRunId);
     if (!child) return { status: "failed", error: `Child workflow run ${childRunId} not found` };
-    return this.settle(child);
+    return this.settle(child, config.workflowId);
   }
 
-  private settle(child: WorkflowRun): ExecutorResult<SubWorkflowOutput> {
+  private settle(child: WorkflowRun, workflowId: string): ExecutorResult<SubWorkflowOutput> {
+    // The attempt already started a child of another workflow (the config
+    // changed under a recovered step). That is a conflict, not a reason to
+    // start a replacement next to it.
+    if (child.workflowId !== workflowId) {
+      return {
+        status: "failed",
+        error: `Child workflow run ${child.id} runs workflow ${child.workflowId}, not ${workflowId}`,
+      };
+    }
     const outcome = childRunOutcome(child);
     if (!outcome) {
       return {
@@ -129,7 +156,9 @@ export class SubWorkflowExecutor extends BaseExecutor<
         correlationId: child.id,
       } as ExecutorResult<SubWorkflowOutput>;
     }
-    if ("error" in outcome) return { status: "failed", error: outcome.error };
+    if ("error" in outcome) {
+      return { status: "failed", error: outcome.error, retryable: outcome.retryable };
+    }
     return { status: "success", output: outcome.output, nextPort: "success" };
   }
 }

package/src/workflows/recovery.ts

@@ -12,7 +12,7 @@ import {
   resolveApprovalRequest,
   updateWorkflowRun,
 } from "../be/db";
-import { getSettledChildRunParentSteps } from "../be/db/workflow-runs";
+import { getRunningSubWorkflowSteps, getSettledChildRunParentSteps } from "../be/db/workflow-runs";
 import type { WorkflowRunStep } from "../types";
 import { shapeApprovalResolution } from "./approval-resolution";
 import { loadCompletedStepRouting } from "./completed-step-routing";
@@ -20,6 +20,7 @@ import { FAILED_TASK_OUTPUT_PREFIX } from "./constants";
 import {
   failRunOnUnreadableReplay,
   findReadyNodes,
+  isStepExecuting,
   isWorkflowRunActive,
   walkGraph,
 } from "./engine";
@@ -76,6 +77,9 @@ export async function recoverIncompleteRuns(registry: ExecutorRegistry): Promise
   // --- Case 6: foreach fan-outs with queued or orphaned items ---
   recovered += await recoverForeachFanouts(registry);
 
+  // --- Case 7: sub-workflow steps a crash left running ---
+  recovered += await recoverOrphanedSubWorkflowSteps(registry);
+
   if (recovered > 0) {
     console.log(`[workflows] Recovered ${recovered} incomplete run(s)`);
   }
@@ -98,6 +102,13 @@ async function recoverRunningRuns(registry: ExecutorRegistry): Promise<number> {
       if (isWorkflowRunActive(runId)) continue;
       const run = await getWorkflowRun(runId);
       if (!run || run.status !== "running") continue;
+      // A child run commits with its initial context. One without it was
+      // created before that held and lost its trigger and inputs in a crash;
+      // walking it from an empty context would run its nodes on blanks.
+      if (run.parentStepId && run.context === undefined) {
+        await failRunningRun(runId, "Child workflow run lost its initial context in a restart");
+        continue;
+      }
 
       const workflow = await getWorkflow(run.workflowId);
       if (!workflow) continue;
@@ -146,6 +157,57 @@ async function recoverRunningRuns(registry: ExecutorRegistry): Promise<number> {
   return recovered;
 }
 
+/** Fail a run that is still `running`; a cancel or finish that committed first wins. */
+async function failRunningRun(runId: string, error: string): Promise<void> {
+  await getDbClient().transaction(async () => {
+    const run = await getWorkflowRun(runId);
+    if (run?.status !== "running") return;
+    await updateWorkflowRun(runId, {
+      status: "failed",
+      error,
+      finishedAt: new Date().toISOString(),
+    });
+  });
+}
+
+/**
+ * Re-enter `sub-workflow` steps a crash left `running`. The running-run case
+ * misses two shapes: a run another branch already parked in `waiting`, and a
+ * loop iteration of a node that completed before. Walking the node lets
+ * executeStep re-claim the same step row, so the executor reconnects to the
+ * child that attempt already started. Foreach items are left to the fan-out
+ * case: their synthetic node ids are not in the definition.
+ */
+async function recoverOrphanedSubWorkflowSteps(registry: ExecutorRegistry): Promise<number> {
+  let recovered = 0;
+  for (const row of await getRunningSubWorkflowSteps()) {
+    try {
+      if (isWorkflowRunActive(row.runId) || isStepExecuting(row.stepId)) continue;
+      const run = await getWorkflowRun(row.runId);
+      if (!run || (run.status !== "running" && run.status !== "waiting")) continue;
+      const workflow = await getWorkflow(run.workflowId);
+      const node = workflow?.definition.nodes.find((n) => n.id === row.nodeId);
+      if (!workflow || !node) continue;
+      // DB reads above yield; a resume may have acquired the run meanwhile.
+      if (isWorkflowRunActive(row.runId)) continue;
+      await walkGraph(
+        workflow.definition,
+        row.runId,
+        (run.context ?? {}) as Record<string, unknown>,
+        [node],
+        registry,
+        workflow.id,
+        getSecretInputKeys(workflow.input),
+      );
+      recovered++;
+    } catch (err) {
+      if (await failRunOnUnreadableReplay(row.runId, err)) continue;
+      console.error(`[workflows] Failed to recover sub-workflow step ${row.stepId}:`, err);
+    }
+  }
+  return recovered;
+}
+
 /** Nodes with a failed step the retry poller will pick up (`nextRetryAt` set). */
 function retryPendingNodeIds(steps: WorkflowRunStep[]): Set<string> {
   const nodeIds = new Set<string>();

package/src/workflows/resume.ts

@@ -18,12 +18,14 @@ import {
   updateWorkflowRunStep,
 } from "../be/db";
 import { createForeachAttemptSteps, getChildWorkflowRunId } from "../be/db/workflow-runs";
-import type {
-  WaitStateRow,
-  WorkflowDefinition,
-  WorkflowNode,
-  WorkflowRun,
-  WorkflowRunStep,
+import {
+  type RetryPolicy,
+  RetryPolicySchema,
+  type WaitStateRow,
+  type WorkflowDefinition,
+  type WorkflowNode,
+  type WorkflowRun,
+  type WorkflowRunStep,
 } from "../types";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import {
@@ -31,6 +33,7 @@ import {
   postApprovalCancellationUpdates,
 } from "./approval-notifications";
 import { shapeApprovalResolution } from "./approval-resolution";
+import { checkpointStepFailure } from "./checkpoint";
 import { loadCompletedStepRouting } from "./completed-step-routing";
 import { FAILED_TASK_OUTPUT_PREFIX } from "./constants";
 import { getNextTargets } from "./definition";
@@ -963,10 +966,11 @@ async function resumeClaimedWait(
 }
 
 /**
- * Resume a waiting `sub-workflow` step once its child run is terminal: a
- * completed child completes the step, any other end (or a deleted child) fails
- * the step and its run. Returns true when this call claimed the step. Safe to call repeatedly:
- * the live event and the recovery sweep both route here.
+ * Resume a waiting `sub-workflow` step once its current attempt's child run is
+ * terminal: a completed child completes the step, any other end (or a deleted
+ * child) fails the step and its run. Returns true when this call claimed the
+ * step. Safe to call repeatedly: the live event and the recovery sweep both
+ * route here, and only the call that claims the step walks its successors.
  */
 export async function resumeFromChildRun(
   parentStepId: string,
@@ -974,13 +978,6 @@ export async function resumeFromChildRun(
 ): Promise<boolean> {
   const step = await getWorkflowRunStep(parentStepId);
   if (!step || step.status !== "waiting" || step.nodeType !== "sub-workflow") return false;
-  const childId = await getChildWorkflowRunId(parentStepId);
-  const child = childId ? await getWorkflowRun(childId) : null;
-  // The child row exists before the step parks, so a missing one was deleted.
-  const outcome = child
-    ? childRunOutcome(child)
-    : { error: `Child workflow run of step ${parentStepId} was deleted` };
-  if (!outcome) return false;
 
   let claimed = false;
   await failClosedOnUnreadableReplay(step.runId, step.id, async () => {
@@ -990,10 +987,32 @@ export async function resumeFromChildRun(
     if (!workflow) return;
 
     const ctx = (run.context ?? {}) as Record<string, unknown>;
-    // A foreach item's failure settles the item: under `onNodeFailure:
-    // "continue"` it can close the join, so it routes like a success.
-    const routing =
-      "error" in outcome
+    // The step's attempt, that attempt's child and the claim share one
+    // transaction: a retry that re-parks the step under a newer attempt in
+    // between must not be settled by the previous attempt's child.
+    const routing = await getDbClient().transaction(async () => {
+      const current = await getWorkflowRunStep(step.id);
+      if (!current || current.status !== "waiting") return null;
+      const childId = await getChildWorkflowRunId(step.id, current.retryCount);
+      const child = childId ? await getWorkflowRun(childId) : null;
+      // The child row exists before the step parks, so a missing one was deleted.
+      const outcome = child
+        ? childRunOutcome(child)
+        : { error: `Child workflow run of step ${parentStepId} was deleted`, retryable: false };
+      if (!outcome) return null;
+      // A retryable end (a failed child) is this attempt failing: the node's
+      // retry policy applies exactly as on the executor path. The poller
+      // re-executes the step under the next attempt, which starts a new child.
+      if ("error" in outcome && outcome.retryable) {
+        const policy = childStepRetryPolicy(workflow.definition, step.nodeId);
+        if (policy && current.retryCount < policy.maxRetries) {
+          await checkpointStepFailure(run.id, step.id, outcome.error, current.retryCount, policy);
+          return CHILD_RETRY_SCHEDULED;
+        }
+      }
+      // A foreach item's failure settles the item: under `onNodeFailure:
+      // "continue"` it can close the join, so it routes like a success.
+      return "error" in outcome
         ? await failStepAndRunIfWaiting(
             workflow.definition,
             step.id,
@@ -1012,6 +1031,12 @@ export async function resumeFromChildRun(
             ctx,
             registry,
           );
+    });
+    if (!routing) return;
+    if (routing === CHILD_RETRY_SCHEDULED) {
+      claimed = true;
+      return;
+    }
     if (!routing.claimed || routing.runFailed) {
       claimed = routing.claimed;
       return;
@@ -1036,6 +1061,20 @@ export async function resumeFromChildRun(
   return claimed;
 }
 
+const CHILD_RETRY_SCHEDULED = {
+  claimed: true,
+  runFailed: false,
+  successors: [] as WorkflowNode[],
+} as const;
+
+/** The `node.retry` of a top-level `sub-workflow` node; foreach items retry through their parent. */
+function childStepRetryPolicy(def: WorkflowDefinition, nodeId: string): RetryPolicy | null {
+  const node = def.nodes.find((candidate) => candidate.id === nodeId);
+  if (!node?.retry) return null;
+  const parsed = RetryPolicySchema.safeParse(node.retry);
+  return parsed.success ? parsed.data : null;
+}
+
 // ─── 64KB firedPayload cap ──────────────────────────────────────────────────
 
 const FIRED_PAYLOAD_BYTE_CAP = 64 * 1024; // 64KB

package/src/workflows/retry-poller.ts

@@ -61,6 +61,9 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
           // the run were read outside it: a cancel committing in between must
           // win, or the step re-executes inside a cancelled run.
           if (!(await claimRetry(run.id, step.id))) continue;
+          // Every result write below is fenced on this claim, so a cancel or
+          // another settle that commits while the executor runs wins.
+          const fence = { retryCount: step.retryCount };
 
           // Rebuild `run.id`, upstream outputs and the node's declared-inputs
           // context the way the original execution saw them. Without the alias
@@ -78,6 +81,8 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
               step.id,
               scriptBodyInterpolationError(node.id, scriptBodyUnresolved),
               step.retryCount,
+              undefined,
+              { fence },
             );
             continue;
           }
@@ -104,14 +109,17 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
             if (result.status === "failed") {
               // Re-failed — use the EXISTING retryCount from the step.
               // checkpointStepFailure handles marking run as failed if no retries left,
-              // or setting nextRetryAt for the next poll cycle.
-              const retryPolicy = node.retry || executor.retryPolicy;
+              // or setting nextRetryAt for the next poll cycle. A non-retryable
+              // failure skips the policy, as in executeStep.
+              const retryPolicy =
+                result.retryable === false ? undefined : node.retry || executor.retryPolicy;
               await checkpointStepFailure(
                 run.id,
                 step.id,
                 result.error || "Retry failed",
                 step.retryCount,
                 retryPolicy,
+                { fence, output: result.output },
               );
             } else if (
               "async" in result &&
@@ -150,6 +158,12 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
               // find the parent already advanced.
               const waiting = await checkpointStepWaiting(run.id, step.id, ctx);
               if (!waiting) continue;
+              // As in executeStep: a child run that finished before the step
+              // parked had its event dropped.
+              if ((result as AsyncExecutorResult).waitFor === "workflow.child.finished") {
+                const { resumeFromChildRun } = await import("./resume");
+                await resumeFromChildRun(step.id, registry);
+              }
             } else {
               // Success! Re-run validation if configured before checkpointing.
               let validationPassed: boolean | undefined;
@@ -168,6 +182,8 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
                     step.id,
                     "Validation failed (mustPass)",
                     step.retryCount,
+                    undefined,
+                    { fence },
                   );
                   continue;
                 }
@@ -186,6 +202,7 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
                     "Validation failed, retrying",
                     step.retryCount,
                     retryPolicy,
+                    { fence },
                   );
                   continue;
                 }
@@ -197,7 +214,9 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
               result.nextPort = resolveValidationPort(node.next, result.nextPort, validationPassed);
 
               // Validation passed (or no validation) — checkpoint and continue
-              await checkpointStep(run.id, step.id, step.nodeId, result, ctx);
+              if (!(await checkpointStep(run.id, step.id, step.nodeId, result, ctx, { fence }))) {
+                continue;
+              }
 
               const port = result.nextPort || "default";
               const successors = getSuccessors(workflow.definition, step.nodeId, port);
@@ -219,7 +238,9 @@ export function startRetryPoller(registry: ExecutorRegistry, intervalMs = 5000):
             if (await failRunOnUnreadableReplay(run.id, err, step.id)) continue;
             const errorMsg = err instanceof Error ? err.message : String(err);
             const retryPolicy = node.retry || executor.retryPolicy;
-            await checkpointStepFailure(run.id, step.id, errorMsg, step.retryCount, retryPolicy);
+            await checkpointStepFailure(run.id, step.id, errorMsg, step.retryCount, retryPolicy, {
+              fence,
+            });
           }
         } catch (err) {
           if (await failRunOnUnreadableReplay(step.runId, err, step.id)) continue;

package/templates/extensions/comms-adherence-gate/README.md

@@ -1,14 +1,14 @@
 # comms-adherence-gate
 
-Agents finish Slack tasks with a final message a human reads. This extension judges that message against the requester's stated comms preferences and their latest request with Jev, [TypeSafe](https://typesafe.ai)'s decision model. In `enforce` it blocks a non-adherent completion once and tells the agent what to fix.
+Agents finish Slack tasks with a final message a human reads, and post to Slack threads directly. This extension judges that text with Jev, [TypeSafe](https://typesafe.ai)'s decision model: against the requester's stated comms preferences and their latest request, and against a plain-language rubric that applies to every message. In `enforce` it blocks a failing call once and tells the agent what to fix. A `plain` failure points the agent at the `comms` skill.
 
 Install config:
 
 ```json
-{ "mode": "shadow" }
+{ "mode": "shadow", "plainMode": "shadow" }
 ```
 
-Start in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`.
+Start in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`. `mode` and `plainMode` move independently.
 
 ## Modes
 
@@ -16,14 +16,22 @@ Start in `shadow`, read the verdicts in KV for a few days, then switch to `enfor
 |---|---|
 | `off` | Never evaluates. |
 | `shadow` (default) | Asks Jev and records the verdict. Never blocks. |
-| `enforce` | Asks Jev, records the verdict, and blocks the `store-progress` call when a dimension fails, at most `maxBlocksPerTask` times per task. The agent gets the failed dimensions, their scores and the stated preference, and calls again. |
+| `enforce` | Asks Jev, records the verdict, and blocks the call when a dimension fails, at most `maxBlocksPerTask` times per task. The agent gets the failed dimensions, their scores and the stated preference, and calls again. |
+
+`mode` governs the preference dimensions (`verbosity`, `tone`, `language`). `plainMode` governs `plain`. A dimension blocks only when its own mode is `enforce`. Both share one block budget per task, across every gated tool.
 
 ## What it gates
 
-Hook: `pre.tool.call` on `store-progress` with `status: "completed"` and a non-empty `output`. Calls made by extensions are skipped. The task must:
+Hook: `pre.tool.call` on:
+
+- `store-progress` with `status: "completed"` and a non-empty `output`, on a task that came from Slack (`source = "slack"` or a `slackThreadTs`). Other completions pass without a Jev call.
+- `slack-reply`, `slack-post`, `slack-start-thread` and `slack-update`, judged on `message`. The task is `slack-reply`'s `taskId`, else the caller's task context. A post with no task context passes.
+
+Only a call the tool itself accepts is judged, so no other task's text reaches Jev. For `store-progress` the caller must own the task, the task must be unassigned, or the caller must be a lead. For the Slack tools the caller must be the task's assignee or its creator, the rule `slack-reply` enforces. Calls made by extensions are skipped. Script SDK calls never reach `pre.tool.call` (the tool registrar dispatches it only for MCP calls); if one ever does, the gate records it and never blocks.
 
-1. Come from Slack (`source = "slack"` or a `slackThreadTs`). Other tasks pass without a Jev call.
-2. Have a requester with stated preferences in `users.metadata.comms`. A requester with none passes. Set them with the `manage-user` tool.
+A requester with no stated preferences in `users.metadata.comms` still gets the `plain` question. Set preferences with the `manage-user` tool.
+
+In a thread with several people, the requester is the person whose message created the task. A message that @-mentions someone (`<@U123>`) is judged against the first mentioned person with stored preferences, resolved through their Slack identity in `user_external_ids`; otherwise against the requester. The lookup is one SQL read, only when the text mentions someone and `mode` is not `off`. The verdict records who was judged in `judgedFor` (`mention` or `requester`) and `audience`.
 
 ## Decision
 
@@ -31,7 +39,21 @@ The gate reads the task row and asks one `noul` question per stated preference i
 
 Jev sees the preferences, the requester's latest message (the text after the last `</thread_context>`, from the last 1,400 characters of the task), the first 400 characters of the task, and the output. Its judging rules say an explicit request outranks the stored default. A requested long answer, story or document is not a verbosity failure.
 
-A dimension fails when its score is below `threshold`. Any failed dimension fails the output.
+It also asks `plain` on every message unless `plainMode` is `off` or the text is a JSON document (structured output for an `outputSchema`). The rubric comes from the `comms` skill: everyday words, one idea per sentence, every number with a unit and a direction word, and no unexplained shorthand (n, median, p90, cohort, baseline, delta, `±X at 95%`). Code identifiers, task ids, PR numbers, links and versions are fine. Jev gets contrasting plain and dense examples in `plain_language_rules`; a prose-only rubric scored plain rewrites as low as the dense originals.
+
+All questions go in one Jev request. A preference dimension fails below `threshold`; `plain` fails below `plainThreshold`. Any failed dimension fails the message.
+
+### Calibration of `plain`
+
+Jev scores dense status text near 0 and plain text near 0.8 to 0.9, with a wide middle of compact but readable engineering notes. Measured on 400 Slack-facing completions over 7 days, at `threshold` 0.75 for preferences:
+
+| `plainThreshold` | Newly blocked (of messages that pass today) |
+|---|---|
+| 0.75 | 81% to 83% |
+| 0.3 | 9% to 13% |
+| 0.25 (default) | 5% to 7% |
+
+At 0.25 the dense prompt-cache-monitor post scores about 0.15 and its plain rewrite about 0.81.
 
 ## Jev transport
 
@@ -51,14 +73,16 @@ Every error lets the completion through: a missing key, an HTTP error, a network
 
 ## Self-test
 
-Call `store-progress` with a non-completed status and `progress` starting with `comms-gate-selftest`. The gate judges a known-bad and a known-good message against a terse preference and writes `selftest:last`: both scores, the threshold, the provider, and `controlsOk` (bad below threshold and good at or above it). Real traffic is untouched.
+Call `store-progress` with a non-completed status and `progress` starting with `comms-gate-selftest`. The gate judges a known-bad and a known-good message against a terse preference, and a dense and a plain message on `plain`, then writes `selftest:last`: every score, both thresholds, the provider, `controlsOk` (verbosity: bad below `threshold`, good at or above it) and `plainControlsOk` (the same against `plainThreshold`). Real traffic is untouched.
 
 ## Config
 
 | Key | Default | Notes |
 |---|---|---|
 | `mode` | `shadow` | `off`, `shadow`, or `enforce` |
-| `threshold` | `0.5` | A dimension scoring below this fails |
+| `threshold` | `0.5` | A preference dimension scoring below this fails |
+| `plainMode` | `shadow` | `off`, `shadow`, or `enforce` for the `plain` dimension |
+| `plainThreshold` | `0.25` | `plain` scoring below this fails. See [Calibration](#calibration-of-plain) |
 | `timeoutMs` | `4000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |
 | `maxBlocksPerTask` | `1` | Blocks per task in `enforce`; after that the gate records and lets it through |
 | `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |
@@ -76,13 +100,14 @@ No key is written to config, KV, logs, or a block reason.
 
 ## KV namespace `ext:comms-gate`
 
-- `last`: the latest verdict, with `scores`, `failed`, `provider`, `latencyMs`, the preferences, a 400-character `askPreview` and a 700-character `outputPreview`.
+- `last`: the latest verdict, with `tool`, `scores`, `failed`, `mode`, `plainMode`, `provider`, `latencyMs`, the preferences, a 400-character `askPreview` and a 700-character `outputPreview`.
 - `fail:<epochMs>:<taskId>`: one row per failed verdict, with `action` (`blocked` or `recorded`).
 - `blocks:<taskId>`: blocks issued for that task.
 - `error:last`, `selftest:last`.
-- Counters: `total`, `pass`, `fail`, `blocked`, `escaped` (enforce, block budget spent), `shadowed`, `error`, and `dim:<dimension>`.
+- Counters: `total`, `pass`, `fail`, `blocked`, `escaped` (a blocking dimension failed, block budget spent), `shadowed` (only non-blocking dimensions failed), `error`, and `dim:<dimension>`.
 
 ## Known limits
 
 - Only the last 1,400 characters of the task are searched for the latest request. A very long final message is cut to its last 900 characters.
-- The block budget is per task, so a retried completion after a block goes through once the budget is spent, even if it still fails.
+- The block budget is per task, so a retried call after a block goes through once the budget is spent, even if it still fails.
+- Each gated Slack post waits for one Jev call (about 0.2 s measured, capped by `timeoutMs`).