@uipath/maestro-builder-sdk 6.8.3 → 6.8.5

package/dist/decompile.js

@@ -37,6 +37,7 @@ import { inferScriptShape } from './core/script-return.js';
 import { DEFAULT_TRIGGER_ID } from './core/expr.js';
 import { parseIxpProjectType } from './core/actions.js';
 import { readFlowGlobals } from './flow-variables.js';
+import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
 import { eventFilterFromTreeLeaf } from './event-filters.js';
 /**
  * The trigger id of the flow currently being decompiled, so a reference through a
@@ -410,13 +411,43 @@ class Graph {
         const first = outcomes[0]?.id;
         return typeof first === 'string' && first !== '' ? `outcome-${first}` : undefined;
     }
+    /**
+     * A base or quick-form human task whose EVERY outcome is wired, all to ONE
+     * step, with no other exit edge — what `serialize` emits for `.step()` after a
+     * task that does not route per outcome (quick-form's default, a pinned 1.0,
+     * `outcomePorts: false`), and what the designer saves when every outcome
+     * handle is dragged to the same node. It decompiles to a `.step()` with
+     * `outcomePorts: false` (2+ outcomes), which recompiles to the same edges.
+     *
+     * A base task on its 1.1/1.2 definition is left out on purpose: that version
+     * IS its routing (`outcomePorts: true` / `exposeError: true` select it), and
+     * it already round-trips exactly as a `.stepSwitch` with empty arms.
+     */
+    convergedFanOut(id) {
+        const n = this.byId.get(id);
+        if (!n || !OUTCOME_HANDLE_NODE_TYPES.has(String(n.type)) || versionRoutesHitl(n))
+            return false;
+        const ids = outcomeIdsOfNode(n);
+        if (ids.length === 0)
+            return false;
+        const exits = this.outEdges(id).filter((e) => e.sourcePort !== 'error' && !ARTIFACT_PORTS.has(e.sourcePort));
+        if (exits.length !== ids.length)
+            return false;
+        const ports = new Set(exits.map((e) => e.sourcePort));
+        if (!ids.every((i) => ports.has(`outcome-${i}`)))
+            return false;
+        return new Set(exits.map((e) => e.targetNodeId)).size === 1;
+    }
     /**
      * Every declared exit of `id`, when ALL of them are wired — the `.stepSwitch`
      * shape. `undefined` otherwise, which leaves the node with a tacit main path
-     * and its siblings as side arms.
+     * and its siblings as side arms — and for a converged fan-out, whose one
+     * target is the main path.
      */
     fullyWiredExits(id) {
         const node = this.byId.get(id);
+        if (this.convergedFanOut(id))
+            return undefined;
         const declared = node ? declaredExitsOfNode(node) : undefined;
         if (declared === undefined || declared.length < 2)
             return undefined;
@@ -609,7 +640,7 @@ function emitStepSpec(node, imp, inputNames, o, graph) {
         case T.hitlQuickForm:
         case T.hitlActionApp:
         case T.hitlDocValidation:
-            return emitHitl(node, imp, inputNames);
+            return emitHitl(node, imp, inputNames, graph);
         case T.queueCreate:
         case T.queueCreateAndWait: {
             // `itemData` is the node's name for the surface's `item` (the reference
@@ -1320,7 +1351,7 @@ function emitAgentCluster(node, imp, inputNames, graph) {
  * definition's own `inputDefaults.recipient` for delivery. Recovering those
  * would add arguments the author never wrote to every task.
  */
-function emitHitl(node, imp, inputNames) {
+function emitHitl(node, imp, inputNames, graph) {
     const i = (node.inputs ?? {});
     const schema = (i.schema ?? {});
     const plain = (v) => {
@@ -1417,11 +1448,39 @@ function emitHitl(node, imp, inputNames) {
         ['render', render !== undefined && render !== 'standard' ? str(render) : undefined],
         ['taxonomy', stationExpr(i.taxonomy)],
     ]);
-    // Per-outcome exits and the error output are VERSION-selected: 1.1 routes per
-    // outcome, 1.2 adds the error output (and implies the routing).
+    // On the base node the VERSION says it: 1.1 routes per outcome, 1.2 adds the
+    // error output (and implies the routing). Everywhere else — quick-form, a
+    // base task on 1.0 — the EDGES say it: outcomes that lead to different places
+    // are routed per outcome (`outcomePorts: true`, which a pinned 1.0 keeps at
+    // 1.0), and outcomes that all lead to one step are a fan-out, which the
+    // task's default recompiles to.
     const version = String(node.typeVersion ?? '');
     const exposeError = version === '1.2';
-    const outcomePorts = version === '1.1';
+    const outEdges = graph?.outEdges(node.id) ?? [];
+    const derivesHandles = OUTCOME_HANDLE_NODE_TYPES.has(String(node.type));
+    const outcomePorts = (node.type === T.hitl && version === '1.1')
+        || (derivesHandles && !versionRoutesHitl(node) && graph !== undefined && !graph.convergedFanOut(node.id)
+            && outEdges.some((e) => e.sourcePort.startsWith('outcome-')));
+    // A lone `completed` edge on a task with several outcomes is the shape the
+    // designer stopped drawing: before flow-workbench #3512 (09-08) it was
+    // unconditioned, so every outcome continued down it; since then Studio Web and
+    // the converter remap it to the primary outcome only. Recompiling writes one
+    // `outcome-<id>` edge per outcome to the same step — the first meaning — so
+    // this is the one place decompile→compile is deliberately not exact. Say so.
+    const legacyCompleted = derivesHandles && outcomeIdsOfNode(node).length > 1
+        && outEdges.some((e) => e.sourcePort === 'completed');
+    // Both a converged fan-out and a legacy lone `completed` mean "every outcome
+    // continues to the next step". Say so in the source with `outcomePorts: false`
+    // rather than leaving it to the `{ version }` pin, so the intent survives an
+    // author dropping the pin.
+    const fanOut = !outcomePorts && derivesHandles && !versionRoutesHitl(node) && outcomeIdsOfNode(node).length > 1
+        && (legacyCompleted || graph?.convergedFanOut(node.id) === true);
+    if (legacyCompleted) {
+        warnOnce(`human task ${str(node.id)} leaves on the legacy 'completed' handle, which Studio Web no longer draws `
+            + `once a task has outcomes (it reads the edge as the primary outcome only). Recompiling emits one `
+            + `outcome-<id> edge per outcome to the same step, so every outcome continues — what the edge meant `
+            + `before flow-workbench #3512.`);
+    }
     const title = plain(i.title);
     const priority = plain(i.priority);
     return `${imp.use('hitl')}(${opts([
@@ -1438,7 +1497,7 @@ function emitHitl(node, imp, inputNames) {
         ['fields', fields.length ? `[${fields.join(', ')}]`
                 : (variant === 'action-app' || variant === 'document-validation') ? undefined : '[]'],
         ['outcomes', `[${outcomes.join(', ')}]`],
-        ['outcomePorts', outcomePorts ? 'true' : undefined],
+        ['outcomePorts', outcomePorts ? 'true' : fanOut ? 'false' : undefined],
         ['exposeError', exposeError ? 'true' : undefined],
     ])})`;
 }
@@ -2081,7 +2140,9 @@ function region(cursor, stop, scope, ipdom, ctx, refInto) {
         // A per-outcome human task routes each NON-primary outcome from its own
         // `outcome-<slug>` exit; the primary one continues the main path, so it is
         // already a successor (see Graph.primaryOutcomePort).
-        {
+        // A converged fan-out has none: every outcome continues to the one
+        // successor, which is what `.step()` recompiles to.
+        if (!ctx.graph.convergedFanOut(node.id)) {
             const primary = ctx.graph.primaryOutcomePort(node.id);
             for (const oe of ctx.graph.outEdges(node.id)
                 .filter((e) => e.sourcePort.startsWith('outcome-') && e.sourcePort !== primary)) {
@@ -2165,18 +2226,28 @@ function portArmExits(node, ctx) {
         return undefined;
     return declaredExitsOfNode(node);
 }
+/** A base human task on its 1.1/1.2 definition, where the VERSION selects per-outcome routing. */
+function versionRoutesHitl(node) {
+    const version = String(node.typeVersion ?? '');
+    return node.type === T.hitl && (version === '1.1' || version === '1.2');
+}
+/** The outcome ids in a human task's `inputs.schema.outcomes`. */
+function outcomeIdsOfNode(node) {
+    const outcomes = (node.inputs?.schema?.outcomes ?? []);
+    return outcomes.map((o) => o?.id).filter((id) => typeof id === 'string' && id !== '');
+}
 /**
  * The exits a node declares, read back off the EMITTED artifact rather than off
- * an authored spec — `inputs.schema.outcomes` for a human task at 1.1/1.2,
- * `inputs.branches` plus `default` for an HTTP call. The authoring-side twin is
- * `declaredExits` in `core/step-ports.ts`; they answer about different inputs,
- * which is why this is not a call into it.
+ * an authored spec — `inputs.schema.outcomes` for a base or quick-form human
+ * task (the product draws one `outcome-<id>` handle per outcome on both, at
+ * every version), `inputs.branches` plus `default` for an HTTP call. The
+ * authoring-side twin is `declaredExits` in `core/step-ports.ts`; they answer
+ * about different inputs, which is why this is not a call into it.
  */
 function declaredExitsOfNode(node) {
     const inputs = (node.inputs ?? {});
     if (String(node.type).startsWith('uipath.human-in-the-loop')) {
-        const version = String(node.typeVersion ?? '');
-        if (version !== '1.1' && version !== '1.2')
+        if (!OUTCOME_HANDLE_NODE_TYPES.has(String(node.type)))
             return undefined;
         const outcomes = (inputs.schema?.outcomes ?? []);
         if (outcomes.length === 0)

package/dist/registry/generators/markdown/sections/lookups.js

@@ -11,6 +11,7 @@ import { sortedStrings } from "../../../compat/compare.js";
 import { pyStr, splitOnce } from "../../../compat/pystr.js";
 import { classify, referenceOf } from "../../../lookup-specs.js";
 import { byAliases } from "../../../naming.js";
+import { resolveFlagArg } from "../../../../core/cli-spelling.js";
 import { authoringField, referenceCollection, referenceQuery } from "../common.js";
 import { firstValue, IDENT, pyOr, pyTruthy, strList } from "../pyvalue.js";
 /** The `resources run list` call that shows what an identity-lookup field accepts. */
@@ -85,9 +86,21 @@ export function lookupLines(connectorKey, action, fields, symbol, invariant) {
             "different connection. Resolve it late:");
         out.push("");
         out.push("```ts");
-        // A dotted wire name is a legal object key only when quoted.
-        const key = IDENT.test(firstName) ? firstName : pyJsonString(firstName);
-        out.push(`${key}: ${call}${sample}`);
+        // A plain multiselect (`users[*]`) is authored as an array of lookups under
+        // its authoring name, the same form `## Example` prints and the one that
+        // compiles to one id per element. Any other wire name is written as a key —
+        // a dotted one is a legal object key only when quoted — and one ending in
+        // `[*]` (`recipients.listIds[*]`) still names ONE list, so its value is an
+        // array too: the flat key compiles to the same list the nested
+        // `recipients: { listIds: [...] }` of `## Example` does.
+        const [authoringName, , multiselectWire] = authoringField(firstField);
+        if (multiselectWire) {
+            out.push(`${authoringName}: [${call}${sample}]`);
+        }
+        else {
+            const key = IDENT.test(firstName) ? firstName : pyJsonString(firstName);
+            out.push(firstName.endsWith("[*]") ? `${key}: [${call}${sample}]` : `${key}: ${call}${sample}`);
+        }
         out.push("```");
         out.push("");
         out.push("| field | helpers | matches on | sends |");
@@ -116,10 +129,12 @@ export function lookupLines(connectorKey, action, fields, symbol, invariant) {
         // ONE command carrying every --resolve, and no `--connection-id`.
         out.push("```bash");
         out.push(`npx flow-sdk registry prepare ${connectorKey} ${action} \\`);
+        // The WIRE name (`users[*]`), which is what prepare's lookup table is keyed
+        // on — the authoring name (`users`) is refused as RESOLVE_UNKNOWN_FIELD.
         const resolves = resolvable.map(([f, reference]) => {
-            const [name] = authoringField(f);
+            const wire = pyStr(pyOr(f.name, authoringField(f)[0]));
             const names = pyOr(strList(reference.lookupNames), ["id"]);
-            return `  --resolve ${name}:${names[0]}=<value>`;
+            return `  --resolve ${resolveFlagArg(wire, names[0], "<value>")}`;
         });
         for (const line of resolves.slice(0, -1))
             out.push(`${line} \\`);

package/dist/registry/prepare/ledger.d.ts

@@ -55,7 +55,9 @@ export interface ResolutionPlan {
 export declare class ResolutionsExhausted extends LookupExhausted {
     readonly first: LookupExhausted;
     readonly plan: ResolutionPlan;
-    constructor(first: LookupExhausted, plan: ResolutionPlan);
+    constructor(first: LookupExhausted, plan: ResolutionPlan, 
+    /** Every miss of the run, when there was more to say than `first`'s own message. */
+    message?: string);
 }
 /** What one `--resolve` run needs; `objectName` narrows the overlay entry the specs are read from. */
 export interface ResolveRun {

package/dist/registry/prepare/ledger.js

@@ -20,7 +20,7 @@
 import { lookupKey } from "../../core/lookups.js";
 import { pyJsonStringify } from "../codecs/pyjson.js";
 import { sortedStrings } from "../compat/compare.js";
-import { PrepareRefusal, resolutionLine, unknownLookupMessage, wroteResolutionsLine } from "./messages.js";
+import { PrepareRefusal, incompleteRunMessage, notTriedLine, resolutionLine, unknownLookupMessage, wroteResolutionsLine, } from "./messages.js";
 import { LedgerRefusal, RESOLUTIONS_FILENAME, ledgerPath, readLedger, writeLedger } from "./objects.js";
 import { lookupSpecsFromOverlay } from "./overlay.js";
 import { LookupExhausted, orderResolutions, parseResolveFlag, resolveOne } from "./resolve.js";
@@ -87,8 +87,10 @@ export function findResolution(existing, nodeType, field, by, value) {
 export class ResolutionsExhausted extends LookupExhausted {
     first;
     plan;
-    constructor(first, plan) {
-        super(first.message, first);
+    constructor(first, plan, 
+    /** Every miss of the run, when there was more to say than `first`'s own message. */
+    message = first.message) {
+        super(message, first);
         this.first = first;
         this.plan = plan;
         this.name = "ResolutionsExhausted";
@@ -117,13 +119,29 @@ export async function writeResolutions(run, specs) {
     const recorded = pyGet(ledger, "resolutions", null);
     const existing = isPlainObject(recorded) ? { ...recorded } : {};
     const resolved = new Map();
+    // An exhaustive miss no longer ends the run: the rest are still tried, so ONE
+    // run reports every value this connection does not hold — a multiselect of
+    // three names used to cost three runs to learn about three misses. A lookup
+    // addressed through a field that missed is skipped, since its path cannot be
+    // built. The WRITE stays all-or-nothing; see the throw below.
+    const misses = [];
+    const unresolved = new Set();
+    const notTried = [];
+    const answered = [];
     for (const [field, by, value] of ordered) {
+        const blockedBy = (table.get(field)?.dependsOn ?? []).find((prerequisite) => unresolved.has(prerequisite));
+        if (blockedBy !== undefined) {
+            unresolved.add(field);
+            notTried.push(notTriedLine(field, by, value, blockedBy));
+            continue;
+        }
         const key = resolutionKey(run.nodeType, field, by, value);
         const found = findResolution(existing, run.nodeType, field, by, value);
         if (found && !run.refreshLookups) {
             const kept = pyStrAny(pyGet(found.row, "value", null));
             resolved.set(field, kept);
             run.reporter.info(resolutionLine(field, by, value, kept, true));
+            answered.push(resolutionLine(field, by, value, kept, true));
             continue;
         }
         let got;
@@ -152,8 +170,25 @@ export async function writeResolutions(run, specs) {
             // refusal, whose text already names the remedy ("the value may be
             // further in"). Upstream's own tests never covered the row, which is
             // how it shipped unimplemented.
-            if (error instanceof LookupExhausted && !error.capped)
-                throw new ResolutionsExhausted(error, { specs: table, ordered });
+            //
+            // Only that exhaustive miss is collected; every other refusal — capped,
+            // transport, unsearchable `by` — still ends the run at once, as before,
+            // so none of them can reach the cross-connection retry.
+            if (error instanceof LookupExhausted && !error.capped) {
+                misses.push(error);
+                unresolved.add(field);
+                continue;
+            }
+            // An exhaustive miss collected EARLIER still decides the run: it is
+            // evidence against this connection, and before the misses were collected
+            // it would have ended the run and started the cross-connection retry
+            // before this lookup was ever tried. So that retry still runs, and its
+            // refusal names the collected misses and then this error.
+            if (misses.length > 0) {
+                const text = error instanceof Error ? error.message : String(error);
+                const lines = [...misses.map((miss) => miss.message), ...notTried, text.startsWith(`${field}:`) ? text : `${field}: ${text}`];
+                throw new ResolutionsExhausted(misses[0], { specs: table, ordered }, incompleteRunMessage(lines, [], answered, ordered.length));
+            }
             throw error;
         }
         resolved.set(field, got);
@@ -163,6 +198,21 @@ export async function writeResolutions(run, specs) {
             delete existing[found.key];
         existing[key] = { nodeType: run.nodeType, field, by, match: value, value: got };
         run.reporter.info(resolutionLine(field, by, value, got));
+        answered.push(resolutionLine(field, by, value, got));
+    }
+    // ALL-OR-NOTHING, deliberately, even though the rows that DID resolve are
+    // correct for this connection. A ledger row carries no connection: it is
+    // keyed `[nodeType, field, by, value]`, and a later run REUSES a recorded row
+    // without asking again unless `--refresh-lookups` is passed (above). So a
+    // partial write from connection A would hand A's workspace ids to the next
+    // run bound to connection B — the 2026-09-23 run resolved one recipient on
+    // one Slack workspace and then re-pinned to another. Until rows are keyed by
+    // connection, a run that misses records nothing and says what it found.
+    if (misses.length > 0) {
+        const message = misses.length === 1 && notTried.length === 0 && answered.length === 0
+            ? misses[0].message
+            : incompleteRunMessage(misses.map((miss) => miss.message), notTried, answered, ordered.length);
+        throw new ResolutionsExhausted(misses[0], { specs: table, ordered }, message);
     }
     const written = { ...ledger, schemaVersion: "1", resolutions: existing };
     writeLedger(path, written);

package/dist/registry/prepare/messages.d.ts

@@ -111,6 +111,14 @@ export declare function lookupVocabularyLines(connectorKey: string, action: stri
 export declare function unknownLookupMessage(unknown: readonly string[], nodeType: string, known: readonly string[]): string;
 /** `  <field>: <by>=<value> -> <id>`, with ` (already resolved)` when the ledger answered. */
 export declare function resolutionLine(field: string, by: string, value: string, got: unknown, alreadyResolved?: boolean): string;
+/** A lookup skipped because the field its collection path is built from did not resolve. */
+export declare function notTriedLine(field: string, by: string, value: string, prerequisite: string): string;
+/**
+ * Every miss of one `--resolve` run, then what DID resolve. Nothing is recorded
+ * when anything misses, and the reader needs both halves to fix every value in
+ * one pass rather than one per run.
+ */
+export declare function incompleteRunMessage(misses: readonly string[], notTried: readonly string[], answered: readonly string[], requested: number): string;
 export declare function wroteResolutionsLine(count: number, ledgerPath: string): string;
 /**
  * `generated N connector module(s) → <out>` — the descriptor generator's own

package/dist/registry/prepare/messages.js

@@ -262,6 +262,23 @@ export function unknownLookupMessage(unknown, nodeType, known) {
 export function resolutionLine(field, by, value, got, alreadyResolved = false) {
     return `  ${field}: ${by}=${value} -> ${pyStrAny(got)}${alreadyResolved ? " (already resolved)" : ""}`;
 }
+/** A lookup skipped because the field its collection path is built from did not resolve. */
+export function notTriedLine(field, by, value, prerequisite) {
+    return `${field}: ${by}=${pyRepr(value)} not tried — its collection is addressed through ${pyRepr(prerequisite)}, which did not resolve.`;
+}
+/**
+ * Every miss of one `--resolve` run, then what DID resolve. Nothing is recorded
+ * when anything misses, and the reader needs both halves to fix every value in
+ * one pass rather than one per run.
+ */
+export function incompleteRunMessage(misses, notTried, answered, requested) {
+    const failed = misses.length + notTried.length;
+    return (`${failed} of ${requested} lookup(s) did not resolve, so nothing was recorded:\n` +
+        [...misses, ...notTried].map((line) => `  ${line}`).join("\n") +
+        (answered.length > 0
+            ? `\nThese resolved, and are recorded only once every lookup of the run does:\n${answered.join("\n")}`
+            : ""));
+}
 export function wroteResolutionsLine(count, ledgerPath) {
     return `  wrote ${count} resolution(s) to ${ledgerPath}`;
 }

package/dist/registry/prepare/pipeline.js

@@ -163,7 +163,10 @@ export async function prepareConnector(options, ports) {
             connectionId: connected.connectionId,
             connection: options.connection,
             pinned,
-        }, error.plan, error.first);
+        }, error.plan, 
+        // The wrapper, not `error.first`: same facts, and its message names every
+        // miss of the run rather than only the first.
+        error);
         // Undo the bindings this run wrote for the connection that cannot serve
         // the lookups, then start over pinned to the one that can. Re-running
         // rather than switching in place is deliberate: the overlay and its

package/dist/registry/prepare/resolve.d.ts

@@ -36,7 +36,21 @@ export interface LookupExhaustedFacts {
     pages: number;
     /** True when a cap, not the collection's end, stopped the scan. */
     capped: boolean;
+    /**
+     * Every distinct value the scan saw at `by`, when the whole collection was
+     * read and holds at most {@link CANDIDATE_LIMIT} records — what to pick from.
+     */
+    candidates?: readonly string[];
+    /** A value the scan saw that equals the wanted one ignoring case; the match itself is exact. */
+    near?: string;
 }
+/**
+ * A collection this small is listed in full when a value is not in it. The
+ * 2026-09-23 run guessed `send_as` 'Bot token' from the field's description
+ * while `available_tokens` held two records, 'Bot' and 'User', and the refusal
+ * said only "scanned 2 record(s)".
+ */
+export declare const CANDIDATE_LIMIT = 20;
 /**
  * The collection was read to the end on THIS connection and had no match
  * (`_resolve.LookupExhausted`).
@@ -63,6 +77,8 @@ export declare class LookupExhausted extends ResolutionRefusal {
     readonly scanned: number;
     readonly pages: number;
     readonly capped: boolean;
+    readonly candidates?: readonly string[];
+    readonly near?: string;
     constructor(message: string, facts: LookupExhaustedFacts);
 }
 /** One `--resolve <field>:<by>=<value>`, parsed. */
@@ -97,8 +113,17 @@ type SpecTable = ReadonlyMap<string, ResolveSpec> | Readonly<Record<string, Reso
  * unsubstituted `{placeholder}` in a URL, and the error the connector returns
  * for that names neither field.
  *
- * A field requested twice keeps its first position and its LAST `by`/`value`,
- * as the Python's dict did.
+ * A field requested more than once keeps its first position and EVERY distinct
+ * `by`/`value`, in the order given; an exact repeat collapses. DELIBERATE
+ * DIVERGENCE FROM THE PYTHON, whose dict kept one request per field — its LAST
+ * `by`/`value` — and dropped the rest without a word. That is fatal for a
+ * multiselect: `--resolve users[*]:…=A --resolve users[*]:…=B --resolve
+ * users[*]:…=C`, one command as the library page prints it, resolved and
+ * recorded only C (2026-09-23, skill-flow-ipe-multiselect), and the probe of
+ * the other connections asked only about C too.
+ *
+ * A PREREQUISITE given more than one value is refused: its id is substituted
+ * into the dependent's collection path, and one placeholder takes one id.
  */
 export declare function orderResolutions(requested: readonly ResolveRequest[], specs: SpecTable): ResolveRequest[];
 /**

package/dist/registry/prepare/resolve.js

@@ -50,6 +50,13 @@ export class ResolutionRefusal extends Refusal {
         this.name = "ResolutionRefusal";
     }
 }
+/**
+ * A collection this small is listed in full when a value is not in it. The
+ * 2026-09-23 run guessed `send_as` 'Bot token' from the field's description
+ * while `available_tokens` held two records, 'Bot' and 'User', and the refusal
+ * said only "scanned 2 record(s)".
+ */
+export const CANDIDATE_LIMIT = 20;
 /**
  * The collection was read to the end on THIS connection and had no match
  * (`_resolve.LookupExhausted`).
@@ -76,6 +83,8 @@ export class LookupExhausted extends ResolutionRefusal {
     scanned;
     pages;
     capped;
+    candidates;
+    near;
     constructor(message, facts) {
         super(message, "RESOLVE_NO_MATCH");
         this.name = "LookupExhausted";
@@ -86,6 +95,10 @@ export class LookupExhausted extends ResolutionRefusal {
         this.scanned = facts.scanned;
         this.pages = facts.pages;
         this.capped = facts.capped;
+        if (facts.candidates !== undefined)
+            this.candidates = facts.candidates;
+        if (facts.near !== undefined)
+            this.near = facts.near;
     }
 }
 /**
@@ -123,13 +136,27 @@ function specOf(specs, field) {
  * unsubstituted `{placeholder}` in a URL, and the error the connector returns
  * for that names neither field.
  *
- * A field requested twice keeps its first position and its LAST `by`/`value`,
- * as the Python's dict did.
+ * A field requested more than once keeps its first position and EVERY distinct
+ * `by`/`value`, in the order given; an exact repeat collapses. DELIBERATE
+ * DIVERGENCE FROM THE PYTHON, whose dict kept one request per field — its LAST
+ * `by`/`value` — and dropped the rest without a word. That is fatal for a
+ * multiselect: `--resolve users[*]:…=A --resolve users[*]:…=B --resolve
+ * users[*]:…=C`, one command as the library page prints it, resolved and
+ * recorded only C (2026-09-23, skill-flow-ipe-multiselect), and the probe of
+ * the other connections asked only about C too.
+ *
+ * A PREREQUISITE given more than one value is refused: its id is substituted
+ * into the dependent's collection path, and one placeholder takes one id.
  */
 export function orderResolutions(requested, specs) {
     const byField = new Map();
-    for (const request of requested)
-        byField.set(request[0], request);
+    for (const request of requested) {
+        const same = byField.get(request[0]);
+        if (same === undefined)
+            byField.set(request[0], [request]);
+        else if (!same.some(([, by, value]) => by === request[1] && value === request[2]))
+            same.push(request);
+    }
     const ordered = [];
     const placed = new Set();
     const place = (field, trail) => {
@@ -141,7 +168,14 @@ export function orderResolutions(requested, specs) {
         }
         const dependsOn = specOf(specs, field)?.dependsOn;
         for (const prerequisite of Array.isArray(dependsOn) ? dependsOn : []) {
-            if (byField.has(prerequisite)) {
+            const given = byField.get(prerequisite);
+            if (given !== undefined && given.length > 1) {
+                throw new ResolutionRefusal(`cannot resolve ${pyRepr(field)}: its collection is addressed through ` +
+                    `${pyRepr(prerequisite)}, which was given ${given.length} values ` +
+                    `(${given.map(([, by, value]) => `${by}=${pyRepr(value)}`).join(", ")}). ` +
+                    `The path takes one id; keep one --resolve ${prerequisite}:<by>=<value> and re-run.`, "RESOLVE_AMBIGUOUS_PREREQUISITE");
+            }
+            if (given !== undefined) {
                 place(prerequisite, [...trail, field]);
             }
             else {
@@ -151,7 +185,7 @@ export function orderResolutions(requested, specs) {
             }
         }
         placed.add(field);
-        ordered.push(byField.get(field));
+        ordered.push(...byField.get(field));
     };
     for (const [field] of requested)
         place(field, []);
@@ -433,9 +467,21 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
         query = query ? `${query}&${filtered}` : filtered;
     }
     const scan = scanCollection(client, connectorKey, collection, connectionId, query);
+    // What the collection DOES hold at `by`, for the refusal: kept only while it
+    // could still be listed in full, plus the first case-insensitive equal.
+    const held = [];
+    let near;
     let step = await scan.next();
     while (!step.done) {
         for (const record of step.value) {
+            const at = readPath(record, by);
+            if (at !== null && at !== undefined) {
+                const text = pyStrAny(at);
+                if (held.length <= CANDIDATE_LIMIT && !held.includes(text))
+                    held.push(text);
+                if (near === undefined && text !== value && text.toLowerCase() === value.toLowerCase())
+                    near = text;
+            }
             if (matchRecord(record, by, value)) {
                 const got = readPath(record, send);
                 if (got === null) {
@@ -463,8 +509,24 @@ export async function resolveOne(client, connectorKey, spec, field, by, value, c
     // The listing command is still offered, once, by the caller's terminal
     // report — where every connection has been tried and seeing what IS there
     // is finally the next step rather than a detour.
+    //
+    // What it DOES carry is what the collection holds, when that is small enough
+    // to read in one line, and a case-only near miss: facts about this
+    // connection, not a remedy. `matchRecord` stays exact — nothing is picked.
+    //
+    // Never under a server-side filter: the scan then read only the records the
+    // filter returned (`name like '%Coder Eval%'` gives 'Coder Evals' and 'Coder
+    // Eval Test'), and listing that subset as what the collection "holds" would
+    // be false. 693 library operations declare a `filterPattern`.
+    const candidates = !capped && !pyTruthy(filterPattern) && scanned <= CANDIDATE_LIMIT && held.length > 0 ? held : undefined;
     throw new LookupExhausted(`${field}: no record in ${pyRepr(collection)} has ${by}=${pyRepr(value)} ` +
         `(scanned ${scanned} record(s) across ${pages + 1} page(s)` +
         (capped ? `; STOPPED AT THE ${MAX_SCANNED}-record cap, so the value may be further in` : "; collection exhausted") +
-        `) on connection ${connectionId}.`, { field, collection, by, value, scanned, pages: pages + 1, capped });
+        `) on connection ${connectionId}.` +
+        (near !== undefined ? ` Did you mean ${pyRepr(near)}? The match is exact, case included.` : "") +
+        (candidates !== undefined ? ` It holds: ${candidates.map(pyRepr).join(", ")}.` : ""), {
+        field, collection, by, value, scanned, pages: pages + 1, capped,
+        ...(candidates !== undefined ? { candidates } : {}),
+        ...(near !== undefined ? { near } : {}),
+    });
 }