Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { SessionStatus } from './entities/session.entity';
import { RECONNECT_LOOP_ALERT_INTERVAL_ATTEMPTS } from './reconnect-policy';
import {
incrementSessionReconnectAttempts,
incrementSessionReconnectLoopAlerts,
} from '../../common/metrics/session-reconnect-metrics';
import { MessageProjector } from './message-projector.service';
import { SessionErrorStore } from './session-error-store.service';
import { SessionRestrictionStore } from './session-restriction-store.service';
import { PresenceStore } from './presence-store.service';
import { AuditService } from '../audit/audit.service';
import { AuditAction } from '../audit/entities/audit-log.entity';
import { EventsGateway } from '../events/events.gateway';
import { WebhookService } from '../webhook/webhook.service';
import { HookManager } from '../../core/hooks';
import {
EngineEventCallbacks,
EngineStatus,
IWhatsAppEngine,
IncomingCallEvent,
AccountRestriction,
PresenceUpdateEvent,
CallOutcomeEvent,
} from '../../engine/interfaces/whatsapp-engine.interface';
import { type createLogger } from '../../common/services/logger.service';
import { userPart } from '../../engine/identity/wa-id';
import { SessionEngineLeafEvents } from './session-engine-leaf-events';
/** The lastError an engine-internal reconnect episode records; onQRCode clears only this one. */
export const RECONNECT_LOOP_REASON = 'Reconnecting after a dropped connection';
/**
* The call-ins SessionEngineEventWiring needs from the lifecycle core. Built ONCE in the
* lifecycle's constructor. Only the CLOSURE members are live-read: the arrow closures bind the
* lifecycle's live methods/state (never a stale copy — specs replace some deps at runtime). The
* dependency VALUE members (messages, sessionErrors, webhookService, eventsGateway, hookManager,
* leafEvents) are captured once at construction — the same reads the pre-extraction inline code
* made of the lifecycle's readonly constructor fields. The closures are deliberately NON-async
* passthroughs returning the callee's own promise object untouched (the Task-1 delegate rule: an
* `async` wrapper would adopt the inner promise and add settlement hops the retirement-race specs
* assert against).
*/
export interface SessionEngineWiringHost {
/** Liveness gate: true only while `engine` is still the live engine registered for `id`. */
isLiveEngine(id: string, engine: IWhatsAppEngine): boolean;
/**
* True while an operator-initiated teardown (stop/logout/forceKill) is retiring exactly this
* engine instance. Its DISCONNECTED is that teardown's own, reported before the eviction; the verb
* announces the settled one once the engine is gone.
*/
isOperatorTeardown(id: string, engine: IWhatsAppEngine): boolean;
/**
* Ownership gate: true while this node may still speak for `id`. Orthogonal to isLiveEngine —
* between a lapsed lease and the teardown the heartbeat schedules, isLiveEngine is still true
* while this is already false. TRUE when no ownership service is wired (single process).
*/
ownsSession(id: string): boolean;
handleEngineReady(id: string, engine: IWhatsAppEngine, phone: string, pushName: string): void;
/**
* Refuse a ready link whose account differs from the one this session is bound to: tear the wrong
* account's engine down (logout wipes its credentials), land the session in FAILED, and record why.
* Never persists the incoming account, and deliberately keeps the original binding.
*/
rejectRebind(
id: string,
engine: IWhatsAppEngine,
sessionName: string,
previousPhone: string,
incomingPhone: string,
): Promise<void>;
handleEngineDisconnected(id: string, engine: IWhatsAppEngine, reason: string): Promise<void>;
updateStatus(id: string, status: SessionStatus): Promise<void>;
cancelReconnect(id: string): void;
/** The live engine reported a non-READY state: record when its READY stretch ended. */
endReadyStretch(id: string): void;
/**
* Park an engine failure reported while a service-level reconnect awaits its re-init, instead of
* applying it: `run` is the failure's side effects, and `reason` is set for an onError report.
* Returns false (nothing parked, the caller applies it now) outside that window.
*/
parkReconnectInitFailure(id: string, run: () => void, reason?: string): boolean;
evictAndForceDestroy(id: string, engine: IWhatsAppEngine): void;
trackPendingCredentialTeardown(sessionName: string, raw: Promise<void>): void;
/** Announce a restriction that has ended; shared with the lifecycle's own READY path. */
reportRestrictionLifted(id: string, lifted: AccountRestriction): void;
/**
* SYNCHRONOUS atomic one-shot claim over the lifecycle's shared stuckAuthRecoveryUsed Set (bound
* by reference through the closure): true exactly once per episode, and only while `engine` is
* still the live owner.
*/
claimStuckAuthRecovery(id: string, engine: IWhatsAppEngine): boolean;
messages: MessageProjector;
sessionErrors: SessionErrorStore;
sessionRestrictions: SessionRestrictionStore;
presence: PresenceStore;
/** @Global AuditService; absent only in the standalone constructions specs build. */
auditService?: AuditService;
webhookService: WebhookService;
eventsGateway: EventsGateway;
hookManager: HookManager;
leafEvents: SessionEngineLeafEvents;
}
/**
* The engine-callback wiring table extracted from SessionEngineLifecycle.initializeEngine: the 17
* callbacks passed to engine.initialize(). Plain class (NOT a NestJS provider — the lifecycle's
* constructor signature is frozen by specs), built inside the lifecycle's constructor. Stateless:
* buildCallbacks closes over (id, engine, sessionName) and reaches the lifecycle exclusively
* through `host`, so the emitted table is behaviorally identical to the inline original — the
* per-callback liveness gating (onMessage/onMessageCreate/onMessageAck/onMessageRevoked/
* onCredentialTeardownStarted are deliberately UNGATED) and every nested call's order preserved.
* The callback bodies moved verbatim, which is why they read `this.logger` against the same-named
* field assigned here; every other former `this.x` read goes through `host`. Specs capture the
* table from `mockEngine.initialize.mock.calls[0][0]` and invoke callbacks directly.
*/
export class SessionEngineEventWiring {
private readonly logger: ReturnType<typeof createLogger>;
constructor(deps: { logger: ReturnType<typeof createLogger> }) {
this.logger = deps.logger;
}
/**
* `previousPhone` is the phone the session row carried when this engine started (null on a fresh
* session), i.e. it had completed a link before. Its presence drives the relink warning below; its
* value gates the onReady account-binding check that refuses a different number's rescan.
* A QR from a previously-linked engine means the stored credentials are gone
* or no longer accepted, and when that happened while the engine was down nothing else in the
* log says so, hence the warning below. One-shot per engine start: a lifecycle reconnect builds a
* new table from the row, which still carries the phone, and warns again.
*/
buildCallbacks(
id: string,
engine: IWhatsAppEngine,
sessionName: string,
host: SessionEngineWiringHost,
previousPhone: string | null = null,
): EngineEventCallbacks {
// The phone this session was bound to when this engine started (null on a fresh session). Its
// presence is the relink signal used below; its value gates onReady's account-binding check.
const previouslyLinked = Boolean(previousPhone);
let relinkWarned = false;
// When the current engine-internal reconnect streak started (epoch ms): stamped at attempt 1, or
// at the first reconnect attempt after a READY, and cleared by onReady. An engine can carry its
// attempt counter across a short-lived READY (Baileys does, so a link that drops right after
// opening keeps backing off), and time spent READY is not downtime.
// Closure state rather than a Map: it is scoped to this engine instance. A service-level
// reconnect builds a new engine and a new callback table, so nothing has to be cleaned up.
let reconnectingSince = 0;
/**
* Persist an engine-driven status, but only while this node still owns the session.
*
* Every caller has already passed the isLiveEngine fence; this closes the other axis. A node
* whose lease lapsed keeps a live engine until the heartbeat's teardown completes, and a status
* written in that window lands on a row a peer now owns. FAILED is the one that does not heal:
* the boot reset and the takeover sweep both exclude it by design, so the session leaves every
* automatic recovery path until an operator restarts it by hand.
*/
const persistStatus = (status: SessionStatus): void => {
if (!host.ownsSession(id)) {
this.logger.warn('Skipped an engine status write for a session this node no longer owns', {
sessionId: id,
status,
action: 'status_write_skipped_not_owned',
});
return;
}
void host.updateStatus(id, status).catch(err =>
this.logger.warn('Failed to persist an engine status', {
sessionId: id,
status,
error: err instanceof Error ? err.message : String(err),
}),
);
};
return {
onQRCode: (qr: string): void => {
if (!host.isLiveEngine(id, engine)) return;
this.logger.log('QR code generated', {
sessionId: id,
action: 'qr_generated',
});
// A whatsapp-web.js revocation that happened while the engine was down leaves no other trace:
// the engine simply boots into the QR screen, with no LOGOUT, no auth failure and no audit
// row. The paths where OpenWA itself discarded the credentials (a LOGOUT close, the
// stuck-auth recovery) also end here, but each of those has already logged its own warning,
// and starting a session under a different ENGINE_TYPE than it was linked with lands here too.
if (previouslyLinked && !relinkWarned) {
relinkWarned = true;
this.logger.warn(
'Previously linked session is asking for a QR again: its stored credentials are missing or no ' +
'longer accepted. Unless an earlier warning for this session (LOGOUT, auth_cleared) or a changed ' +
'ENGINE_TYPE explains it, WhatsApp dropped the link while the engine was down (unlinked from the ' +
"phone, expired while offline, or the engine's stored auth state was lost). Check Linked devices " +
'on the phone before re-pairing.',
{ sessionId: id, action: 'relink_required' },
);
}
// A QR shows WhatsApp answered. Left in place, the recorded reconnect text would reappear in every
// INITIALIZING gap between QR windows of a session waiting to be paired; if closes keep failing
// after the QR, the next attempt from the fifth on writes it again. Any other reason stays.
if (host.sessionErrors.get(id)?.startsWith(RECONNECT_LOOP_REASON)) host.sessionErrors.clear(id);
void host.webhookService.dispatch(id, 'session.qr', { sessionId: id, qr });
// Push the QR to subscribed dashboard clients over the WebSocket (the `session.qr` event is
// advertised + consumed there, so clients can render it live instead of polling GET /qr).
host.eventsGateway.emitQRCode(id, qr);
// Execute hook for QR event
void host.hookManager.execute(
'session:qr',
{ sessionId: id },
{
sessionId: id,
source: 'Engine',
},
);
persistStatus(SessionStatus.QR_READY);
},
onReady: (phone, pushName): void => {
reconnectingSince = 0;
// Account-binding guard: a ready link whose number differs from the one this session is
// already bound to is a different account scanning its QR (a takeover), not a re-link. Refuse
// it rather than silently overwrite the binding. An empty incoming phone (wwjs can report one)
// is not identifiable, so it is never treated as a mismatch.
if (previousPhone && phone && userPart(phone) !== userPart(previousPhone)) {
void host.rejectRebind(id, engine, sessionName, previousPhone, phone);
return;
}
host.handleEngineReady(id, engine, phone, pushName);
},
// PostgreSQL only: holds each inbound message from arrival until its row is written.
...(host.messages.holdsInbound
? { admitInbound: arrival => host.messages.admitInbound(id, engine, arrival) }
: {}),
onMessage: (message, ticket) => host.messages.handleInboundMessage(id, engine, message, ticket),
onHistoryMessages: messages => {
if (!host.isLiveEngine(id, engine)) return;
// Persist for the chat view only; no dispatch (these predate the live session).
return host.messages
.persistHistoryMessages(id, engine, messages)
.catch(err => this.logger.error(`Failed to persist history messages for ${id}`, String(err)));
},
onMessageCreate: (message, ticket): void => host.messages.handleOwnSendEcho(id, engine, message, ticket),
onMessageAck: (messageId, status, chatId): void =>
host.messages.handleMessageAck(id, engine, messageId, status, chatId),
onMessageReceipt: (event): void => host.messages.handleMessageReceipt(id, engine, event),
onMessageRevoked: (message, actor): void => host.messages.handleMessageRevoked(id, engine, message, actor),
onMessageReaction: (event): void => {
if (!host.isLiveEngine(id, engine)) return;
if (!event.messageId) {
this.logger.warn('Ignoring message reaction without a target message id', {
sessionId: id,
action: 'message_reaction_ignored',
});
return;
}
this.logger.debug(`Message reaction received: ${event.messageId} -> ${event.reaction}`, {
sessionId: id,
messageId: event.messageId,
action: 'message_reaction_received',
});
host.messages.applyReactionQueued(id, event);
},
onMessageEdited: (message): void => {
if (!host.isLiveEngine(id, engine)) return;
if (!message.messageId) {
this.logger.warn('Ignoring message edit without a target message id', {
sessionId: id,
action: 'message_edit_ignored',
});
return;
}
this.logger.debug(`Message edited: ${message.messageId}`, {
sessionId: id,
messageId: message.messageId,
action: 'message_edited',
});
host.messages.applyMessageEditQueued(id, message);
},
onEventResponse: (event): void => {
if (!host.isLiveEngine(id, engine)) return;
this.logger.debug(`Event response: ${event.response} to ${event.eventMessageId}`, {
sessionId: id,
chatId: event.chatId,
eventMessageId: event.eventMessageId,
action: 'event_response',
});
const payload = { sessionId: id, ...event };
host.eventsGateway.emitEventResponse(id, payload);
void host.webhookService.dispatch(id, 'event.response', payload);
},
onPollVote: (event): void => {
if (!host.isLiveEngine(id, engine)) return;
if (!event.pollMessageId) {
this.logger.warn('Ignoring poll vote without a poll message id', {
sessionId: id,
action: 'poll_vote_ignored',
});
return;
}
this.logger.debug(`Poll vote: ${event.selectedOptions.length} option(s) on ${event.pollMessageId}`, {
sessionId: id,
chatId: event.chatId,
pollMessageId: event.pollMessageId,
action: 'poll_vote',
});
const payload = { sessionId: id, ...event };
host.eventsGateway.emitPollVote(id, payload);
void host.webhookService.dispatch(id, 'poll.vote', payload);
},
onGroupEvent: (event): void => {
if (!host.isLiveEngine(id, engine)) return;
this.logger.debug(`Group event: ${event.kind} in ${event.groupId}`, {
sessionId: id,
groupId: event.groupId,
kind: event.kind,
action: 'group_event',
});
host.leafEvents.dispatchGroupEvent(id, event);
},
onCall: (event: IncomingCallEvent): void => {
if (!host.isLiveEngine(id, engine)) return;
this.logger.log('Incoming call', {
sessionId: id,
callId: event.callId,
isVideo: event.isVideo,
isGroup: event.isGroup,
action: 'call_received',
});
const payload: Record<string, unknown> = { ...event };
host.eventsGateway.emitCallReceived(id, payload);
void host.webhookService.dispatch(id, 'call.received', payload);
// Opt-in auto-reject runs AFTER the dispatch so a reject failure can never eat the event.
void host.leafEvents.maybeAutoRejectCall(id, engine, event.callId);
},
onReconnecting: (attempt: number, nextDelayMs: number): void => {
if (!host.isLiveEngine(id, engine)) return;
// Count it whichever layer scheduled it: the counter's published meaning is "reconnect
// attempts scheduled across all sessions", and an engine that retries internally was simply
// never counted, so the series read 0 on Baileys however long a session looped.
incrementSessionReconnectAttempts();
if (attempt === 1 || reconnectingSince === 0) reconnectingSince = Date.now();
// Below the loop threshold this is a blip, not an episode: the 515 restart WhatsApp asks for
// right after a successful pairing is one attempt, and so is any drop that comes straight
// back. Reporting those would put "reconnecting" on a session that is linking normally.
if (attempt < RECONNECT_LOOP_ALERT_INTERVAL_ATTEMPTS) return;
const downForSeconds = Math.round((Date.now() - reconnectingSince) / 1000);
const downFor = downForSeconds >= 120 ? `${Math.round(downForSeconds / 60)}m` : `${downForSeconds}s`;
// The engine holds the session at INITIALIZING for the whole episode, which is the same thing
// it reports for a session waiting to be paired. Record why, so `lastError` says so on
// GET /sessions/:id, the only durable operator surface this path reaches. Rewritten on every
// attempt from here on, so the attempt and the downtime it shows never lag the episode.
host.sessionErrors.set(id, `${RECONNECT_LOOP_REASON} (attempt ${attempt}, down for ${downFor}).`);
if (attempt % RECONNECT_LOOP_ALERT_INTERVAL_ATTEMPTS !== 0) return;
// Same cadence, same log shape and the same already-documented webhook the service-level
// reconnect path emits, so an operator watching for a stuck session does not have to know
// which layer happens to be doing the retrying.
this.logger.warn(`Session is reconnect-looping: attempt ${attempt} scheduled`, {
sessionId: id,
attempts: attempt,
nextDelayMs,
downForSeconds,
action: 'reconnect_loop',
});
incrementSessionReconnectLoopAlerts();
void host.webhookService.dispatch(id, 'session.reconnect_loop', {
sessionId: id,
attempts: attempt,
nextDelayMs,
});
},
onDisconnected: (reason: string): void => {
if (!host.isLiveEngine(id, engine)) return;
// Shared with the liveness watchdog (see handleEngineDisconnected). Pass the captured
// engine so the handler can re-check identity across its DB await — this closure's `engine`
// (and `session`) snapshots can be stale by the time a disconnect lands, so the handler
// re-reads the row itself and fences every side effect on `engine` still being the live
// owner. The captured engine is the exact generation token (no numeric counter).
void host.handleEngineDisconnected(id, engine, reason);
},
onStateChanged: (engineState: EngineStatus): void => {
if (!host.isLiveEngine(id, engine)) return;
if (engineState !== EngineStatus.READY) host.endReadyStretch(id);
const statusMap: Record<EngineStatus, SessionStatus> = {
[EngineStatus.DISCONNECTED]: SessionStatus.DISCONNECTED,
[EngineStatus.INITIALIZING]: SessionStatus.INITIALIZING,
[EngineStatus.QR_READY]: SessionStatus.QR_READY,
[EngineStatus.AUTHENTICATING]: SessionStatus.AUTHENTICATING,
[EngineStatus.READY]: SessionStatus.READY,
[EngineStatus.ACTION_REQUIRED]: SessionStatus.ACTION_REQUIRED,
[EngineStatus.FAILED]: SessionStatus.FAILED,
};
const newStatus = statusMap[engineState];
if (!newStatus) return;
// An operator-initiated teardown reports DISCONNECTED on entry, before the engine is
// evicted: whatsapp-web.js sets the status and only then awaits browser.close(). Announced
// here it would tell every consumer the session is down while GET /sessions still reports
// the engine as loaded, and the verb's own write after the eviction is dropped as a
// duplicate, so the settled view would never be announced at all. Skipped for the exact
// instance being torn down; stop/logout/forceKill each write DISCONNECTED afterwards.
if (newStatus === SessionStatus.DISCONNECTED && host.isOperatorTeardown(id, engine)) return;
// A FAILED reported inside a service-level reconnect's init window is parked with onError.
const persist = (): void => persistStatus(newStatus);
if (newStatus === SessionStatus.FAILED && host.parkReconnectInitFailure(id, persist)) return;
persist();
},
onActionRequired: (reason: string): void => {
if (!host.isLiveEngine(id, engine)) return;
this.logger.warn(`Session requires operator action: ${reason}`, {
sessionId: id,
reason,
action: 'action_required',
});
// Record the reason so the last-error projection surfaces it while the session is
// ACTION_REQUIRED, then updateStatus (via onStateChanged above) has already written the
// status. Set here too to be defensive: the callback order is onStateChanged then
// onActionRequired, but persisting the reason here means it is available regardless.
host.sessionErrors.set(id, reason);
void host.hookManager.execute('session:error', { reason }, { sessionId: id, source: 'Engine' });
},
onCallOutcome: (event: CallOutcomeEvent): void => {
if (!host.isLiveEngine(id, engine)) return;
this.logger.log(`Call ${event.outcome}: ${event.callId}`, {
sessionId: id,
callId: event.callId,
outcome: event.outcome,
action: 'call_outcome',
});
const payload: Record<string, unknown> = { sessionId: id, ...event };
// One event per outcome rather than a single call.ended carrying a field: a consumer that
// only cares about missed calls should be able to subscribe to exactly that.
if (event.outcome === 'accepted') {
host.eventsGateway.emitCallAccepted(id, payload);
void host.webhookService.dispatch(id, 'call.accepted', payload);
} else if (event.outcome === 'rejected') {
host.eventsGateway.emitCallRejected(id, payload);
void host.webhookService.dispatch(id, 'call.rejected', payload);
} else {
host.eventsGateway.emitCallMissed(id, payload);
void host.webhookService.dispatch(id, 'call.missed', payload);
}
},
onPresenceUpdate: (event: PresenceUpdateEvent): void => {
if (!host.isLiveEngine(id, engine)) return;
// WhatsApp reports presence on every transition and freely repeats itself, so only an actual
// change is published. Without this, one watched chat with an active typist produces a
// continuous stream of identical events — enough to drown every other webhook a consumer
// subscribes to. The store is the only thing that knows the previous state, so it decides.
if (!host.presence.record(id, event)) return;
const payload: Record<string, unknown> = { sessionId: id, ...event };
host.eventsGateway.emitPresenceUpdate(id, payload);
void host.webhookService.dispatch(id, 'presence.update', payload);
},
onAccountRestriction: (restriction: AccountRestriction | null): void => {
if (!host.isLiveEngine(id, engine)) return;
// A lift is only news if we were holding a restriction; an engine that reports "no
// restriction" on every connect (the Baileys probe does exactly that) must stay quiet.
if (!restriction) {
const lifted = host.sessionRestrictions.clear(id);
if (lifted) host.reportRestrictionLifted(id, lifted);
return;
}
// Both engines repeat an unchanged restriction — whatsapp-web.js on every reconnect attempt,
// Baileys on every connect probe — so only a change reaches an operator.
if (!host.sessionRestrictions.set(id, restriction)) return;
this.logger.warn(`WhatsApp restricted this session's account: ${restriction.kind}`, {
sessionId: id,
kind: restriction.kind,
code: restriction.code,
expiresAt: restriction.expiresAt,
action: 'account_restricted',
});
const payload = {
active: true,
kind: restriction.kind,
code: restriction.code,
expiresAt: restriction.expiresAt ? new Date(restriction.expiresAt).toISOString() : null,
};
void host.webhookService.dispatch(id, 'session.restriction', { sessionId: id, ...payload });
host.eventsGateway.emitSessionRestriction(id, payload);
// Audited, unlike the engine-level connect/disconnect transitions next door: this is rare,
// it is not reconnect noise, and the store that serves it to the API is in memory — so this
// row is the only durable record of when the account was restricted.
void host.auditService?.logWarn(AuditAction.SESSION_RESTRICTED, {
sessionId: id,
metadata: {
kind: restriction.kind,
code: restriction.code,
expiresAt: restriction.expiresAt ? new Date(restriction.expiresAt).toISOString() : null,
},
errorMessage: `WhatsApp restricted this account: ${restriction.kind} (${restriction.code})`,
});
},
onError: (reason: string): void => {
if (!host.isLiveEngine(id, engine)) return;
this.logger.error(`Session engine failed: ${reason}`, undefined, {
sessionId: id,
reason,
action: 'engine_error',
});
// Remember the reason so findOne/findAll can surface it to the dashboard,
// then persist the FAILED status. This is terminal — no reconnect is
// scheduled (unlike onDisconnected), since re-scanning is required.
host.sessionErrors.set(id, reason);
const fail = (): void => {
// A prior onDisconnected may have scheduled a reconnect. This failure is terminal
// (re-scan required), so cancel it — otherwise the pending timer would resurrect a
// session the operator must manually restart.
host.cancelReconnect(id);
void host.hookManager.execute(
'session:error',
{ reason },
{
sessionId: id,
source: 'Engine',
},
);
persistStatus(SessionStatus.FAILED);
// onError is terminal (no reconnect is scheduled — re-scan is required). Evict the dead engine
// and SIGKILL its process: leaving it in the map would hold a concurrency slot indefinitely and
// make the next start() reject the session as "already started" instead of re-initializing it.
host.evictAndForceDestroy(id, engine);
};
// During a service-level reconnect's init the lifecycle parks this instead: once init settles it
// either applies it or, for a retryable failure, evicts the engine and re-arms the backoff.
if (!host.parkReconnectInitFailure(id, fail, reason)) fail();
},
onCredentialTeardownStarted: (operation: Promise<void>): void => {
// The adapter fired the moment it began the call that ends in an fs.rm of this session's
// on-disk auth dir. Track it under the captured session NAME (the fence key — see
// awaitPendingTeardown), and NOT guarded on this engine still being live: a logout that
// captured this engine must register its destructive promise even as a concurrent
// stop()/delete() evicts it, or the rm would race a start this fence should have held back.
// `session.name` is the immutable snapshot captured at initializeEngine entry, so a row
// delete/recreate under the same name cannot poison the key.
host.trackPendingCredentialTeardown(sessionName, operation);
},
claimStuckAuthRecovery: (): boolean => host.claimStuckAuthRecovery(id, engine),
};
}
}