bosun 0.42.5 → 0.43.0

package/voice/vision-session-state.mjs

@@ -10,6 +10,7 @@ const _visionSessionState = new Map();
 const MAX_TRACE_TURNS = 12;
 const MAX_TURN_EVENTS = 40;
 const MAX_TURN_FINGERPRINTS = 32;
+const MAX_MULTIMODAL_FALLBACK_HISTORY = 8;
 const SECRET_KEY_PATTERN = /(token|key|secret|password|authorization|credential|cookie|client_secret|access_token)/i;
 
 function getSessionKey(sessionId) {
@@ -20,6 +21,47 @@ function nowIso() {
   return new Date().toISOString();
 }
 
+function cloneValue(value) {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function uniqueStrings(values) {
+  return [...new Set(
+    (Array.isArray(values) ? values : [values])
+      .map((entry) => String(entry ?? "").trim())
+      .filter(Boolean),
+  )];
+}
+
+function buildProfileSlug(value, fallback = "session") {
+  const src = String(value || "").trim().toLowerCase();
+  let result = "";
+  for (const ch of src) {
+    if ((ch >= "a" && ch <= "z") || (ch >= "0" && ch <= "9") || ch === "." || ch === "_") {
+      result += ch;
+    } else if (result.length > 0 && result[result.length - 1] !== "-") {
+      result += "-";
+    }
+  }
+  while (result.endsWith("-")) result = result.slice(0, -1);
+  while (result.startsWith("-")) result = result.slice(1);
+  return result || fallback;
+}
+
+function normalizeText(value) {
+  return String(value ?? "").trim();
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (value === true || value === false) return value;
+  const normalized = normalizeText(value).toLowerCase();
+  if (!normalized) return fallback;
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return fallback;
+}
+
 function redactSecretLikeText(value) {
   const raw = String(value || "").trim();
   if (!raw) return raw;
@@ -128,6 +170,87 @@ function annotateTurnFromEvent(turn, event) {
   }
 }
 
+function normalizeBrowserWorkerIsolation(input = {}, fallback = {}) {
+  const source = {
+    ...(fallback && typeof fallback === "object" ? fallback : {}),
+    ...(input && typeof input === "object" ? input : {}),
+  };
+  const sessionId = getSessionKey(source.sessionId || source.ownerSessionId || fallback?.sessionId);
+  const parentSessionId = getSessionKey(source.parentSessionId || fallback?.parentSessionId) || null;
+  const rootSessionId = getSessionKey(source.rootSessionId || fallback?.rootSessionId) || parentSessionId || sessionId || null;
+  const profileScope = normalizeText(source.profileScope || fallback?.profileScope || "isolated-subagent") || "isolated-subagent";
+  const profileId = normalizeText(
+    source.profileId
+    || fallback?.profileId
+    || `${buildProfileSlug(rootSessionId || "root", "root")}--${buildProfileSlug(sessionId || "session")}`,
+  ) || `${buildProfileSlug(rootSessionId || "root", "root")}--${buildProfileSlug(sessionId || "session")}`;
+  const multimodalFallback = normalizeMultimodalFallback(source.multimodalFallback, fallback?.multimodalFallback);
+  return {
+    workerId: normalizeText(source.workerId || fallback?.workerId || `browser-worker:${profileId}`) || `browser-worker:${profileId}`,
+    sessionId: sessionId || null,
+    ownerSessionId: sessionId || null,
+    parentSessionId,
+    rootSessionId,
+    profileId,
+    profileDir: normalizeText(source.profileDir || fallback?.profileDir || `.bosun/.cache/browser-workers/${profileId}`) || `.bosun/.cache/browser-workers/${profileId}`,
+    profileScope,
+    status: normalizeText(source.status || fallback?.status || "attached") || "attached",
+    requestedCapabilities: uniqueStrings(source.requestedCapabilities || fallback?.requestedCapabilities),
+    toolHints: uniqueStrings(source.toolHints || fallback?.toolHints),
+    multimodalFallback,
+    metadata: sanitizeTraceValue(source.metadata || fallback?.metadata || {}),
+    assignedAt: normalizeText(source.assignedAt || fallback?.assignedAt || "") || nowIso(),
+    updatedAt: nowIso(),
+    releasedAt: normalizeText(source.releasedAt || fallback?.releasedAt || "") || null,
+  };
+}
+
+function normalizeMultimodalFallback(input = {}, fallback = {}) {
+  const source = {
+    ...(fallback && typeof fallback === "object" ? fallback : {}),
+    ...(input && typeof input === "object" ? input : {}),
+  };
+  const history = Array.isArray(source.history)
+    ? source.history
+        .filter((entry) => entry && typeof entry === "object")
+        .map((entry) => ({
+          at: normalizeText(entry.at || entry.timestamp || "") || nowIso(),
+          reason: normalizeText(entry.reason || "") || null,
+          summary: normalizeText(entry.summary || entry.description || "") || null,
+          source: normalizeText(entry.source || "") || null,
+        }))
+        .slice(-MAX_MULTIMODAL_FALLBACK_HISTORY)
+    : [];
+  return {
+    enabled: normalizeBoolean(source.enabled, true),
+    mode: normalizeText(source.mode || "vision_summary_to_text") || "vision_summary_to_text",
+    available: normalizeBoolean(source.available, history.length > 0 || Boolean(normalizeText(source.summary || source.description || source.lastDescription))),
+    reason: normalizeText(source.reason || "") || null,
+    summary: normalizeText(source.summary || source.description || source.lastDescription || "") || null,
+    source: normalizeText(source.source || "") || null,
+    frameHash: normalizeText(source.frameHash || "") || null,
+    width: Number.isFinite(Number(source.width)) ? Number(source.width) : null,
+    height: Number.isFinite(Number(source.height)) ? Number(source.height) : null,
+    updatedAt: normalizeText(source.updatedAt || source.lastUpdatedAt || "") || null,
+    history,
+  };
+}
+
+function buildMultimodalFallbackDescription(state, fallback = {}) {
+  const summary = normalizeText(fallback.summary || state?.lastSummary || "");
+  const source = normalizeText(fallback.source || state?.lastFrameSource || "") || "screen";
+  const width = Number.isFinite(Number(fallback.width)) ? Number(fallback.width) : state?.lastFrameWidth;
+  const height = Number.isFinite(Number(fallback.height)) ? Number(fallback.height) : state?.lastFrameHeight;
+  const dimension = width && height ? ` (${width}x${height})` : "";
+  if (summary) {
+    return `[${source}${dimension}] ${summary}`;
+  }
+  if (state?.lastFrameHash) {
+    return `Visual context from ${source}${dimension} is available for text fallback.`;
+  }
+  return "";
+}
+
 export function getVisionSessionState(sessionId) {
   const key = getSessionKey(sessionId);
   if (!key) return null;
@@ -143,6 +266,20 @@ export function getVisionSessionState(sessionId) {
       lastFrameSource: "screen",
       lastFrameWidth: null,
       lastFrameHeight: null,
+      browserWorker: null,
+      multimodalFallback: {
+        enabled: true,
+        mode: "vision_summary_to_text",
+        available: false,
+        reason: null,
+        summary: null,
+        source: null,
+        frameHash: null,
+        width: null,
+        height: null,
+        updatedAt: null,
+        history: [],
+      },
       voiceTurnTrace: null,
     });
   }
@@ -155,6 +292,126 @@ export function clearVisionSessionState(sessionId) {
   return _visionSessionState.delete(key);
 }
 
+export function ensureBrowserWorkerIsolation(sessionId, options = {}) {
+  const state = getVisionSessionState(sessionId);
+  if (!state) return null;
+  state.browserWorker = normalizeBrowserWorkerIsolation({
+    sessionId,
+    ...options,
+  }, state.browserWorker || {});
+  if (!state.multimodalFallback || typeof state.multimodalFallback !== "object") {
+    state.multimodalFallback = normalizeMultimodalFallback();
+  }
+  if (options.multimodalFallback || state.browserWorker?.multimodalFallback) {
+    state.multimodalFallback = normalizeMultimodalFallback(
+      state.browserWorker?.multimodalFallback || options.multimodalFallback,
+      state.multimodalFallback,
+    );
+  }
+  return cloneValue(state.browserWorker);
+}
+
+export function getBrowserWorkerIsolation(sessionId) {
+  const state = getVisionSessionState(sessionId);
+  if (!state?.browserWorker) return null;
+  return cloneValue(state.browserWorker);
+}
+
+export function listBrowserWorkerIsolations(options = {}) {
+  const rootSessionId = getSessionKey(options.rootSessionId);
+  const parentSessionId = getSessionKey(options.parentSessionId);
+  return [..._visionSessionState.values()]
+    .map((state) => state?.browserWorker || null)
+    .filter(Boolean)
+    .filter((worker) => {
+      if (rootSessionId && getSessionKey(worker.rootSessionId) !== rootSessionId) return false;
+      if (parentSessionId && getSessionKey(worker.parentSessionId) !== parentSessionId) return false;
+      return true;
+    })
+    .map((worker) => cloneValue(worker));
+}
+
+export function releaseBrowserWorkerIsolation(sessionId, reason = "released") {
+  const state = getVisionSessionState(sessionId);
+  if (!state?.browserWorker) return null;
+  const released = normalizeBrowserWorkerIsolation({
+    ...state.browserWorker,
+    status: "released",
+    releasedAt: nowIso(),
+    metadata: {
+      ...(state.browserWorker.metadata && typeof state.browserWorker.metadata === "object" ? state.browserWorker.metadata : {}),
+      releaseReason: normalizeText(reason) || "released",
+    },
+  }, state.browserWorker);
+  state.browserWorker = null;
+  return cloneValue(released);
+}
+
+export function recordMultimodalFallback(sessionId, input = {}) {
+  const state = getVisionSessionState(sessionId);
+  if (!state) return null;
+  const description = buildMultimodalFallbackDescription(state, input);
+  const nextHistoryEntry = {
+    at: nowIso(),
+    reason: normalizeText(input.reason || "") || null,
+    summary: normalizeText(input.summary || input.description || description) || null,
+    source: normalizeText(input.source || state.lastFrameSource || "") || null,
+  };
+  const fallback = normalizeMultimodalFallback({
+    ...state.multimodalFallback,
+    ...input,
+    available: Boolean(description),
+    summary: description || normalizeText(input.summary || input.description || ""),
+    source: normalizeText(input.source || state.lastFrameSource || ""),
+    frameHash: normalizeText(input.frameHash || state.lastFrameHash || ""),
+    width: Number.isFinite(Number(input.width)) ? Number(input.width) : state.lastFrameWidth,
+    height: Number.isFinite(Number(input.height)) ? Number(input.height) : state.lastFrameHeight,
+    updatedAt: nowIso(),
+    history: [
+      ...(Array.isArray(state.multimodalFallback?.history) ? state.multimodalFallback.history : []),
+      nextHistoryEntry,
+    ].slice(-MAX_MULTIMODAL_FALLBACK_HISTORY),
+  }, state.multimodalFallback);
+  state.multimodalFallback = fallback;
+  if (state.browserWorker) {
+    state.browserWorker = normalizeBrowserWorkerIsolation({
+      ...state.browserWorker,
+      multimodalFallback: fallback,
+    }, state.browserWorker);
+  }
+  return cloneValue(fallback);
+}
+
+export function describeMultimodalFallback(sessionId, options = {}) {
+  const state = getVisionSessionState(sessionId);
+  if (!state) {
+    return {
+      sessionId: getSessionKey(sessionId),
+      available: false,
+      description: "",
+      browserWorker: null,
+    };
+  }
+  const fallback = normalizeMultimodalFallback(options, state.multimodalFallback);
+  const description = normalizeText(
+    options.description
+    || options.summary
+    || fallback.summary
+    || buildMultimodalFallbackDescription(state, fallback),
+  );
+  return {
+    sessionId: getSessionKey(sessionId),
+    available: Boolean(description),
+    description,
+    browserWorker: cloneValue(state.browserWorker),
+    fallback: cloneValue({
+      ...fallback,
+      summary: description || fallback.summary,
+      available: Boolean(description),
+    }),
+  };
+}
+
 export function beginVoiceTurnTrace(sessionId, metadata = {}) {
   const state = getVisionSessionState(sessionId);
   if (!state) return null;

package/voice/voice-action-dispatcher.mjs

@@ -376,6 +376,7 @@ registerAction("agent.delegate", async (params, context) => {
       model,
       cwd,
       sessionId,
+      scope: `voice-dispatch:${sessionId}`,
       sessionType: "voice-dispatch",
       timeoutMs: 5 * 60 * 1000,
     });
@@ -554,19 +555,20 @@ registerAction("system.fleet", async () => {
 registerAction("system.config", async (params) => {
   const cfg = loadConfig();
   const key = String(params.key || "").trim();
-  if (key) {
-    const value = cfg[key];
-    return value !== undefined ? { [key]: value } : { error: `Config key "${key}" not found.` };
-  }
-  return {
-    primaryAgent: cfg.primaryAgent,
-    mode: cfg.mode,
-    kanbanBackend: cfg.kanbanBackend || cfg.kanban?.backend,
-    projectName: cfg.projectName,
+  const normalizedConfig = {
+    primaryAgent: cfg.primaryAgent || getPrimaryAgentName(),
+    mode: cfg.mode || "generic",
+    kanbanBackend: cfg.kanbanBackend || cfg.kanban?.backend || "internal",
+    projectName: cfg.projectName || cfg.project || process.env.PROJECT_NAME || "unknown",
     autoFixEnabled: cfg.autoFixEnabled,
     watchEnabled: cfg.watchEnabled,
     voiceEnabled: cfg.voice?.enabled !== false,
   };
+  if (key) {
+    const value = normalizedConfig[key] ?? cfg[key];
+    return value !== undefined ? { [key]: value } : { error: `Config key "${key}" not found.` };
+  }
+  return normalizedConfig;
 });
 
 registerAction("system.health", async () => {
@@ -854,10 +856,54 @@ registerAction("workflow.retry", async (params) => {
   const currentRun = engine?.getRunDetail ? engine.getRunDetail(runId) : null;
   if (!currentRun) throw new Error(`Workflow run "${runId}" not found`);
   const currentStatus = String(currentRun?.status || "").trim().toLowerCase();
-  if (mode === "from_failed" && currentStatus !== "failed") {
+  const retryOptions = typeof engine.getRetryOptions === "function"
+    ? engine.getRetryOptions(runId)
+    : null;
+  const safeInterruptedResume =
+    mode === "from_failed" &&
+    retryOptions?.guardedState?.code === "create_tasks_pending" &&
+    retryOptions?.guardedState?.safeResume === true &&
+    retryOptions?.recommendedMode === "from_failed";
+  const createTasksPendingGuard = retryOptions?.guardedState?.code === "create_tasks_pending";
+  if (mode === "from_failed" && currentStatus !== "failed" && !createTasksPendingGuard) {
     throw new Error(`retry mode "from_failed" requires a failed run (current=${currentRun?.status || "unknown"})`);
   }
-  return engine.retryRun(runId, { mode });
+  const resolvedRetry = safeInterruptedResume
+    ? {
+        mode,
+        operatorAction: "resume",
+        decisionReason: retryOptions?.recommendedReason || "create_tasks_pending.resume_only",
+        blocked: false,
+        guardedState: retryOptions?.guardedState || null,
+        retryArgs: {
+          mode,
+          _resumeInterrupted: true,
+          ...(retryOptions?.recommendedReason
+            ? { _decisionReason: retryOptions.recommendedReason }
+            : {}),
+        },
+      }
+    : (
+        createTasksPendingGuard && typeof engine.resolveOperatorRetry === "function"
+          ? engine.resolveOperatorRetry(runId, mode)
+          : null
+      );
+  if (resolvedRetry?.blocked) {
+    throw new Error(resolvedRetry.blockedMessage || "Workflow retry is blocked for this run state.");
+  }
+  const retryArgs = resolvedRetry?.retryArgs || { mode };
+  if (safeInterruptedResume && !resolvedRetry?.retryArgs) {
+    retryArgs._resumeInterrupted = true;
+    if (retryOptions?.recommendedReason) retryArgs._decisionReason = retryOptions.recommendedReason;
+  }
+  const result = await engine.retryRun(runId, retryArgs);
+  return {
+    ...result,
+    operatorAction:
+      resolvedRetry?.operatorAction || (mode === "from_scratch" ? "restart" : "retry"),
+    decisionReason: resolvedRetry?.decisionReason || null,
+    guardedState: resolvedRetry?.guardedState || retryOptions?.guardedState || null,
+  };
 });
 
 // ── Skill/prompt actions ────────────────────────────────────────────────────
@@ -1241,4 +1287,3 @@ export function getVoiceActionPromptSection() {
   lines.push("");
   return lines.join("\n");
 }
-

package/voice/voice-agents-sdk.mjs

@@ -17,7 +17,7 @@
  */
 
 import { loadConfig } from "../config/config.mjs";
-import { resolveVoiceOAuthToken } from "./voice-auth-manager.mjs";
+import { resolveSharedOAuthToken as resolveVoiceOAuthToken } from "../agent/provider-auth-state.mjs";
 
 // ── Module-scope lazy imports ───────────────────────────────────────────────
 

package/voice/voice-auth-manager.mjs

@@ -1,15 +1,15 @@
 import { createHash, randomBytes } from "node:crypto";
 import { exec as childExec } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-
-const VOICE_AUTH_STATE_PATH = join(homedir(), ".bosun", "voice-auth-state.json");
-const STATE_TTL_MS = 15_000;
-
-let _cachedState = null;
-let _cachedStateAt = 0;
+import { CredentialStore } from "../workflow/credential-store.mjs";
+import {
+  clearSharedOAuthToken,
+  getProviderAuthStatePath,
+  hasSharedOAuthToken,
+  readProviderAuthState,
+  resolveSharedOAuthToken,
+  saveSharedOAuthToken,
+} from "../agent/provider-auth-state.mjs";
 
 function normalizeProvider(provider) {
   return String(provider || "").trim().toLowerCase();
@@ -32,27 +32,6 @@ function escapeHtml(value) {
     .replace(/'/g, ''');
 }
 
-function readStateFile() {
-  if (!existsSync(VOICE_AUTH_STATE_PATH)) return {};
-  const raw = readFileSync(VOICE_AUTH_STATE_PATH, "utf8");
-  const parsed = JSON.parse(raw);
-  if (!parsed || typeof parsed !== "object") return {};
-  return parsed;
-}
-
-function getCachedState(forceReload = false) {
-  const isFresh = !forceReload && _cachedState && Date.now() - _cachedStateAt < STATE_TTL_MS;
-  if (isFresh) return _cachedState;
-
-  try {
-    _cachedState = readStateFile();
-  } catch {
-    _cachedState = {};
-  }
-  _cachedStateAt = Date.now();
-  return _cachedState;
-}
-
 function isExpired(expiresAt) {
   if (!expiresAt) return false;
   const ts = Number(new Date(expiresAt).getTime());
@@ -60,6 +39,19 @@ function isExpired(expiresAt) {
   return ts <= Date.now() + 30_000;
 }
 
+function resolveCredentialStore(options = {}) {
+  if (options.credentialStore) return options.credentialStore;
+  if (!options.configDir) return null;
+  try {
+    return new CredentialStore({
+      configDir: options.configDir,
+      secretKey: options.secretKey,
+    });
+  } catch {
+    return null;
+  }
+}
+
 function getProviderEnvCandidates(provider) {
   switch (provider) {
     case "openai":
@@ -89,98 +81,22 @@ function getProviderEnvCandidates(provider) {
   }
 }
 
-function getStateTokenCandidates(provider, state) {
-  const byProvider = state?.providers?.[provider] || state?.[provider] || {};
-  return [
-    {
-      token: byProvider?.accessToken,
-      expiresAt: byProvider?.expiresAt,
-      source: "state",
-    },
-    {
-      token: byProvider?.access_token,
-      expiresAt: byProvider?.expires_at,
-      source: "state",
-    },
-  ];
-}
-
 export function resolveVoiceOAuthToken(provider, forceReload = false) {
   const normalizedProvider = normalizeProvider(provider);
   if (!normalizedProvider) return null;
-
-  const envToken = getProviderEnvCandidates(normalizedProvider)
-    .map((token) => normalizeEnvValue(token))
-    .find(Boolean);
-  if (envToken) {
-    return {
-      token: envToken,
-      source: "env",
-      provider: normalizedProvider,
-    };
-  }
-
-  const state = getCachedState(forceReload);
-  const candidates = getStateTokenCandidates(normalizedProvider, state);
-  for (const candidate of candidates) {
-    const token = String(candidate?.token || "").trim();
-    if (!token) continue;
-    if (isExpired(candidate?.expiresAt)) continue;
-    return {
-      token,
-      source: candidate.source,
-      provider: normalizedProvider,
-      expiresAt: candidate?.expiresAt || null,
-    };
-  }
-
-  return null;
+  return resolveSharedOAuthToken(normalizedProvider, forceReload);
 }
 
 export function hasVoiceOAuthToken(provider, forceReload = false) {
-  return Boolean(resolveVoiceOAuthToken(provider, forceReload));
+  return hasSharedOAuthToken(provider, forceReload);
 }
 
 export function saveVoiceOAuthToken(provider, payload = {}) {
-  const normalizedProvider = normalizeProvider(provider);
-  if (!normalizedProvider) {
-    throw new Error("provider is required");
-  }
-
-  const token = String(payload?.accessToken || payload?.access_token || "").trim();
-  if (!token) {
-    throw new Error("access token is required");
-  }
-
-  const current = getCachedState(true);
-  const next = {
-    ...current,
-    providers: {
-      ...(current?.providers || {}),
-      [normalizedProvider]: {
-        accessToken: token,
-        expiresAt: payload?.expiresAt || payload?.expires_at || null,
-        refreshToken: payload?.refreshToken || payload?.refresh_token || null,
-        tokenType: payload?.tokenType || payload?.token_type || "Bearer",
-        updatedAt: new Date().toISOString(),
-      },
-    },
-  };
-
-  mkdirSync(dirname(VOICE_AUTH_STATE_PATH), { recursive: true });
-  writeFileSync(VOICE_AUTH_STATE_PATH, JSON.stringify(next, null, 2));
-  _cachedState = next;
-  _cachedStateAt = Date.now();
-
-  return {
-    ok: true,
-    path: VOICE_AUTH_STATE_PATH,
-    provider: normalizedProvider,
-  };
+  return saveSharedOAuthToken(provider, payload);
 }
 
 export function getVoiceAuthStatePath() {
-  return VOICE_AUTH_STATE_PATH;
+  return getProviderAuthStatePath();
 }
 
 // ── Generic OAuth PKCE provider registry ─────────────────────────────────────
@@ -286,6 +202,80 @@ const OAUTH_PROVIDERS = {
   },
 };
 
+function resolveVoiceProviderCredentialRecord(provider, options = {}) {
+  const credentialStore = resolveCredentialStore(options);
+  if (!credentialStore) return { record: null, validation: null };
+  const candidates = credentialStore.listByProvider(provider);
+  const record = candidates.find((entry) => {
+    const authMode = normalizeProvider(entry?.lifecycle?.authMode || entry?.metadata?.authMode || "oauth");
+    return !authMode || authMode === "oauth";
+  }) || null;
+  if (!record) return { record: null, validation: null };
+  return {
+    record,
+    validation: credentialStore.validate(record.name, {
+      env: options.env || process.env,
+      config: options.config || null,
+      workflowId: options.workflowId,
+    }),
+  };
+}
+
+export function describeVoiceProviderLifecycle(provider, options = {}) {
+  const normalizedProvider = normalizeProvider(provider);
+  const cfg = OAUTH_PROVIDERS[normalizedProvider];
+  if (!cfg) {
+    return {
+      provider: normalizedProvider,
+      status: "unknown",
+      missingActions: [],
+      envKeys: [],
+      refreshable: false,
+    };
+  }
+
+  const token = resolveVoiceOAuthToken(normalizedProvider, options.forceReload === true);
+  const loginStatus = _providerPendingLogin.get(normalizedProvider)?.status || "idle";
+  const clientIdConfigured = normalizeEnvValue(cfg.clientId).length >= 8;
+  const { record, validation } = resolveVoiceProviderCredentialRecord(normalizedProvider, options);
+  const refreshable = Boolean(token?.refreshToken || validation?.refreshable);
+  const missingActions = [];
+
+  if (!clientIdConfigured) missingActions.push("configure_client");
+  if (!token?.token && !record?.name) missingActions.push("sign_in");
+  if (token?.expiresAt && isExpired(token.expiresAt) && refreshable) missingActions.push("refresh_token");
+
+  return {
+    provider: normalizedProvider,
+    status: token?.token
+      ? (isExpired(token.expiresAt) ? "expired" : "connected")
+      : (loginStatus === "pending" ? "pending" : "idle"),
+    hasToken: Boolean(token?.token),
+    expiresAt: token?.expiresAt || validation?.expiresAt || null,
+    refreshable,
+    connectedSource: token?.source || (record?.name ? "credential-store" : null),
+    pendingStatus: loginStatus,
+    clientIdConfigured,
+    requiredEnvKeys: cfg.clientSecret
+      ? [`BOSUN_${normalizedProvider.toUpperCase()}_OAUTH_CLIENT_ID`, `BOSUN_${normalizedProvider.toUpperCase()}_OAUTH_CLIENT_SECRET`]
+      : [`BOSUN_${normalizedProvider.toUpperCase()}_OAUTH_CLIENT_ID`],
+    missingActions,
+    credentialName: record?.name || null,
+    validationErrors: validation?.errors || [],
+  };
+}
+
+export function validateVoiceProviderLifecycle(provider, options = {}) {
+  const lifecycle = describeVoiceProviderLifecycle(provider, options);
+  return {
+    ok: lifecycle.missingActions.length === 0 && lifecycle.validationErrors.length === 0,
+    status: lifecycle.status,
+    missingActions: lifecycle.missingActions,
+    validationErrors: lifecycle.validationErrors,
+    refreshable: lifecycle.refreshable,
+  };
+}
+
 // Module-scope per-provider pending login state (never inside a function — hard rule).
 const _providerPendingLogin = new Map();
 
@@ -498,25 +488,14 @@ function _cancelProviderLogin(provider) {
 }
 
 function _logoutProvider(provider) {
-  const curr = getCachedState(true);
-  if (!curr?.providers?.[provider]) return { ok: true, wasLoggedIn: false };
-  const next = {
-    ...curr,
-    providers: { ...(curr.providers || {}) },
-  };
-  delete next.providers[provider];
-  mkdirSync(dirname(VOICE_AUTH_STATE_PATH), { recursive: true });
-  writeFileSync(VOICE_AUTH_STATE_PATH, JSON.stringify(next, null, 2));
-  _cachedState = next;
-  _cachedStateAt = Date.now();
-  return { ok: true, wasLoggedIn: true };
+  return clearSharedOAuthToken(provider);
 }
 
 async function _refreshProviderToken(provider) {
   const cfg = OAUTH_PROVIDERS[provider];
   if (!cfg) throw new Error(`Unknown OAuth provider: ${provider}`);
 
-  const state = getCachedState(true);
+  const state = readProviderAuthState(true);
   const providerData = state?.providers?.[provider] || {};
   const refreshToken = providerData.refreshToken || providerData.refresh_token;
   if (!refreshToken) throw new Error(`No refresh token stored for ${provider}`);