@uipath/maestro-builder-sdk 6.8.3 → 6.8.5

package/dist/check.js

@@ -11,11 +11,11 @@ import { isLookupToken, resolvedValue, unresolvedLookupMessage, } from './core/l
 import { EVENT_FILTER_OPERATORS, readEventFilter, eventFilterProblem } from './event-filters.js';
 import { extractRefs } from './core/expr-check.js';
 import { bindingSelfNameMessage } from './core/binding-messages.js';
-import { hitlRoutesPerOutcome } from './core/hitl-routing.js';
-import { declaredExits, hasExits } from './core/step-ports.js';
+import { hitlDerivesOutcomeHandles, hitlExitModel, hitlRoutesPerOutcome } from './core/hitl-routing.js';
+import { declaredExits, hasExits, stopsAtEnd } from './core/step-ports.js';
 import { FLOW_SCHEMA_VERSIONS } from './format-profile.js';
 import { compareSchemaVersions, schemaVersionRefusal } from './schema-version.js';
-import { prepareCommand } from './core/cli-spelling.js';
+import { prepareCommand, resolveFlagArg } from './core/cli-spelling.js';
 export function check(built, opts = {}) {
     return checkFlow(built, [], opts);
 }
@@ -107,14 +107,16 @@ function checkFlow(built, ancestors, opts = {}) {
     const hitlOutcomeSteps = new Map();
     const hitlOutcomeRouted = new Map();
     // The other half of that bookkeeping: hitl steps that declare a CHOICE (more
-    // than one outcome) and still leave on ONE exit, so every outcome leaves the
-    // node the same way. Since more than one outcome infers per-outcome routing,
-    // reaching this map means the single exit was chosen — by a variant, a pinned
-    // version, or `outcomePorts: false` — and WHICH of the three decides what the
-    // remedy can be. Whether it is a mistake at all depends on something no single
-    // step can see — whether anything downstream reads the chosen outcome — so the
-    // decision waits until the expressions are collected (see
-    // HITL_OUTCOMES_UNREACHABLE below).
+    // than one outcome) and do not route it, so every outcome goes to the same
+    // place — the same next step (a base or quick-form task that does not route
+    // per outcome), or the one `completed` exit (an app-backed variant). Since
+    // more than one outcome infers per-outcome routing on the base node, reaching
+    // this map means that was chosen — by a variant, a pinned version, or
+    // `outcomePorts: false` — and WHICH decides what the remedy can be. Whether
+    // it is a mistake at all depends on something no single step can see —
+    // whether anything downstream reads the chosen outcome — so the decision
+    // waits until the expressions are collected (see HITL_OUTCOMES_UNREACHABLE
+    // below).
     const hitlChoiceNoPorts = new Map();
     // Data Fabric writes that target a record `{ fromRead: '<step>' }` — update and
     // delete share the selector, so they share the check.
@@ -179,6 +181,30 @@ function checkFlow(built, ancestors, opts = {}) {
                 step: term.name,
             });
         }
+        // Nothing may follow a human task whose EVERY outcome ends the run, except a
+        // `.return()`. Each outcome gets its own End node — the flow runtime never
+        // reads `action`, so only the graph can end the run there — which leaves
+        // the next step with no incoming edge. A `.return()` is an End already, so
+        // the outcomes join it. Side exits attach to the task and do not count.
+        for (const [i, st] of steps.entries()) {
+            if (st.kind !== 'action' || st.spec.kind !== 'hitl')
+                continue;
+            const model = hitlExitModel(st.spec.inputs, st.options?.version);
+            if (model.shape !== 'every-outcome' || !model.exits.every((e) => e.endsProcess))
+                continue;
+            const after = steps.slice(i + 1).find((x) => x.kind !== 'stepToList' && x.kind !== 'stepToRef');
+            if (after === undefined || after.kind === 'return')
+                continue;
+            diags.push({
+                level: 'error',
+                code: 'HITL_UNREACHABLE_AFTER',
+                message: `Every outcome of human task "${st.name}" is action: 'End' `
+                    + `(${model.exits.map((e) => e.value).join(', ')}), so each one ends the run at its own End node, and `
+                    + `"${'name' in after ? after.name : after.kind}" after it can never run. Drop action: 'End' from the `
+                    + 'outcomes that should continue, or end the path here with .return().',
+                step: st.name,
+            });
+        }
         // The action a port-scoped edge leaves, tracked because `stepToList` and
         // `stepToRef` FOLLOW the step they attach to rather than nesting inside it.
         let prevAction;
@@ -224,41 +250,35 @@ function checkFlow(built, ancestors, opts = {}) {
                     });
                 }
             }
-            // The mirror of HITL_OUTCOME_PORTS_OFF below: `completed` on a human task
-            // that routes per outcome.
+            // The mirror of HITL_OUTCOME_PORTS_OFF below: `completed` on a base or
+            // quick-form human task that has outcomes.
             //
-            // Per-outcome routing moves the step to the node's 1.1/1.2 definition, and
-            // those declare ONE source handle — `outcome-{item.id}`, repeated over
-            // `inputs.schema.outcomes`. There is no `completed` handle to leave from,
-            // so this edge is refused by the product: `flow validate` answers "Edge
-            // references undeclared source handle \"completed\" on node \"<step>\""
-            // (measured). Without this rule `check` was silent, `compile` emitted it,
-            // and the author found out from validate — or from a consumer that
-            // inspects ports.
-            //
-            // Since more than one outcome INFERS the routing, this is now also the
-            // rule an author meets when they write the old shape on a multi-outcome
-            // task, so the message names the two ways back to a `completed` exit.
+            // The product draws one `outcome-<id>` handle per outcome on those two node
+            // types, at every definition version, and `completed` only when there are
+            // none (flow-workbench `build-handle-customization.ts`). An edge on it is
+            // stale: Studio Web and the converter remap it to the PRIMARY outcome
+            // (#3512), so every other outcome loses its path — and `flow validate`
+            // accepts it without `handleCustomization`, so nothing later catches it.
+            // `serialize` refuses to emit one; this says why, in the author's terms.
             if ((s.kind === 'stepToList' || s.kind === 'stepToRef') && s.port === 'completed') {
                 const prevSpec = prevAction?.spec;
                 const isHitl = !!prevSpec && 'kind' in prevSpec && prevSpec.kind === 'hitl';
-                const routed = isHitl && hitlRoutesPerOutcome(prevSpec.inputs, prevAction?.options?.version);
-                if (routed) {
-                    const first = prevSpec.inputs.outcomes?.[0];
-                    const firstId = outcomeSlug(typeof first === 'string' ? first : first?.name, 0);
-                    const why = prevSpec.inputs?.exposeError === true ? 'exposeError selects'
-                        : prevSpec.inputs?.outcomePorts === true ? 'outcomePorts selects'
-                            : `its ${(prevSpec.inputs?.outcomes ?? []).length} outcomes select`;
+                const model = isHitl ? hitlExitModel(prevSpec.inputs, prevAction?.options?.version) : undefined;
+                if (model && model.shape !== 'placeholder') {
+                    const ports = model.exits.map((e) => `"${e.port}"`).join(', ');
+                    const routed = model.shape === 'per-outcome';
                     diags.push({
                         level: 'error', code: 'HITL_COMPLETED_PORT_GONE', step: prevAction?.name,
-                        message: `Port "completed" does not exist on human task "${prevAction?.name}". ${why} the node's `
-                            + `${prevSpec.inputs?.exposeError === true ? '1.2' : '1.1'} definition, whose only source handle is `
-                            + `"outcome-<id>" repeated over the outcomes — the 1.0 definition's single 'completed' exit is not `
-                            + `part of it. The FIRST outcome ("outcome-${firstId}") is what continues the main path.`,
-                        suggestion: prevSpec.inputs?.outcomePorts === true || prevSpec.inputs?.exposeError === true
-                            ? `route the outcomes (.stepToList('outcome-${firstId}', …)), or drop outcomePorts to keep the 'completed' exit`
-                            : `route the outcomes (.stepToList('outcome-${firstId}', …)), or keep the single exit with `
-                                + `outcomePorts: false`,
+                        message: `Port "completed" does not exist on human task "${prevAction?.name}". It has outcomes, so `
+                            + `the product draws one handle per outcome (${ports}) and no 'completed' — an edge there is `
+                            + `remapped to the primary outcome and the others lose their path. `
+                            + (routed
+                                ? `The FIRST outcome ("${model.exits[0]?.port}") is what continues the main path.`
+                                : `.step() after this task already continues every outcome to the next step.`),
+                        suggestion: routed
+                            ? `route the outcomes (.stepToList('${model.exits[1]?.port ?? model.exits[0]?.port}', …)), or continue `
+                                + `every outcome to the next step with outcomePorts: false`
+                            : `drop the 'completed' route — .step() continues every outcome — or route each outcome with .stepSwitch`,
                     });
                 }
             }
@@ -273,29 +293,20 @@ function checkFlow(built, ancestors, opts = {}) {
                             + `${prevAction ? `"${prevAction.name}" ` : ''}is not a human task.`,
                     });
                 }
-                else if (!hitlRoutesPerOutcome(prevSpec.inputs, prevAction?.options?.version)) {
-                    // Reachable three ways now that more than one outcome infers the
-                    // routing: `outcomePorts: false`, a pinned `{ version: '1.0' }`, or a
-                    // variant that has no per-outcome definition to select.
-                    const off = prevSpec.inputs?.outcomePorts === false ? 'outcomePorts: false turns them off'
-                        : prevSpec.inputs?.variant !== undefined
-                            ? `the '${prevSpec.inputs.variant}' variant has no per-outcome definition version`
-                            : prevAction?.options?.version !== undefined
-                                ? `{ version: '${prevAction.options.version}' } pins the definition that has none`
-                                : 'it declares fewer than two outcomes';
-                    diags.push({
-                        level: 'error', code: 'HITL_OUTCOME_PORTS_OFF', step: prevAction?.name,
-                        message: `Port "${s.port}" routes a per-outcome exit, but human task "${prevAction?.name}" `
-                            + `does not have them — ${off}, so its single exit is 'completed'. Per-outcome exits are the `
-                            + `node's 1.1 definition.`,
-                        suggestion: prevSpec.inputs?.variant !== undefined
-                            ? `route on out('${prevAction?.name}', 'Action') downstream`
-                            : `outcomePorts: true`,
-                    });
-                }
                 else {
+                    const model = hitlExitModel(prevSpec.inputs, prevAction?.options?.version);
                     const ids = (prevSpec.inputs.outcomes ?? []).map((o, i) => outcomeSlug(typeof o === 'string' ? o : o?.name, i));
-                    if (!ids.includes(want)) {
+                    if (model.shape === 'placeholder') {
+                        diags.push({
+                            level: 'error', code: 'HITL_OUTCOME_PORTS_OFF', step: prevAction?.name,
+                            message: `Port "${s.port}" routes a per-outcome exit, but human task "${prevAction?.name}" `
+                                + `has none — ${ids.length === 0 ? 'it declares no outcomes'
+                                    : `the '${prevSpec.inputs?.variant}' variant reads its outcomes from its app`}, so its single `
+                                + `exit is 'completed'.`,
+                            suggestion: `route on out('${prevAction?.name}', 'Action') downstream`,
+                        });
+                    }
+                    else if (!ids.includes(want)) {
                         diags.push({
                             level: 'error', code: 'HITL_OUTCOME_PORT_UNKNOWN', step: prevAction?.name,
                             message: `Port "${s.port}" routes the outcome id ${JSON.stringify(want)}, but human task `
@@ -303,6 +314,19 @@ function checkFlow(built, ancestors, opts = {}) {
                                 + `outcome names slugified (lowercase, non-alphanumerics to '-').`,
                         });
                     }
+                    else if (model.shape === 'every-outcome') {
+                        // The port is real, but it is ALREADY wired: a task that does not
+                        // route per outcome continues every outcome to the next step, so a
+                        // second route would put two edges on one port (#741).
+                        diags.push({
+                            level: 'error', code: 'HITL_OUTCOME_PORTS_OFF', step: prevAction?.name,
+                            message: `Port "${s.port}" is already wired: human task "${prevAction?.name}" does not route per `
+                                + `outcome — ${fanOutWhy(model.why, prevAction?.options?.version)} — so .step() continues every `
+                                + `outcome to the next step, "${s.port}" included. A second route would put two edges on one port.`,
+                            suggestion: `outcomePorts: true (then the first outcome continues and the others are routed), `
+                                + `or route every outcome with .stepSwitch`,
+                        });
+                    }
                     else if (prevAction) {
                         let routed = hitlOutcomeRouted.get(prevAction.name);
                         if (!routed)
@@ -384,10 +408,13 @@ function checkFlow(built, ancestors, opts = {}) {
                     // the whole truth there, and the rule below would be a false positive.
                     const allEnd = outcomes.length > 0
                         && outcomes.every((o) => typeof o !== 'string' && o?.action === 'End');
-                    if (outcomes.length > 1 && !allEnd
+                    // `.stepSwitch` routes every outcome as an arm, so it never belongs here.
+                    if (outcomes.length > 1 && !allEnd && s0.kind !== 'stepSwitch'
                         && !hitlRoutesPerOutcome(s.spec.inputs, s.options?.version)) {
                         hitlChoiceNoPorts.set(s.name, {
                             names: outcomes.map((o) => String((typeof o === 'string' ? o : o?.name) ?? '').trim()),
+                            ends: outcomes.filter((o) => typeof o !== 'string' && o?.action === 'End')
+                                .map((o) => String(o.name ?? '').trim()),
                             variant: s.spec.inputs?.variant,
                             pinned: s.options?.version,
                             portsOff: s.spec.inputs?.outcomePorts === false,
@@ -1237,6 +1264,9 @@ function checkFlow(built, ancestors, opts = {}) {
 function checkConnectorLookups(step, spec, opts, diags) {
     const specs = opts.lookups?.(spec.key, spec.action, spec.version, spec.object);
     const resolutions = opts.resolutions ?? {};
+    // One LOOKUP_LITERAL_ID per field: a multiselect of three pasted ids is one
+    // mistake with one remedy, not three.
+    const literalWarned = new Set();
     const visit = (value, path) => {
         if (isLookupToken(value)) {
             // A match key the field does not declare is certainly wrong, and the
@@ -1277,7 +1307,17 @@ function checkConnectorLookups(step, spec, opts, diags) {
             return;
         }
         if (Array.isArray(value)) {
-            value.forEach((v, i) => visit(v, [...path, String(i)]));
+            // An element is named by the WIRE name the lookup table is keyed on —
+            // `users[*]`, `contacts[*].id` — not by its index. `users.0` matched no
+            // spec, so a pasted id, a token with a bad match key, or a runtime value
+            // inside a multiselect passed every rule below unseen. A name that already
+            // is the array's (a flat `'users[*]'` key, or a field typed as an array)
+            // stays as it is.
+            const last = path[path.length - 1] ?? '';
+            const element = last.endsWith('[*]') || specs?.[path.join('.')]
+                ? path
+                : [...path.slice(0, -1), `${last}[*]`];
+            value.forEach((v) => visit(v, element));
             return;
         }
         if (value && typeof value === 'object' && !(value instanceof Expr)) {
@@ -1302,6 +1342,9 @@ function checkConnectorLookups(step, spec, opts, diags) {
         const literal = value instanceof Expr ? value.value : value;
         if (typeof literal !== 'string')
             return;
+        if (literalWarned.has(field))
+            return;
+        literalWarned.add(field);
         const { target, call } = lookupPhrases(field, lookup, spec);
         diags.push({
             level: 'warning',
@@ -1313,7 +1356,7 @@ function checkConnectorLookups(step, spec, opts, diags) {
                 + `compile nor deploy can tell. Write what you mean and resolve it late:\n`
                 + `  ${call}\n`
                 + `then record the value once with \`${prepareCommand(spec.key)} `
-                + `${spec.action} --resolve ${field}:${lookup.by[0] ?? 'id'}=<value>\`.`,
+                + `${spec.action} --resolve ${resolveFlagArg(field, lookup.by[0] ?? 'id', '<value>')}\`.`,
             step,
         });
     };
@@ -1530,7 +1573,7 @@ function runtimeLookupDiagnostic(step, spec, field, lookup, value) {
         + `neither compile nor validate can tell. Resolve the value you know instead:\n`
         + `  ${call}\n`
         + `then record it once with \`${prepareCommand(spec.key, spec.action)} `
-        + `--resolve ${field}:${lookup.by[0] ?? 'id'}=<value>\`; or read the id from a step whose `
+        + `--resolve ${resolveFlagArg(field, lookup.by[0] ?? 'id', '<value>')}\`; or read the id from a step whose `
         + `output returned one (\`${lookup.value}\`).`
         + (isEmail
             ? `\n\`${single.raw}\` reads \`${leaf}\`, an e-mail address, not a \`${target}\`.`
@@ -3747,15 +3790,19 @@ function nearestInterval(every) {
  * is why the e2e task's covering assertion is structural, and why these are
  * rung-1 errors rather than something the ladder catches.
  *
- * There is deliberately NO rule requiring an arm to contribute exactly one edge
- * (i.e. no rejecting a `.branch` inside an arm because its two mutually
- * exclusive paths both wire into the Merge). BPMN's parallel-gateway join waits
- * for a token per incoming flow, which reads like a deadlock — but the
- * platform's own canonical emitter does precisely this: it rejoins
- * every `if/else` and every `switch` arm on a `core.logic.merge`, wiring the
- * mutually exclusive `false` port straight into it. Those flows deploy and run.
- * A checker that banned the shape would be inventing a constraint the platform
- * does not have.
+ * The join is a `bpmn:parallelGateway`, and it waits for a token on EVERY
+ * incoming flow (flow-v1 `gateway-join-tracker.ts:33-36`). So two mutually
+ * exclusive edges into it — a `.branch` / `.switch` / `.stepSwitch` inside an
+ * arm whose paths both end at the Merge — leave the join waiting for the path
+ * that was not taken, and the run stays Running with no incident. That was
+ * measured live on 09-01 (a Merge fed by a Decision's two ports). An older note
+ * here said such flows "deploy and run"; they deploy, and they do not finish.
+ * This function does NOT refuse that general shape yet — it predates the human
+ * task rule below and is tracked as its own SDK issue. It does refuse it when a
+ * human task's outcome edge is among the arm's alternative edges into the join
+ * — a fan-out task at the arm's end, one empty `.stepSwitch` arm beside a body
+ * arm, a task on one side of a `.branch` (HITL_FAN_OUT_INTO_JOIN) — and an
+ * `action: 'End'` outcome inside an arm (HITL_END_OUTCOME_IN_PARALLEL).
  */
 function checkParallel(s, diags) {
     const at = (code, message, suggestion) => {
@@ -3798,6 +3845,14 @@ function checkParallel(s, diags) {
                 + `terminate its own arm, or move the earlier step(s) before the \`.parallel(…)\` call.`, `.parallel('${s.name}', [(a) => a.terminate('${term.name}'), …])`);
         }
     });
+    arms.forEach((arm, i) => {
+        const steps = Array.isArray(arm) ? arm : [];
+        const fanIn = hitlFanInto(steps);
+        if (fanIn)
+            diags.push(fanInDiag(s.name, i, steps, fanIn));
+        for (const h of hitlEndHazards(steps))
+            diags.push(endDiag(s.name, h));
+    });
     // An arm that ends the flow reaches an End node instead of the Merge, so it
     // contributes NO incoming edge. Verified on the emitted graph: with two arms
     // and one returning, the Merge has a single incoming edge and is no longer a
@@ -3821,6 +3876,180 @@ function checkParallel(s, diags) {
         });
     }
 }
+/**
+ * The edges a step list hands on, mirroring serialize's `emit` tail for tail.
+ *
+ * `.branch` / `.switch` / `.stepSwitch` hand on every arm's tails (an empty arm
+ * hands on the port it started from), a fan-out human task one per continuing
+ * outcome, a routed one its primary outcome; `.return` / `.terminate` / `.break`
+ * and a `stepToRef('output', …)` hand on none, `.stepToList` leaves the path as
+ * it was, and every other step hands on its own single edge.
+ */
+function armTails(steps, incoming) {
+    let tails = incoming;
+    for (const st of steps) {
+        if (st.kind === 'stepToList')
+            continue;
+        if (st.kind === 'stepToRef') {
+            if (st.port === 'output')
+                tails = [];
+            continue;
+        }
+        if (st.kind === 'return' || st.kind === 'terminate' || st.kind === 'break')
+            return [];
+        if (st.kind === 'action') {
+            tails = actionTails(st.name, st.spec, st.options?.version);
+        }
+        else if (st.kind === 'stepSwitch') {
+            const spec = st.spec;
+            const outcomes = spec.kind === 'hitl' && hitlDerivesOutcomeHandles(spec.inputs?.variant);
+            tails = st.cases.flatMap((c) => armTails(c.body, [{ from: st.name, ...(outcomes ? { outcome: String(c.value) } : {}) }])
+                .map((t) => (outcomes && !t.humanSwitch ? { ...t, humanSwitch: { step: st.name, outcome: String(c.value) } } : t)));
+        }
+        else if (st.kind === 'branch') {
+            tails = [...armTails(st.then, [{ from: st.name }]), ...armTails(st.otherwise, [{ from: st.name }])];
+        }
+        else if (st.kind === 'switch') {
+            tails = [
+                ...st.cases.flatMap((c) => armTails(c.body, [{ from: st.name }])),
+                ...(st.default !== undefined ? armTails(st.default, [{ from: st.name }]) : []),
+            ];
+        }
+        else {
+            tails = [{ from: st.name ?? st.kind }];
+        }
+    }
+    return tails;
+}
+function actionTails(name, spec, version) {
+    if (spec.kind !== 'hitl' || !hitlDerivesOutcomeHandles(spec.inputs?.variant))
+        return [{ from: name }];
+    const model = hitlExitModel(spec.inputs, version);
+    if (model.shape === 'placeholder')
+        return [{ from: name }];
+    if (model.shape === 'per-outcome')
+        return model.exits.slice(0, 1).map((e) => ({ from: name, outcome: e.value }));
+    return model.exits.filter((e) => !e.endsProcess).map((e) => ({ from: name, outcome: e.value }));
+}
+/**
+ * The tails of a `.parallel` arm when they would starve its join: two or more
+ * alternative edges — only one fires — at least one of which is a human task's
+ * outcome edge, or the end of a human-task `.stepSwitch` arm. The join waits
+ * for a token on every incoming flow.
+ *
+ * However the task got there, it is the same graph: a fan-out task at the arm's
+ * end (its outcomes are the alternatives), a `.stepSwitch` with an empty arm
+ * beside a body arm, a complete `.stepSwitch` with nothing after it (one edge
+ * per arm's last step), a task on one side of a `.branch`. serialize refuses the
+ * same condition, edge for edge. Rejoining arms with NO human task in them are
+ * the older, general case, and not refused here.
+ */
+function hitlFanInto(steps) {
+    const tails = armTails(steps, [{ from: '(fork)' }]);
+    return tails.length >= 2 && tails.some((t) => t.outcome !== undefined || t.humanSwitch !== undefined) ? tails : undefined;
+}
+function fanInDiag(join, arm, steps, tails) {
+    const tagged = tails.find((t) => t.outcome !== undefined || t.humanSwitch !== undefined);
+    const task = tagged.outcome !== undefined ? tagged.from : tagged.humanSwitch.step;
+    if (tails.every((t) => t.from === task && t.outcome !== undefined)) {
+        return {
+            level: 'error', code: 'HITL_FAN_OUT_INTO_JOIN', step: task,
+            message: `Human task "${task}" ends its path inside parallel "${join}", so its outcomes `
+                + `${tails.map((t) => t.outcome).join(', ')} each get their own edge into the join. Only one outcome ever `
+                + `fires, and the join waits for a token on every incoming edge, so the run never gets past "${join}" — with `
+                + `no incident, and \`flow validate\` answers Valid. Add a step after "${task}" inside the arm, so every `
+                + `outcome continues to that step and only its one edge reaches the join (the decision is `
+                + `out('${task}', 'Action')), or move the task out of the \`.parallel(…)\`.`,
+            suggestion: `a.step('${task}', hitl(…)).step('record', …)`,
+        };
+    }
+    const edges = tails.map((t) => (t.outcome !== undefined ? `outcome ${t.outcome} of "${t.from}"`
+        : t.humanSwitch ? `"${t.from}" (on outcome ${t.humanSwitch.outcome} of "${t.humanSwitch.step}")` : `"${t.from}"`));
+    const last = [...steps].reverse().find((x) => x.kind !== 'stepToList' && x.kind !== 'stepToRef');
+    return {
+        level: 'error', code: 'HITL_FAN_OUT_INTO_JOIN', step: task,
+        message: `Parallel "${join}" arm ${arm + 1} ends on ${tails.length} alternative paths, and each gets its own edge `
+            + `into the join: ${edges.join(', ')}. Only one of them runs, and the join waits for a token on every incoming `
+            + `edge, so the run never gets past "${join}" — with no incident, and \`flow validate\` answers Valid. Add a `
+            + `step at the end of the arm${last?.name ? `, after "${last.name}"` : ''}, so the paths meet on that step and `
+            + `only its one edge reaches the join, or move human task "${task}" out of the \`.parallel(…)\`.`,
+        suggestion: `….step('record', …)  // last step of arm ${arm + 1}`,
+    };
+}
+/**
+ * Human tasks in one `.parallel` arm that continue every outcome while some of
+ * them are `action: 'End'`. The End outcome's path stops at its End node, so the
+ * join waits for the continuing path that did not run.
+ *
+ * Recurses into `.branch` / `.switch` / `.stepSwitch` bodies, which reach the
+ * join too. Not into a loop body (the loop node is what reaches the join) or a
+ * nested `.parallel` (its own join is checked on its own).
+ */
+function hitlEndHazards(steps) {
+    const found = [];
+    for (const st of steps) {
+        if (st.kind === 'action' && st.spec.kind === 'hitl') {
+            const model = hitlExitModel(st.spec.inputs, st.options?.version);
+            if (model.shape !== 'every-outcome')
+                continue;
+            const ending = model.exits.filter((e) => e.endsProcess).map((e) => e.value);
+            if (ending.length > 0 && ending.length < model.exits.length)
+                found.push({ step: st.name, outcomes: ending, via: 'action-end' });
+        }
+        else if (st.kind === 'branch') {
+            found.push(...hitlEndHazards(st.then), ...hitlEndHazards(st.otherwise));
+        }
+        else if (st.kind === 'switch') {
+            for (const c of st.cases)
+                found.push(...hitlEndHazards(c.body));
+            if (st.default)
+                found.push(...hitlEndHazards(st.default));
+        }
+        else if (st.kind === 'stepSwitch') {
+            // An outcome with no arm gets an End (serialize's `endExit`), and so does
+            // an arm that ends in `.return()`. Beside an arm that continues, that End
+            // is where this arm's token stops on that outcome.
+            const spec = st.spec;
+            const exits = spec.kind === 'hitl' && hitlDerivesOutcomeHandles(spec.inputs?.variant)
+                ? declaredExits(st.spec, st.options?.version) : undefined;
+            if (exits && hasExits(exits)) {
+                const stopped = exits.filter((e) => {
+                    const c = st.cases.find((x) => x.value === e.value);
+                    return !c || (armTails(c.body, [{ from: st.name }]).length === 0 && stopsAtEnd(c.body));
+                }).map((e) => e.value);
+                if (stopped.length > 0 && armTails([st], [{ from: '(fork)' }]).length > 0) {
+                    found.push({ step: st.name, outcomes: stopped, via: 'step-switch' });
+                }
+            }
+            for (const c of st.cases)
+                found.push(...hitlEndHazards(c.body));
+        }
+    }
+    return found;
+}
+function endDiag(join, h) {
+    const list = h.outcomes.join(', ');
+    if (h.via === 'step-switch') {
+        return {
+            level: 'error', code: 'HITL_END_OUTCOME_IN_PARALLEL', step: h.step,
+            message: `Human task "${h.step}" is a .stepSwitch inside parallel "${join}", and ${h.outcomes.length === 1
+                ? `outcome ${list} has` : `outcomes ${list} have`} no arm, or an arm that ends in .return(). That path `
+                + `stops at an End node, while the join waits for a token from this arm on the path that continues, so the `
+                + `run never gets past "${join}" — with no incident, and \`flow validate\` answers Valid. Give every outcome `
+                + `an arm that continues (and move a .return() after the \`.parallel(…)\`), or move the task out of the `
+                + `\`.parallel(…)\`.`,
+            suggestion: `{ value: '${h.outcomes[0]}', body: (b) => b.step(…) }`,
+        };
+    }
+    return {
+        level: 'error', code: 'HITL_END_OUTCOME_IN_PARALLEL', step: h.step,
+        message: `Human task "${h.step}" is inside parallel "${join}", and ${h.outcomes.length === 1
+            ? `outcome ${list} is` : `outcomes ${list} are`} action: 'End'. `
+            + `That path stops at its own End node, while the join waits for a token from this arm on its `
+            + `continuing path, so the run never gets past "${join}". Drop action: 'End' there and act on `
+            + `out('${h.step}', 'Action') after the join, or move the task out of the \`.parallel(…)\`.`,
+    };
+}
 /**
  * Diagnose a `transform` step.
  *
@@ -4059,34 +4288,46 @@ function outcomeSlug(name, index) {
         .replace(/^-+|-+$/g, '');
     return slug || `outcome-${index + 1}`;
 }
+/**
+ * Why a base or quick-form task continues every outcome to the next step, as a
+ * clause for a diagnostic. `pinned` is the step's `{ version }`.
+ */
+function fanOutWhy(why, pinned) {
+    switch (why) {
+        case 'outcomePorts: false': return 'outcomePorts: false says so';
+        case 'quick-form': return 'a quick-form task does not unless it sets outcomePorts: true';
+        case 'pinned': return `{ version: '${pinned}' } pins it without outcomePorts: true`;
+        case 'one outcome': return 'it has a single outcome';
+        case 'every outcome ends': return "every outcome is action: 'End'";
+    }
+}
 /**
  * HITL_OUTCOMES_UNREACHABLE — a human task offers the reviewer a CHOICE that
  * nothing downstream can act on.
  *
- * The single-exit shape publishes the outcomes and routes none of them: the 1.0
- * definition's ONE source handle is `completed`, so the outcomes reach the
- * reviewer and `inputs.schema.outcomes`, and then every button the reviewer can
- * press leaves the node the same way. Two outcomes, one path — an approval whose
- * approve and reject arms are indistinguishable is a modelling error, not a
- * style choice, yet it compiles and `flow validate` answers `Valid`
+ * A task that does not route per outcome sends every outcome to the same place:
+ * on the base node and quick-form, one `outcome-<id>` edge per outcome, all to
+ * the same next step; on an app-backed variant, its one `completed` exit. The
+ * outcomes reach the reviewer and `inputs.schema.outcomes`, and then every
+ * button the reviewer can press leads to the same step. Two outcomes, one path —
+ * an approval whose approve and reject arms are indistinguishable is a modelling
+ * error, not a style choice, yet it compiles and `flow validate` answers `Valid`
  * (flow-builder-sdk#735).
  *
  * On a plain base task that is no longer reachable: more than one outcome now
  * INFERS per-outcome routing (`hitlRoutesPerOutcome`, #739), because a warning
  * alone did not change what agents emitted — #739 measured the diagnostic
  * firing three times and the unreachable artifact shipping anyway. What is left
- * for this rule is the cases where the single exit is CHOSEN and the choice may
- * still be a mistake: a `variant` (no per-outcome definition version exists to
- * select, #729), a pinned `{ version: '1.0' }`, and an explicit
- * `outcomePorts: false`.
+ * for this rule is the cases where not routing is CHOSEN and the choice may
+ * still be a mistake: quick-form's default, a pinned `{ version }`, an explicit
+ * `outcomePorts: false`, and the app-backed variants.
  *
- * In all three the shape is correct when something reads the chosen outcome:
- * `out('<step>', 'Action')` feeding a `.switch()` routes the decision as data,
- * and it is the ONLY shape the quick-form, action-app and document-validation
- * variants have. So the rule is not "outcomes without ports", which would
- * refuse that shape; it is "outcomes that no exit and no expression
- * distinguishes". That is why it runs here, after `walk`, rather than inside
- * `checkHitl`: the deciding evidence is the rest of the flow.
+ * In all of them the shape is correct when something reads the chosen outcome:
+ * `out('<step>', 'Action')` feeding a `.switch()` routes the decision as data.
+ * So the rule is not "outcomes without routes", which would refuse that shape;
+ * it is "outcomes that no route and no expression distinguishes". That is why it
+ * runs here, after `walk`, rather than inside `checkHitl`: the deciding evidence
+ * is the rest of the flow.
  *
  * A read counts when it can SEE the outcome — `.output.Action`, the whole
  * answer object (`out('<step>')` / `$vars.<step>.output`, which carries
@@ -4116,35 +4357,46 @@ function reportUnreachableHitlOutcomes(choices, exprs, diags) {
         for (const m of js.matchAll(/\$vars\.([A-Za-z0-9_]+)\s*\[/g))
             readsOutcome.add(m[1]);
     }
-    for (const [step, { names, variant, pinned, portsOff }] of choices) {
+    for (const [step, { names, ends, variant, pinned, portsOff }] of choices) {
         if (readsOutcome.has(step))
             continue;
         const ids = names.map((n, i) => outcomeSlug(n, i));
-        // Why this task kept the single exit decides which remedy is even legal:
-        // `outcomePorts: true` is refused on a variant and conflicts with a pin, so
-        // offering it there would trade a warning for a compile error.
-        // On a base task with no pin, more than one outcome would have inferred the
-        // routing — so the only way such a task reaches here is `outcomePorts:
-        // false`, and it is the only case where offering the flag is legal.
-        const canTakePorts = variant === undefined && pinned === undefined && portsOff === true;
-        const kept = variant !== undefined
-            ? `The "${variant}" variant has no per-outcome definition version to select`
-            : pinned !== undefined
-                ? `{ version: '${pinned}' } pins the definition whose only exit is 'completed'`
-                : `outcomePorts: false keeps the single exit`;
+        // The base node and quick-form draw a handle per outcome, so both can route
+        // it — `.stepSwitch`, or `outcomePorts: true` (a pin keeps its version). An
+        // app-backed variant cannot: the Action read is its only remedy.
+        const canRoute = hitlDerivesOutcomeHandles(variant);
+        // On those two, an `action: 'End'` outcome gets its own End node, so the
+        // graph already tells it apart. Only the outcomes that CONTINUE share a step.
+        const continuing = canRoute ? names.filter((n) => !ends.includes(n)) : names;
+        if (continuing.length < 2)
+            continue;
+        const endNote = canRoute && ends.length > 0
+            ? ` (${ends.join(', ')} ${ends.length === 1 ? 'is' : 'are'} action: 'End' and end${ends.length === 1 ? 's' : ''} the run instead)`
+            : '';
+        const kept = !canRoute
+            ? `The "${variant}" variant reads its outcomes from its app and leaves on its single 'completed' exit`
+            : portsOff
+                ? `outcomePorts: false continues every outcome to the next step`
+                : variant === 'quick-form'
+                    ? `A quick-form task continues every outcome to the next step unless it routes them`
+                    : `{ version: '${pinned}' } without outcomePorts: true continues every outcome to the next step`;
         diags.push({
             level: 'warning', code: 'HITL_OUTCOMES_UNREACHABLE', step,
             message: `Human task "${step}" declares ${names.length} outcomes (${names.join(', ')}), but nothing `
-                + `downstream tells them apart: the node emits its single 'completed' exit and every outcome leaves `
-                + `on it, and no expression reads out('${step}', 'Action') either. The outcomes reach the reviewer `
-                + `and the artifact; the decision does not reach the flow. ${kept}, so switch on `
-                + `out('${step}', 'Action') to route the decision as data`
-                + (canTakePorts
-                    ? `, or drop outcomePorts: false for per-outcome exits (${ids.map((i) => `'outcome-${i}'`).join(', ')}).`
+                + `downstream tells them apart: ${canRoute
+                    ? `${ends.length > 0 ? `${continuing.join(', ')} continue` : 'every outcome continues'} to the same step${endNote}`
+                    : "the node leaves on its single 'completed' exit"}, and no expression reads `
+                + `out('${step}', 'Action') either. The outcomes reach the reviewer and the artifact; the decision `
+                + `does not reach the flow. ${kept}, so switch on out('${step}', 'Action') to route the decision as data`
+                + (canRoute
+                    ? `, or give each outcome its own route (${ids.map((i) => `'outcome-${i}'`).join(', ')}) with `
+                        + `.stepSwitch${portsOff ? ' or by dropping outcomePorts: false' : ' or outcomePorts: true'}.`
                     : '.'),
-            suggestion: canTakePorts
+            suggestion: portsOff
                 ? 'drop outcomePorts: false'
-                : `.switch('route', out('${step}', 'Action'), …)`,
+                : canRoute
+                    ? `.stepSwitch('${step}', …), or outcomePorts: true`
+                    : `.switch('route', out('${step}', 'Action'), …)`,
         });
     }
 }
@@ -4174,12 +4426,19 @@ function checkHitl(step, inputs, diags) {
     }
     const isApp = variant === 'action-app';
     const isDocval = variant === 'document-validation';
-    // Per-outcome ports and the error output are the BASE node's 1.1/1.2
-    // definitions; no sub-typed variant has a per-outcome version to select.
-    if ((inputs?.outcomePorts === true || inputs?.exposeError === true) && variant !== undefined) {
-        at('HITL_OUTCOME_PORTS_VARIANT', `Human task "${step}" asks for ${inputs?.exposeError ? 'exposeError' : 'outcomePorts'}, but its `
-            + `variant is "${variant}" — per-outcome exits exist only on the base node type's 1.1/1.2 `
-            + `definitions.`, `Omit \`variant\`, or route on out('${step}', 'Action') downstream.`);
+    // The error output is the BASE node's 1.2 definition, which no variant has.
+    // Per-outcome exits are not a version question: quick-form draws one handle
+    // per outcome like the base node, so it may ask for them; the two app-backed
+    // variants read their outcomes from the app and leave on `completed`.
+    if (variant !== undefined
+        && (inputs?.exposeError === true || (inputs?.outcomePorts === true && !hitlDerivesOutcomeHandles(variant)))) {
+        at('HITL_OUTCOME_PORTS_VARIANT', inputs?.exposeError === true
+            ? `Human task "${step}" asks for exposeError, but its variant is "${variant}" — the error output `
+                + `exists only on the base node type's 1.2 definition.`
+            : `Human task "${step}" asks for outcomePorts, but its variant is "${variant}", which reads its `
+                + `outcomes from its app and leaves on its single 'completed' exit.`, inputs?.exposeError === true
+            ? 'Omit `variant`, or drop exposeError.'
+            : `Route on out('${step}', 'Action') downstream.`);
         return;
     }
     if (inputs?.document !== undefined && !isDocval) {