@salesforce/afv-skills 1.47.0 → 1.49.0

package/skills/service-omni-agent-users-create/scripts/run-create.sh

@@ -0,0 +1,298 @@
+#!/usr/bin/env bash
+# run-create.sh - INTERNAL (invoke via detect-and-create.sh, which enforces the safe_to_write guard): render Apex tokens, execute, parse created users; passwords set via separate System.setPassword, never extracted from logs. Contract + security: SKILL.md + references/apex-template-notes.md.
+
+set -euo pipefail
+
+if [ $# -lt 4 ]; then
+  echo '{"error":"Usage: bash run-create.sh <org-alias> <count> <profile-id> <org-suffix>"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+COUNT="$2"
+PROFILE_ID="$3"
+SUFFIX="$4"
+
+# Validate every arg BEFORE it is sed-substituted into anonymous Apex. These tokens are interpolated
+# into executable Apex, so anything outside a strict grammar (Apex/sed metacharacters, code) is
+# rejected up front rather than executed.
+if ! [[ "$COUNT" =~ ^[1-9][0-9]{0,2}$ ]]; then
+  echo "{\"error\":\"Invalid count '$COUNT' (expected a positive integer 1-999).\"}" >&2; exit 1
+fi
+if ! [[ "$PROFILE_ID" =~ ^[A-Za-z0-9]{15}([A-Za-z0-9]{3})?$ ]]; then
+  echo "{\"error\":\"Invalid profile-id '$PROFILE_ID' (expected a 15- or 18-char Salesforce Id).\"}" >&2; exit 1
+fi
+if ! [[ "$SUFFIX" =~ ^[A-Za-z0-9]{1,18}$ ]]; then
+  echo "{\"error\":\"Invalid org-suffix '$SUFFIX' (expected 1-18 alphanumeric chars).\"}" >&2; exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TEMPLATE="$SCRIPT_DIR/../assets/create-users.apex.template"
+
+if [ ! -f "$TEMPLATE" ]; then
+  echo "{\"error\":\"Apex template not found: $TEMPLATE\"}" >&2
+  exit 1
+fi
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+RESOLVED="$WORK/create-users.resolved.apex"
+
+sed -e "s|__COUNT__|${COUNT}|g" \
+    -e "s|__PROFILE_ID__|${PROFILE_ID}|g" \
+    -e "s|__SUFFIX__|${SUFFIX}|g" \
+    "$TEMPLATE" > "$RESOLVED"
+
+# Execute Anonymous Apex. sf apex run --json shapes differ for compile-fail / runtime-fail /
+# success / CLI-fail; each is handled below.
+APEX_JSON=$(sf apex run --target-org "$ORG" --file "$RESOLVED" --json 2>/dev/null || true)
+
+# Strip C0 control chars: sf embeds an unescaped debug log in .result.logs, which jq>=1.7 rejects.
+# This merges the log to one line; the grep below is anchored to tolerate that.
+APEX_JSON=$(printf '%s' "$APEX_JSON" | tr -d '\000-\037')
+
+CLI_STATUS=$(echo "$APEX_JSON" | jq -r '.status // 0' 2>/dev/null || echo "0")
+COMPILE_SUCCESS=$(echo "$APEX_JSON" | jq -r '.result.compiled // false' 2>/dev/null || echo "false")
+EXEC_SUCCESS=$(echo "$APEX_JSON"    | jq -r '.result.success  // false' 2>/dev/null || echo "false")
+
+translate_error() {
+  local raw="$1"
+  case "$raw" in
+    *LICENSE_LIMIT_EXCEEDED*)
+      echo "Org has reached its user license limit. Free up a license slot (deactivate unused users in Setup > Users) or request a larger CDO from OrgFarm."
+      ;;
+    *DUPLICATE_USERNAME*)
+      echo "Username collision with another Salesforce org (globally unique constraint). Rare - retry the skill; if it persists, another agent may be concurrently running against the same suffix."
+      ;;
+    *INVALID_EMAIL_ADDRESS*)
+      echo "Salesforce rejected the @example.com email. This should never happen - likely a bug in the skill's Apex template. Escalate."
+      ;;
+    *INSUFFICIENT_ACCESS*|*NoAccessException*)
+      echo "Executing user lacks required permission. Ensure the sf-CLI-authenticated user has System Administrator profile or equivalent."
+      ;;
+    *INVALID_LOGIN*|*INVALID_SESSION_ID*)
+      echo "Salesforce session expired. Re-authenticate: sf org login web -a $ORG -r <my-domain-url>"
+      ;;
+    *)
+      echo "$raw"
+      ;;
+  esac
+}
+
+if [ "$CLI_STATUS" != "0" ]; then
+  CLI_ERR=$(echo "$APEX_JSON" | jq -r '.message // "Unknown CLI error"' 2>/dev/null)
+  FRIENDLY=$(translate_error "$CLI_ERR")
+  echo "{\"error\":\"$FRIENDLY\",\"raw\":$(echo "$CLI_ERR" | jq -R .)}" >&2
+  exit 1
+fi
+
+if [ "$COMPILE_SUCCESS" != "true" ]; then
+  COMPILE_ERR=$(echo "$APEX_JSON" | jq -r '.result.compileProblem // "Unknown compile error"' 2>/dev/null)
+  COMPILE_LINE=$(echo "$APEX_JSON" | jq -r '.result.line // "?"' 2>/dev/null)
+  echo "{\"error\":\"Apex compile failed at line $COMPILE_LINE: $COMPILE_ERR\"}" >&2
+  exit 1
+fi
+
+if [ "$EXEC_SUCCESS" != "true" ]; then
+  EXEC_ERR=$(echo "$APEX_JSON" | jq -r '.result.exceptionMessage // "Unknown execution error"' 2>/dev/null)
+  if [ -z "$EXEC_ERR" ] || [ "$EXEC_ERR" = "Unknown execution error" ] || [ "$EXEC_ERR" = "null" ]; then
+    EXEC_ERR=$(echo "$APEX_JSON" | jq -r '.message // "Unknown execution error"' 2>/dev/null)
+  fi
+  FRIENDLY=$(translate_error "$EXEC_ERR")
+  echo "{\"error\":\"$FRIENDLY\",\"raw\":$(echo "$EXEC_ERR" | jq -R .)}" >&2
+  exit 1
+fi
+
+# Parse AGENT_USER_CREATED|<userId>|<username>|<email> from the log; decode the HTML-encoded pipe
+# (&#124;) that sf emits, else the grep misses every user.
+LOG=$(echo "$APEX_JSON" | jq -r '.result.logs // ""' 2>/dev/null | sed 's/&#124;/|/g')
+
+# Anchor on a real 005 Id + @example.com domain so the match ignores the Apex source echoed in the merged log.
+CREATED_RAW=$(echo "$LOG" | grep -oE 'AGENT_USER_CREATED\|005[a-zA-Z0-9]{15}\|[^|]+@example\.com\|[^|]+@example\.com' || true)
+
+if [ -z "$CREATED_RAW" ]; then
+  CREATED_USERS_JSON='[]'
+else
+  CREATED_USERS_JSON=$(echo "$CREATED_RAW" \
+    | awk -F'|' '
+        BEGIN { print "[" }
+        NR > 1 { printf "," }
+        {
+          printf "{\"id\":\"%s\",\"username\":\"%s\",\"email\":\"%s\"}", $2, $3, $4
+        }
+        END { print "]" }
+    ')
+  if ! echo "$CREATED_USERS_JSON" | jq -c '.' >/dev/null 2>&1; then
+    echo "{\"error\":\"Internal parse error: AGENT_USER_CREATED lines produced invalid JSON.\",\"raw_lines\":$(echo "$CREATED_RAW" | jq -Rs .)}" >&2
+    exit 1
+  fi
+  CREATED_USERS_JSON=$(echo "$CREATED_USERS_JSON" | jq -c '.')
+fi
+
+# Set each User's password via System.setPassword (the only working path for Apex-inserted users).
+# Fail-closed on the TraceFlag gate below; on failure the User stays active + reset_required.
+# Full security rationale: references/apex-template-notes.md.
+ENRICHED_USERS='[]'
+NEEDS_RESET='[]'
+ROLLED_BACK='[]'
+
+# Generated passwords are written to a restricted (0600) file and NEVER returned in stdout, so
+# plaintext cannot enter an AI/tool transcript when this leaf is invoked directly. The coordinator
+# passes OMNI_CREDENTIALS_FILE/OMNI_CREDENTIALS_KEY to escrow into its own file; standalone runs
+# default to ./CREDENTIALS.json. File format: { "<key>": [ {username, password}, ... ] }.
+# Secrets never touch argv/env (both visible via process inspection): each {username,password} pair is
+# appended as one JSON line to this 0600 temp file (inside $WORK, mode 0700) and fed to jq only via
+# stdin / --slurpfile. $WORK is removed by the EXIT trap, so the plaintext file never persists.
+CRED_PAIRS_FILE="$WORK/cred-pairs.jsonl"
+: > "$CRED_PAIRS_FILE"; chmod 600 "$CRED_PAIRS_FILE" 2>/dev/null || true
+CRED_COUNT=0
+CRED_FILE="${OMNI_CREDENTIALS_FILE:-$PWD/CREDENTIALS.json}"
+CRED_KEY="${OMNI_CREDENTIALS_KEY:-service-omni-agent-users-create}"
+CRED_WRITTEN="false"
+write_credentials() {
+  # $1 = path to a JSONL file of {username,password} objects. Secret-bearing pairs are read via
+  # --slurpfile (a file, never argv); the existing credentials file is piped in via stdin.
+  local pairs_file="$1" existing='{}' tmp
+  [ -f "$CRED_FILE" ] && existing=$(cat "$CRED_FILE" 2>/dev/null || echo '{}')
+  tmp=$(mktemp) || return 1
+  if ! printf '%s' "$existing" | jq --arg k "$CRED_KEY" --slurpfile c "$pairs_file" '. + {($k): $c}' > "$tmp" 2>/dev/null || [ ! -s "$tmp" ]; then
+    rm -f "$tmp"; return 1
+  fi
+  if ! mv "$tmp" "$CRED_FILE" 2>/dev/null; then rm -f "$tmp"; return 1; fi
+  chmod 600 "$CRED_FILE" 2>/dev/null || true
+  return 0
+}
+
+set_password_via_apex() {
+  # $1=user_id  $2=plaintext_password. Echoes "ok" on success, else the exception text.
+  local uid="$1" pw="$2" apex_file res
+  apex_file="$WORK/setpw.apex"
+  # uid (18-char Id) and pw ([A-Za-z0-9]) can't break out of the Apex string literal.
+  printf "System.setPassword('%s', '%s');\n" "$uid" "$pw" > "$apex_file"
+  res=$(sf apex run --target-org "$ORG" --file "$apex_file" --json 2>/dev/null | tr -d '\000-\037' || true)
+  rm -f "$apex_file"
+  if [ "$(echo "$res" | jq -r '.result.success // false' 2>/dev/null)" = "true" ]; then
+    echo "ok"
+  else
+    echo "$res" | jq -r '.result.exceptionMessage // .message // "setPassword failed"' 2>/dev/null
+  fi
+}
+
+# TraceFlag gate (fail-closed): prove no active TraceFlag exists for the running user BEFORE any
+# System.setPassword, else a password literal could persist to a queryable ApexLog. Cannot prove safe
+# => no password set, users left active + reset_required. See references/apex-template-notes.md.
+TRACEFLAG_SAFE=false
+TRACEFLAG_REASON="TraceFlag state could not be determined"
+ME_UNAME=$(sf org display --target-org "$ORG" --json 2>/dev/null | jq -r '.result.username // empty' 2>/dev/null || true)
+if [ -z "${ME_UNAME:-}" ]; then
+  TRACEFLAG_REASON="could not resolve the running user (sf org display failed)"
+else
+  ME_UID=$(sf data query --target-org "$ORG" \
+    --query "SELECT Id FROM User WHERE Username='$ME_UNAME' LIMIT 1" \
+    --json 2>/dev/null | jq -r '.result.records[0].Id // empty' 2>/dev/null || true)
+  if [ -z "${ME_UID:-}" ]; then
+    TRACEFLAG_REASON="could not resolve the running user's Id"
+  else
+    NOW_UTC=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    if TF_JSON=$(sf data query --target-org "$ORG" --use-tooling-api \
+        --query "SELECT Id FROM TraceFlag WHERE TracedEntityId='$ME_UID' AND ExpirationDate > $NOW_UTC" \
+        --json 2>/dev/null) && [ -n "$TF_JSON" ]; then
+      TF_STATUS=$(echo "$TF_JSON" | jq -r '.status // 1' 2>/dev/null || echo 1)
+      if [ "$TF_STATUS" = "0" ]; then
+        TF_COUNT=$(echo "$TF_JSON" | jq -r 'if (.result.totalSize != null) then .result.totalSize elif (.result.records != null) then (.result.records | length) else "unknown" end' 2>/dev/null || echo "unknown")
+        if [ "$TF_COUNT" = "0" ]; then
+          TRACEFLAG_SAFE=true
+          TRACEFLAG_REASON=""
+        elif [ "$TF_COUNT" = "unknown" ]; then
+          TRACEFLAG_REASON="the TraceFlag query returned an unparseable result"
+        else
+          TRACEFLAG_REASON="an active Apex debug TraceFlag exists for the running user ($TF_COUNT found)"
+        fi
+      else
+        TRACEFLAG_REASON="the TraceFlag Tooling API query returned an error status"
+      fi
+    else
+      TRACEFLAG_REASON="the TraceFlag Tooling API query failed"
+    fi
+  fi
+fi
+
+if [ "$(echo "$CREATED_USERS_JSON" | jq -r 'length')" -gt 0 ]; then
+  while IFS= read -r row; do
+    USER_ID=$(echo "$row" | jq -r '.id')
+    UNAME=$(echo "$row" | jq -r '.username')
+    EMAIL=$(echo "$row" | jq -r '.email')
+
+    if [ "$TRACEFLAG_SAFE" != "true" ]; then
+      # Fail closed: skip setPassword, keep the User active + flag for manual reset.
+      NEEDS_RESET=$(echo "$NEEDS_RESET" | jq -c --arg u "$UNAME" '. + [$u]')
+      ENRICHED_USERS=$(echo "$ENRICHED_USERS" | jq -c \
+        --arg id "$USER_ID" --arg u "$UNAME" --arg e "$EMAIL" \
+        '. + [{id: $id, username: $u, email: $e, password: null, password_status: "reset_required", password_error: "skipped: TraceFlag safety could not be proven (fail-closed)"}]')
+      continue
+    fi
+
+    # Strong [A-Za-z0-9] password + fixed mixed-class suffix (Salesforce complexity). The || true
+    # swallows tr's SIGPIPE (head closes the pipe) so pipefail+set -e don't abort mid-insert.
+    RAND="$(LC_ALL=C tr -dc 'A-Za-z0-9' < /dev/urandom 2>/dev/null | head -c 14 || true)"
+    PW="${RAND}aB3"
+    SETPW_RESULT=$(set_password_via_apex "$USER_ID" "$PW")
+
+    if [ "$SETPW_RESULT" = "ok" ]; then
+      # Feed the SECRET via stdin (never argv/env); username is not secret so --arg is fine.
+      printf '%s' "$PW" | jq -Rsc --arg u "$UNAME" '{username: $u, password: .}' >> "$CRED_PAIRS_FILE"
+      CRED_COUNT=$((CRED_COUNT + 1))
+      ENRICHED_USERS=$(echo "$ENRICHED_USERS" | jq -c \
+        --arg id "$USER_ID" --arg u "$UNAME" --arg e "$EMAIL" \
+        '. + [{id: $id, username: $u, email: $e, password: null, password_status: "generated"}]')
+    else
+      # Non-destructive: keep the active User, flag it for a manual password reset.
+      NEEDS_RESET=$(echo "$NEEDS_RESET" | jq -c --arg u "$UNAME" '. + [$u]')
+      ENRICHED_USERS=$(echo "$ENRICHED_USERS" | jq -c \
+        --arg id "$USER_ID" --arg u "$UNAME" --arg e "$EMAIL" --arg r "$SETPW_RESULT" \
+        '. + [{id: $id, username: $u, email: $e, password: null, password_status: "reset_required", password_error: $r}]')
+    fi
+  done < <(echo "$CREATED_USERS_JSON" | jq -c '.[]')
+fi
+
+# Escrow generated passwords to the restricted file; never emit plaintext in stdout. Fail-closed:
+# if escrow fails, the passwords were set on-org but cannot be handed back, so flag those users for a
+# manual reset rather than leaking the plaintext.
+CRED_WARNING=""
+if [ "$CRED_COUNT" -gt 0 ]; then
+  if write_credentials "$CRED_PAIRS_FILE"; then
+    CRED_WRITTEN="true"
+  else
+    CRED_WARNING="Passwords were set on the created users but could NOT be escrowed to the credentials file ($CRED_FILE); plaintext was deliberately NOT emitted to stdout. Reset these users' passwords in Setup > Users."
+    # Escrow failed → the plaintext is unrecoverable, so these users genuinely need a manual reset:
+    # add them to users_needing_password_reset (not just the per-user status) before flipping status.
+    ESCROW_FAILED_UNAMES=$(echo "$ENRICHED_USERS" | jq -c '[ .[] | select(.password_status=="generated") | .username ]')
+    NEEDS_RESET=$(jq -c -n --argjson a "$NEEDS_RESET" --argjson b "$ESCROW_FAILED_UNAMES" '$a + $b | unique')
+    ENRICHED_USERS=$(echo "$ENRICHED_USERS" | jq -c '[ .[] | if .password_status=="generated" then (.password_status="reset_required" | .password_error="escrow_failed") else . end ]')
+  fi
+fi
+
+# Surface why password generation was skipped when the TraceFlag gate failed.
+SECURITY_WARNING=""
+if [ "$TRACEFLAG_SAFE" != "true" ]; then
+  SECURITY_WARNING="Password generation was SKIPPED (fail-closed) because ${TRACEFLAG_REASON}. No System.setPassword was executed, so no plaintext could enter an ApexLog. The created users are ACTIVE and flagged password_status:\"reset_required\" - set their passwords in Setup > Users after confirming no debug TraceFlag is active, or disable the TraceFlag and re-run."
+fi
+[ -n "$CRED_WARNING" ] && SECURITY_WARNING="${SECURITY_WARNING:+$SECURITY_WARNING }$CRED_WARNING"
+
+jq -n \
+  --argjson created "$ENRICHED_USERS" \
+  --argjson needs_reset "$NEEDS_RESET" \
+  --argjson rolled_back "$ROLLED_BACK" \
+  --arg security_warning "$SECURITY_WARNING" \
+  --arg cred_written "$CRED_WRITTEN" \
+  --arg cred_file "$CRED_FILE" \
+  '{
+    created_users: $created,
+    created_count: ($created | length),
+    users_needing_password_reset: $needs_reset,
+    rolled_back_users: $rolled_back,
+    credentials_written: ($cred_written == "true"),
+    credentials_file: (if $cred_written == "true" then $cred_file else null end),
+    security_warning: (if $security_warning == "" then null else $security_warning end),
+    security_note: "Passwords are set via anonymous Apex System.setPassword. The plaintext appears in the inline executeAnonymous debug log and, ONLY when a debug-log TraceFlag is active for the running user, in a queryable ApexLog row. To avoid ever persisting plaintext to a log, this script FAILS CLOSED BEFORE the first System.setPassword: it proves via a SOQL-filtered Tooling API query (ExpirationDate > now) that no active TraceFlag exists for the running user. If safety cannot be positively proven - the running user cannot be resolved, the Tooling API query fails or is unparseable, or any active TraceFlag exists - NO password is generated at all; the created users are left ACTIVE and flagged password_status:\"reset_required\", and security_warning explains why. Generated passwords are NEVER returned in this output; they are written to a restricted 0600 credentials_file (default ./CREDENTIALS.json, or OMNI_CREDENTIALS_FILE) so plaintext cannot enter a tool/AI transcript. Read the file once, distribute securely, then delete it. Set passwords for reset_required users in Setup > Users after ensuring no debug TraceFlag is active (or disable the TraceFlag and re-run)."
+  }'

package/skills/service-omni-agent-users-create/scripts/tests/test_user_create_security.py

@@ -0,0 +1,171 @@
+"""Org-free security tests proving the TraceFlag fail-closed contract for both run-create.sh scripts: setPassword runs only when no active TraceFlag exists (else users stay reset_required; a failing TraceFlag query also fails closed), proven via a fake-sf marker file."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+SKILLS_ROOT = Path(__file__).resolve().parents[3]  # the skills/ directory
+AGENT_SCRIPT = SKILLS_ROOT / "service-omni-agent-users-create/scripts/run-create.sh"
+SUPERVISOR_SCRIPT = SKILLS_ROOT / "service-omni-supervisor-users-create/scripts/run-create.sh"
+
+FAKE_SF = r"""#!/usr/bin/env bash
+# Minimal fake `sf` for TraceFlag fail-closed tests. Differentiates the create-users Apex from the
+# System.setPassword Apex by reading the --file contents, and records setPassword submissions.
+cmd="$1"; sub="$2"; shift 2 || true
+all="$*"
+file=""
+prev=""
+for a in "$@"; do
+  if [ "$prev" = "--file" ]; then file="$a"; fi
+  prev="$a"
+done
+case "$cmd $sub" in
+  "apex run")
+    # The setPassword Apex is EXACTLY `System.setPassword('id','pw');` on its first line; the
+    # create-users template may merely mention setPassword in a comment, so match the first line only.
+    if [ -n "$file" ] && head -1 "$file" 2>/dev/null | grep -q '^System.setPassword'; then
+      : > "$FAKE_SETPW_MARKER"
+      echo '{"status":0,"result":{"compiled":true,"success":true,"logs":""}}'
+    else
+      echo '{"status":0,"result":{"compiled":true,"success":true,"logs":"AGENT_USER_CREATED|005000000000001AAA|agent1.sfx@example.com|agent1.sfx@example.com SUPERVISOR_CREATED|005000000000002AAA|supervisor1.sfx@example.com|supervisor1.sfx@example.com"}}'
+    fi
+    ;;
+  "org display")
+    echo '{"status":0,"result":{"username":"admin@example.com"}}'
+    ;;
+  "data query")
+    if printf '%s' "$all" | grep -q "TraceFlag"; then
+      case "${FAKE_TF:-none}" in
+        active) echo '{"status":0,"result":{"totalSize":1,"records":[{"Id":"7tf000000000001AAA","ExpirationDate":"2999-01-01T12:00:00.000+0000"}]}}' ;;
+        fail)   exit 1 ;;
+        *)      echo '{"status":0,"result":{"totalSize":0,"records":[]}}' ;;
+      esac
+    else
+      echo '{"status":0,"result":{"records":[{"Id":"005000000000009AAA"}]}}'
+    fi
+    ;;
+  *)
+    echo '{"status":0,"result":{}}'
+    ;;
+esac
+"""
+
+
+def _run(script: Path, tf_mode: str):
+    """Run a user-create script with the fake sf; return (rc, parsed_json, setpw_called)."""
+    with tempfile.TemporaryDirectory() as tmp:
+        bindir = Path(tmp) / "bin"
+        bindir.mkdir()
+        (bindir / "sf").write_text(FAKE_SF)
+        (bindir / "sf").chmod(0o755)
+        marker = Path(tmp) / "setpw_called"
+
+        cred_file = Path(tmp) / "CREDENTIALS.json"
+        env = dict(os.environ)
+        env["PATH"] = f"{bindir}:{env['PATH']}"
+        env["FAKE_TF"] = tf_mode
+        env["FAKE_SETPW_MARKER"] = str(marker)
+        # Isolate the credentials escrow file inside the temp dir so a run never writes to the repo.
+        env["OMNI_CREDENTIALS_FILE"] = str(cred_file)
+
+        proc = subprocess.run(
+            ["bash", str(script), "myorg", "1", "00e000000000001AAA", "sfx"],
+            capture_output=True, text=True, env=env, cwd=tmp,
+        )
+        out = None
+        try:
+            out = json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            pass
+        cred_text = cred_file.read_text() if cred_file.exists() else ""
+        return proc.returncode, out, marker.exists(), proc.stdout + proc.stderr, cred_text
+
+
+class TraceFlagFailClosedTests(unittest.TestCase):
+    SCRIPTS = (("agent", AGENT_SCRIPT), ("supervisor", SUPERVISOR_SCRIPT))
+
+    def test_no_traceflag_sets_password(self):
+        for label, script in self.SCRIPTS:
+            with self.subTest(script=label):
+                rc, out, setpw_called, raw, cred_text = _run(script, "none")
+                self.assertEqual(rc, 0, raw)
+                self.assertIsNotNone(out, raw)
+                self.assertTrue(setpw_called, "System.setPassword must run when no TraceFlag is active")
+                self.assertIsNone(out.get("security_warning"), raw)
+                self.assertEqual(out["created_users"][0]["password_status"], "generated", raw)
+                # P0: plaintext must NEVER be in stdout - it is escrowed to the 0600 credentials file.
+                self.assertIsNone(out["created_users"][0]["password"], raw)
+                self.assertTrue(out.get("credentials_written"), raw)
+                self.assertTrue(str(out.get("credentials_file", "")).endswith("CREDENTIALS.json"), raw)
+                pw = json.loads(cred_text)
+                pairs = next(iter(pw.values()))
+                self.assertTrue(pairs and pairs[0].get("password"), "escrow file must hold the plaintext")
+                self.assertNotIn(pairs[0]["password"], raw, "generated password leaked into stdout/stderr")
+
+    def test_active_traceflag_never_calls_setpassword(self):
+        for label, script in self.SCRIPTS:
+            with self.subTest(script=label):
+                rc, out, setpw_called, raw, cred_text = _run(script, "active")
+                self.assertEqual(rc, 0, raw)
+                self.assertIsNotNone(out, raw)
+                self.assertFalse(setpw_called,
+                                 "PROOF FAILED: System.setPassword was submitted while a TraceFlag was active")
+                self.assertIsNotNone(out.get("security_warning"), raw)
+                self.assertEqual(out["created_users"][0]["password_status"], "reset_required", raw)
+                self.assertIsNone(out["created_users"][0]["password"], raw)
+
+    def test_traceflag_query_failure_fails_closed(self):
+        for label, script in self.SCRIPTS:
+            with self.subTest(script=label):
+                rc, out, setpw_called, raw, cred_text = _run(script, "fail")
+                self.assertEqual(rc, 0, raw)
+                self.assertIsNotNone(out, raw)
+                self.assertFalse(setpw_called,
+                                 "A failed TraceFlag query must fail closed (no setPassword)")
+                self.assertIsNotNone(out.get("security_warning"), raw)
+                self.assertEqual(out["created_users"][0]["password_status"], "reset_required", raw)
+
+
+class SourceContractTests(unittest.TestCase):
+    """Guard the exact fail-closed shape so a refactor cannot silently regress it."""
+
+    def test_setpassword_is_gated_on_traceflag_safe(self):
+        for script in (AGENT_SCRIPT, SUPERVISOR_SCRIPT):
+            src = script.read_text()
+            self.assertIn('if [ "$TRACEFLAG_SAFE" != "true" ]; then', src, str(script))
+            # The active-TraceFlag path must `continue` before reaching set_password_via_apex.
+            gate = src.index('if [ "$TRACEFLAG_SAFE" != "true" ]; then')
+            setpw = src.index("SETPW_RESULT=$(set_password_via_apex")
+            self.assertLess(gate, setpw, f"{script}: TRACEFLAG_SAFE gate must precede setPassword")
+
+    def test_traceflag_query_uses_soql_expiration_filter(self):
+        for script in (AGENT_SCRIPT, SUPERVISOR_SCRIPT):
+            src = script.read_text()
+            self.assertIn("ExpirationDate > $NOW_UTC", src, str(script))
+            self.assertIn("TRACEFLAG_SAFE=false", src, str(script))
+
+    def test_password_never_passed_via_jq_argv(self):
+        # The generated password must not reach jq (or any command) through argv/env, which are visible
+        # via process inspection. It is fed to jq over stdin and escrowed via --slurpfile (a file).
+        for script in (AGENT_SCRIPT, SUPERVISOR_SCRIPT):
+            src = script.read_text()
+            self.assertNotIn('--arg p "$PW"', src, f"{script}: password must not be a jq --arg")
+            self.assertNotIn('--argjson c "$pairs"', src, f"{script}: pairs (with secrets) must not be jq argv")
+            self.assertIn('printf \'%s\' "$PW" | jq -Rsc', src, f"{script}: password must be fed via stdin")
+            self.assertIn('--slurpfile c "$pairs_file"', src, f"{script}: escrow must read pairs from a file")
+
+    def test_escrow_failure_marks_users_needing_reset(self):
+        # When escrow fails the plaintext is unrecoverable, so the affected users must be listed in
+        # users_needing_password_reset (not only flipped in per-user status).
+        for script in (AGENT_SCRIPT, SUPERVISOR_SCRIPT):
+            src = script.read_text()
+            self.assertIn("ESCROW_FAILED_UNAMES=", src, str(script))
+            self.assertIn("NEEDS_RESET=$(jq -c -n --argjson a \"$NEEDS_RESET\" --argjson b \"$ESCROW_FAILED_UNAMES\"", src, str(script))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

package/skills/service-omni-agent-work-sharing-configure/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: service-omni-agent-work-sharing-configure
+description: "Use to configure or verify org-wide AgentWork visibility for supervisors after explicit confirmation. Triggers: let supervisors read AgentWork, configure AgentWork sharing, verify AgentWork OWD, make AgentWork visible to supervisors, change AgentWork internal access. Do not use to filter which reps appear in Command Center; use service-omni-supervisor-config-deploy for that."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "0.1"
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-supervisor-config-deploy"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["python3"]
+      semver: ">=3.8"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-agent-work-sharing-configure
+
+Detect and optionally configure the standard `AgentWork` object's internal organization-wide default. The supported headless contract is `CustomObject:AgentWork` metadata: retrieve the current metadata, preserve `externalSharingModel`, deploy internal `sharingModel=Read`, and retrieve it again for proof.
+
+This setting grants read visibility broadly to internal users who already have object access. It is not a substitute for an `OmniSupervisorConfig`: that configuration filters which reps, queues, skills, actions, and tabs a supervisor sees, but does not grant record access.
+
+## Inputs
+
+```bash
+bash scripts/configure-and-report.sh <org-alias> --plan
+bash scripts/configure-and-report.sh <org-alias> --confirm-org-wide-visibility
+```
+
+- `org-alias` is required and must already be authenticated with `sf`.
+- `--plan` retrieves and reports the current and desired models without deploying.
+- `--confirm-org-wide-visibility` is required only when a run must change `Private` to `Read`. Omitting it blocks before deployment.
+
+## Safety contract
+
+- A run refuses production customer orgs. Plan mode remains read-only.
+- `externalSharingModel` is preserved exactly.
+- `Read` and `ReadWrite` already provide internal read visibility and are reused. The skill never narrows `ReadWrite` to `Read`.
+- The only supported mutation is `Private` to `Read`; the skill never grants internal edit access.
+- Failed classification, retrieve, deploy, or read-back blocks. It never reports success from an inconclusive response.
+- Use a dedicated sandbox or test org because changing an OWD can initiate sharing recalculation.
+
+## Workflow
+
+1. Classify the target org and enforce the production-write guard.
+2. Retrieve `CustomObject:AgentWork` through Metadata API.
+3. Read internal and external sharing models.
+4. Reuse `Read` or `ReadWrite` with no deploy.
+5. In plan mode, report the proposed `Private` to `Read` change and exit yellow.
+6. In run mode, require explicit blast-radius confirmation.
+7. Deploy only the standard-object metadata containing preserved external sharing and internal `Read`.
+8. Retrieve again and require internal `Read` plus the unchanged external model.
+
+## Output
+
+A single JSON object containing `status`, `previous_sharing_model`, `sharing_model`, `external_sharing_model`, `changed`, `dry_run`, `deploy_id`, and `blocking_issue`.
+
+- `configured`: a confirmed `Private` to `Read` deployment succeeded and read-back matched.
+- `reused`: current `Read` or `ReadWrite` already provides visibility.
+- `action_needed`: plan mode found `Private`; no write occurred.
+- `blocked`: a safety guard or supported-API verification failed.
+
+## Limitations
+
+- This skill changes visibility, not supervisor scope. Use the supervisor configuration skill for filtering.
+- It does not create sharing rules or per-record `AgentWorkShare` rows.
+- It cannot prove a particular supervisor's complete UI access; validate the end-to-end Command Center journey with the intended supervisor user after configuration.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | Before approving the org-wide change or diagnosing a retrieve/deploy failure |

package/skills/service-omni-agent-work-sharing-configure/references/api-notes.md

@@ -0,0 +1,31 @@
+# AgentWork sharing API notes
+
+## Supported contract
+
+`AgentWork` is a standard object whose organization-wide defaults round-trip through the `CustomObject` Metadata API representation:
+
+```xml
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <externalSharingModel>Private</externalSharingModel>
+    <sharingModel>Read</sharingModel>
+</CustomObject>
+```
+
+Retrieve with `CustomObject:AgentWork`. A deployment must preserve the retrieved `externalSharingModel`; only the internal `sharingModel` is changed.
+
+## Access semantics
+
+- `Private`: object permissions alone do not make every AgentWork record readable.
+- `Read`: Public Read Only for internal access.
+- `ReadWrite`: already includes read access, so this skill leaves it unchanged instead of narrowing access.
+
+Object permissions, supervisor permissions, and supervisor configuration filters still apply. An OWD change does not grant object permission and does not select which reps appear in Command Center.
+
+## Verification
+
+A successful deploy response is insufficient. Retrieve `CustomObject:AgentWork` again and require:
+
+- `sharingModel=Read` after a change.
+- `externalSharingModel` equal to its pre-deploy value.
+
+After metadata verification, sign in as the intended supervisor and validate that the expected work is visible and unrelated supervisor scopes remain filtered correctly.