@botbuddy/cli 1.64.33 → 1.65.0

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.33",
-  "source_commit": "644a0f64f3b74a556a821c8a8997ea4e8910f282",
-  "source_sha256": "1da5f11e7e2200acf29d273111d3550497ea0fa16ea3a570083273995c9d22de",
+  "release_version": "1.65.0",
+  "source_commit": "be92b3792490c1097c679ddd9a8ae52b3e5e6bf2",
+  "source_sha256": "74e6ce7639343fa57b8faa8d4082eeb7bdd0267b8335b2768c09477fd3e032e0",
   "target": "darwin-arm64",
-  "sha256": "49b0b67a0e368a26b4f205881120a4dbc114e246e84413d77c108adbbd0ec8de"
+  "sha256": "94a46209aebe5086ddf8dbd6c6c6588fa700bc56ec9b013ff3a56aba08cafbc0"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.64.33",
-  "source_commit": "644a0f64f3b74a556a821c8a8997ea4e8910f282",
-  "source_sha256": "1da5f11e7e2200acf29d273111d3550497ea0fa16ea3a570083273995c9d22de",
+  "release_version": "1.65.0",
+  "source_commit": "be92b3792490c1097c679ddd9a8ae52b3e5e6bf2",
+  "source_sha256": "74e6ce7639343fa57b8faa8d4082eeb7bdd0267b8335b2768c09477fd3e032e0",
   "target": "linux-x64",
-  "sha256": "75b79c530c451304354c4bdffe23f373a7de6824f203cba9a7acb7e1bc0cfb2e"
+  "sha256": "7efa17f7d96f9be166a0589f8634a72825e8886707a92b837b98731a81fdb5de"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.64.33",
-  "source_commit": "644a0f64f3b74a556a821c8a8997ea4e8910f282",
-  "source_sha256": "1da5f11e7e2200acf29d273111d3550497ea0fa16ea3a570083273995c9d22de",
+  "release_version": "1.65.0",
+  "source_commit": "be92b3792490c1097c679ddd9a8ae52b3e5e6bf2",
+  "source_sha256": "74e6ce7639343fa57b8faa8d4082eeb7bdd0267b8335b2768c09477fd3e032e0",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "49b0b67a0e368a26b4f205881120a4dbc114e246e84413d77c108adbbd0ec8de",
+      "sha256": "94a46209aebe5086ddf8dbd6c6c6588fa700bc56ec9b013ff3a56aba08cafbc0",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "75b79c530c451304354c4bdffe23f373a7de6824f203cba9a7acb7e1bc0cfb2e",
+      "sha256": "7efa17f7d96f9be166a0589f8634a72825e8886707a92b837b98731a81fdb5de",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.64.33",
-  "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
+  "version": "1.65.0",
+  "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {
     "bb": "./bin/botbuddy.mjs",

package/src/api.mjs

@@ -415,6 +415,8 @@ export function containerHostRegisterEndpoint(serverUrl = SERVER_URL) {
  */
 export function registerContainerHost(body, options = {}) { return postContainerHostControl(body, options, "register", "container_host_register"); }
 export function daemonHandoverRequest(body, options = {}) { return postContainerHostControl(body, options, "handover", "daemon_handover"); }
+// BOT-3127: the owner-only automatic-update describe read (same auth as handover).
+export function daemonAutomaticUpdateRequest(body, options = {}) { return postContainerHostControl(body, options, "automatic-update", "daemon_handover"); }
 async function postContainerHostControl(body, {
   fetchImpl = fetch,
   auth: pinnedAuth = null,

package/src/daemon/automatic.mjs

@@ -1,4 +1,4 @@
-import { callToolJson, resolveCallAuth } from "../api.mjs";
+import { callToolJson, daemonAutomaticUpdateRequest, resolveCallAuth } from "../api.mjs";
 import {
   assertSshHost,
   installedBinaryPath,
@@ -11,13 +11,20 @@ const fail = (code) => {
 };
 // One explicit administrator installation grants only the fixed native
 // coordinator/schedule. Persisted operator opt-in remains a separate drawer act.
+// BOT-3127: user-scoped. The spec names no tenant; the host's owner asks the
+// server for the host's inert rollout label and the root binding pins that.
 export async function installAutomaticDaemonUpdater(spec, {
   validateRelease = validateDaemonRelease,
   resolveAuth = resolveCallAuth,
   identity = callToolJson,
+  describe = daemonAutomaticUpdateRequest,
   stage = stageRemoteDaemonRelease,
   native = nativeHandoverCommand,
 } = {}) {
+  if (spec && typeof spec === "object" && Object.hasOwn(spec, "tenant")) {
+    // Automatic updates belong to the host's owner, not a project.
+    fail("daemon_automatic_install_tenant_not_used");
+  }
   if (
     !spec || typeof spec !== "object" || Array.isArray(spec) ||
     Object.keys(spec).some((key) =>
@@ -28,13 +35,11 @@ export async function installAutomaticDaemonUpdater(spec, {
         "serviceUser",
         "releaseRoot",
         "expectedHostKey",
-        "tenant",
       ].includes(key)
     ) || !["linux", "darwin"].includes(spec.platform) ||
     typeof spec.serviceUser !== "string" || spec.serviceUser === "root" ||
     !/^[a-z_][a-z0-9_-]*$/i.test(spec.serviceUser) ||
-    !/^bbh-[0-9a-f]{24}$/.test(spec.expectedHostKey) ||
-    typeof spec.tenant !== "string" || !spec.tenant
+    !/^bbh-[0-9a-f]{24}$/.test(spec.expectedHostKey)
   ) fail("daemon_automatic_install_spec_invalid");
   assertSshHost(spec.sshHost);
   const release = await validateRelease({ releaseRoot: spec.releaseRoot }, {
@@ -48,14 +53,30 @@ export async function installAutomaticDaemonUpdater(spec, {
   if (resolved?.error || !resolved?.auth) {
     fail("daemon_automatic_install_auth_required");
   }
-  const who = await identity("whoami", {}, {
-    auth: resolved.auth,
-    tenant: spec.tenant,
-  });
+  const who = await identity("whoami", {}, { auth: resolved.auth });
   if (
     !who?.ok || who.isError || typeof who.data?.owner_email !== "string" ||
-    !who.data.owner_email.includes("@") || who.data.tenant_id !== spec.tenant
+    !who.data.owner_email.includes("@")
   ) fail("daemon_automatic_install_owner_unavailable");
+  const described = await describe({
+    action: "describe",
+    host_key: spec.expectedHostKey,
+  }, { auth: resolved.auth });
+  const owner = described?.data?.owner_email, label = described?.data?.tenant_id;
+  if (
+    !described?.ok || described.data?.success !== true ||
+    described.data.host_key !== spec.expectedHostKey ||
+    typeof owner !== "string" || owner.toLowerCase() !== who.data.owner_email.toLowerCase() ||
+    typeof label !== "string" || !label
+  ) {
+    // A 4xx answer carries its code in `error` (e.g. daemon_host_scope).
+    const code = described?.data?.code ?? described?.error;
+    fail(
+      typeof code === "string" && /^(?:[A-Z_]{1,64}|[a-z_]{1,64})$/.test(code)
+        ? `daemon_automatic_install_owner_refused: ${code}`
+        : "daemon_automatic_install_owner_refused",
+    );
+  }
   const staged = await stage({
     platform: spec.platform,
     host: spec.sshHost,
@@ -70,8 +91,8 @@ export async function installAutomaticDaemonUpdater(spec, {
     mode: "automatic-install",
     input: {
       host_key: spec.expectedHostKey,
-      owner_email: who.data.owner_email,
-      tenant_id: who.data.tenant_id,
+      owner_email: owner,
+      tenant_id: label,
     },
   });
   if (result?.installed !== true || result.protocol !== 2) {

package/src/pw/staging-auth.mjs

@@ -74,8 +74,10 @@ const realm = 'const G = page.constructor.constructor("return globalThis")();';
 // (a Playwright storage state holding exactly the bound origin + one supabase-js
 // key), check it is the persona's unexpired aal2 session, write it to the origin's
 // localStorage and reload the lane's pages on it. Returns no session material.
-export function installCode({ statePath, origin, storageKey, email }) {
-  const args = { statePath, origin, storageKey, email };
+// BOT-3145: requiredAuth comes from the persona's binding sign-in kind (sign-in-kinds.mjs
+// requiredAuthFor): { aal: "aal2" } for password + TOTP, { amr: "sso/saml" } for okta-saml.
+export function installCode({ statePath, origin, storageKey, email, requiredAuth = { aal: "aal2" } }) {
+  const args = { statePath, origin, storageKey, email, requiredAuth };
   return `async (page) => {
   ${realm}
   const args = ${j(args)};
@@ -97,7 +99,10 @@ export function installCode({ statePath, origin, storageKey, email }) {
   } catch {
     return { ok: false, code: "slot_state_unreadable" };
   }
-  if (claims.aal !== "aal2") return { ok: false, code: "session_not_aal2" };
+  if (args.requiredAuth.amr) {
+    const methods = Array.isArray(claims.amr) ? claims.amr.map((entry) => entry && entry.method ? entry.method : String(entry)) : [];
+    if (!methods.includes(args.requiredAuth.amr)) return { ok: false, code: "session_not_sso" };
+  } else if (claims.aal !== "aal2") return { ok: false, code: "session_not_aal2" };
   if (String(claims.email ?? "").toLowerCase() !== args.email) return { ok: false, code: "session_persona_mismatch" };
   if (typeof claims.exp !== "number" || claims.exp * 1000 <= Date.now() + 60000) return { ok: false, code: "session_expired" };
   try {
@@ -330,6 +335,7 @@ export async function runStagingAuth({ plan, host, env, deps, socketRun, resolve
   const persona = findPersona(found.binding, plan.persona);
   if (!persona) return refuse(io, "persona_not_allowlisted", 2, {}, vars);
   const { stagingTargetFromBinding } = await import("../staging-pool/policy.mjs");
+  const { requiredAuthFor } = await import("../staging-pool/sign-in-kinds.mjs");
   const bound = stagingTargetFromBinding(found.binding);
   // deps.stagingAuthTarget is a test-only seam (a loopback page for the real-daemon
   // test); no flag or environment variable can redirect the install origin.
@@ -375,7 +381,7 @@ export async function runStagingAuth({ plan, host, env, deps, socketRun, resolve
   }
   let installed;
   try {
-    installed = await ctx.run(installCode({ statePath: claim.taken.statePath, origin: target.origin, storageKey: target.storageKey, email: persona.email }));
+    installed = await ctx.run(installCode({ statePath: claim.taken.statePath, origin: target.origin, storageKey: target.storageKey, email: persona.email, requiredAuth: requiredAuthFor(persona.signIn) }));
   } finally {
     // Single use either way: the slot never outlives this command.
     await claim.discard().catch(() => {});

package/src/staging-pool/binding.mjs

@@ -6,6 +6,8 @@
 // is never read from a repository checkout. Node-stdlib-only and self-contained:
 // the installed job keeps a validated snapshot in its config.
 
+import { parseSignIn } from "./sign-in-kinds.mjs";
+
 export class BindingError extends Error {
   constructor(message, code = "pool_binding_invalid") {
     super(message);
@@ -84,7 +86,10 @@ export function parsePoolBinding(raw) {
     need(typeof persona.password_env === "string" && ENV_RE.test(persona.password_env), `persona ${alias} needs password_env (an UPPER_SNAKE env var name in password_env_file)`);
     const count = persona.default_count ?? 1;
     need(Number.isInteger(count) && count >= 0 && count <= MAX_POOL_SIZE, `persona ${alias} default_count must be 0-${MAX_POOL_SIZE}`);
-    parsedPersonas[alias] = Object.freeze({ alias, email: persona.email, passwordEnv: persona.password_env, defaultCount: count });
+    // BOT-3145: an optional sign_in block (absent = password + TOTP, unchanged).
+    const signIn = parseSignIn(persona.sign_in);
+    need(signIn.ok, `persona ${alias} ${signIn.ok ? "" : signIn.message}`);
+    parsedPersonas[alias] = Object.freeze({ alias, email: persona.email, passwordEnv: persona.password_env, defaultCount: count, signIn: signIn.signIn });
   }
   return Object.freeze({
     tenant: raw.tenant,

package/src/staging-pool/cli.mjs

@@ -25,6 +25,7 @@ import * as nodeFs from "node:fs/promises";
 import { readFileSync, readdirSync, realpathSync } from "node:fs";
 import { homedir, userInfo } from "node:os";
 import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 
@@ -35,7 +36,10 @@ import { buildLaunchAgentPlist, createLaunchctl } from "./launchd.mjs";
 import { createEnvFilePasswordSource } from "./password-source.mjs";
 import { MintRefusedError, assertMintAllowed, assertPersonaAllowed, listProcessAncestors, stagingTargetFromBinding } from "./policy.mjs";
 import { PoolEmptyError, createSessionPool } from "./pool.mjs";
+import { SIGN_IN_KINDS } from "./sign-in-kinds.mjs";
+import { createBindingSignIn, signInLookup } from "./signin-dispatch.mjs";
 import { createGoTrueTotpSignIn } from "./signin-gotrue-totp.mjs";
+import { createOktaSamlSignIn, loadOrCreateHoldKey } from "./signin-okta-saml.mjs";
 import { createRedactor } from "./state-file.mjs";
 import { createBotBuddyTotpProvider, probeBotBuddy } from "./totp-botbuddy.mjs";
 import { HUMAN_ONLY_COMMANDS, formatGuidance, guidance, installLine, isKnownCode, remedyLine } from "./errors.mjs";
@@ -58,14 +62,18 @@ export const BUNDLE_FILES = Object.freeze([
   "pool.mjs",
   "registry.mjs",
   "refresh-runtime.mjs",
+  "okta-steps.mjs",
+  "sign-in-kinds.mjs",
+  "signin-dispatch.mjs",
   "signin-gotrue-totp.mjs",
+  "signin-okta-saml.mjs",
   "state-file.mjs",
   "take-outbox.mjs",
   "totp-botbuddy.mjs",
 ]);
 
 const VALUE_FLAGS = new Set(["persona", "home", "botbuddy-bin", "interval", "owner", "tenant", "pool"]);
-const BOOLEAN_FLAGS = new Set(["keep-sessions", "help", "check"]);
+const BOOLEAN_FLAGS = new Set(["keep-sessions", "help", "check", "retry-held"]);
 
 export function parseArgs(argv) {
   const [command, ...rest] = argv;
@@ -174,22 +182,55 @@ function reasonsFor(ctx) {
   return healthReasons(guidanceVars(ctx));
 }
 
+const neverMint = async () => {
+  throw new Error("take/status never mint");
+};
+
+// BOT-3145: true when the binding names at least one okta-saml persona.
+function hasOktaPersonas(binding) {
+  return Object.values(binding?.personas ?? {}).some((persona) => persona.signIn?.kind === SIGN_IN_KINDS.OKTA_SAML);
+}
+
+// take/status refresh slots (take-time liveness) but never sign in: every adapter's
+// credential and browser inputs throw.
+function refreshOnlySignIn({ ctx, fetchImpl, logger, sleep, now }) {
+  const binding = ctx.poolBinding;
+  return createBindingSignIn({
+    binding,
+    totp: createGoTrueTotpSignIn({ fetchImpl, totpProvider: neverMint, passwordFor: neverMint, logger, sleep, nowMs: now }),
+    okta: hasOktaPersonas(binding)
+      ? createOktaSamlSignIn({
+        fetchImpl,
+        launchBrowser: neverMint,
+        passwordFor: neverMint,
+        signInFor: signInLookup(binding),
+        holdSecret: () => {
+          throw new Error("take/status never mint");
+        },
+        logger,
+        sleep,
+        nowMs: now,
+      })
+      : undefined,
+  });
+}
+
+// BOT-3145: the job's Chromium for an okta-saml sign-in. The installed runtime copy has no
+// node_modules (the bundle stays builtins-only), so playwright is required at sign-in time from
+// the installed @botbuddy/cli package (the botbuddyBin the human installed with), which declares
+// it as a dependency. Nothing a caller passes chooses the module.
+export function createPackagedBrowserLauncher({ botbuddyBin, requireFrom = createRequire }) {
+  return async function launchBrowser() {
+    const { chromium } = requireFrom(botbuddyBin)("playwright");
+    return chromium.launch({ headless: true });
+  };
+}
+
 function buildPool({ ctx, target, signIn, now, logger, intervalSeconds, fetchImpl, sleep }) {
   return createSessionPool({
     poolDir: ctx.paths.pool,
     target,
-    signIn: signIn ?? createGoTrueTotpSignIn({
-      fetchImpl,
-      totpProvider: async () => {
-        throw new Error("take/status never mint");
-      },
-      passwordFor: async () => {
-        throw new Error("take/status never mint");
-      },
-      logger,
-      sleep,
-      nowMs: now,
-    }),
+    signIn: signIn ?? refreshOnlySignIn({ ctx, fetchImpl, logger, sleep, now }),
     now,
     logger,
     ...(intervalSeconds ? { intervalMs: intervalSeconds * 1000 } : {}),
@@ -493,7 +534,7 @@ export async function runStagingPool(argv, deps = {}) {
       redactor.register(value);
       return value;
     };
-    return createGoTrueTotpSignIn({
+    const totp = createGoTrueTotpSignIn({
       fetchImpl,
       totpProvider: createBotBuddyTotpProvider({ exec, botbuddyBin, env, tenant: binding.tenant, appSlug: binding.appSlug }),
       passwordFor,
@@ -501,6 +542,20 @@ export async function runStagingPool(argv, deps = {}) {
       sleep,
       nowMs: now,
     });
+    // BOT-3145: okta-saml personas sign in through the IdP in the job's headless Chromium.
+    const okta = hasOktaPersonas(binding)
+      ? createOktaSamlSignIn({
+        fetchImpl,
+        launchBrowser: deps.launchBrowser ?? createPackagedBrowserLauncher({ botbuddyBin }),
+        passwordFor,
+        signInFor: signInLookup(binding),
+        holdSecret: () => loadOrCreateHoldKey(join(ctx.paths.root, "credential-hold.key")),
+        logger: emit,
+        sleep,
+        nowMs: now,
+      })
+      : undefined;
+    return createBindingSignIn({ binding, totp, okta });
   }
 
   function requireBotbuddyBin(options) {
@@ -642,7 +697,7 @@ export async function runStagingPool(argv, deps = {}) {
       const persona = entry ? entry.email : assertPersonaAllowed(target, options.persona);
       if (!ctx.installed || ctx.installed.error) throw ctx.installed?.error ?? new ConfigError("The pool job is not installed; the human runs the install first.", "pool_not_installed");
       const pool = buildPool({ ctx, target, signIn: minterFor(ctx, target), now, logger: emit, intervalSeconds: ctx.installed.intervalSeconds, fetchImpl, sleep });
-      const minted = await pool.mintOne({ persona });
+      const minted = await pool.mintOne({ persona, retryHeld: options["retry-held"] === true });
       emit({ ok: true, command: "mint-one", target: target.name, signIns: 1, ...minted.meta });
       return 0;
     },

package/src/staging-pool/errors.mjs

@@ -93,6 +93,10 @@ export const ERROR_CODES = Object.freeze({
     "The pool's session for {persona} is no longer AAL2, so it was discarded.",
     "The persona's TOTP factor was rotated (the staging seed job ran) after the session was minted.",
     `${AUTH}   # once; the next ready slot is fresh. If it repeats, report this code`, "retry_once"),
+  session_not_sso: entry("agent", "take",
+    "The pool's session for {persona} is not an SSO (sso/saml) session, so it was discarded.",
+    "The persona's binding says okta-saml, but the slot holds another kind of session (the binding changed after it was minted).",
+    `${AUTH}   # once; the next ready slot is fresh. If it repeats, report this code`, "retry_once"),
   session_expired: entry("agent", "take",
     "The pool's session for {persona} had expired, so it was discarded.",
     "The pool job has not refreshed recently (the Mac slept or the job stopped).",
@@ -177,6 +181,18 @@ export const ERROR_CODES = Object.freeze({
     "Staging sign-in for {persona} keeps failing, so the job is backing off.",
     "The last mint_failed line in {log} names it: password_rejected or no_verified_totp_factor = seed drift; mint_retries_exhausted = a staging Auth outage, so wait for the next attempt; password_source_* = the password env file; totp_source_failed = the botbuddy CLI login.",
     "grep mint_failed {log} | tail -1   # then run bb help symptom with the code that line names"),
+  credential_held: entry("human", "repair",
+    "The job holds {persona}: its IdP refused, or never confirmed, the configured password, so the job will not submit it again.",
+    "The password in {envFile} is wrong or stale. Re-submitting it would lock the shared IdP test user out (and the tenant's CI with it). The last mint_failed line in {log} names okta_password_rejected or okta_password_unconfirmed.",
+    "grep mint_failed {log} | tail -1   # fix the persona's password variable in {envFile} (the hold clears when the value changes); if the password was right, check the IdP user, then retry once: bb staging-pool mint-one --persona {persona} --retry-held"),
+  credential_hold_unavailable: entry("human", "repair",
+    "The job could not compute a credential hold for {persona}, so it signed nothing in (a refused password must always be holdable).",
+    "The pool's credential-hold.key is unreadable or corrupt (under 32 bytes).",
+    "ls -l {poolHome}/credential-hold.key   # restore read access; if it is corrupt, remove it (recorded holds are then lost: check the IdP user first), then: bb staging-pool mint-one --persona {persona}"),
+  health_unreadable: entry("human", "repair",
+    "The pool's health.json is unreadable, so the job signs nothing in: it may hold a credential hold.",
+    "The file was truncated or its permissions changed.",
+    "ls -l {poolHome}/pool/health.json   # repair or restore it (removing it drops any credential hold: check the IdP user first), then: {tickCommand}"),
   last_tick_failed: entry("human", "repair",
     "The pool job's last tick had sign-in (mint) failures.",
     "The last mint_failed line in {log} names the cause.",
@@ -334,10 +350,88 @@ export const ERROR_CODES = Object.freeze({
     "The persona's factor is not verified, or Auth's MFA settings changed.",
     "bb staging-pool probe   # after re-running the staging persona seed"),
   persona_mismatch: entry("human", "repair",
-    "MFA verify returned a session for a different user.",
+    "Sign-in returned a session for a different user.",
     "The binding's persona email does not match the seeded user.",
     "botbuddy call get_staging_pool --pin {tenant}   # check the registered personas, then: bb staging-pool mint-one --persona {persona}"),
 
+  // ── BOT-3145: okta-saml personas (signin-okta-saml.mjs). The job, never an agent, signs in.
+  okta_password_rejected: entry("human", "repair",
+    "Okta rejected {persona}'s configured password; the job holds the persona until the value changes.",
+    "The password variable in {envFile} is wrong or stale (the IdP test user's password was rotated).",
+    "grep mint_failed {log} | tail -1   # update the variable in {envFile}, then: bb staging-pool mint-one --persona {persona}"),
+  okta_password_unconfirmed: entry("human", "repair",
+    "Okta kept its sign-in form after {persona}'s password was submitted, with no error the job recognises; it is held like a rejection.",
+    "A wrong password in markup the job has not seen, or an Okta page change. The okta_page_state line in {log} shows the value-free screen.",
+    "grep okta_page_state {log} | tail -1   # check the password in {envFile} (the hold clears when it changes), then: bb staging-pool mint-one --persona {persona}"),
+  okta_account_locked: entry("human", "repair",
+    "Okta reports {persona} as locked or suspended.",
+    "Too many failed sign-ins (from any client), or an Okta admin suspended the user.",
+    "grep mint_failed {log} | tail -1   # unlock the user in the Okta admin console, then retry once: bb staging-pool mint-one --persona {persona} --retry-held"),
+  okta_mfa_prompt: entry("human", "repair",
+    "Okta asked {persona} for a second factor; the pool signs in with a password only.",
+    "The Okta app's authentication policy now requires MFA for this user.",
+    "grep okta_page_state {log} | tail -1   # make the Okta app's sign-on policy password-only for the test user, then: bb staging-pool mint-one --persona {persona}"),
+  okta_saml_relay_expired: entry("human", "repair",
+    "GoTrue refused the SAML callback because its RelayState expired.",
+    "Okta answered too slowly (over GoTrue's relay window). The job retries on its next attempt.",
+    "grep mint_failed {log} | tail -1   # repeated: bb staging-pool mint-one --persona {persona}"),
+  okta_timeout: entry("human", "repair",
+    "No SAML callback reached GoTrue's ACS in time after the Okta steps.",
+    "Okta or staging Auth is slow or down. The okta_page_state line in {log} shows where it stopped.",
+    "grep okta_page_state {log} | tail -1   # then: bb staging-pool mint-one --persona {persona}"),
+  okta_steps_failed: entry("human", "repair",
+    "The Okta sign-in steps did not complete (the username or password field never appeared).",
+    "An Okta outage, or an Okta sign-in widget change the pinned selectors do not match.",
+    "grep okta_page_state {log} | tail -1   # report it with the CLI version (bb version)"),
+  okta_unreachable: entry("human", "repair",
+    "The job's browser could not reach Okta.",
+    "No network, a proxy, or an Okta outage.",
+    "grep mint_failed {log} | tail -1   # then: bb staging-pool mint-one --persona {persona}"),
+  okta_unexpected_host: entry("human", "repair",
+    "The SSO sign-in led to a host that is not the registered IdP host, so the job typed nothing.",
+    "The tenant's SSO provider for this domain changed, or the binding's sign_in.idp_host is wrong.",
+    "botbuddy call get_staging_pool --pin {tenant}   # compare sign_in.idp_host with the provider; the tenant re-registers its binding"),
+  okta_browser_unavailable: entry("human", "repair",
+    "The job could not start headless Chromium for an Okta sign-in.",
+    "Playwright's Chromium is not installed for the CLI's playwright version.",
+    "npm exec --yes --package=playwright@\"$(npm view @botbuddy/cli dependencies.playwright)\" -- playwright install chromium   # then: bb staging-pool mint-one --persona {persona}"),
+  okta_target_unsupported: entry("human", "repair",
+    "Okta SAML personas sign in on staging only.",
+    "A local (loopback) target has no SAML service provider.",
+    "bb staging-pool mint-one --persona {persona}   # against the installed staging pool"),
+  okta_adapter_unavailable: entry("human", "repair",
+    "This job was built without the Okta sign-in adapter.",
+    "A runtime older than the binding's okta-saml persona.",
+    "bb update   # refreshes the pool runtime, then: bb staging-pool mint-one --persona {persona}"),
+  wrong_sign_in_kind: entry("human", "repair",
+    "The Okta adapter was asked to sign in a persona that is not okta-saml.",
+    "An internal routing error.",
+    "bb staging-pool status   # report this code with the CLI version (bb version)"),
+  sso_begin_failed: entry("human", "repair",
+    "Staging Auth refused to start SSO for the persona's domain.",
+    "No SSO provider is assigned to sign_in.sso_domain on staging, or Auth is down; {log} has the status.",
+    "grep mint_failed {log} | tail -1   # then: bb staging-pool mint-one --persona {persona}"),
+  sso_callback_error: entry("human", "repair",
+    "GoTrue answered the SAML callback with an error or without a session.",
+    "The SSO provider's certificate or attribute mapping changed on staging; {log} has GoTrue's error code.",
+    "grep mint_failed {log} | tail -1   # then: bb staging-pool mint-one --persona {persona}"),
+  sso_acs_not_intercepted: entry("human", "repair",
+    "The SAML callback reached the app without passing GoTrue's ACS route, so the session was not stored.",
+    "Staging Auth's ACS path changed.",
+    "grep mint_failed {log} | tail -1   # report this code with the CLI version (bb version)"),
+  sso_user_unreadable: entry("human", "repair",
+    "Staging Auth would not return the user for the new SSO session.",
+    "An Auth outage or a revoked session; {log} has the status.",
+    "grep mint_failed {log} | tail -1   # then: bb staging-pool mint-one --persona {persona}"),
+  sso_admission_failed: entry("human", "repair",
+    "The tenant's admission function did not admit {persona} as a member.",
+    "The persona lost its organisation membership on staging, or the function's contract changed; {log} has its outcome and route.",
+    "grep mint_failed {log} | tail -1   # restore the persona's membership, then: bb staging-pool mint-one --persona {persona}"),
+  not_sso_session: entry("human", "repair",
+    "The SSO sign-in returned a session without the sso/saml method.",
+    "Staging Auth's SSO configuration changed.",
+    "grep mint_failed {log} | tail -1   # report this code with the CLI version (bb version)"),
+
   unexpected_error: entry("agent", "codes",
     "bb staging-pool failed unexpectedly (see detail).",
     "An error outside the known cases.",
@@ -348,7 +442,7 @@ export const ERROR_CODES = Object.freeze({
 export const AUTH_ONLY_CODES = Object.freeze(new Set([
   "auth_requires_staging_environment", "auth_requires_lane_lock", "lane_not_claimed", "exact_lane_holder_required",
   "tenant_binding_required", "persona_not_allowlisted", "lane_browser_not_open", "browser_session_not_staging", "persistent_profile_refused",
-  "session_install_failed", "staging_session_cleanup_pending", "session_not_aal2", "session_expired",
+  "session_install_failed", "staging_session_cleanup_pending", "session_not_aal2", "session_not_sso", "session_expired",
   "session_persona_mismatch", "slot_state_invalid", "slot_state_unreadable", "daemon_node_unsupported",
   "daemon_run_failed", "daemon_result_missing", "daemon_result_invalid", "pool_take_failed", "pool_empty", "pool_refill_unavailable",
 ]));

package/src/staging-pool/fixtures/2026-10-14-okta-sso-signin.json

@@ -0,0 +1,68 @@
+{
+  "_captured": "2026-10-14 by ENT-5553 (agent session, read-only: no credential, username or OTP was typed anywhere). Two real sources: (1) the staging GoTrue + edge logs and auth schema for the green daily real-Okta CI run 38518046301 (sso-staging-regression.yml, 2026-10-14T05:42Z), which signed sso-convert-acceptance in through Okta; (2) a headless, input-free load of the Okta tenant's public sign-in page and its /.well-known/okta-organization. The password, error and factor-challenge screens cannot be captured without typing a credential, so they are NOT in this file: their selectors are the ones the shared okta-steps.mjs already drives green every day in CI, and every classified or unclassified Okta failure in the pool job logs a value-free okta_page_state line so the first real failure supplies its capture. Recapture when okta.widgetVersion or the GoTrue version changes.",
+  "okta": {
+    "host": "integrator-4707698.okta.com",
+    "wellKnown": { "status": 200, "pipeline": "idx", "cell": "ok14" },
+    "widgetVersion": "7.50.0",
+    "identifierScreen": {
+      "title": "supply-guard-integrator-4707698 - Sign In",
+      "inputs": [
+        { "type": "hidden", "name": "fromURI" },
+        { "type": "text", "name": "identifier" },
+        { "type": "checkbox", "name": "rememberMe" },
+        { "type": "submit", "value": "Next" }
+      ],
+      "dataSe": [
+        "auth-container",
+        "o-form",
+        "o-form-content",
+        "o-form-head",
+        "o-form-error-container",
+        "o-form-fieldset-container",
+        "o-form-fieldset-identifier",
+        "o-form-input-identifier",
+        "o-form-fieldset-rememberMe",
+        "help"
+      ],
+      "visibleHeading": "Sign In",
+      "hiddenHeadingsInDom": ["The page has timed out"]
+    }
+  },
+  "gotrue": {
+    "version": "staging, 2026-10-14",
+    "ssoBegin": {
+      "request": "POST https://ikdoydgubernmxzdqtxz.supabase.co/auth/v1/sso",
+      "status": 200,
+      "at": "2026-10-14T05:43:32.877Z",
+      "notFoundError": {
+        "status": 404,
+        "body": { "error_code": "sso_provider_not_found", "msg": "No SSO provider assigned for this domain" }
+      }
+    },
+    "acs": {
+      "request": "POST https://staging-api.supply-guard.io/auth/v1/sso/saml/acs",
+      "status": 302,
+      "at": "2026-10-14T05:43:37.323Z",
+      "secondsAfterBegin": 4.4,
+      "errorRedirect": {
+        "_source": "staging auth + edge logs 2026-10-14T16:48:04Z-16:48:38Z: three POSTs of a junk SAMLResponse with a non-UUID RelayState, sent by mistake by ENT-5553's loopback acceptance harness before it pinned Playwright's route.fetch to loopback. GoTrue rejected each before any flow or session state.",
+        "status": 303,
+        "authLogError": "400: SAML RelayState is not a valid UUID or URL"
+      },
+      "authEvent": {
+        "action": "login",
+        "actor_username": "sso-convert-acceptance@okta-e2e.supplyguard.test",
+        "actor_via_sso": true,
+        "traits": { "provider": "sso:c3580884-a8f1-4288-b018-3ee8495d6fdb" }
+      }
+    },
+    "persona": {
+      "email": "sso-convert-acceptance@okta-e2e.supplyguard.test",
+      "is_sso_user": true,
+      "provider": "sso:c3580884-a8f1-4288-b018-3ee8495d6fdb",
+      "mfaFactors": 0,
+      "membership": { "organization_id": "34650000-0000-4000-8000-000000000001", "role": "admin" },
+      "session": { "aal": "aal1", "amr": ["sso/saml"] }
+    }
+  }
+}

package/src/staging-pool/health.mjs

@@ -9,11 +9,13 @@ import { guidance, remedyLine } from "./errors.mjs";
 export const HEALTH_REASON_CODES = Object.freeze([
   "config_invalid", "persona_not_configured", "job_not_loaded", "no_tick_yet", "tick_stale",
   "mint_backing_off", "last_tick_failed", "ticks_failing", "persona_below_target",
+  // BOT-3145: an IdP-refused password held until it changes; a health.json that cannot be read.
+  "credential_held", "health_unreadable",
 ]);
 
 // report_blocker → state the reason + remedy to the human ONCE and stop.
-export function healthReasons({ label, log, installCommand, docs, configPath, tickCommand, checkout, persona }) {
-  const vars = { label, log, installCommand, docs, configPath, tickCommand, checkout, persona };
+export function healthReasons({ label, log, installCommand, docs, configPath, tickCommand, checkout, persona, envFile, poolHome }) {
+  const vars = { label, log, installCommand, docs, configPath, tickCommand, checkout, persona, envFile, poolHome };
   return Object.freeze(Object.fromEntries(HEALTH_REASON_CODES.map((code) => {
     const g = guidance(code, vars, { real: true });
     return [code, Object.freeze({ agentAction: g.agent_action, remedy: remedyLine(g), vars })];
@@ -48,6 +50,8 @@ export function assessPoolHealth({ status, personas, intervalSeconds, nowMs, job
   if (requestedPersona && Object.keys(personas).length > 0 && !(personas[requestedPersona] > 0)) {
     return unhealthy("persona_not_configured", { persona: requestedPersona });
   }
+  // BOT-3145: a health.json the job cannot read stops every okta-saml sign-in (fail closed).
+  if (status?.health?.unreadable) return unhealthy("health_unreadable");
   const lastTick = status?.lastTick;
   if (!lastTick?.at) return unhealthy("no_tick_yet");
   if (nowMs - Date.parse(lastTick.at) > STALE_INTERVALS * intervalMs) {
@@ -58,6 +62,11 @@ export function assessPoolHealth({ status, personas, intervalSeconds, nowMs, job
   const scope = requestedPersona ? [requestedPersona] : Object.keys(personas);
   for (const persona of scope) {
     const entry = personaHealth[persona];
+    // BOT-3145: the IdP refused (or never confirmed) this persona's password; nothing retries
+    // it until the human changes the value, so waiting cannot fix it.
+    if (entry?.credentialHeld) {
+      return unhealthy("credential_held", { persona, detail: `last ${entry.lastMintError ?? "unknown"}` });
+    }
     if (entry?.nextMintAttemptAt && Date.parse(entry.nextMintAttemptAt) > nowMs) {
       return unhealthy("mint_backing_off", {
         persona,