@botbuddy/cli 1.60.6 → 1.60.7

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.6",
-  "source_commit": "ae130a31e09d0752d2f395aac02d51fa89e0c93f",
-  "source_sha256": "7c1fe3ec9d1d28f25c665e4f607690dc512fabf0a9f1eebaf1c86e1611382edf",
+  "release_version": "1.60.7",
+  "source_commit": "6299d1f0f325871a33f5aa28bff8dc8029e7350c",
+  "source_sha256": "ac9f92aeaec3cf0cb18de06f1e16b0ee2c44c413ec7c84866f949909611098f1",
   "target": "darwin-arm64",
-  "sha256": "2cd38dbe8411dd7499107065d3c526bd171f9edc37bc820aa79ab2c5cead27ec"
+  "sha256": "1e24ee9c3fa9ac6447ff9f0c8096d80c4e2a98348d0e3b0277d406dfe8109e17"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.60.6",
-  "source_commit": "ae130a31e09d0752d2f395aac02d51fa89e0c93f",
-  "source_sha256": "7c1fe3ec9d1d28f25c665e4f607690dc512fabf0a9f1eebaf1c86e1611382edf",
+  "release_version": "1.60.7",
+  "source_commit": "6299d1f0f325871a33f5aa28bff8dc8029e7350c",
+  "source_sha256": "ac9f92aeaec3cf0cb18de06f1e16b0ee2c44c413ec7c84866f949909611098f1",
   "target": "linux-x64",
-  "sha256": "4d422182d63d0ee3ac38bf2823d255fd059ca5195efda355681e8f94137eaf7a"
+  "sha256": "68dfb56ddf1b4647dcd00644d88489fe2022b4136d72443e33f83a86ecb270bb"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.60.6",
-  "source_commit": "ae130a31e09d0752d2f395aac02d51fa89e0c93f",
-  "source_sha256": "7c1fe3ec9d1d28f25c665e4f607690dc512fabf0a9f1eebaf1c86e1611382edf",
+  "release_version": "1.60.7",
+  "source_commit": "6299d1f0f325871a33f5aa28bff8dc8029e7350c",
+  "source_sha256": "ac9f92aeaec3cf0cb18de06f1e16b0ee2c44c413ec7c84866f949909611098f1",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "2cd38dbe8411dd7499107065d3c526bd171f9edc37bc820aa79ab2c5cead27ec",
+      "sha256": "1e24ee9c3fa9ac6447ff9f0c8096d80c4e2a98348d0e3b0277d406dfe8109e17",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "4d422182d63d0ee3ac38bf2823d255fd059ca5195efda355681e8f94137eaf7a",
+      "sha256": "68dfb56ddf1b4647dcd00644d88489fe2022b4136d72443e33f83a86ecb270bb",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.60.6",
+  "version": "1.60.7",
   "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/pw/run.mjs

@@ -190,7 +190,10 @@ function consumeWrapperFlags(list, deps, start = 0) {
 }
 
 // The non-secret values a staging-auth refusal names in its next command.
-const authVars = (plan) => ({ lane: plan.lane, persona: plan.persona });
+const authVars = (plan, deps = {}) => {
+  const cwd = deps.cwd ?? process.cwd();
+  return { lane: plan.lane, persona: plan.persona, cwd, ticketFlag: stagingAuth.ticketFlagFor(cwd) };
+};
 
 // `bb pw auth --help` / `bb pw [flags] <lane> auth --help`: auth's own help, before
 // any credential, lock or daemon call.
@@ -229,8 +232,8 @@ async function runPwInner(argv, deps = {}) {
   // local mode — before any credential, lock or issuer call.
   if (plan.mode === "auth") {
     const authEnvironment = resolveEnvironment({ flag: deps.environment ?? null, env });
-    if (authEnvironment.error || authEnvironment.environment !== "staging") return stagingAuth.refuse({ stdout, stderr }, "auth_requires_staging_environment", 2, {}, authVars(plan));
-    if (env.BB_PW_NO_LOCK === "1") return stagingAuth.refuse({ stdout, stderr }, "auth_requires_lane_lock", 3, {}, authVars(plan));
+    if (authEnvironment.error || authEnvironment.environment !== "staging") return stagingAuth.refuse({ stdout, stderr }, "auth_requires_staging_environment", 2, {}, authVars(plan, deps));
+    if (env.BB_PW_NO_LOCK === "1") return stagingAuth.refuse({ stdout, stderr }, "auth_requires_lane_lock", 3, {}, authVars(plan, deps));
   }
   const { spawnExec, socketRun } = deps.daemon ?? await import("./daemon.mjs");
   if (plan.scope === "global") { if (plan.mode === "reap") { await (deps.reap ?? (await import("./reap.mjs")).reap)({ env, stdout }); return 0; } if (env.BB_PW_NO_LOCK !== "1") { stderr.write("bb-pw: close-all and kill-all require BB_PW_NO_LOCK=1 because they can affect lanes you do not own.\n"); return 3; } return spawnExec(plan, env); }
@@ -278,7 +281,7 @@ async function runPwInner(argv, deps = {}) {
     // A lane that is provably no longer ours (not a transient verify error):
     // clear the session we installed and revoke its custody (AC-3).
     if (auth.reason === "not_held" || auth.reason === "held_by_other") await stagingAuth.onLaneAuthorityLost(authCtx).catch(() => {});
-    if (plan.mode === "auth" && (auth.reason === "not_held" || auth.reason === "held_by_other")) return stagingAuth.refuse({ stdout, stderr }, "lane_not_claimed", 3, { detail: auth.message }, authVars(plan));
+    if (plan.mode === "auth" && (auth.reason === "not_held" || auth.reason === "held_by_other")) return stagingAuth.refuse({ stdout, stderr }, "lane_not_claimed", 3, { detail: auth.message }, authVars(plan, deps));
     stderr.write(`${auth.message}\n`); return 3;
   }
   // Report the host the lock service actually stored (alias-collapsed), so the
@@ -305,10 +308,10 @@ async function runPwInner(argv, deps = {}) {
       const me = await authCtx.resolveCallerId().catch(() => null);
       if (me && me === auth.holder) { holderMatch = "self"; authCtx.callerIds = [...authCtx.callerIds, me]; }
     }
-    if (holderMatch !== "self") return stagingAuth.refuse({ stdout, stderr }, "exact_lane_holder_required", 3, {}, authVars(plan));
+    if (holderMatch !== "self") return stagingAuth.refuse({ stdout, stderr }, "exact_lane_holder_required", 3, {}, authVars(plan, deps));
     if (tracker) {
       const browserSession = await tracker.status();
-      if (browserSession.active && browserSession.environment && browserSession.environment !== "staging") return stagingAuth.refuse({ stdout, stderr }, "browser_session_not_staging", 2, {}, authVars(plan));
+      if (browserSession.active && browserSession.environment && browserSession.environment !== "staging") return stagingAuth.refuse({ stdout, stderr }, "browser_session_not_staging", 2, {}, authVars(plan, deps));
     }
     return stagingAuth.runStagingAuth(authCtx);
   }

package/src/pw/staging-auth.mjs

@@ -15,6 +15,7 @@
 //     clear that fails blocks the lane until it is resolved.
 //   * The ledger (~/.botbuddy/pw-staging-auth/<host>/lane-<n>.json, 0600) holds
 //     non-secret install records only.
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -229,8 +230,24 @@ const GUIDED_FIELDS = ["message", "cause", "actor", "next", "doc", "help", "agen
  * `extra` fields already rendered by the pool (an empty pool's health reason) win.
  * `vars` are non-secret only: lane, persona alias, allowed aliases, checkout.
  */
+/**
+ * ` --ticket BOT-123` from the checkout's branch name (`…/bot-123-…`), or "" so a
+ * lane-claim command never prints a <ticket> placeholder. Best effort, refusal-only.
+ */
+export function ticketFlagFor(cwd, { exec = execFileSync } = {}) {
+  try {
+    // symbolic-ref also names an unborn branch; a detached HEAD has no ticket.
+    const branch = String(exec("git", ["-C", cwd, "symbolic-ref", "--short", "-q", "HEAD"], { encoding: "utf8", timeout: 2000, stdio: ["ignore", "pipe", "ignore"] })).trim();
+    const match = /(?:^|[/_-])((?:bot|ent)-\d+)(?=$|[/_-])/i.exec(branch);
+    return match ? ` --ticket ${match[1].toUpperCase()}` : "";
+  } catch {
+    return "";
+  }
+}
+
 export function refuse({ stdout, stderr }, code, exitCode = 3, extra = {}, vars = {}) {
-  const g = guidance(isKnownCode(code) ? code : "pool_take_failed", vars);
+  // A real refusal: never a <placeholder> (AC-8 follow-up).
+  const g = guidance(isKnownCode(code) ? code : "pool_take_failed", { consequence: "bb pw auth has no pool to take a session from", ...vars }, { real: true });
   const guided = { message: g.message, cause: g.cause, actor: g.actor_label, next: g.next, doc: g.doc, help: g.help, agentAction: g.agent_action, remedy: remedyLine(g) };
   for (const field of GUIDED_FIELDS) if (extra[field] !== undefined) guided[field] = extra[field];
   const text = {
@@ -256,15 +273,20 @@ export async function runStagingAuth({ plan, host, env, deps, socketRun, resolve
   const poolModule = deps.stagingPoolModule ?? await loadPool();
   const poolOptions = deps.stagingPool ?? {};
   const cwd = deps.cwd ?? process.cwd();
-  const vars = { lane: plan.lane, persona: plan.persona, checkout: cwd };
+  const vars = { lane: plan.lane, persona: plan.persona, cwd, ticketFlag: ticketFlagFor(cwd) };
   let found;
   try {
     found = await (await loadBinding()).readRepoPoolBinding(cwd);
   } catch (error) {
     return refuse(io, error?.code === "pool_binding_invalid" ? "pool_binding_invalid" : "pool_not_configured", 3, { detail: String(error?.message ?? error) }, vars);
   }
-  if (!found) return refuse(io, "pool_not_configured", 3, {}, vars);
-  Object.assign(vars, { checkout: found.repoRoot ?? cwd, allowed: Object.keys(found.binding.personas ?? {}) });
+  if (!found) {
+    // Name a stable checkout that declares a pool, if this Mac has one on record.
+    const { findKnownCheckouts } = await import("../staging-pool/checkouts.mjs");
+    const [candidate] = await findKnownCheckouts({ ...(poolOptions.home ? { home: poolOptions.home } : {}), ...(poolOptions.isStableCheckout ? { isStable: poolOptions.isStableCheckout } : {}) }).catch(() => []);
+    return refuse(io, "pool_not_configured", 3, {}, { ...vars, checkout: candidate?.path });
+  }
+  Object.assign(vars, { allowed: Object.keys(found.binding.personas ?? {}) });
   const { findPersona } = await loadBinding();
   const persona = findPersona(found.binding, plan.persona);
   if (!persona) return refuse(io, "persona_not_allowlisted", 2, {}, vars);

package/src/staging-pool/checkouts.mjs

@@ -0,0 +1,120 @@
+// BOT-2084 (AC-8 follow-up): which repository checkouts on this Mac declare a
+// staging_session_pool, so a refusal run from the wrong directory (e.g. `~`) can
+// name a concrete `cd <path>` instead of a placeholder.
+//
+// Sources, both non-secret paths only:
+//   * every installed pool's config.json `checkout` (written by install);
+//   * ~/.botbuddy/staging-session-pool/known-checkouts.json (0600), updated each
+//     time a bb staging-pool / bb pw auth command resolves a binding from a cwd.
+// A candidate counts only if it still exists and still declares a pool binding.
+// Node-stdlib-only and self-contained (bundled with the installed job).
+import { chmodSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, sep } from "node:path";
+
+import { readRepoPoolBinding } from "./binding.mjs";
+
+const MAX_KNOWN = 20;
+
+const linkedWorktree = (path) => {
+  try {
+    return statSync(join(path, ".git")).isFile();
+  } catch {
+    return false;
+  }
+};
+const TEMP_ROOTS = ["/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
+// Path segments that mark agent, scratch or disposable checkouts.
+const DISPOSABLE_SEGMENTS = new Set(["worktrees", "scratch-workspaces"]);
+
+/**
+ * A checkout a human can be told to `cd` into: not under a temp dir, not an agent
+ * or scratch worktree (a `worktrees` / `scratch-workspaces` path segment), and not
+ * a linked git worktree (`.git` is a file). Remedies addressed to a human never
+ * embed any other path (AC-8 follow-up, found on staging acceptance).
+ */
+export function isStableCheckout(path, { tmp = tmpdir(), gitFileIsWorktree = linkedWorktree } = {}) {
+  if (typeof path !== "string" || !path.startsWith("/")) return false;
+  const roots = [...TEMP_ROOTS, tmp];
+  try {
+    roots.push(realpathSync(tmp));
+  } catch {
+    // tmp may not resolve in a test sandbox
+  }
+  for (const root of roots) {
+    const base = String(root).replace(/\/+$/, "");
+    if (base && (path === base || path.startsWith(`${base}/`))) return false;
+  }
+  if (path.split(sep).some((segment) => DISPOSABLE_SEGMENTS.has(segment))) return false;
+  return !gitFileIsWorktree(path);
+}
+const poolsRoot = (home) => join(home, ".botbuddy", "staging-session-pool");
+export const knownCheckoutsPath = (home = homedir()) => join(poolsRoot(home), "known-checkouts.json");
+
+function readKnown(home) {
+  try {
+    const data = JSON.parse(readFileSync(knownCheckoutsPath(home), "utf8"));
+    return Array.isArray(data?.checkouts) ? data.checkouts.filter((entry) => typeof entry?.path === "string" && entry.path.startsWith("/")) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Best effort: remember a checkout that resolved a binding. Never throws. */
+export function recordCheckout({ home = homedir(), path, poolId, now = Date.now() } = {}) {
+  try {
+    if (typeof path !== "string" || !path.startsWith("/")) return;
+    const entries = [{ path, pool_id: poolId ?? null, seen_at: new Date(now).toISOString() }, ...readKnown(home).filter((entry) => entry.path !== path)].slice(0, MAX_KNOWN);
+    mkdirSync(poolsRoot(home), { recursive: true, mode: 0o700 });
+    const file = knownCheckoutsPath(home);
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify({ version: 1, checkouts: entries }, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, file);
+  } catch {
+    // A refusal's hint must never fail the command that produced it.
+  }
+}
+
+function installedCheckouts(home) {
+  const found = [];
+  let names = [];
+  try {
+    names = readdirSync(poolsRoot(home));
+  } catch {
+    return found;
+  }
+  for (const name of names) {
+    try {
+      const config = JSON.parse(readFileSync(join(poolsRoot(home), name, "config.json"), "utf8"));
+      if (typeof config?.checkout === "string" && config.checkout.startsWith("/")) found.push({ path: config.checkout, pool_id: name, seen_at: config.installedAt ?? null });
+    } catch {
+      // not installed, or unreadable: not a candidate
+    }
+  }
+  return found;
+}
+
+/**
+ * Checkouts that still declare a staging_session_pool, most relevant first:
+ * installed pools' checkouts, then the most recently seen. `poolId` narrows to
+ * one pool when it is known.
+ */
+export async function findKnownCheckouts({ home = homedir(), poolId = null, readBinding = readRepoPoolBinding, isStable = isStableCheckout } = {}) {
+  const seen = new Set();
+  const result = [];
+  for (const entry of [...installedCheckouts(home), ...readKnown(home)]) {
+    if (seen.has(entry.path)) continue;
+    seen.add(entry.path);
+    if (!isStable(entry.path)) continue;
+    try {
+      const found = await readBinding(entry.path);
+      if (!found || found.repoRoot !== entry.path) continue;
+      if (poolId && found.binding.poolId !== poolId) continue;
+      result.push({ path: entry.path, poolId: found.binding.poolId });
+    } catch {
+      // gone, or no longer a valid binding
+    }
+  }
+  return result;
+}

package/src/staging-pool/cli.mjs

@@ -34,11 +34,13 @@ import { PoolEmptyError, createSessionPool } from "./pool.mjs";
 import { createGoTrueTotpSignIn } from "./signin-gotrue-totp.mjs";
 import { createRedactor } from "./state-file.mjs";
 import { createBotBuddyTotpProvider, probeBotBuddy } from "./totp-botbuddy.mjs";
-import { formatGuidance, guidance, isKnownCode, remedyLine } from "./errors.mjs";
+import { HUMAN_ONLY_COMMANDS, formatGuidance, guidance, isKnownCode, remedyLine } from "./errors.mjs";
+import { findKnownCheckouts, isStableCheckout as defaultIsStableCheckout, recordCheckout } from "./checkouts.mjs";
 import { STAGING_POOL_HELP } from "./help.mjs";
 
 export const BUNDLE_FILES = Object.freeze([
   "binding.mjs",
+  "checkouts.mjs",
   "cli.mjs",
   "config.mjs",
   "errors.mjs",
@@ -86,29 +88,50 @@ export function exitCodeFor(error) {
 
 // Where this invocation's pool lives: the job passes --home; everyone else
 // resolves it from the repo binding (cwd).
-async function resolveContext({ options, cwd, home, readBinding = readRepoPoolBinding }) {
+// The checkout a human-facing remedy may name: this repo root or the one install
+// recorded, if stable; else a stable checkout seen earlier for this pool; else none.
+async function stableCheckoutFor({ repoRoot, installed, poolId, home, readBinding, isStable }) {
+  if (repoRoot && isStable(repoRoot)) return repoRoot;
+  // The install-recorded checkout may since have moved or been deleted: name it only
+  // while it still declares this pool's binding.
+  const recorded = installed?.checkout;
+  if (recorded && isStable(recorded)) {
+    const found = await readBinding(recorded).catch(() => null);
+    if (found && found.repoRoot === recorded && found.binding.poolId === poolId) return recorded;
+  }
+  const [candidate] = await findKnownCheckouts({ home, poolId, readBinding, isStable }).catch(() => []);
+  return candidate?.path;
+}
+
+async function resolveContext({ options, cwd, home, readBinding = readRepoPoolBinding, isStableCheckout = defaultIsStableCheckout }) {
   if (options.home) {
     const paths = poolHomePaths({ home, root: options.home });
     const config = readInstalledConfig(paths.config);
-    return { paths, poolBinding: config.poolBinding, installed: config, rawBinding: config.binding };
+    const stableCheckout = await stableCheckoutFor({ installed: config, poolId: config.poolBinding.poolId, home, readBinding, isStable: isStableCheckout });
+    return { paths, poolBinding: config.poolBinding, installed: config, rawBinding: config.binding, stableCheckout };
   }
   const found = await readBinding(cwd);
   if (!found) {
-    throw new ConfigError("This repository declares no staging_session_pool in .botbuddy-agent.json, so it has no staging session pool.", "pool_not_configured");
+    throw new ConfigError(`${cwd} is not inside a repository whose .botbuddy-agent.json declares staging_session_pool.`, "pool_not_configured");
   }
   const paths = poolHomePaths({ home, poolId: found.binding.poolId });
+  // Remembered so a later refusal run from the wrong directory can name this checkout.
+  recordCheckout({ home, path: found.repoRoot, poolId: found.binding.poolId });
   let installed = null;
   try {
     installed = readInstalledConfig(paths.config);
   } catch (error) {
     if (error?.code !== "config_missing") installed = { error };
   }
-  return { paths, poolBinding: found.binding, installed, repoRoot: found.repoRoot };
+  const stableCheckout = await stableCheckoutFor({ repoRoot: found.repoRoot, installed: installed?.error ? null : installed, poolId: found.binding.poolId, home, readBinding, isStable: isStableCheckout });
+  return { paths, poolBinding: found.binding, installed, repoRoot: found.repoRoot, stableCheckout };
 }
 
 const shellWord = (value) => (/^[A-Za-z0-9_./:@,=~+-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`);
-export const installCommandFor = (repoRoot, fallback) =>
-  repoRoot ? `cd ${shellWord(repoRoot)} && bb staging-pool install --botbuddy-bin "$(command -v botbuddy)"` : fallback;
+// No checkout known → undefined, so a real refusal says where to run it instead of
+// printing the binding's `<your … checkout>` placeholder.
+export const installCommandFor = (repoRoot) =>
+  repoRoot ? `cd ${shellWord(repoRoot)} && bb staging-pool install --botbuddy-bin "$(command -v botbuddy)"` : undefined;
 
 // The non-secret values every guidance template may name.
 export function guidanceVars(ctx, extra = {}) {
@@ -116,12 +139,12 @@ export function guidanceVars(ctx, extra = {}) {
   return {
     label: ctx.poolBinding.launchdLabel,
     log: ctx.paths.log,
-    installCommand: installCommandFor(ctx.repoRoot, ctx.poolBinding.installCommand),
+    installCommand: installCommandFor(ctx.stableCheckout),
     docs: ctx.poolBinding.docs,
     configPath: ctx.paths.config,
     poolHome: ctx.paths.root,
     tickCommand: `bb staging-pool tick --home ${shellWord(ctx.paths.root)}`,
-    checkout: ctx.repoRoot,
+    checkout: ctx.stableCheckout,
     envFile: ctx.poolBinding.passwordEnvFile,
     allowed: Object.keys(ctx.poolBinding.personas ?? {}),
     ...extra,
@@ -196,8 +219,9 @@ export async function takeForLane({
   uid = userInfo().uid,
   logger = () => {},
   readBinding = readRepoPoolBinding,
+  isStableCheckout = defaultIsStableCheckout,
 } = {}) {
-  const ctx = await resolveContext({ options: {}, cwd, home, readBinding });
+  const ctx = await resolveContext({ options: {}, cwd, home, readBinding, isStableCheckout });
   const entry = findPersona(ctx.poolBinding, persona);
   const target = stagingTargetFromBinding(ctx.poolBinding);
   if (!entry) assertPersonaAllowed(target, persona);
@@ -228,6 +252,68 @@ function humanCommandLine(argv) {
   return argv.map((token) => (/^[A-Za-z0-9_./:=@-]+$/.test(token) ? token : `'${token.replace(/'/g, "'\\''")}'`)).join(" ");
 }
 
+// What a missing pool binding means for each subcommand (AC-8 follow-up: an
+// install refusal must not talk about taking a session).
+const NO_POOL_CONSEQUENCE = Object.freeze({
+  install: "there is no pool definition to install",
+  uninstall: "there is no pool to remove",
+  tick: "there is no pool to refill",
+  "mint-one": "there is no pool to sign a persona in for",
+  status: "there is no pool to report on",
+  probe: "there are no pool personas to probe",
+  "print-plist": "there is no pool job to describe",
+});
+
+/**
+ * Build the refusal for a failed subcommand: the JSON record and the text block.
+ * A human-only subcommand always names Human (Jono) and prints no Agent line. The
+ * checkout comes from this directory, else from a checkout an install recorded or
+ * one seen earlier; with none, the next step says where to run the command.
+ */
+export async function refusalFor({ argv, command, error, options = {}, cwd = process.cwd(), home = homedir(), readBinding = readRepoPoolBinding, isStableCheckout = defaultIsStableCheckout }) {
+  const code = typeof error?.code === "string" && isKnownCode(error.code) ? error.code : "unexpected_error";
+  const humanOnly = HUMAN_ONLY_COMMANDS.has(command);
+  let ctx = null;
+  try {
+    ctx = await resolveContext({ options, cwd, home, readBinding, isStableCheckout });
+  } catch {
+    ctx = null;
+  }
+  if (!ctx) {
+    const [candidate] = await findKnownCheckouts({ home, readBinding, isStable: isStableCheckout }).catch(() => []);
+    if (candidate) {
+      try {
+        ctx = await resolveContext({ options: {}, cwd: candidate.path, home, readBinding, isStableCheckout });
+      } catch {
+        ctx = null;
+      }
+    }
+  }
+  const line = humanCommandLine(argv ?? [command]);
+  const vars = guidanceVars(ctx, {
+    command: line,
+    retry: `bb staging-pool ${line}`,
+    cwd,
+    consequence: NO_POOL_CONSEQUENCE[command] ?? "there is no pool to act on",
+    markers: Array.isArray(error?.markers) ? error.markers.join(", ") : undefined,
+  });
+  vars.persona = options.persona ?? error?.persona ?? vars.allowed?.[0];
+  const actor = humanOnly ? "human" : null;
+  const g = guidance(code, vars, { real: true, actor });
+  const record = {
+    ok: false, command, code, message: g.message, cause: g.cause, actor: g.actor_label, next: g.next,
+    agentAction: g.agent_action, doc: g.doc, help: g.help, detail: String(error?.message ?? error ?? "").slice(0, 500),
+  };
+  // A pool refusal (pool_empty / unhealthy) already carries its health guidance;
+  // an ordinary error's own message stays in `detail`.
+  if (typeof error?.reason === "string") for (const field of GUIDANCE_FIELDS) if (error[field] !== undefined) record[field] = error[field];
+  record.remedy ??= remedyLine(g);
+  if (humanOnly) Object.assign(record, { actor: g.actor_label, agentAction: "report_blocker" });
+  // An empty pool is explained by its health reason (e.g. job_not_loaded).
+  const textG = typeof error?.reason === "string" && error.reason !== code && isKnownCode(error.reason) ? guidance(error.reason, vars, { real: true, actor }) : g;
+  return { record, text: formatGuidance(textG, { agentLine: !humanOnly }), exitCode: exitCodeFor(error) };
+}
+
 export async function runStagingPool(argv, deps = {}) {
   const {
     env = process.env,
@@ -246,6 +332,7 @@ export async function runStagingPool(argv, deps = {}) {
     sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     readBinding = readRepoPoolBinding,
     readSecretFile = readFileSync,
+    isStableCheckout = defaultIsStableCheckout,
   } = deps;
 
   const redactor = createRedactor();
@@ -304,7 +391,7 @@ export async function runStagingPool(argv, deps = {}) {
 
   const commands = {
     async install(options) {
-      const ctx = await resolveContext({ options: {}, cwd, home, readBinding });
+      const ctx = await resolveContext({ options: {}, cwd, home, readBinding, isStableCheckout });
       const target = stagingTargetFromBinding(ctx.poolBinding);
       assertMintAllowed({ target, env, listAncestors });
       const botbuddyBin = requireBotbuddyBin(options);
@@ -327,6 +414,8 @@ export async function runStagingPool(argv, deps = {}) {
         botbuddyBin,
         intervalSeconds: explicitInterval ?? existing?.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS,
         existingPersonas: existing?.personas,
+        checkout: ctx.repoRoot,
+        installedAt: new Date(now()).toISOString(),
       });
       await fs.writeFile(ctx.paths.config, serialiseInstalledConfig(config), { mode: 0o600 });
       await fs.chmod(ctx.paths.config, 0o600);
@@ -351,7 +440,7 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async uninstall(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = await resolveContext({ options, cwd, home, readBinding, isStableCheckout });
       const target = stagingTargetFromBinding(ctx.poolBinding);
       // The job and its sessions are the human's: an agent never stops or empties them.
       assertMintAllowed({ target, env, listAncestors });
@@ -365,7 +454,7 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async tick(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = await resolveContext({ options, cwd, home, readBinding, isStableCheckout });
       const target = stagingTargetFromBinding(ctx.poolBinding);
       assertMintAllowed({ target, env, listAncestors });
       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");
@@ -375,7 +464,7 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async "mint-one"(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = await resolveContext({ options, cwd, home, readBinding, isStableCheckout });
       const target = stagingTargetFromBinding(ctx.poolBinding);
       assertMintAllowed({ target, env, listAncestors });
       const entry = findPersona(ctx.poolBinding, options.persona);
@@ -388,7 +477,7 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async status(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = await resolveContext({ options, cwd, home, readBinding, isStableCheckout });
       const target = stagingTargetFromBinding(ctx.poolBinding);
       const pool = buildPool({ ctx, target, now, logger: emit, fetchImpl, sleep });
       if (options.check) {
@@ -403,7 +492,7 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async probe(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = await resolveContext({ options, cwd, home, readBinding, isStableCheckout });
       const botbuddyBin = options["botbuddy-bin"] ?? ctx.installed?.botbuddyBin;
       if (!botbuddyBin) throw new ConfigError('probe needs --botbuddy-bin "$(command -v botbuddy)" (or an installed job).', "pool_not_installed");
       const receipt = await probeBotBuddy({
@@ -420,42 +509,19 @@ export async function runStagingPool(argv, deps = {}) {
     },
 
     async "print-plist"(options) {
-      const ctx = await resolveContext({ options, cwd, home, readBinding });
+      const ctx = await resolveContext({ options, cwd, home, readBinding, isStableCheckout });
       stdout(jobPlist(ctx, Number(options.interval ?? ctx.installed?.intervalSeconds ?? DEFAULT_INTERVAL_SECONDS)));
       return 0;
     },
   };
 
+  // One JSON line (machine-readable) then the same guidance as text, on stderr.
   // One JSON line (machine-readable) then the same guidance as text, on stderr.
   async function fail(command, error, options = {}) {
-    const code = typeof error?.code === "string" && isKnownCode(error.code) ? error.code : "unexpected_error";
-    let ctx = null;
-    try {
-      ctx = await resolveContext({ options, cwd, home, readBinding });
-    } catch {
-      ctx = null;
-    }
-    const persona = options.persona ?? error?.persona;
-    const vars = guidanceVars(ctx, {
-      persona,
-      command: humanCommandLine(argv),
-      markers: Array.isArray(error?.markers) ? error.markers.join(", ") : undefined,
-      checkout: ctx?.repoRoot ?? cwd,
-      retry: `bb staging-pool ${humanCommandLine(argv)}`,
-    });
-    const g = guidance(code, vars);
-    const record = {
-      ok: false, command, code, message: g.message, cause: g.cause, actor: g.actor_label, next: g.next,
-      agentAction: g.agent_action, doc: g.doc, help: g.help, detail: String(error?.message ?? error ?? "").slice(0, 500),
-    };
-    // A pool refusal already carries its health guidance (pool_empty / unhealthy).
-    for (const field of GUIDANCE_FIELDS) if (error?.[field] !== undefined) record[field] = error[field];
-    record.remedy ??= remedyLine(g);
+    const { record, text, exitCode } = await refusalFor({ argv, command, error, options, cwd, home, readBinding, isStableCheckout });
     stderr(JSON.stringify(redactor.redact({ ts: new Date(now()).toISOString(), ...record })));
-    // An empty pool is explained by its health reason (e.g. job_not_loaded).
-    const text = typeof error?.reason === "string" && error.reason !== code && isKnownCode(error.reason) ? guidance(error.reason, vars) : g;
-    stderr(redactor.redact(formatGuidance(text)));
-    return exitCodeFor(error);
+    stderr(redactor.redact(text));
+    return exitCode;
   }
 
   let parsed;

package/src/staging-pool/config.mjs

@@ -87,7 +87,7 @@ export function readInstalledConfig(path, { readFile = readFileSync } = {}) {
 }
 
 // rawBinding: { tenant, staging_session_pool } exactly as committed.
-export function buildInstalledConfig({ rawBinding, poolBinding, botbuddyBin, intervalSeconds = DEFAULT_INTERVAL_SECONDS, existingPersonas }) {
+export function buildInstalledConfig({ rawBinding, poolBinding, botbuddyBin, intervalSeconds = DEFAULT_INTERVAL_SECONDS, existingPersonas, checkout, installedAt }) {
   const personas = {};
   for (const persona of Object.values(poolBinding.personas)) {
     personas[persona.email] = Number.isInteger(existingPersonas?.[persona.email]) ? existingPersonas[persona.email] : persona.defaultCount;
@@ -98,6 +98,9 @@ export function buildInstalledConfig({ rawBinding, poolBinding, botbuddyBin, int
     personas,
     botbuddyBin,
     intervalSeconds,
+    // The checkout install ran from (non-secret), so a refusal elsewhere can name it.
+    ...(typeof checkout === "string" && checkout.startsWith("/") ? { checkout } : {}),
+    ...(installedAt ? { installedAt } : {}),
   });
 }
 

package/src/staging-pool/errors.mjs

@@ -3,8 +3,11 @@
 // command and the doc section. `bb help symptom <code>` prints the same entry.
 //
 // Node-stdlib-only and self-contained (the installed job copies this directory).
-// Templates take only non-secret values (lane, persona alias, paths, labels);
-// a missing value renders as a <placeholder>, never as an empty string.
+// Templates take only non-secret values (lane, persona alias, paths, labels).
+// A real refusal (`{ real: true }`) never prints a <placeholder>: a missing value
+// in prose becomes plain words, and a `next` command that needs a value it does
+// not have falls back to "run this from inside a repository checkout …". Only
+// `bb help symptom` (the reference view) shows <placeholders>.
 
 export const DOC_URL = "https://github.com/bot-buddy/botbuddy-webapp/blob/main/docs/agent-staging-acceptance-mfa.md";
 
@@ -39,15 +42,15 @@ export const ERROR_CODES = Object.freeze({
   auth_requires_lane_lock: entry("agent", "take",
     "bb pw auth needs a lock-gated lane, and this run is unlocked.",
     "BB_PW_NO_LOCK=1 is set in this shell.",
-    `bb locks -m --lane {lane} --ticket <ticket> && env -u BB_PW_NO_LOCK ${AUTH}`),
+    `bb locks -m --lane {lane}{ticketFlag} && env -u BB_PW_NO_LOCK ${AUTH}`),
   lane_not_claimed: entry("agent", "take",
     "The lane lock is not held by this agent session.",
     "The lane was never claimed, its lock expired, or another agent holds it.",
-    `bb locks -m --lane {lane} --ticket <ticket> && ${AUTH}`),
+    `bb locks -m --lane {lane}{ticketFlag} && ${AUTH}`),
   exact_lane_holder_required: entry("agent", "take",
     "The lane lock is held by another agent session of your owner, not by this session.",
     "The lane was claimed from a different session or sub-agent; auth needs the exact holder.",
-    `bb locks -m --lane {lane} --ticket <ticket>   # from THIS session, then: ${AUTH}`),
+    `bb locks -m --lane {lane}{ticketFlag}   # from THIS session, then: ${AUTH}`),
   persona_not_allowlisted: entry("agent", "take",
     "Persona \"{persona}\" is not one of this repository's staging_session_pool personas.",
     "A typo, or an email where the alias is expected. Allowed aliases: {allowed}.",
@@ -65,9 +68,9 @@ export const ERROR_CODES = Object.freeze({
     "The lane was opened with --persistent or --profile.",
     `${REOPEN} && ${AUTH}   # no --persistent / --profile`),
   pool_not_configured: entry("agent", "configure",
-    "This directory's repository declares no staging_session_pool, so there is no pool to take from.",
-    "The command ran outside the repository checkout, or the repository has not opted in.",
-    "cd <repository checkout> && {retry}"),
+    "{cwd} is not inside a repository whose .botbuddy-agent.json declares staging_session_pool, so {consequence}.",
+    "The command ran outside the repository checkout (for example from your home directory), or that repository has not opted in.",
+    "cd {checkout} && {retry}"),
 
   // ── bb pw … auth: install into the lane (agent retries once, then reports)
   session_install_failed: entry("agent", "take",
@@ -139,15 +142,15 @@ export const ERROR_CODES = Object.freeze({
   mint_backing_off: entry("human", "repair",
     "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; password_source_* = the password env file; totp_source_failed = the botbuddy CLI login.",
-    "grep mint_failed {log} | tail -1   # then the matching code: bb help symptom <code>"),
+    "grep mint_failed {log} | tail -1   # then run bb help symptom with the code that line names"),
   last_tick_failed: entry("human", "repair",
-    "The pool job's last tick could not sign {persona} in.",
+    "The pool job's last tick had sign-in (mint) failures.",
     "The last mint_failed line in {log} names the cause.",
     "grep mint_failed {log} | tail -1   # repair that code, then: {tickCommand}"),
   ticks_failing: entry("human", "repair",
     "Pool ticks run but none has succeeded for 3+ intervals.",
     "A persistent mint failure; {log} names it.",
-    "grep mint_failed {log} | tail -1   # then: bb help symptom <code>"),
+    "grep mint_failed {log} | tail -1   # then run bb help symptom with the code that line names"),
   persona_below_target: entry("human", "repair",
     "The pool has been below its configured size for {persona} for 3+ ticks.",
     "Agents take sessions faster than the job refills them, or mints are partly failing ({log}).",
@@ -180,12 +183,12 @@ export const ERROR_CODES = Object.freeze({
   // ── who may run what
   agent_context: entry("human", "install",
     "This bb staging-pool command is human-only and this shell is inside an agent session ({markers}).",
-    `It ran from a Claude or Codex terminal. ${HUMAN_ONLY}`,
-    "From Terminal.app or iTerm: cd {checkout} && bb staging-pool {command}"),
+    `It ran from a Claude or Codex terminal; run it from Terminal.app or iTerm instead. ${HUMAN_ONLY}`,
+    "cd {checkout} && bb staging-pool {command}"),
   agent_context_unknown: entry("human", "install",
     "bb staging-pool could not establish that this is not an agent session (ps failed), so it refused.",
-    `/bin/ps is unavailable or restricted in this shell. ${HUMAN_ONLY}`,
-    "From Terminal.app or iTerm: cd {checkout} && bb staging-pool {command}"),
+    `/bin/ps is unavailable or restricted in this shell; run it from Terminal.app or iTerm instead. ${HUMAN_ONLY}`,
+    "cd {checkout} && bb staging-pool {command}"),
 
   // ── configuration (repository binding and installed config)
   config_missing: entry("human", "configure",
@@ -285,27 +288,62 @@ export const ERROR_CODES = Object.freeze({
     "bb staging-pool status   # once; report this code, the detail and the CLI version (bb version)", "report_blocker"),
 });
 
+// Codes only `bb pw … auth` can raise; every other code can come from `bb staging-pool`.
+export const AUTH_ONLY_CODES = Object.freeze(new Set([
+  "auth_requires_staging_environment", "auth_requires_lane_lock", "lane_not_claimed", "exact_lane_holder_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_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",
+]));
+
+// `bb staging-pool` subcommands only a human runs. A refusal from one names
+// Human (Jono) whatever the code, and prints no Agent guidance.
+export const HUMAN_ONLY_COMMANDS = Object.freeze(new Set(["install", "uninstall", "tick", "mint-one"]));
+
+export const CHECKOUT_SENTENCE = "From inside a repository checkout whose .botbuddy-agent.json declares staging_session_pool (for BotBuddy: your botbuddy-webapp clone on main), run";
+export const BARE_INSTALL = 'bb staging-pool install --botbuddy-bin "$(command -v botbuddy)"';
+
 // Vars that are already whole command lines; every other var is a single shell word.
-const COMMAND_VARS = new Set(["installCommand", "tickCommand", "command", "retry"]);
+const COMMAND_VARS = new Set(["installCommand", "tickCommand", "command", "retry", "ticketFlag"]);
+// Vars where an empty string is a real value (no flag), not a missing one.
+const OPTIONAL_VARS = new Set(["ticketFlag"]);
 const SHELL_SAFE = /^[A-Za-z0-9_./:@,=~+-]+$/;
 // A <placeholder> stays as written: the reader replaces it.
 const shellWord = (value) => (SHELL_SAFE.test(value) || /^<[^<>]+>$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`);
 
+// What a missing value reads as in prose (real refusals only).
+const DESCRIBED = Object.freeze({
+  persona: "the persona", lane: "the lane", log: "the pool log", configPath: "the installed pool config",
+  label: "the launchd job", envFile: "the persona password file", markers: "agent markers",
+  cwd: "This directory", consequence: "there is no pool to act on", command: "this command",
+  checkout: "the repository checkout", allowed: "the binding's personas", firstAllowed: "a listed persona",
+});
+
+const isMissing = (key, value) => value === undefined || value === null || (value === "" && !OPTIONAL_VARS.has(key)) || (Array.isArray(value) && value.length === 0);
+
 // In a `next` command a caller-supplied value (a typed persona, a checkout path
 // with spaces) is shell-quoted, so the line stays one safe copy-paste.
-function fill(template, vars, { shell = false } = {}) {
+function fill(template, vars, { shell = false, missing = null, describe = false } = {}) {
   return String(template).replace(/\{([A-Za-z]+)\}/g, (_, key) => {
     const value = vars?.[key];
-    if (Array.isArray(value)) return value.length ? value.map((item) => (shell ? shellWord(String(item)) : String(item))).join(", ") : `<${key}>`;
-    if (value === undefined || value === null || value === "") return `<${key}>`;
+    if (isMissing(key, value)) {
+      missing?.add(key);
+      return describe ? (DESCRIBED[key] ?? "it") : `<${key}>`;
+    }
+    if (Array.isArray(value)) return value.map((item) => (shell ? shellWord(String(item)) : String(item))).join(", ");
     return shell && !COMMAND_VARS.has(key) ? shellWord(String(value)) : String(value);
   });
 }
 
 export const isKnownCode = (code) => Object.hasOwn(ERROR_CODES, String(code ?? ""));
 
-/** The guidance for one code, interpolated with non-secret vars. */
-export function guidance(code, vars = {}) {
+/**
+ * The guidance for one code, interpolated with non-secret vars.
+ *   real   a refusal someone will act on: no <placeholder> is ever printed.
+ *   actor  "human" for a human-only subcommand, whatever the code's default.
+ */
+export function guidance(code, vars = {}, { real = false, actor = null } = {}) {
   const known = isKnownCode(code);
   const spec = known ? ERROR_CODES[code] : ERROR_CODES.unexpected_error;
   const allowed = Array.isArray(vars.allowed) ? vars.allowed : vars.allowed ? [vars.allowed] : [];
@@ -313,20 +351,36 @@ export function guidance(code, vars = {}) {
     ...vars,
     allowed,
     firstAllowed: vars.firstAllowed ?? allowed[0],
+    ticketFlag: vars.ticketFlag ?? (real ? "" : " --ticket <ticket>"),
     // Without a resolved pool these still read as runnable commands from the checkout.
     tickCommand: vars.tickCommand ?? "bb staging-pool tick",
-    installCommand: vars.installCommand ?? `cd ${vars.checkout ? shellWord(String(vars.checkout)) : "<checkout>"} && bb staging-pool install --botbuddy-bin "$(command -v botbuddy)"`,
+    installCommand: vars.installCommand ?? (vars.checkout ? `cd ${shellWord(String(vars.checkout))} && ${BARE_INSTALL}` : (real ? undefined : `cd <checkout> && ${BARE_INSTALL}`)),
   };
   // What a "go to the right checkout" step re-runs: auth by default.
   filled.retry = vars.retry ?? fill(AUTH, filled, { shell: true });
+  let next;
+  if (real) {
+    const missing = new Set();
+    next = fill(spec.next, filled, { shell: true, missing });
+    if (missing.size) {
+      // No concrete checkout (or a value only a resolved pool knows): say where to
+      // run it, and give the command that works from there.
+      const bareMissing = new Set();
+      const bare = fill(spec.next.replace("cd {checkout} && ", ""), { ...filled, installCommand: BARE_INSTALL }, { shell: true, missing: bareMissing });
+      next = `${CHECKOUT_SENTENCE}: ${bareMissing.size ? filled.retry : bare}`;
+    }
+  } else {
+    next = fill(spec.next, filled, { shell: true });
+  }
+  const finalActor = actor ?? spec.actor;
   return {
     code: known ? code : String(code ?? "unexpected_error"),
-    message: fill(spec.message, filled),
-    cause: fill(spec.cause, filled),
-    actor: spec.actor,
-    actor_label: ACTOR_LABELS[spec.actor],
-    next: fill(spec.next, filled, { shell: true }),
-    agent_action: spec.agentAction,
+    message: fill(spec.message, filled, { describe: real }),
+    cause: fill(spec.cause, filled, { describe: real }),
+    actor: finalActor,
+    actor_label: ACTOR_LABELS[finalActor],
+    next,
+    agent_action: finalActor === "human" ? "report_blocker" : spec.agentAction,
     doc: `${DOC_URL}#${DOC_SECTIONS[spec.doc]}`,
     help: `bb help symptom ${known ? code : "unexpected_error"}`,
   };
@@ -339,13 +393,13 @@ export function remedyLine(g) {
 }
 
 /** Plain-text block for stderr. */
-export function formatGuidance(g, { prefix = "bb staging-pool" } = {}) {
+export function formatGuidance(g, { prefix = "bb staging-pool", agentLine = true } = {}) {
   const lines = [
     `${prefix}: ${g.message} [${g.code}]`,
     `  Likely cause: ${g.cause}`,
     `  Next (${g.actor_label}${g.actor === "human" ? ", from Terminal.app or iTerm" : ""}): ${g.next}`,
   ];
-  if (g.actor === "human") lines.push("  Agent: do not run that. Report this code and the next step to the human once, then stop.");
+  if (g.actor === "human" && agentLine) lines.push("  Agent: do not run that. Report this code and the next step to the human once, then stop.");
   lines.push(`  Docs: ${g.doc}`, `  Explain: ${g.help}`);
   return lines.join("\n");
 }

package/src/staging-pool/health.mjs

@@ -15,7 +15,7 @@ export const HEALTH_REASON_CODES = Object.freeze([
 export function healthReasons({ label, log, installCommand, docs, configPath, tickCommand, checkout, persona }) {
   const vars = { label, log, installCommand, docs, configPath, tickCommand, checkout, persona };
   return Object.freeze(Object.fromEntries(HEALTH_REASON_CODES.map((code) => {
-    const g = guidance(code, vars);
+    const g = guidance(code, vars, { real: true });
     return [code, Object.freeze({ agentAction: g.agent_action, remedy: remedyLine(g), vars })];
   })));
 }
@@ -35,7 +35,7 @@ export function assessPoolHealth({ status, personas, intervalSeconds, nowMs, job
     const record = { ok: false, reason, agentAction, ...extra };
     if (vars) {
       // Re-rendered with the persona this assessment is about.
-      const g = guidance(reason, { ...vars, persona: extra.persona ?? requestedPersona ?? vars.persona });
+      const g = guidance(reason, { ...vars, persona: extra.persona ?? requestedPersona ?? vars.persona }, { real: true });
       remedy = remedyLine(g);
       Object.assign(record, { message: g.message, cause: g.cause, actor: g.actor_label, next: g.next, doc: g.doc, help: g.help });
     }