@salesforce/afv-skills 1.47.0 → 1.49.0

package/skills/service-omni-queue-members-assign/references/api-notes.md

@@ -0,0 +1,144 @@
+# API notes — GroupMember binding for Omni Queue
+
+## `GroupMember` sObject shape (v66)
+
+The `GroupMember` sObject represents a user's (or nested group's) membership in a Salesforce `Group`. On Salesforce, a **Queue is a specialized `Group`** — same underlying table, distinguished by `Group.Type='Queue'` vs. `Type='Regular'` (public groups). Every membership row lives in `GroupMember`.
+
+Fields we care about:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `Id` | 18-char Id | The membership row's Id, used for teardown |
+| `GroupId` | Reference (`Group.Id`) | The queue/public-group this membership belongs to |
+| `UserOrGroupId` | Polymorphic reference (`User.Id` or `Group.Id`) | The member being bound. For agent-to-queue bindings this is always a `User.Id` |
+| `SystemModstamp` | Datetime | Server-side write timestamp; useful in idempotency checks |
+
+**We never set:**
+- `CreatedById`, `CreatedDate`, `LastModifiedById`, `LastModifiedDate` — Salesforce writes these on insert; supplying them is a compile-time error on the Data API.
+
+## Why we query, not upsert
+
+`GroupMember` has no external ID field and no natural composite key exposed as an upsert target. The Data API's `PATCH /sobjects/GroupMember/<externalId__c>/<value>` pattern is unavailable. The only insert paths are:
+
+- **POST** with `{GroupId, UserOrGroupId}` — creates a new row. Duplicate `(GroupId, UserOrGroupId)` tuples raise `DUPLICATE_VALUE`.
+- **Metadata API `Queue` deploy with `<queueMembers>` block** — replaces membership atomically (dangerous — will remove out-of-band members).
+
+For a skill that must be idempotent AND non-destructive, the pattern is:
+
+1. SOQL for existing memberships → set of `existing_user_ids`
+2. Compute `missing_user_ids = expected − existing_user_ids`
+3. POST one row per missing user (individually — no batching, no rollback semantics needed at this scale)
+4. Re-query to confirm.
+
+This is why the skill is called `verify-and-bind.sh`, not `upsert-and-report.sh` — no upsert primitive exists.
+
+## SOQL patterns used
+
+**Locate the queue:**
+
+```sql
+SELECT Id
+FROM Group
+WHERE DeveloperName = 'CaseQueue' AND Type = 'Queue'
+```text
+
+- `Type='Queue'` matters — a public group and a queue can share the same DeveloperName (rare, but possible on orgs with hand-crafted metadata).
+- We use `DeveloperName`, not `Name` — Name is the localized label and can drift; DeveloperName is the stable API identifier.
+
+**Locate the agent users:**
+
+```sql
+SELECT Id, Username
+FROM User
+WHERE Username IN ('agent1.0abc123a@example.com', 'agent2.0abc123a@example.com', 'agent3.0abc123a@example.com')
+```
+
+- We use `Username` (globally unique), not `Email` (not unique) or `Alias` (not unique).
+- No `IsActive` filter — inactive users can still be queue members (they just don't receive new work); we want to bind them regardless.
+
+**Locate existing memberships:**
+
+```sql
+SELECT Id, UserOrGroupId
+FROM GroupMember
+WHERE GroupId = '00GRZ000004esvR2AQ'
+  AND UserOrGroupId IN ('005RZ0000005xyzAAA', '005RZ0000005abcBBB', '005RZ0000005defCCC')
+```text
+
+- Scope the query to the specific queue + specific users, not all queue members — avoids returning hundreds of unrelated rows on production-like orgs.
+- The polymorphic `UserOrGroupId` filter works for User Ids; the query returns only User-typed members.
+
+## POST payload
+
+```
+POST /services/data/v66.0/sobjects/GroupMember
+{
+  "GroupId": "00GRZ000004esvR2AQ",
+  "UserOrGroupId": "005RZ0000005abcBBB"
+}
+```text
+
+- Success: HTTP 201 with `{"id":"011RZ00000ABCDE0AB","success":true,"errors":[]}`.
+- **Duplicate write:** Salesforce server-side dedupes `GroupMember` on the (`GroupId`, `UserOrGroupId`) uniqueness constraint at the persistence layer. A duplicate POST returns HTTP 201 with `success:true` and the **existing row's Id** — no `DUPLICATE_VALUE` error is raised, and no new row is created. Successive POSTs of the same tuple produce exactly one GroupMember row.
+  - Implication: the skill's detect step (querying existing memberships) is the primary mechanism preventing inflated `bound_count` on re-runs. Without detect, every re-run would report all N users as newly "bound" even though no new rows were created.
+  - The `DUPLICATE_VALUE` branch in the skill's script is retained for future-proofing (in case Salesforce changes this behavior in a future API version) but is not currently reachable.
+
+## `sf api request rest` output channel
+
+The `sf api request rest` CLI command emits a `Warning: This command is currently in beta. Any aspect of this command can change without advanced notice. Don't use beta commands in your scripts.` line to **stderr** on every invocation. The JSON response body goes to **stdout**.
+
+**Do NOT** capture with `2>&1` when the output is going to be parsed by `jq`, because the Warning line becomes the first line of the merged stream and every subsequent `jq '.field'` call silently fails (jq returns exit-1 for non-JSON input, which gets swallowed by `|| echo "false"` fallbacks).
+
+**Correct pattern:**
+```bash
+POST_STDERR=$(mktemp)
+POST_RESULT=$(sf api request rest ... 2>"$POST_STDERR" || true)
+POST_SUCCESS=$(echo "$POST_RESULT" | jq -r '.success // false')
+# On failure, read $POST_STDERR (excluding Warning: lines) for the real error
+rm -f "$POST_STDERR"
+```
+
+**Also acceptable:** `2>/dev/null` if you don't need to surface CLI-level errors (auth failures, network drops). But redirecting to a temp file preserves that visibility.
+
+## Common failure modes and how the skill translates them
+
+| Salesforce error | Skill translation | Actionable? |
+|---|---|---|
+| ~~`DUPLICATE_VALUE` on POST~~ | ~~Treat as reused~~ | **Not reachable** — GroupMember dedupes at the persistence layer (see above) |
+| Non-JSON stdout (Warning line) | Skill bug — script merged stderr into stdout | Yes — use the temp-file pattern |
+| `MALFORMED_ID` | Skill bug — user Id or group Id malformed before POST | Yes — file an issue against the skill |
+| `INSUFFICIENT_ACCESS_OR_READONLY` on POST | Executing user lacks `ModifyAllData` or queue-write perm | Yes — re-authenticate as a System Administrator |
+| `INVALID_TYPE` on GroupMember SOQL | Never seen — GroupMember is universally available | If it happens, the org is corrupt; escalate |
+| `INVALID_FIELD` on `GroupMember.CreatedDate` | `GroupMember` does not expose `CreatedDate` in SOQL (nor `CreatedById`, `LastModifiedDate`, `SystemModstamp` — they exist internally but are not queryable). Non-blocking for this skill. | Query only `Id`, `GroupId`, `UserOrGroupId` — the reliably queryable columns |
+| Empty `User` query result (any expected username missing) | The agent users were not created, or were created with a different `count`/suffix | Yes — re-run `service-omni-agent-users-create` with the same count |
+| `Group` DeveloperName not found | The queue is missing (or was renamed) | Yes — re-run `service-omni-queue-deploy`, or create the queue manually per its click-path |
+
+## Why individual POSTs, not composite tree
+
+Salesforce supports `POST /composite/tree/GroupMember` for batching up to 200 inserts atomically. We deliberately avoid it here because:
+
+- **Blast radius.** A single bad user Id rolls back all inserts in a tree request. Individual POSTs isolate failures — one duplicate doesn't sink the batch.
+- **Report clarity.** Individual POST responses give us per-user status directly; parsing composite-tree responses adds ~40 lines of jq without any latency win at N ≤ 10.
+- **Idempotency reasoning.** With individual POSTs, the loop `for missing_user in missing_users: POST; on-duplicate: skip` is transparent. A tree request would need pre-filtering by re-querying inside the batch, adding a race window.
+
+For skills that need to bind hundreds of users (a v1.1 concern — supervisor tools), we'd revisit this and use `/composite/tree` with client-side duplicate stripping.
+
+## Teardown hook (not implemented in v1)
+
+A future `service-omni-queue-members-assign-remove` skill would:
+
+1. Query `GroupMember` where `GroupId=<queue-id>` AND `UserOrGroupId IN <agent-user-ids>` → collect Ids to delete.
+2. DELETE `/sobjects/GroupMember/<id>` one at a time.
+3. Re-verify final member count.
+
+Not part of the v1 coordinator's forward path — teardown is out of scope for the routing-setup coordinator; a separate `teardown-coordinate` skill will handle it holistically.
+
+## Why not Apex?
+
+Compared to `service-omni-agent-users-create`, this skill does not use Anonymous Apex because:
+
+- **No transactional invariant.** User creation needs `insert User + System.setPassword` in one transaction — if setPassword fails, we want the User rolled back. GroupMember has no such coupling.
+- **No policy enforcement.** User creation triggers profile-validation, license-consumption, and password-policy Apex-side checks that are cleaner to observe in a debug log. GroupMember insert is a simple two-field row.
+- **Simpler operator debugging.** REST POSTs return structured JSON; Apex debug log parsing requires anchored regexes.
+
+The tradeoff: an Apex approach could bulk-insert all N rows in one transaction (~1 API round-trip instead of N). At N ≤ 10 the difference is a second or two — not worth the debugging complexity.

package/skills/service-omni-queue-members-assign/scripts/tests/_bootstrap.py

@@ -0,0 +1,67 @@
+"""Shared paths + fake-`sf` harness for the queue-members-assign contract suite.
+
+Drives ``verify-and-bind.sh`` via ``subprocess`` and asserts on exit codes + emitted JSON.
+Org-free and network-free. ``jq`` comes from the real PATH.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]
+SKILL_DIR = "service-omni-queue-members-assign"
+SCRIPT = f"{SKILL_DIR}/scripts/verify-and-bind.sh"
+
+# org display succeeds, but the Organization safe_to_write query FAILS (non-zero, stderr-only).
+# Reproduces an auth/network/API failure: the script must emit structured blocked JSON on stdout
+# instead of a silent `set -e` exit.
+_FAKE_SF_ORG_QUERY_FAILS = r"""#!/usr/bin/env bash
+sub="${1:-} ${2:-}"; args="$*"
+case "$sub" in
+  "org display") echo '{"status":0,"result":{"id":"00Dxx0000000000EAA"}}'; exit 0;;
+  "data query")
+    if printf '%s' "$args" | grep -q "FROM Organization"; then
+      echo "ERROR running data query: INVALID_SESSION_ID" >&2
+      exit 1
+    fi
+    echo '{"status":0,"result":{"records":[],"totalSize":0}}'; exit 0;;
+  *) echo '{"status":0,"result":{}}'; exit 0;;
+esac
+"""
+
+
+def run(args, path_prefix=None, scrub_sf=False, extra_env=None):
+    env = dict(os.environ)
+    if scrub_sf:
+        kept = [d for d in env.get("PATH", "").split(os.pathsep)
+                if d and not os.path.exists(os.path.join(d, "sf"))]
+        env["PATH"] = os.pathsep.join(kept)
+    if path_prefix:
+        env["PATH"] = path_prefix + os.pathsep + env.get("PATH", "")
+    if extra_env:
+        env.update({k: str(v) for k, v in extra_env.items()})
+    proc = subprocess.run(
+        ["bash", str(SKILLS_ROOT / SCRIPT), *args],
+        capture_output=True, text=True, env=env, cwd=str(SKILLS_ROOT),
+    )
+    return proc.returncode, (proc.stdout or "") + (proc.stderr or "")
+
+
+class FakeSf:
+    def __init__(self, body=_FAKE_SF_ORG_QUERY_FAILS):
+        self._body = body
+        self._tmp = None
+
+    def __enter__(self):
+        self._tmp = tempfile.mkdtemp(prefix="qm-fake-sf-")
+        sf = Path(self._tmp) / "sf"
+        sf.write_text(self._body)
+        sf.chmod(0o755)
+        return self._tmp
+
+    def __exit__(self, *exc):
+        import shutil
+        if self._tmp:
+            shutil.rmtree(self._tmp, ignore_errors=True)

package/skills/service-omni-queue-members-assign/scripts/tests/test_queue_members_contracts.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Contract tests for service-omni-queue-members-assign/scripts/verify-and-bind.sh."""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _bootstrap import (  # noqa: E402
+    SCRIPT,
+    SKILLS_ROOT,
+    FakeSf,
+    _FAKE_SF_ORG_QUERY_FAILS,
+    run,
+)
+
+
+def _last_json(out: str) -> dict:
+    dec = json.JSONDecoder()
+    obj, i, n = None, 0, len(out)
+    while i < n:
+        if out[i] in "{[":
+            try:
+                cand, end = dec.raw_decode(out, i)
+                if isinstance(cand, dict):
+                    obj = cand
+                i = end
+                continue
+            except json.JSONDecodeError:
+                pass
+        i += 1
+    assert obj is not None, f"no JSON object found in output:\n{out}"
+    return obj
+
+
+class SyntaxTests(unittest.TestCase):
+    def test_bash_syntax_valid(self):
+        proc = subprocess.run(["bash", "-n", str(SKILLS_ROOT / SCRIPT)],
+                              capture_output=True, text=True)
+        self.assertEqual(proc.returncode, 0, proc.stderr)
+
+
+class InputContractTests(unittest.TestCase):
+    def test_missing_args_rejected(self):
+        rc, out = run([], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Usage", out)
+
+    def test_injection_shaped_queue_name_rejected(self):
+        rc, out = run(["org", "Bad Name; DROP"], scrub_sf=True)
+        self.assertEqual(rc, 1, out)
+        self.assertIn("Invalid queue_developer_name", out)
+
+
+class OrgQueryFailClosedTests(unittest.TestCase):
+    def test_org_query_failure_emits_blocked_json_on_stdout(self):
+        # Regression (blocker 2): a failing Organization safe_to_write query used to make the command
+        # substitution non-zero and `set -e` killed the script before any JSON. It must now fail closed
+        # with a structured blocked result on stdout.
+        with FakeSf(_FAKE_SF_ORG_QUERY_FAILS) as p:
+            rc, out = run(["sandbox", "CaseQueue"], path_prefix=p)
+        self.assertEqual(rc, 1, out)
+        self.assertTrue(out.strip(), "expected structured JSON, got empty output")
+        v = _last_json(out)
+        self.assertEqual(v["status"], "blocked", out)
+        self.assertIn("Organization", v["blocking_issue"], out)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/service-omni-queue-members-assign/scripts/verify-and-bind.sh

@@ -0,0 +1,362 @@
+#!/usr/bin/env bash
+# verify-and-bind.sh - bind agent users into a Queue via GroupMember POSTs (explicit usernames/IDs or the generated demo pattern); idempotent, non-destructive (never removes members). Args, output contract, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo '{"error":"Usage: bash verify-and-bind.sh <org-alias> [<queue-developer-name>] [<count>] [<explicit-members-csv>]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+QUEUE_DN="${2:-CaseQueue}"
+COUNT="${3:-3}"
+API_VERSION="v66.0"
+USERNAME_PREFIX="agent"
+USERNAME_DOMAIN="example.com"
+
+# Explicit real-agent members: 4th positional, or env (IDs take precedence over usernames).
+EXPLICIT_MEMBERS_CSV="${4:-${MEMBER_USER_IDS_CSV:-${MEMBER_USERNAMES_CSV:-}}}"
+EXPLICIT_MODE="false"
+if [ -n "$EXPLICIT_MEMBERS_CSV" ]; then
+  EXPLICIT_MODE="true"
+  # Derive COUNT from the explicit list length (trim blanks) - it overrides the positional count.
+  COUNT=$(printf '%s' "$EXPLICIT_MEMBERS_CSV" | tr ',' '\n' | sed 's/^ *//;s/ *$//' | grep -c . || true)
+fi
+
+# Sanity: count must be integer 1..10
+if ! [[ "$COUNT" =~ ^[0-9]+$ ]] || [ "$COUNT" -lt 1 ] || [ "$COUNT" -gt 10 ]; then
+  echo "{\"error\":\"Invalid count '$COUNT' - must be integer 1..10${EXPLICIT_MODE:+ (derived from explicit-members-csv)}\"}" >&2
+  exit 1
+fi
+
+# QUEUE_DN is interpolated into SOQL, so validate its DeveloperName shape before any sf call.
+if ! [[ "$QUEUE_DN" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
+  echo "{\"error\":\"Invalid queue_developer_name '$QUEUE_DN'. Must start with a letter and contain only letters, digits, and underscores (max 80 chars).\"}" >&2
+  exit 1
+fi
+
+if ! sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
+  echo "{\"error\":\"Org alias '$ORG' is not authenticated. Run: sf org login web -a $ORG -r <my-domain-url>\"}" >&2
+  exit 1
+fi
+
+# Helper: emit blocked JSON and exit 1
+emit_blocked() {
+  local msg="$1"
+  local click_path="${2:-}"
+  local queue_id="${3:-null}"
+  local suffix="${4:-}"
+
+  local manual_actions='[]'
+  if [ -n "$click_path" ]; then
+    manual_actions=$(jq -n --arg cp "$click_path" '[{id: "MANUAL_FIX", title: "Manual fix required", click_path: $cp}]')
+  fi
+
+  jq -n \
+    --arg msg "$msg" \
+    --arg dn "$QUEUE_DN" \
+    --arg qid "$queue_id" \
+    --arg suf "$suffix" \
+    --argjson count "$COUNT" \
+    --argjson ma "$manual_actions" \
+    '{
+      skill: "service-omni-queue-members-assign",
+      status: "blocked",
+      queue: {
+        developer_name: $dn,
+        id: (if $qid == "null" then null else $qid end)
+      },
+      org_suffix: (if $suf == "" then null else $suf end),
+      requested_count: $count,
+      before: null,
+      bound_this_run: [],
+      bound_count: 0,
+      reused_count: 0,
+      after: null,
+      manual_actions: $ma,
+      blocking_issue: $msg
+    }'
+  exit 1
+}
+
+# Helper: emit read-only plan preview JSON and exit 0 (PLAN_ONLY mode)
+emit_plan() {
+  local status="$1"
+  local detail="$2"
+  jq -n \
+    --arg status "$status" \
+    --arg detail "$detail" \
+    --arg dn "$QUEUE_DN" \
+    '{
+      skill: "service-omni-queue-members-assign",
+      status: $status,
+      plan_mode: true,
+      plan_detail: $detail,
+      queue: {developer_name: $dn},
+      manual_actions: [],
+      blocking_issue: null
+    }'
+  exit 0
+}
+
+# Step 1 - Organization + safe_to_write
+# Fail-closed with structured JSON: without the `|| emit_blocked`, an auth/network/API failure makes
+# the command substitution non-zero and `set -e` would kill the script before any blocked JSON is
+# emitted. The jq -e guard covers a zero-exit-but-empty/unparseable response for the same reason.
+ORG_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id, IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" \
+  --json 2>/dev/null) \
+  || emit_blocked "Could not query the Organization object (authentication, network, or API access failed). Re-run with a valid, reachable org connection." "" "null" ""
+echo "$ORG_JSON" | jq -e '.result.records[0].Id' >/dev/null 2>&1 \
+  || emit_blocked "Organization query returned no parseable record (inconclusive). Refusing to proceed without confirming the org is safe to write." "" "null" ""
+
+ORG_ID=$(echo "$ORG_JSON"    | jq -r '.result.records[0].Id')
+IS_SANDBOX=$(echo "$ORG_JSON" | jq -r '.result.records[0].IsSandbox')
+TRIAL_EXP=$(echo "$ORG_JSON"  | jq -r '.result.records[0].TrialExpirationDate // "null"')
+ORG_TYPE=$(echo "$ORG_JSON"   | jq -r '.result.records[0].OrganizationType')
+
+SAFE_TO_WRITE=false
+if [ "$IS_SANDBOX" = "true" ]; then
+  SAFE_TO_WRITE=true
+elif [ "$TRIAL_EXP" != "null" ]; then
+  SAFE_TO_WRITE=true
+elif [ "$ORG_TYPE" = "Developer Edition" ] || [ "$ORG_TYPE" = "Base Edition" ]; then
+  SAFE_TO_WRITE=true
+fi
+
+# Canonical org suffix: chars 10-17 of the 18-char Org Id, lowercased. Uses the SAME expression as the
+# user-create leaves' detect-existing.sh so the generated agent/supervisor usernames match exactly.
+SUFFIX=$(echo -n "${ORG_ID:10:8}" | tr '[:upper:]' '[:lower:]')
+
+if [ "$SAFE_TO_WRITE" != "true" ]; then
+  emit_blocked "Refusing to bind queue members on a real production customer org (IsSandbox=$IS_SANDBOX, TrialExpirationDate=$TRIAL_EXP, OrganizationType=$ORG_TYPE). Target a sandbox, trial CDO, or Developer Edition org." "" "null" "$SUFFIX"
+fi
+
+# Step 2 - Locate the Queue
+Q_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id FROM Group WHERE DeveloperName='$QUEUE_DN' AND Type='Queue'" \
+  --json 2>/dev/null)
+
+Q_COUNT=$(echo "$Q_JSON" | jq -r '.result.totalSize // 0' 2>/dev/null || echo "0")
+if [ "$Q_COUNT" -eq 0 ]; then
+  emit_blocked \
+    "Queue '$QUEUE_DN' does not exist on org. Run service-omni-queue-deploy first, or create manually via the click-path." \
+    "Setup → Queues → New → Label: '$QUEUE_DN', DeveloperName: '$QUEUE_DN', Supported Objects: Case → Save" \
+    "null" "$SUFFIX"
+fi
+
+QUEUE_ID=$(echo "$Q_JSON" | jq -r '.result.records[0].Id')
+
+# Step 3 - Locate the users to bind (generated demo pattern OR explicit real agents)
+if [ "$EXPLICIT_MODE" = "true" ]; then
+  # Explicit real agents: each token is a Username (...@...) or a 15/18-char User Id (005...).
+  USERNAME_IN=""
+  ID_IN=""
+  BADTOK=""
+  while IFS= read -r tok; do
+    [ -z "$tok" ] && continue
+    if [[ "$tok" =~ ^005[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$ ]]; then
+      ID_IN="${ID_IN:+$ID_IN,}'$tok'"
+    elif [[ "$tok" =~ ^[^,\'\"[:space:]]+@[^,\'\"[:space:]]+$ ]]; then
+      USERNAME_IN="${USERNAME_IN:+$USERNAME_IN,}'$tok'"
+    else
+      BADTOK="$BADTOK '$tok'"
+    fi
+  done <<< "$(printf '%s' "$EXPLICIT_MEMBERS_CSV" | tr ',' '\n' | sed 's/^ *//;s/ *$//')"
+
+  if [ -n "$BADTOK" ]; then
+    emit_blocked "explicit-members-csv contains token(s) that are neither a Username (...@...) nor a 15/18-char User Id (005...):$BADTOK" "" "$QUEUE_ID" "$SUFFIX"
+  fi
+
+  # Build the WHERE predicate from whichever token kinds were supplied.
+  WHERE_PARTS=""
+  [ -n "$USERNAME_IN" ] && WHERE_PARTS="Username IN ($USERNAME_IN)"
+  [ -n "$ID_IN" ] && WHERE_PARTS="${WHERE_PARTS:+$WHERE_PARTS OR }Id IN ($ID_IN)"
+
+  U_JSON=$(sf data query --target-org "$ORG" \
+    --query "SELECT Id, Username FROM User WHERE ($WHERE_PARTS) AND IsActive=true" \
+    --json 2>/dev/null)
+
+  U_COUNT=$(echo "$U_JSON" | jq -r '.result.totalSize // 0' 2>/dev/null || echo "0")
+  if [ "$U_COUNT" -lt "$COUNT" ]; then
+    FOUND=$(echo "$U_JSON" | jq -c '[.result.records[].Username]')
+    emit_blocked \
+      "Expected $COUNT ACTIVE user(s) from the explicit list; resolved only $U_COUNT active ($FOUND). Check the usernames/IDs are correct and the users are active." \
+      "" "$QUEUE_ID" "$SUFFIX"
+  fi
+else
+  # Demo pattern: agent1..N.<suffix>@example.com
+  EXPECTED_USERNAMES=()
+  for i in $(seq 1 "$COUNT"); do
+    EXPECTED_USERNAMES+=("${USERNAME_PREFIX}${i}.${SUFFIX}@${USERNAME_DOMAIN}")
+  done
+
+  # Build SOQL IN clause: 'un1','un2',...
+  IN_CLAUSE=""
+  for un in "${EXPECTED_USERNAMES[@]}"; do
+    if [ -n "$IN_CLAUSE" ]; then IN_CLAUSE="$IN_CLAUSE,"; fi
+    IN_CLAUSE="$IN_CLAUSE'$un'"
+  done
+
+  # Only active users can be routed work; filter IsActive=true so an inactive occupant can't satisfy the count.
+  U_JSON=$(sf data query --target-org "$ORG" \
+    --query "SELECT Id, Username FROM User WHERE Username IN ($IN_CLAUSE) AND IsActive=true" \
+    --json 2>/dev/null)
+
+  U_COUNT=$(echo "$U_JSON" | jq -r '.result.totalSize // 0' 2>/dev/null || echo "0")
+  if [ "$U_COUNT" -lt "$COUNT" ]; then
+    FOUND=$(echo "$U_JSON" | jq -c '[.result.records[].Username]')
+    emit_blocked \
+      "Expected $COUNT ACTIVE agent users matching pattern 'agent{1..$COUNT}.$SUFFIX@example.com'; found $U_COUNT active ($FOUND). Run service-omni-agent-users-create with count=$COUNT first (and reactivate any deactivated agent users)." \
+      "" "$QUEUE_ID" "$SUFFIX"
+  fi
+fi
+
+# Map username → userId, and build user Id array for downstream queries
+USERS_JSON=$(echo "$U_JSON" | jq -c '[.result.records[] | {id: .Id, username: .Username}]')
+USER_IDS_ARR=$(echo "$USERS_JSON" | jq -c '[.[].id]')
+
+# Build SOQL IN clause for user IDs
+USER_IDS_IN=""
+for uid in $(echo "$USER_IDS_ARR" | jq -r '.[]'); do
+  if [ -n "$USER_IDS_IN" ]; then USER_IDS_IN="$USER_IDS_IN,"; fi
+  USER_IDS_IN="$USER_IDS_IN'$uid'"
+done
+
+# Step 4 - Query existing GroupMember rows for this queue + these users
+GM_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT Id, UserOrGroupId FROM GroupMember WHERE GroupId='$QUEUE_ID' AND UserOrGroupId IN ($USER_IDS_IN)" \
+  --json 2>/dev/null)
+
+EXISTING_USER_IDS=$(echo "$GM_JSON" | jq -c '[.result.records[].UserOrGroupId]')
+EXISTING_COUNT=$(echo "$EXISTING_USER_IDS" | jq 'length')
+
+# Compute missing = expected - existing
+MISSING_USERS=$(echo "$USERS_JSON" | jq -c --argjson existing "$EXISTING_USER_IDS" \
+  '[.[] | select(.id as $id | ($existing | index($id)) == null)]')
+MISSING_COUNT=$(echo "$MISSING_USERS" | jq 'length')
+
+# PLAN_ONLY: all detection above is read-only. Report what a --run would do and stop before any write.
+if [ "${PLAN_ONLY:-}" = "1" ]; then
+  if [ "$MISSING_COUNT" -eq 0 ]; then
+    emit_plan "reused" "All $COUNT agent user(s) already members of queue '$QUEUE_DN'."
+  else
+    emit_plan "action_needed" "Would bind $MISSING_COUNT missing of $COUNT agent user(s) into queue '$QUEUE_DN'."
+  fi
+fi
+
+# Step 5 - POST GroupMember for each missing user
+BOUND_THIS_RUN='[]'
+BOUND_COUNT=0
+PARTIAL_ERRORS=()
+
+if [ "$MISSING_COUNT" -gt 0 ]; then
+  for row in $(echo "$MISSING_USERS" | jq -c '.[]'); do
+    USER_ID=$(echo "$row" | jq -r '.id')
+    USERNAME=$(echo "$row" | jq -r '.username')
+
+    # sf api request rest (beta) writes a warning to stderr; redirect it so stdout is pure JSON.
+    POST_STDERR="$(mktemp)"
+    POST_RESULT=$(sf api request rest --target-org "$ORG" \
+      "/services/data/$API_VERSION/sobjects/GroupMember" \
+      --method POST \
+      --body "{\"GroupId\":\"$QUEUE_ID\",\"UserOrGroupId\":\"$USER_ID\"}" 2>"$POST_STDERR" || true)
+
+    # Success = {id, success:true, errors:[]}; error = array of {errorCode, message} or single obj
+    POST_SUCCESS=$(echo "$POST_RESULT" | jq -r '.success // false' 2>/dev/null || echo "false")
+
+    if [ "$POST_SUCCESS" = "true" ]; then
+      GM_ID=$(echo "$POST_RESULT" | jq -r '.id')
+      # GroupMember dedupes server-side (a duplicate POST returns success with the existing Id), so
+      # the detect step above is what prevents inflated bound_count; any success here is a new bind.
+      BOUND_THIS_RUN=$(echo "$BOUND_THIS_RUN" | jq -c \
+        --arg uid "$USER_ID" --arg un "$USERNAME" --arg gmid "$GM_ID" \
+        '. + [{user_id: $uid, username: $un, group_member_id: $gmid}]')
+      BOUND_COUNT=$((BOUND_COUNT + 1))
+    else
+      # Try to extract error code + message
+      ERR_CODE=$(echo "$POST_RESULT" | jq -r 'if type == "array" then .[0].errorCode else .errorCode // "UNKNOWN" end' 2>/dev/null || echo "UNKNOWN")
+      ERR_MSG=$(echo "$POST_RESULT" | jq -r 'if type == "array" then .[0].message else .message // "Unknown POST error" end' 2>/dev/null || echo "Unknown POST error")
+
+      # Fallback: if POST_RESULT was empty (CLI-level failure), pull first non-Warning stderr line
+      if [ "$ERR_CODE" = "UNKNOWN" ] && [ -z "$POST_RESULT" ]; then
+        ERR_MSG=$(grep -v '^Warning:' "$POST_STDERR" | head -1 || echo "sf CLI produced no output")
+      fi
+
+      if [ "$ERR_CODE" = "DUPLICATE_VALUE" ]; then
+        # Safety net for a concurrent re-POST; detect-before-POST already prevents duplicate binds.
+        :
+      else
+        PARTIAL_ERRORS+=("$USERNAME ($USER_ID): $ERR_CODE - $ERR_MSG")
+      fi
+    fi
+    rm -f "$POST_STDERR"
+  done
+fi
+
+# Step 6 - Re-query final membership
+AFTER_GM_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT UserOrGroupId FROM GroupMember WHERE GroupId='$QUEUE_ID' AND UserOrGroupId IN ($USER_IDS_IN)" \
+  --json 2>/dev/null)
+
+AFTER_USER_IDS=$(echo "$AFTER_GM_JSON" | jq -c '[.result.records[].UserOrGroupId]')
+AFTER_COUNT=$(echo "$AFTER_USER_IDS" | jq 'length')
+
+# Step 7 - Compute status
+REUSED_COUNT=$EXISTING_COUNT
+
+if [ ${#PARTIAL_ERRORS[@]} -gt 0 ] || [ "$AFTER_COUNT" -lt "$COUNT" ]; then
+  STATUS="partial"
+  # Assemble blocking_issue string
+  BLOCKING_ISSUE="Partial bind: after re-query, $AFTER_COUNT of $COUNT expected users are members. Failures: ${PARTIAL_ERRORS[*]:-"(none; count mismatch only)"}"
+elif [ "$BOUND_COUNT" -eq 0 ]; then
+  STATUS="reused"
+  BLOCKING_ISSUE=""
+else
+  STATUS="bound"
+  BLOCKING_ISSUE=""
+fi
+
+# Step 8 - Emit report
+BLOCKING_JQ_ARG='null'
+if [ -n "$BLOCKING_ISSUE" ]; then
+  BLOCKING_JQ_ARG=$(jq -n --arg s "$BLOCKING_ISSUE" '$s')
+fi
+
+jq -n \
+  --arg status "$STATUS" \
+  --arg dn "$QUEUE_DN" \
+  --arg qid "$QUEUE_ID" \
+  --arg suf "$SUFFIX" \
+  --argjson count "$COUNT" \
+  --argjson before_ids "$EXISTING_USER_IDS" \
+  --argjson before_count "$EXISTING_COUNT" \
+  --argjson bound "$BOUND_THIS_RUN" \
+  --argjson bound_count "$BOUND_COUNT" \
+  --argjson reused_count "$REUSED_COUNT" \
+  --argjson after_ids "$AFTER_USER_IDS" \
+  --argjson after_count "$AFTER_COUNT" \
+  --argjson blocking "$BLOCKING_JQ_ARG" \
+  --arg member_source "$([ "$EXPLICIT_MODE" = "true" ] && echo explicit || echo generated_pattern)" \
+  '{
+    skill: "service-omni-queue-members-assign",
+    status: $status,
+    queue: {developer_name: $dn, id: $qid},
+    org_suffix: $suf,
+    member_source: $member_source,
+    requested_count: $count,
+    before: {
+      existing_member_user_ids: $before_ids,
+      existing_member_count: $before_count
+    },
+    bound_this_run: $bound,
+    bound_count: $bound_count,
+    reused_count: $reused_count,
+    after: {
+      member_user_ids: $after_ids,
+      member_count: $after_count
+    },
+    manual_actions: [],
+    blocking_issue: $blocking
+  }'