@botbuddy/cli 1.25.0 → 1.27.0

package/src/telemetry-outbox.mjs

@@ -0,0 +1,327 @@
+// BOT-1316 — durable, local-first lifecycle delivery for foreground wrappers.
+// This module deliberately knows nothing about MCP or child output. Producers
+// append a small, allowlisted lifecycle event before spawning a child; delivery
+// is a separate, idempotent step against execution-ingest.
+
+import { createHash } from "node:crypto";
+import { chmod, link, mkdir, open, readFile, readdir, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const OUTBOX_SCHEMA_VERSION = 1;
+export const MAX_OUTBOX_LINE_BYTES = 16 * 1024;
+const LOCK_WAIT_MS = 25;
+const LOCK_ATTEMPTS = 80;
+const SENSITIVE = /(?:[a-z][a-z0-9+.-]*:\/\/[^\s/@:]+:[^\s/@]+@[^\s/]+(?:\/[^\s]*)?|bb_[a-z0-9_-]{10,}|gh[pousr]_[a-z0-9]{16,}|github_pat_[a-z0-9_]{20,}|glpat-[a-z0-9_-]{16,}|xox[baprs]-[a-z0-9-]{10,}|sk-[a-z0-9]{20,}|(?:akia|asia)[a-z0-9]{16}|-----begin[a-z0-9 ]*private key-----[\s\S]*?-----end[a-z0-9 ]*private key-----)|\bbearer\s+[^\s"']+|(?:^|[^a-z0-9])(?:[a-z0-9]+_)*(?:token|api[_-]?key|private[_-]?key|password|secret)(?:_[a-z0-9]+)*\s*[=:]\s*(?:"[^"]*"|'[^']*'|[^\s"']+)/gi;
+const DROP_KEYS = new Set(["stdout", "stderr", "output", "raw_output", "bounded_log", "env", "environment_values", "environment_value", "secrets"]);
+const CONTEXT_KEYS = new Set([
+  "agent", "repo", "ticket", "pr", "branch", "sha", "environment", "runner", "phase",
+  "worker", "shard", "retry", "current_spec", "passed", "failed", "skipped", "health", "correlations",
+]);
+const CORRELATION_KEYS = new Set([
+  "tool_event_id", "command_receipt_id", "test_run_id", "test_execution_id", "wait_session_id",
+  "lane_session_id", "agent_signal_seq", "stack_lease_id",
+]);
+const PROGRESS_KEYS = new Set(["completed", "total", "phase", "current_item", "worker", "shard"]);
+const DIAGNOSTIC_KEYS = new Set(["code", "message", "category", "signal", "retryable"]);
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+
+function redactString(value) {
+  SENSITIVE.lastIndex = 0;
+  return value.replace(SENSITIVE, "[REDACTED]");
+}
+
+// Exported for wrappers and reporter adapters. Removing forbidden fields is more
+// robust than merely redacting values: raw output is never useful lifecycle data.
+export function redactTelemetry(value) {
+  if (Array.isArray(value)) return value.map(redactTelemetry);
+  if (!value || typeof value !== "object") return typeof value === "string" ? redactString(value) : value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !DROP_KEYS.has(key.toLowerCase()))
+    .map(([key, item]) => [key, redactTelemetry(item)]));
+}
+
+function repositoryHash(repository) {
+  return hash(repository.toLowerCase()).slice(0, 32);
+}
+
+function validTenant(value) { return typeof value === "string" && /^[a-z0-9][a-z0-9-]{0,63}$/.test(value); }
+function validRepository(value) { return typeof value === "string" && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value); }
+
+function eventPayload(event) {
+  const clean = redactTelemetry(event);
+  if (!clean || typeof clean !== "object" || Array.isArray(clean)) throw new Error("telemetry event must be an object");
+  // execution-ingest is intentionally strict. Keep this client-side allowlist so
+  // a reporter cannot accidentally turn arbitrary process state into telemetry.
+  const allowed = new Set(["schema_version", "action", "producer_kind", "source_run_id", "attempt", "producer_event_id", "producer_sequence", "occurred_at", "context", "progress", "outcome", "diagnostic", "evidence_refs"]);
+  for (const key of Object.keys(clean)) if (!allowed.has(key)) delete clean[key];
+  // Mirror the server contract at the producer boundary. A malformed reporter
+  // must not create a permanently retrying record merely because it included
+  // a harmless but unrecognised field.
+  if (clean.context && typeof clean.context === "object" && !Array.isArray(clean.context)) {
+    clean.context = Object.fromEntries(Object.entries(clean.context).filter(([key]) => CONTEXT_KEYS.has(key)));
+    if (clean.context.correlations && typeof clean.context.correlations === "object" && !Array.isArray(clean.context.correlations)) {
+      clean.context.correlations = Object.fromEntries(Object.entries(clean.context.correlations).filter(([key]) => CORRELATION_KEYS.has(key)));
+    }
+  }
+  if (clean.progress && typeof clean.progress === "object" && !Array.isArray(clean.progress)) {
+    clean.progress = Object.fromEntries(Object.entries(clean.progress).filter(([key]) => PROGRESS_KEYS.has(key)));
+  }
+  if (clean.diagnostic && typeof clean.diagnostic === "object" && !Array.isArray(clean.diagnostic)) {
+    clean.diagnostic = Object.fromEntries(Object.entries(clean.diagnostic).filter(([key]) => DIAGNOSTIC_KEYS.has(key)));
+  }
+  return clean;
+}
+
+async function durableWrite(path, value, { append = false } = {}) {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  const handle = await open(path, append ? "a" : "w", 0o600);
+  try {
+    await handle.writeFile(text);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await chmod(path, 0o600);
+}
+
+async function atomicJson(path, value) {
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await durableWrite(temp, `${JSON.stringify(value)}\n`);
+  await rename(temp, path);
+  // Persist the directory entry, not just the file data, before reporting the
+  // acknowledgement checkpoint as durable.
+  let dir;
+  try { dir = await open(dirname(path), "r"); await dir.sync(); } finally { await dir?.close(); }
+}
+
+function parseRecord(line) {
+  let parsed;
+  try { parsed = JSON.parse(line); } catch {
+    const error = new Error("invalid_json");
+    error.code = "invalid_json";
+    throw error;
+  }
+  if (!parsed || parsed.schema_version !== OUTBOX_SCHEMA_VERSION || typeof parsed.checksum !== "string" || !parsed.event) throw new Error("invalid_record_shape");
+  const expected = hash(JSON.stringify(parsed.event));
+  if (parsed.checksum !== expected) throw new Error("checksum_mismatch");
+  return parsed;
+}
+
+function safeErrorClass(error) {
+  const raw = String(error?.code ?? error?.name ?? "delivery_failed");
+  return raw.replace(/[^a-z0-9_.-]/gi, "_").slice(0, 96) || "delivery_failed";
+}
+
+export async function createTelemetryOutbox({
+  root = join(homedir(), ".botbuddy", "telemetry"), tenant, repository, producerVersion, now = () => new Date(),
+} = {}) {
+  if (!validTenant(tenant)) throw new Error("telemetry tenant must be a lowercase slug");
+  if (!validRepository(repository)) throw new Error("telemetry repository must be canonical owner/name");
+  if (typeof producerVersion !== "string" || !producerVersion) throw new Error("telemetry producer version is required");
+  const directory = join(root, tenant, repositoryHash(repository));
+  const path = join(directory, "outbox.ndjson");
+  const lockPath = join(directory, "outbox.lock");
+  const quarantinePath = join(directory, "outbox.quarantine.ndjson");
+  const statusPath = join(directory, "status.json");
+  const legacyImportPath = join(directory, "legacy-test-runs.imported.json");
+
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+
+  async function acquireLock() {
+    for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+      try {
+        // Write a complete, fsynced owner record first, then atomically publish
+        // it with link(2). A crash can leave an unreferenced temp file but can
+        // never strand the shared lock name with missing PID metadata.
+        const candidate = `${lockPath}.${process.pid}.${Date.now()}.tmp`;
+        await durableWrite(candidate, JSON.stringify({ pid: process.pid, created_at: now().toISOString() }));
+        try { await link(candidate, lockPath); } finally { await unlink(candidate).catch(() => {}); }
+        return async () => { try { await unlink(lockPath); } catch { /* a process may have cleaned its own stale lock */ } };
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+        let owner = null;
+        try { owner = JSON.parse(await readFile(lockPath, "utf8")); } catch { /* incomplete lock is never age-reclaimed */ }
+        // A lock may be reclaimed only after proving the same-host PID is gone.
+        if (Number.isInteger(owner?.pid) && owner.pid > 0) {
+          let alive = true;
+          try { process.kill(owner.pid, 0); } catch (probe) { alive = probe?.code !== "ESRCH"; }
+          if (!alive) { try { await unlink(lockPath); } catch { /* winner will retry */ } continue; }
+        }
+        await sleep(LOCK_WAIT_MS);
+      }
+    }
+    const err = new Error("telemetry_outbox_lock_busy");
+    err.code = "telemetry_outbox_lock_busy";
+    throw err;
+  }
+
+  async function readStatus() {
+    try { return JSON.parse(await readFile(statusPath, "utf8")); } catch { return {}; }
+  }
+
+  async function writeStatus(patch) {
+    const current = await readStatus();
+    await atomicJson(statusPath, { ...current, ...patch, producer_version: producerVersion, updated_at: now().toISOString() });
+  }
+
+  async function hasCredentialAttestation({ tenant: attestedTenant, fingerprint }) {
+    const persisted = await readStatus();
+    const attestation = persisted.credential_attestation;
+    return attestation?.schema_version === 1
+      && attestation.tenant === attestedTenant
+      && attestation.fingerprint === fingerprint;
+  }
+
+  async function recordCredentialAttestation({ tenant: attestedTenant, fingerprint }) {
+    if (!validTenant(attestedTenant) || !/^[a-f0-9]{64}$/.test(fingerprint ?? "")) throw new Error("invalid telemetry credential attestation");
+    await writeStatus({ credential_attestation: { schema_version: 1, tenant: attestedTenant, fingerprint, attested_at: now().toISOString() } });
+  }
+
+  async function readLines() {
+    try { return (await readFile(path, "utf8")).split("\n").filter(Boolean); } catch (error) { if (error?.code === "ENOENT") return []; throw error; }
+  }
+
+  async function append(event) {
+    const release = await acquireLock();
+    try {
+      const payload = eventPayload(event);
+      const record = {
+        schema_version: OUTBOX_SCHEMA_VERSION,
+        created_at: now().toISOString(),
+        producer_version: producerVersion,
+        repository,
+        event: payload,
+        delivery_attempts: 0,
+        checksum: hash(JSON.stringify(payload)),
+      };
+      const line = `${JSON.stringify(record)}\n`;
+      if (Buffer.byteLength(line) > MAX_OUTBOX_LINE_BYTES) {
+        const error = new Error("telemetry_event_oversized"); error.code = "telemetry_event_oversized"; throw error;
+      }
+      // append + fsync completes before the caller gets a durable receipt, which
+      // is the required pre-spawn barrier for foreground commands.
+      await durableWrite(path, line, { append: true });
+      await writeStatus({ last_error_class: null });
+      return { durable: true, path, event: payload };
+    } finally { await release(); }
+  }
+
+  async function quarantine(line, offset, reason) {
+    await durableWrite(quarantinePath, `${JSON.stringify({ offset, reason, quarantined_at: now().toISOString(), line: line.slice(0, MAX_OUTBOX_LINE_BYTES) })}\n`, { append: true });
+  }
+
+  async function replay(deliver, { maxEvents = Infinity, deadline = Infinity } = {}) {
+    if (typeof deliver !== "function") throw new Error("telemetry replay requires a delivery function");
+    const release = await acquireLock();
+    try {
+      const lines = await readLines();
+      const remaining = [];
+      let delivered = 0;
+      let quarantined = 0;
+      let halted = false;
+      let attempted = 0;
+      let offset = 0;
+      for (const line of lines) {
+        let record;
+        try {
+          if (Buffer.byteLength(line) > MAX_OUTBOX_LINE_BYTES) throw new Error("line_oversized");
+          record = parseRecord(line);
+        } catch (error) {
+          quarantined += 1;
+          await quarantine(line, offset, error.message || "invalid_record");
+          offset += Buffer.byteLength(line) + 1;
+          continue;
+        }
+        if (halted || attempted >= maxEvents || Date.now() >= deadline) { halted = true; remaining.push(record); offset += Buffer.byteLength(line) + 1; continue; }
+        try {
+          attempted += 1;
+          const result = await deliver(record.event, record);
+          if (!result?.accepted) {
+            if (result?.permanent) {
+              quarantined += 1;
+              await quarantine(line, offset, result.error ?? "delivery_rejected");
+              continue;
+            }
+            throw Object.assign(new Error("delivery_rejected"), { code: result?.error ?? "delivery_rejected" });
+          }
+          delivered += 1;
+          await writeStatus({ last_successful_delivery_at: now().toISOString(), last_error_class: null });
+        } catch (error) {
+          halted = true;
+          remaining.push({ ...record, delivery_attempts: Number(record.delivery_attempts ?? 0) + 1, last_error_class: safeErrorClass(error), last_attempt_at: now().toISOString() });
+          await writeStatus({ last_error_class: safeErrorClass(error) });
+        }
+        offset += Buffer.byteLength(line) + 1;
+      }
+      const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+      await durableWrite(tmp, remaining.map((record) => `${JSON.stringify(record)}\n`).join(""));
+      await rename(tmp, path);
+      let dir;
+      try { dir = await open(directory, "r"); await dir.sync(); } finally { await dir?.close(); }
+      return { delivered, remaining: remaining.length, quarantined };
+    } finally { await release(); }
+  }
+
+  async function status() {
+    const lines = await readLines();
+    let oldest = null;
+    let queued = 0;
+    for (const line of lines) {
+      try {
+        const record = parseRecord(line);
+        queued += 1;
+        if (!oldest || record.created_at < oldest) oldest = record.created_at;
+      } catch { queued += 1; }
+    }
+    const persisted = await readStatus();
+    return {
+      queued_count: queued,
+      oldest_queued_at: oldest,
+      last_successful_delivery_at: persisted.last_successful_delivery_at ?? null,
+      last_error_class: persisted.last_error_class ?? null,
+      producer_version: producerVersion,
+      path,
+    };
+  }
+
+  // The historical hook reporter writes summaries below `.botbuddy/test-runs`.
+  // Import them only through deterministic source/event keys; the persisted
+  // fingerprint ledger prevents repeated scans from growing the outbox, while
+  // server idempotency remains a second safety net if a machine dies mid-write.
+  async function importLegacyTestRunReceipts(legacyDirectory, { maxReceipts = Infinity, deadline = Infinity } = {}) {
+    let imported = {};
+    try { imported = JSON.parse(await readFile(legacyImportPath, "utf8")); } catch { /* first migration */ }
+    let names = [];
+    try { names = (await readdir(legacyDirectory)).filter((name) => name.endsWith(".json")); } catch (error) { if (error?.code === "ENOENT") return { imported: 0, skipped: 0 }; throw error; }
+    let added = 0;
+    let skipped = 0;
+    for (const name of names.sort()) {
+      if (added >= maxReceipts || Date.now() >= deadline) break;
+      const file = join(legacyDirectory, name);
+      let raw;
+      try { raw = await readFile(file, "utf8"); } catch { skipped += 1; continue; }
+      const fingerprint = hash(`${name}\0${raw}`);
+      if (imported[fingerprint]) { skipped += 1; continue; }
+      let summary;
+      try { summary = JSON.parse(raw); } catch { skipped += 1; continue; }
+      if (!summary || typeof summary !== "object" || typeof summary.runner !== "string") { skipped += 1; continue; }
+      const sourceRunId = `legacy-${fingerprint.slice(0, 32)}`;
+      const started = typeof summary.started_at === "string" ? summary.started_at : now().toISOString();
+      const finished = typeof summary.finished_at === "string" ? summary.finished_at : now().toISOString();
+      const passed = summary.verdict === "pass" || summary.exit_code === 0;
+      const context = { repo: repository, environment: "local", runner: summary.runner, phase: passed ? "complete" : "failed", health: "uninstrumented" };
+      await append({ schema_version: 1, action: "start", producer_kind: "hook", source_run_id: sourceRunId, attempt: 1, producer_event_id: `${sourceRunId}:start`, producer_sequence: 0, occurred_at: started, context });
+      await append({ schema_version: 1, action: "terminal", producer_kind: "hook", source_run_id: sourceRunId, attempt: 1, producer_event_id: `${sourceRunId}:terminal`, producer_sequence: 1, occurred_at: finished, context, outcome: passed ? "passed" : "failed" });
+      imported[fingerprint] = { name, imported_at: now().toISOString() };
+      added += 1;
+    }
+    await atomicJson(legacyImportPath, imported);
+    return { imported: added, skipped };
+  }
+
+  return { directory, path, quarantinePath, statusPath, append, replay, status, hasCredentialAttestation, recordCredentialAttestation, importLegacyTestRunReceipts };
+}

package/src/wait-profile.mjs

@@ -1,116 +1,165 @@
 import { readFile } from "node:fs/promises";
 import { dirname, join, parse } from "node:path";
-import { readProfileCredential } from "./agent-credential-store.mjs";
+import {
+  readKeychainSecret,
+  keychainAvailable,
+  DEFAULT_MCP_ENV_VAR,
+} from "./agent-credential-store.mjs";
+import { getConfig } from "./config.mjs";
 
-// Public CLI profiles remain tenant-bound machine-principal contracts.
-export const PROFILE_FILE = ".botbuddy-agent.json";
+// BOT-1608: the committed repo file that binds a worktree to a tenant and names
+// the env/Keychain var carrying its MCP credential — DATA, not an indirection
+// through a hard-coded profile name (the retired PROFILES map). It co-locates
+// with `.mcp.json`, which already declares the tenant via `?tenant=`.
+export const AGENT_BINDING_FILE = ".botbuddy-agent.json";
 
-const PROFILES = Object.freeze({
-  "botbuddy-dev": Object.freeze({
-    tenant: "botbuddy",
-    tokenEnv: "BOTBUDDY_BB_AGENT_KEY",
-  }),
-  "supplyguard-dev": Object.freeze({
-    tenant: "supply-guard",
-    tokenEnv: "BOTBUDDY_SG_AGENT_KEY",
-  }),
-});
+// Same slug shape the server accepts on `?tenant=`, and a shell env-var name.
+const TENANT_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const ENV_VAR_RE = /^[A-Z][A-Z0-9_]*$/;
 
-export function getAgentProfile(name) {
-  return PROFILES[name] ?? null;
-}
-
-// BOT-1593: when no profile is named (no --profile, no .botbuddy-agent.json) but
-// EXACTLY ONE supported profile's credential env var is populated, that slot is the
-// unambiguous profile. Used only by best-effort setup-error telemetry to attribute a
-// `profile_required` failure that still has a usable env bearer — never for the wait
-// itself. Returns the profile name, or null when zero or more than one slot is set
-// (ambiguous → no attribution). Reads env only; never touches the Keychain.
-export function findEnvProfile(env = process.env) {
-  const populated = Object.entries(PROFILES).filter(
-    ([, { tokenEnv }]) => typeof env[tokenEnv] === "string" && env[tokenEnv].length > 0,
-  );
-  return populated.length === 1 ? populated[0][0] : null;
+// Parse a `.botbuddy-agent.json` body into { tenant, mcpEnv }. Fails CLOSED on a
+// malformed file and on the retired `{ profile }` shape — the profile→tenant map
+// is exactly what BOT-1608 deletes, so a `{ profile }` file cannot be migrated
+// without re-introducing it. The error names the new shape (a one-time edit).
+export function parseAgentBinding(raw) {
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    const err = new Error(`${AGENT_BINDING_FILE} is not valid JSON`);
+    err.code = "invalid_binding";
+    throw err;
+  }
+  if (typeof config?.profile === "string" && config?.tenant == null) {
+    const err = new Error(
+      `${AGENT_BINDING_FILE} uses the retired { "profile" } shape — replace it with `
+        + `{ "schema_version": 1, "tenant": "<slug>", "mcp_env": "${DEFAULT_MCP_ENV_VAR}" } (BOT-1608)`,
+    );
+    err.code = "binding_migration_required";
+    throw err;
+  }
+  if (config?.schema_version !== 1 || typeof config?.tenant !== "string" || !TENANT_SLUG_RE.test(config.tenant)) {
+    const err = new Error(`${AGENT_BINDING_FILE} must declare schema_version 1 and a lowercase tenant slug`);
+    err.code = "invalid_binding";
+    throw err;
+  }
+  let mcpEnv = DEFAULT_MCP_ENV_VAR;
+  if (config.mcp_env != null) {
+    if (typeof config.mcp_env !== "string" || !ENV_VAR_RE.test(config.mcp_env)) {
+      const err = new Error(`${AGENT_BINDING_FILE} mcp_env must be an UPPER_SNAKE_CASE variable name`);
+      err.code = "invalid_binding";
+      throw err;
+    }
+    mcpEnv = config.mcp_env;
+  }
+  return { tenant: config.tenant, mcpEnv };
 }
 
-export async function findProfileName(cwd) {
+// Read the committed `.botbuddy-agent.json`, walking up from cwd to the fs root.
+// Returns { tenant, mcpEnv } or null when no file exists anywhere above cwd; a
+// malformed / retired-shape file throws (see parseAgentBinding).
+export async function readAgentBinding(cwd = process.cwd()) {
   let dir = cwd;
   const root = parse(dir).root;
   while (true) {
+    let raw = null;
     try {
-      const raw = await readFile(join(dir, PROFILE_FILE), "utf8");
-      const config = JSON.parse(raw);
-      if (config?.schema_version !== 1 || typeof config?.profile !== "string") {
-        throw new Error(`${PROFILE_FILE} must contain schema_version 1 and a profile`);
-      }
-      return config.profile;
+      raw = await readFile(join(dir, AGENT_BINDING_FILE), "utf8");
     } catch (err) {
       if (err?.code !== "ENOENT") throw err;
     }
+    if (raw != null) return parseAgentBinding(raw);
     if (dir === root) return null;
     dir = dirname(dir);
   }
 }
 
-export async function resolveAgentProfile({
+// The tenants the current login credential can reach (from `botbuddy login`),
+// used for the "sole configured tenant" resolution rung. Best-effort: an empty
+// list (config not loaded, or a tenant-sealed token) simply skips that rung.
+function defaultConfiguredTenants() {
+  const cfg = getConfig() ?? {};
+  return Array.isArray(cfg.token_tenants) ? cfg.token_tenants.filter((t) => typeof t === "string" && t) : [];
+}
+
+// The credential for a resolved binding: the mcp_env var (loaded from the shell,
+// or the Keychain item whose service name IS that var). Never reads the Keychain
+// when it is unavailable (BOTBUDDY_NO_KEYCHAIN / non-darwin) — the env var is the
+// sole source there.
+async function defaultReadCredential(mcpEnv, env) {
+  const fromEnv = typeof env[mcpEnv] === "string" && env[mcpEnv] ? env[mcpEnv] : null;
+  if (fromEnv) return fromEnv;
+  if (!keychainAvailable()) return null;
+  return readKeychainSecret(mcpEnv);
+}
+
+// BOT-1604 AC9 / BOT-1608 resolution order for in-repo agent-context commands
+// (`bb-wait`, `botbuddy pw`, …): explicit `--tenant`/`--env` → the committed
+// `.botbuddy-agent.json` → the sole configured login tenant if exactly one →
+// else FAIL CLOSED with an actionable error. Never a silent default.
+//
+// Returns { tenant, tokenEnv, token } — tokenEnv is the resolved mcp_env var and
+// token the credential read from it (or an explicit override). `token` may be
+// null (no credential exported yet); the caller decides whether that is fatal.
+export async function resolveAgentBinding({
   cwd = process.cwd(),
   env = process.env,
-  explicitProfile = null,
+  explicitTenant = null,
+  explicitEnv = null,
   explicitToken = null,
-  readCredential = readProfileCredential,
+  readBinding = readAgentBinding,
+  configuredTenants = defaultConfiguredTenants,
+  readCredential = defaultReadCredential,
 } = {}) {
-  const name = explicitProfile || await findProfileName(cwd);
-  if (!name) {
+  let binding = null;
+  let bindingError = null;
+  try {
+    binding = await readBinding(cwd);
+  } catch (err) {
+    bindingError = err;
+  }
+
+  let tenant = explicitTenant || binding?.tenant || null;
+  // A malformed/retired committed file must NOT be silently bypassed by the
+  // sole-configured-tenant fallback (Codex P2): when readBinding threw and no
+  // explicit --tenant overrode it, skip the fallback so bindingError surfaces
+  // below. An explicit --tenant is still an intentional override.
+  if (!tenant && !bindingError) {
+    const tenants = configuredTenants();
+    if (tenants.length === 1) tenant = tenants[0];
+  }
+  if (!tenant) {
+    // A malformed committed file is the more specific failure — surface it so the
+    // operator fixes the file rather than chasing a generic "no binding" message.
+    if (bindingError) throw bindingError;
     const err = new Error(
-      `no BotBuddy agent profile found (add ${PROFILE_FILE} or pass --profile)`,
+      `no BotBuddy tenant resolved — commit a ${AGENT_BINDING_FILE} `
+        + `({"schema_version":1,"tenant":"<slug>","mcp_env":"${DEFAULT_MCP_ENV_VAR}"}) `
+        + "or pass --tenant <slug>",
     );
-    err.code = "profile_required";
+    err.code = "agent_binding_required";
     throw err;
   }
-  const profile = getAgentProfile(name);
-  if (!profile) {
-    const err = new Error(`unknown BotBuddy agent profile '${name}'`);
-    err.code = "unknown_profile";
-    throw err;
-  }
-  return {
-    name,
-    tenant: profile.tenant,
-    tokenEnv: profile.tokenEnv,
-    // A freshly bootstrapped credential must take effect even if a calling shell
-    // still has a stale profile variable. `--token` remains the explicit escape
-    // hatch for a one-off credential.
-    token: explicitToken || await readCredential(name) || env[profile.tokenEnv] || null,
-  };
+
+  const tokenEnv = explicitEnv || binding?.mcpEnv || DEFAULT_MCP_ENV_VAR;
+  const token = explicitToken || (await readCredential(tokenEnv, env)) || null;
+  return { tenant, tokenEnv, token };
 }
 
-export function withPrincipalReceipt(receipt, profile, registration = {}) {
-  if (!profile) {
-    // BOT-1572: a session-token wait has no profile, but the receipt must still
-    // carry principal.session_id / agent_id / tenant_id derived by the relay from
-    // the token. Only attach when the relay actually echoed a session identity.
-    if (registration.sessionId || registration.agentId || registration.sessionTenant != null) {
-      return {
-        ...receipt,
-        principal: {
-          profile: null,
-          tenant_id: registration.sessionTenant ?? null,
-          agent_id: registration.agentId ?? null,
-          session_id: registration.sessionId ?? null,
-          session_agent_id: registration.sessionAgentId ?? null,
-        },
-      };
-    }
-    return receipt;
-  }
+// Attach the resolved principal to a wait receipt. With the profile bridge gone
+// there is no profile name — the tenant comes from the binding (or the relay's
+// session identity). Only attached when a principal identity is known.
+export function withPrincipalReceipt(receipt, binding, registration = {}) {
+  const hasSession =
+    registration.sessionId || registration.agentId || registration.sessionTenant != null;
+  if (!binding && !hasSession) return receipt;
   return {
     ...receipt,
     principal: {
-      profile: profile.name,
-      tenant_id: registration.sessionTenant ?? profile.tenant,
+      tenant_id: registration.sessionTenant ?? binding?.tenant ?? null,
       agent_id: registration.agentId ?? null,
       // BOT-1467: the arming session's agent, when the relay attributed the wait
-      // to it instead of the profile agent (null for an ordinary profile wait).
+      // to it (null for an ordinary binding wait).
       session_id: registration.sessionId ?? null,
       session_agent_id: registration.sessionAgentId ?? null,
     },