@stage-labs/metro 0.1.0-beta.316 → 0.1.0-beta.317

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.316",
+  "version": "0.1.0-beta.317",
   "description": "The metro command line: run your agent on this machine, relaying its chat channels and connectors to Claude Code.",
   "license": "MIT",
   "repository": {

package/runtime/node_modules/@metro-labs/core/package.json

@@ -26,6 +26,7 @@
     "./lines": "./src/lines.ts",
     "./endpoints": "./src/endpoints.ts",
     "./stations/types": "./src/stations/types.ts",
+    "./stations/account-status": "./src/stations/account-status.ts",
     "./stations/channel-directory": "./src/stations/channel-directory.ts",
     "./stations/channel-pages": "./src/stations/channel-pages.ts",
     "./stations/account-files": "./src/stations/account-files.ts",

package/runtime/node_modules/@metro-labs/core/src/stations/account-status.ts

@@ -0,0 +1,26 @@
+import { isRecord } from '../is-record.js';
+
+export const ACCOUNT_STATES = ['connected', 'connecting', 'logged_out', 'disconnected'] as const;
+
+export type AccountState = (typeof ACCOUNT_STATES)[number];
+
+export interface AccountStatus {
+  state: AccountState;
+  reason?: string;
+  since: number;
+}
+
+const REASON_MAX = 300;
+
+export function accountStatus(state: AccountState, reason?: string, since = Date.now()): AccountStatus {
+  const text = reason?.trim().slice(0, REASON_MAX) ?? '';
+  return text === '' ? { state, since } : { state, reason: text, since };
+}
+
+export function accountStatusOf(raw: unknown): AccountStatus | null {
+  if (!isRecord(raw)) return null;
+  const state = ACCOUNT_STATES.find((s) => s === raw.state);
+  const since = raw.since;
+  if (state === undefined || typeof since !== 'number' || !Number.isFinite(since)) return null;
+  return accountStatus(state, typeof raw.reason === 'string' ? raw.reason : undefined, since);
+}

package/runtime/node_modules/@metro-labs/core/src/stations/types.ts

@@ -114,6 +114,8 @@ export interface Station {
   readFilters?: ReadonlySet<ReadFilter>;
   approvals?: boolean;
   sendsFrames?: boolean;
+  reportsStatus?: boolean;
+  pairAgain?: { identity: string };
   attachmentMode: AttachmentMode;
   forget?: (accountId: string) => void;
   forgetExcept?: (keptAccountIds: readonly string[]) => void;

package/runtime/node_modules/@metro-labs/daemon/src/agents/account-routes.ts

@@ -13,6 +13,7 @@ export type AccountRoute =
   | { kind: 'enabled'; station: StationName; accountId: string }
   | { kind: 'policy'; station: StationName; accountId: string }
   | { kind: 'profiles'; station: StationName; accountId: string }
+  | { kind: 'repair'; station: StationName; accountId: string }
   | { kind: 'name'; station: StationName; accountId: string };
 
 const ROUTE_METHODS: Record<AccountRoute['kind'], string[]> = {
@@ -26,10 +27,11 @@ const ROUTE_METHODS: Record<AccountRoute['kind'], string[]> = {
   enabled: ['PUT'],
   policy: ['PUT'],
   profiles: ['GET'],
+  repair: ['POST'],
   name: ['GET', 'POST'],
 };
 
-const SUB_ROUTES = ['allowlist', 'senders', 'resolve', 'enabled', 'name', 'policy', 'profiles'] as const;
+const SUB_ROUTES = ['allowlist', 'senders', 'resolve', 'enabled', 'name', 'policy', 'profiles', 'repair'] as const;
 
 type SubRoute = (typeof SUB_ROUTES)[number];
 

package/runtime/node_modules/@metro-labs/daemon/src/agents/accounts-api.ts

@@ -37,6 +37,7 @@ interface AttachSessionApi {
     owner: AttachOwner,
     station: InteractiveStation,
     input: Record<string, unknown>,
+    repair?: string,
   ) => Promise<AttachView>;
   view: (owner: AttachOwner, attachId: string) => AttachView;
   submit: (
@@ -315,16 +316,36 @@ async function handleStep(
   sendJson(req, res, 200, view);
 }
 
+async function handleRepair(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: AccountApiDeps,
+  owner: AttachOwner,
+  target: { station: StationName; accountId: string },
+): Promise<void> {
+  const { station, accountId } = target;
+  if (!isInteractiveStation(station) || stationByName(station)?.pairAgain === undefined)
+    throw new ApiError(`${station} cannot pair again`, 400);
+  const view = await deps.attachSessions.start(owner, station, asInput(await readJsonBody(req)), accountId);
+  sendJson(req, res, 201, view);
+}
+
+type AttachRoute = Extract<AccountRoute, { kind: 'start' | 'session' | 'step' | 'repair' }>;
+
+const isAttachRoute = (route: AccountRoute): route is AttachRoute =>
+  route.kind === 'start' || route.kind === 'session' || route.kind === 'step' || route.kind === 'repair';
+
 async function dispatchAttach(
   req: IncomingMessage,
   res: ServerResponse,
   deps: AccountApiDeps,
   agentId: string,
-  route: Extract<AccountRoute, { kind: 'start' | 'session' | 'step' }>,
+  route: AttachRoute,
   session?: ApiSession,
 ): Promise<void> {
   const owner: AttachOwner = { agentId, organization: session?.subject, userId: session?.userId, sessionId: session?.sessionId, authorization: req.headers.authorization };
   if (route.kind === 'start') return handleStart(req, res, deps, agentId, owner);
+  if (route.kind === 'repair') return handleRepair(req, res, deps, owner, route);
   if (route.kind === 'session') return handleSession(req, res, deps, owner, route.attachId);
   return handleStep(req, res, deps, owner, route.attachId);
 }
@@ -337,7 +358,7 @@ async function dispatchRoute(
   route: AccountRoute,
   session?: ApiSession,
 ): Promise<void> {
-  if (route.kind === 'start' || route.kind === 'session' || route.kind === 'step') return dispatchAttach(req, res, deps, agentId, route, session);
+  if (isAttachRoute(route)) return dispatchAttach(req, res, deps, agentId, route, session);
   if (route.kind === 'allowlist') return handleAllowlist(req, res, deps, agentId, route);
   if (route.kind === 'enabled') return handleEnabled(req, res, deps, agentId, route);
   if (route.kind === 'policy') return handlePolicy(req, res, deps, agentId, route);

package/runtime/node_modules/@metro-labs/daemon/src/agents/api.ts

@@ -13,6 +13,7 @@ import {
   type AccountRoute,
 } from './account-routes.js';
 import type { AgentSummary } from './admin.js';
+import { pairAgainStations, statusStations } from '../stations/registry.js';
 
 const PREFIX = '/api/agents';
 
@@ -70,6 +71,8 @@ async function handleList(
     capabilities: deps.capabilities(),
     features: deps.features ?? [],
     attachable: deps.attachable ?? ATTACHABLE,
+    reportsStatus: statusStations(),
+    pairAgain: pairAgainStations(),
     ...(deps.toolGroups === undefined ? {} : { tools: deps.toolGroups() }),
   };
   if (!wantsAccounts(req)) {

package/runtime/node_modules/@metro-labs/daemon/src/agents/file-admin.ts

@@ -210,6 +210,23 @@ export function localRenewGmail(agentId: string, accountId: string, previous: st
   return { agentId, station: 'gmail', accountId };
 }
 
+const sameIdentity = (a: unknown, b: unknown): boolean =>
+  typeof a === 'string' && typeof b === 'string' && a.replace(/[\s()+-]/g, '').toLowerCase() === b.replace(/[\s()+-]/g, '').toLowerCase();
+
+const shownIdentity = (value: unknown): string => (typeof value === 'string' && value !== '' ? value : 'unknown');
+
+export function localPairAgain(agentId: string, station: StationName, accountId: string, identity: string, config: Record<string, unknown>, dir = agentsDir()): AccountRef {
+  const stored = agentOrThrow(agentId, dir);
+  const account = stored.file.stations.find((s) => s.station === station && s.id === accountId);
+  if (account === undefined) throw new AgentAdminError('This channel is gone. Nothing was changed.', 404);
+  const before = account.config[identity];
+  const after = config[identity];
+  if (!sameIdentity(before, after)) throw new AgentAdminError(`This channel is ${shownIdentity(before)}, not ${shownIdentity(after)}. Nothing was changed.`, 400);
+  account.config = { ...account.config, ...config };
+  save(stored);
+  return { agentId, station, accountId };
+}
+
 export function readLocalAgentFile(agentId: string, dir = agentsDir()): AgentFile {
   const found = storedAgents(dir).find((s) => s.file.id === agentId);
   if (found === undefined) throw missing();

package/runtime/node_modules/@metro-labs/daemon/src/mcp/accounts.ts

@@ -6,6 +6,7 @@ import {
 } from '../stations/registry.js';
 import { listEndpoints } from '../stations/webhook-endpoints.js';
 import { hookUrl, threemaCallbackUrl } from '../stations/attach.js';
+import { accountStatusOf } from '@metro-labs/core/stations/account-status';
 import { accountEnabled, agentIdForAccount, allowlistForAccount, approversForAccount, knownAccounts, type KnownAccount } from '../agents/map.js';
 
 const accountId = (acc: unknown): string | undefined => {
@@ -85,8 +86,33 @@ function withCallbackUrl(acc: unknown): unknown {
   return { ...rest, callback: threemaCallbackUrl(callbackId, callbackToken) };
 }
 
-const decorate = (station: string, rows: unknown[]): unknown[] =>
-  station === 'threema' ? rows.map(withCallbackUrl) : rows;
+function withStatus(reports: boolean, acc: unknown): unknown {
+  const rec = asRecord(acc);
+  if (rec === undefined || !('status' in rec)) return acc;
+  const { status, ...rest } = rec;
+  const live = reports ? accountStatusOf(status) : null;
+  return live === null ? rest : { ...rest, status: live };
+}
+
+function decorate(station: string, rows: unknown[]): unknown[] {
+  const reports = stationByName(station)?.reportsStatus === true;
+  const live = rows.map((row) => withStatus(reports, row));
+  return station === 'threema' ? live.map(withCallbackUrl) : live;
+}
+
+const STATUS_WAIT_MS = 5_000;
+
+function answerIn<T>(call: Promise<T>, ms: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`no answer within ${String(ms)} ms`));
+    }, ms);
+  });
+  return Promise.race([call, late]).finally(() => {
+    clearTimeout(timer);
+  });
+}
 
 export interface ScopedAccounts {
   accounts: Record<string, unknown[]>;
@@ -99,7 +125,8 @@ async function liveAccounts(
   if (!hasTrain(station))
     return { rows: inCoreAccounts(station), reachable: true };
   try {
-    const resp = await forwardTrainCall(station, 'accounts', {});
+    const call = forwardTrainCall(station, 'accounts', {});
+    const resp = await (stationByName(station)?.reportsStatus === true ? answerIn(call, STATUS_WAIT_MS) : call);
     const list = (resp.result as { accounts?: unknown[] } | undefined)?.accounts;
     return { rows: decorate(station, Array.isArray(list) ? list : []), reachable: true };
   } catch {

package/runtime/node_modules/@metro-labs/daemon/src/routes/local-mode.ts

@@ -4,6 +4,7 @@ import { AttachSessions } from '../stations/attach-session.js';
 import { startInteractiveAttach } from '../stations/attach-interactive.js';
 import { assertAttachOwner, finishGmailUpgrade, startGmailAttach } from './gmail-attach.js';
 import { detachWithGmailRevocation } from './gmail-detach.js';
+import { finishPairAgain, pairAgainInput } from './pair-again.js';
 import { recentSenders } from '../agents/senders.js';
 import { forwardTrainCall } from '../stations/train-call.js';
 import type { AgentApiDeps } from '../agents/api.js';
@@ -44,11 +45,16 @@ function attachSessions(deps: LocalModeDeps): AttachSessions {
       assertAttachOwner(owner);
       return Promise.resolve();
     },
-    start: (station, input, hooks, owner) => station === 'gmail' ? startGmailAttach(station, input, hooks, owner) : startInteractiveAttach(station, input, hooks),
-    complete: async (owner, station, config, active) => {
+    start: (station, input, hooks, owner, repair) => {
+      if (repair !== undefined) return startInteractiveAttach(station, pairAgainInput(owner, station, repair, input), hooks);
+      return station === 'gmail' ? startGmailAttach(station, input, hooks, owner) : startInteractiveAttach(station, input, hooks);
+    },
+    complete: async (owner, station, config, active, repair) => {
       assertAttachOwner(owner);
       if (!active()) throw new ApiError('This sign-in was cancelled or expired.', 409);
-      const ref = (station === 'gmail' ? finishGmailUpgrade(owner, config) : null) ?? await localAttachAccount(owner.agentId, station, config);
+      const ref = repair !== undefined
+        ? finishPairAgain(owner, station, repair, config)
+        : (station === 'gmail' ? finishGmailUpgrade(owner, config) : null) ?? await localAttachAccount(owner.agentId, station, config);
       const activated = await deps.syncStations(station).then(
         () => true,
         (err: unknown) => {

package/runtime/node_modules/@metro-labs/daemon/src/routes/pair-again.ts

@@ -0,0 +1,23 @@
+import { ApiError } from '@metro-labs/http/api-error';
+import type { StationName } from '@metro-labs/core/station-names';
+import { localPairAgain, readLocalAgentFile } from '../agents/file-admin.js';
+import type { AccountRef } from '../agents/account-attach.js';
+import { stationByName } from '../stations/registry.js';
+import type { AttachOwner } from '../stations/attach-session.js';
+
+function identityOf(station: string): string {
+  const identity = stationByName(station)?.pairAgain?.identity;
+  if (identity === undefined) throw new ApiError(`${station} cannot pair again`, 400);
+  return identity;
+}
+
+export function pairAgainInput(owner: AttachOwner, station: string, accountId: string, input: Record<string, unknown>): Record<string, unknown> {
+  const identity = identityOf(station);
+  const account = readLocalAgentFile(owner.agentId).stations.find((s) => s.station === station && s.id === accountId);
+  if (account === undefined) throw new ApiError('No such channel on this agent.', 404);
+  return { ...input, expect: account.config[identity] };
+}
+
+export function finishPairAgain(owner: AttachOwner, station: StationName, accountId: string, config: Record<string, unknown>): AccountRef {
+  return localPairAgain(owner.agentId, station, accountId, identityOf(station), config);
+}

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-interactive.ts

@@ -97,7 +97,7 @@ async function startWhatsapp(
       },
       onPaired: hooks.done,
       onFailed: hooks.fail,
-    });
+    }, normalizePhone(input.expect));
     await login.start();
   } catch (err) {
     await login?.cancel();

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-session.ts

@@ -19,6 +19,7 @@ export type StartAttach = (
   input: Record<string, unknown>,
   hooks: DriverHooks,
   owner: AttachOwner,
+  repair?: string,
 ) => Promise<StartedAttach>;
 
 export const ATTACH_ID_RE = /^as_[A-Za-z0-9_-]{22}$/;
@@ -60,6 +61,7 @@ type CompleteAttach = (
   station: StationName,
   config: Record<string, unknown>,
   active: () => boolean,
+  repair?: string,
 ) => Promise<{ accountId: string; activated: boolean }>;
 
 type AuthorizeAttach = (owner: AttachOwner) => Promise<void>;
@@ -72,6 +74,7 @@ export interface AttachSessionDeps {
 
 interface Session {
   owner: AttachOwner;
+  repair?: string;
   driver: AttachDriver | null;
   view: AttachView;
   finishing?: boolean;
@@ -177,6 +180,7 @@ export class AttachSessions {
           session.committing = true;
           return true;
         },
+        session.repair,
       );
       this.settle(session, {
         status: 'done',
@@ -187,12 +191,12 @@ export class AttachSessions {
       });
       log.info(
         { agentId: session.owner.agentId, station, account: landed.accountId },
-        'attach-session: signed in and attached a station account',
+        session.repair === undefined ? 'attach-session: signed in and attached a station account' : 'attach-session: paired a station account again',
       );
     } catch (err) {
       const reason =
         err instanceof ApiError ? err.message : 'could not store the account';
-      log.warn({ station, err: errMsg(err) }, 'attach-session: store failed');
+      log.warn({ station, ...(err instanceof ApiError ? { status: err.status } : { err: errMsg(err).replace(/\d{6,}/g, '<number>') }) }, 'attach-session: store failed');
       this.settle(session, { status: 'failed', prompt: '', error: reason });
     }
   }
@@ -230,6 +234,7 @@ export class AttachSessions {
     owner: AttachOwner,
     station: InteractiveStation,
     input: Record<string, unknown>,
+    repair?: string,
   ): Promise<AttachView> {
     await this.deps.authorize(owner);
     this.admit(owner);
@@ -237,6 +242,7 @@ export class AttachSessions {
     const attachId = newAttachId();
     const session: Session = {
       owner,
+      ...(repair === undefined ? {} : { repair }),
       driver: null,
       view: blankView(attachId, station),
     };
@@ -248,6 +254,7 @@ export class AttachSessions {
         input,
         this.hooksFor(attachId, station),
         owner,
+        repair,
       );
       if (this.sessions.get(attachId) !== session || session.view.expiresAt <= Date.now()) {
         await started.driver.cancel();

package/runtime/node_modules/@metro-labs/daemon/src/stations/registry.ts

@@ -41,6 +41,12 @@ export const accountStationCapabilities = (): Record<string, string[]> => {
   return out;
 };
 
+export const statusStations = (): string[] =>
+  STATIONS.filter((s) => s.reportsStatus === true).map((s) => s.name);
+
+export const pairAgainStations = (): string[] =>
+  STATIONS.filter((s) => s.pairAgain !== undefined).map((s) => s.name);
+
 export function forgetOrphans(known: readonly { station: string; id: string }[]): void {
   for (const s of STATIONS) {
     if (s.forgetExcept === undefined) continue;

package/runtime/node_modules/@metro-labs/http/src/connector-oauth.ts

@@ -11,6 +11,8 @@ const CLIENT_NAME = 'Metro';
 
 export class OAuthInvalidGrant extends ConnectorVerifyError {}
 
+const SIGN_IN_AGAIN = new Set(['invalid_grant', 'invalid_client', 'unauthorized_client']);
+
 export interface OAuthClient {
   clientId: string;
   clientSecret?: string;
@@ -143,10 +145,17 @@ async function postToken(
   } catch (err) {
     throw refused(`Metro could not reach that server to finish signing in: ${whyUnreachable(err)}`);
   }
-  const body: unknown = await res.json().catch(() => null);
-  if (form.grant_type === 'refresh_token' && res.status === 400 && isRecord(body) && body.error === 'invalid_grant') throw new OAuthInvalidGrant('That server requires a new sign-in.', 400);
-  if (!res.ok || !isRecord(body))
-    throw refused('That server refused to complete the sign-in.');
+  return tokenAnswer(form.grant_type === 'refresh_token', res.status, res.ok, await res.json().catch(() => null));
+}
+
+const errorCode = (body: unknown): string | null => (isRecord(body) && typeof body.error === 'string' && /^[a-z_]{1,64}$/.test(body.error) ? body.error : null);
+
+const grantGone = (refreshing: boolean, status: number, code: string | null): boolean => refreshing && (status === 400 || status === 401) && code !== null && SIGN_IN_AGAIN.has(code);
+
+function tokenAnswer(refreshing: boolean, status: number, ok: boolean, body: unknown): OAuthTokens {
+  const code = errorCode(body);
+  if (grantGone(refreshing, status, code)) throw new OAuthInvalidGrant('That server requires a new sign-in.', 400);
+  if (!ok || !isRecord(body)) throw refused(`That server refused to complete the sign-in (${String(status)}${code === null ? '' : ` ${code}`}).`);
   return tokensFrom(body);
 }
 

package/runtime/node_modules/@metro-labs/whatsapp/src/actions.ts

@@ -196,12 +196,13 @@ function makeDelete(clientFor: ClientFor): StationHandler {
 function makeAccounts(clientFor: ClientFor): StationHandler {
   return (id) => {
     const list = [...accounts.values()].map((a) => {
-      const phone = clientFor(a.id).self();
+      const client = clientFor(a.id);
+      const phone = client.self();
       return {
         id: a.id,
         handle: phone === null ? null : `+${phone}`,
         url: phone === null ? null : `https://wa.me/${phone}`,
-        connected: phone !== null,
+        status: client.status(),
       };
     });
     respond(id, { result: { accounts: list } });

package/runtime/node_modules/@metro-labs/whatsapp/src/client-types.ts

@@ -4,6 +4,7 @@ import type { MemberList } from '@metro-labs/core/stations/types';
 import type { ChannelList } from '@metro-labs/core/stations/channel-directory';
 import type { ProfileChange } from '@metro-labs/core/stations/profile';
 import type { SenderProfile } from '@metro-labs/core/stations/sender-profile';
+import type { AccountStatus } from '@metro-labs/core/stations/account-status';
 import type { WhatsAppAccount } from './types.js';
 import type { InboundMessage, ReactionInput } from './format.js';
 import type { SenderFound } from './resolve.js';
@@ -25,6 +26,7 @@ export interface WAMedia {
 export interface WAClient {
   account: WhatsAppAccount;
   self(): string | null;
+  status(): AccountStatus;
   start(handlers: InboundHandlers): Promise<void>;
   read(jid: string, options?: HistoryOptions): Promise<HistoryPage>;
   listMembers(jid: string, limit?: number): Promise<MemberList>;

package/runtime/node_modules/@metro-labs/whatsapp/src/client.ts

@@ -1,7 +1,6 @@
 import makeWASocket, {
   jidNormalizedUser,
   Browsers,
-  DisconnectReason,
   fetchLatestWaWebVersion,
   type proto,
   type WAMessage,
@@ -13,7 +12,7 @@ import { errMsg } from '@metro-labs/core/log';
 import type { WhatsAppAccount } from './types.js';
 import type { InboundHandlers, WAClient, WAMedia, ClientRuntime } from './client-types.js';
 export type { InboundHandlers, WAClient, WAMedia } from './client-types.js';
-import { makeProfileCache, nonEmpty, type SenderProfile } from '@metro-labs/core/stations/sender-profile';
+import { makeProfileCache, type SenderProfile } from '@metro-labs/core/stations/sender-profile';
 import type { SelfRef } from './parse.js';
 import type { History } from './history.js';
 import { createClientHistory } from './client-history.js';
@@ -22,11 +21,13 @@ import { bindMessages } from './messages.js';
 import { listMembers } from './members.js';
 import { SendExpiry } from './send-expiry.js';
 import { baileysLogger } from './logger.js';
-import { makeNameBook, nameFiles, phoneOf, type NameBook } from './names.js';
+import { makeNameBook, nameFiles, type NameBook } from './names.js';
+import { limiter, PictureMemory, PROFILE_READS, readPeer, withName, type PeerProfile } from './profile.js';
 import { useAccountAuthState } from './auth-state.js';
 import { knownKey, makeKeyCache, targetKey, type KeyCache } from './keys.js';
 import { makeOutbox, type Outbox } from './outbox.js';
 import { deliveryNotes, describeNote } from './delivery.js';
+import { closeOf, closeReason, ConnectionWatch, failureOf, type Closed } from './connection.js';
 import {
   ACK_WAIT_MS,
   bindAcks,
@@ -51,6 +52,7 @@ interface State {
   acks: AckWatch;
   names: NameBook;
   channels: WhatsAppChannels;
+  watch: ConnectionWatch;
 }
 type SendOpts = Parameters<WASocket['sendMessage']>[2];
 type SendContent = Parameters<WASocket['sendMessage']>[1];
@@ -107,19 +109,10 @@ function servedFromOutbox(
   return message;
 }
 
-const TERMINAL: Record<number, string> = {
-  [DisconnectReason.loggedOut]: ' — re-pair required',
-  [DisconnectReason.connectionReplaced]:
-    ' — another metro took this device; not reconnecting (two sockets on one ' +
-    'identity evict each other and risk a 463 timelock)',
-};
-
-export function terminalReason(code: number | undefined): string | undefined {
-  return code === undefined ? undefined : TERMINAL[code];
-}
-
-function onClose(st: State, code: number | undefined): void {
-  const terminal = terminalReason(code);
+function onClose(st: State, closed: Closed): void {
+  const { code } = closed;
+  const terminal = closeReason(closed);
+  if (!st.closed) st.watch.closed(closed);
   if (st.closed || terminal !== undefined) {
     process.stderr.write(
       `whatsapp[${st.account.id}] disconnected (code=${code ?? '?'})${terminal ?? ''}\n`,
@@ -132,6 +125,7 @@ function onClose(st: State, code: number | undefined): void {
     process.stderr.write(
       `whatsapp[${st.account.id}] reconnect failed: ${errMsg(e)}\n`,
     );
+    st.watch.failed(failureOf(e, 'reconnect'));
   });
 }
 
@@ -140,14 +134,15 @@ function bindConnection(st: State, sock: WASocket): void {
     const { connection, lastDisconnect } = update;
     if (connection === 'open') {
       process.stderr.write(`whatsapp[${st.account.id}] connected\n`);
+      if (st.sock === sock) st.watch.opened();
       st.openResolve?.();
       return;
     }
     if (connection !== 'close') return;
-    const code = (
-      lastDisconnect?.error as { output?: { statusCode?: number } } | undefined
-    )?.output?.statusCode;
-    onClose(st, code);
+    onClose(st, closeOf(lastDisconnect?.error));
+  });
+  sock.ws.on('frame', () => {
+    if (st.sock === sock) st.watch.heard();
   });
 }
 
@@ -254,24 +249,24 @@ function mediaContent(m: WAMedia): SendContent {
   };
 }
 
-async function readProfile(st: State, jid: string): Promise<SenderProfile> {
-  const sock = await ready(st);
-  const [statuses, avatar] = await Promise.all([sock.fetchStatus(jid).catch(() => undefined), sock.profilePictureUrl(jid, 'image').catch(() => undefined)]);
-  const about = nonEmpty((statuses?.[0]?.status as { status?: unknown } | undefined)?.status);
-  const picture = nonEmpty(avatar);
-  const phone = phoneOf(jid.endsWith('@lid') ? await sock.signalRepository.lidMapping.getPNForLID(jid).catch(() => null) : jid);
-  const name = st.names.get(jid);
-  return {
-    id: jid,
-    ...(name === undefined ? {} : { display_name: name }),
-    ...(phone === undefined ? {} : { name: phone, address: phone }),
-    ...(about === undefined ? {} : { about }),
-    ...(picture === undefined ? {} : { avatar: picture }),
+function profileReader(st: State): (jid: string) => Promise<SenderProfile | null> {
+  const pictures = new PictureMemory();
+  const reads = limiter(PROFILE_READS);
+  const senders = makeProfileCache<PeerProfile>(async (jid) => {
+    const sock = await ready(st);
+    return reads(() => readPeer(sock, jid, pictures));
+  }, {
+    onError: (jid, err) => process.stderr.write(`whatsapp[${st.account.id}] could not read the profile of ${jid}: ${errMsg(err)}\n`),
+  });
+  return async (jid) => {
+    const peer = await senders.get(jid);
+    return peer === null ? null : withName(peer, st.names);
   };
 }
 
 async function disconnect(st: State): Promise<void> {
   st.closed = true;
+  st.watch.stop();
   st.openResolve?.();
   try {
     st.history.close();
@@ -295,6 +290,7 @@ function initialState(account: WhatsAppAccount, runtime: ClientRuntime): State {
     acks: makeAckWatch(),
     names: makeNameBook(nameFiles.path(account.id)),
     channels: new WhatsAppChannels(account.id),
+    watch: new ConnectionWatch(account.id, () => st.sock?.ws.isOpen !== false),
   };
   resetGate(st);
   return st;
@@ -305,9 +301,7 @@ export function createClient(
   runtime: ClientRuntime = { makeSocket: makeWASocket, fetchVersion: fetchLatestWaWebVersion },
 ): WAClient {
   const st = initialState(account, runtime);
-  const senders = makeProfileCache<SenderProfile>((jid) => readProfile(st, jid), {
-    onError: (jid, err) => process.stderr.write(`whatsapp[${st.account.id}] could not read the profile of ${jid}: ${errMsg(err)}\n`),
-  });
+  const senderProfile = profileReader(st);
   return {
     account,
     self() {
@@ -317,14 +311,15 @@ export function createClient(
     },
     async start(handlers) {
       st.handlers = handlers;
+      st.watch.watch();
       try {
         await connect(st);
       } catch (e) {
-        process.stderr.write(
-          `whatsapp[${account.id}] connect failed: ${errMsg(e)}\n`,
-        );
+        process.stderr.write(`whatsapp[${account.id}] connect failed: ${errMsg(e)}\n`);
+        st.watch.failed(failureOf(e, 'connect'));
       }
     },
+    status: () => st.watch.read(),
     read(jid, options) {
       const page = st.history.read(jid, options);
       for (const message of page.messages) st.keys.remember(message.key);
@@ -394,7 +389,7 @@ export function createClient(
         await sock.updateProfilePicture(me, { url: change.avatar.path });
       }
     },
-    senderProfile: (jid) => senders.get(jid),
+    senderProfile,
     disconnect: () => st.closing ??= disconnect(st),
   };
 }

package/runtime/node_modules/@metro-labs/whatsapp/src/connection.ts

@@ -0,0 +1,139 @@
+import { DisconnectReason } from 'baileys';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { TrainError } from '@metro-labs/core/train-error';
+import { accountStatus, type AccountStatus } from '@metro-labs/core/stations/account-status';
+
+export const RECONNECT_GRACE_MS = 3 * 60_000;
+export const SILENT_MS = 90_000;
+const CHECK_MS = 30_000;
+
+const TERMINAL: Record<number, string> = {
+  [DisconnectReason.loggedOut]: ' — re-pair required',
+  [DisconnectReason.connectionReplaced]:
+    ' — another metro took this device; not reconnecting (two sockets on one ' +
+    'identity evict each other and risk a 463 timelock)',
+};
+
+export function terminalReason(code: number | undefined): string | undefined {
+  return code === undefined ? undefined : TERMINAL[code];
+}
+
+export const closeReason = (closed: Closed): string | undefined =>
+  terminalReason(closed.removed ? DisconnectReason.loggedOut : closed.code);
+
+export interface Closed {
+  code: number | undefined;
+  message: string;
+  removed: boolean;
+}
+
+const recordOf = (value: unknown): Record<string, unknown> => (isRecord(value) ? value : {});
+
+export function closeOf(error: unknown): Closed {
+  const boom = recordOf(error);
+  const output = recordOf(boom.output);
+  const data = recordOf(boom.data);
+  return {
+    code: typeof output.statusCode === 'number' ? output.statusCode : undefined,
+    message: error instanceof Error ? error.message : '',
+    removed: data.tag === 'conflict' && recordOf(data.attrs).type === 'device_removed',
+  };
+}
+
+export function statusAfterClose(closed: Closed, now: number): AccountStatus {
+  if (closed.removed) return accountStatus('logged_out', 'WhatsApp removed this linked device.', now);
+  if (closed.code === DisconnectReason.loggedOut) return accountStatus('logged_out', 'WhatsApp logged this device out.', now);
+  if (closed.code === DisconnectReason.connectionReplaced)
+    return accountStatus('disconnected', 'Another Metro took over this WhatsApp device, so this one stopped.', now);
+  const code = `code ${closed.code === undefined ? '?' : String(closed.code)}`;
+  return accountStatus('connecting', `The connection dropped (${closed.message === '' ? code : `${closed.message}, ${code}`}).`, now);
+}
+
+export function failureOf(e: unknown, step: 'connect' | 'reconnect'): AccountStatus {
+  if (e instanceof TrainError && e.code === 'whatsapp_auth') return accountStatus('logged_out', 'No WhatsApp link is stored for this channel.');
+  return accountStatus('disconnected', `Metro could not ${step} to WhatsApp: ${errMsg(e)}`);
+}
+
+export interface Liveness {
+  open: boolean;
+  socketOpen: boolean;
+  lastFrameAt: number;
+}
+
+function openStatus(current: AccountStatus, live: Liveness, now: number): AccountStatus {
+  const trouble = !live.socketOpen ? 'The WhatsApp connection is not open.' : now - live.lastFrameAt > SILENT_MS ? 'WhatsApp stopped answering.' : null;
+  if (trouble === null) return current.state === 'connected' ? current : accountStatus('connected', undefined, now);
+  return current.state === 'connected' ? accountStatus('connecting', trouble, now) : current;
+}
+
+export function liveStatus(current: AccountStatus, live: Liveness, now: number): AccountStatus {
+  if (current.state === 'logged_out') return current;
+  const next = live.open ? openStatus(current, live, now) : current;
+  if (next.state !== 'connecting' || now - next.since < RECONNECT_GRACE_MS) return next;
+  return accountStatus('disconnected', `${next.reason ?? 'Metro could not reach WhatsApp.'} It has not come back for 3 minutes.`, next.since + RECONNECT_GRACE_MS);
+}
+
+export class ConnectionWatch {
+  private status: AccountStatus;
+  private open = false;
+  private lastFrameAt = 0;
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private readonly accountId: string,
+    private readonly socketOpen: () => boolean,
+    now = Date.now(),
+  ) {
+    this.status = accountStatus('connecting', undefined, now);
+  }
+
+  opened(now = Date.now()): void {
+    this.open = true;
+    this.lastFrameAt = now;
+    this.enter(accountStatus('connected', undefined, now));
+  }
+
+  heard(now = Date.now()): void {
+    this.lastFrameAt = now;
+  }
+
+  closed(closed: Closed, now = Date.now()): void {
+    this.open = false;
+    const next = statusAfterClose(closed, now);
+    if (next.state !== 'connecting') this.enter(next);
+    else if (this.status.state === 'connecting') this.enter(accountStatus('connecting', next.reason, this.status.since));
+    else if (this.status.state !== 'disconnected') this.enter(next);
+  }
+
+  failed(status: AccountStatus): void {
+    this.open = false;
+    this.enter(status);
+  }
+
+  read(now = Date.now()): AccountStatus {
+    const next = liveStatus(this.status, { open: this.open, socketOpen: this.socketOpen(), lastFrameAt: this.lastFrameAt }, now);
+    if (next !== this.status) this.enter(next);
+    return this.status;
+  }
+
+  watch(): void {
+    if (this.timer !== null) return;
+    this.timer = setInterval(() => {
+      this.read();
+    }, CHECK_MS);
+    this.timer.unref();
+  }
+
+  stop(): void {
+    if (this.timer !== null) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  private enter(next: AccountStatus): void {
+    const before = this.status.state;
+    this.status = next;
+    if (before === next.state) return;
+    process.stderr.write(`whatsapp[${this.accountId}] state ${before} -> ${next.state}${next.reason === undefined ? '' : `: ${next.reason}`}\n`);
+  }
+}

package/runtime/node_modules/@metro-labs/whatsapp/src/login.ts

@@ -6,6 +6,7 @@ import makeWASocket, {
 } from 'baileys';
 import { errMsg, log } from '@metro-labs/core/log';
 import { inMemoryAuthState } from './auth-state.js';
+import type { ClientRuntime } from './client-types.js';
 
 export class WhatsappLoginError extends Error {}
 
@@ -32,6 +33,13 @@ export function normalizePhone(raw: unknown): string {
   return phone;
 }
 
+export function assertSamePhone(phone: string, expect: string): void {
+  if (expect !== '' && phone !== '' && phone !== expect)
+    throw new WhatsappLoginError(
+      `This channel is +${expect}. Pair it again with that number, or add a new channel for +${phone}.`,
+    );
+}
+
 function closeReason(err: unknown): number | undefined {
   return (err as { output?: { statusCode?: number } } | undefined)?.output
     ?.statusCode;
@@ -47,14 +55,18 @@ export class WhatsappLogin {
   constructor(
     private phone: string,
     private events: WhatsappLoginEvents,
-  ) {}
+    private expect = '',
+    private runtime: ClientRuntime = { makeSocket: makeWASocket, fetchVersion: fetchLatestWaWebVersion },
+  ) {
+    assertSamePhone(phone, expect);
+  }
 
   get mode(): 'pairing-code' | 'qr' {
     return this.phone === '' ? 'qr' : 'pairing-code';
   }
 
   async start(): Promise<void> {
-    const { version, error } = await fetchLatestWaWebVersion({});
+    const { version, error } = await this.runtime.fetchVersion({});
     if (error)
       throw new WhatsappLoginError(
         'could not reach WhatsApp to start the pairing',
@@ -64,7 +76,7 @@ export class WhatsappLogin {
 
   private open(version: [number, number, number]): void {
     if (this.settled) return;
-    const sock = makeWASocket({
+    const sock = this.runtime.makeSocket({
       version,
       auth: this.auth.state,
       browser: Browsers.macOS('Safari'),
@@ -131,6 +143,10 @@ export class WhatsappLogin {
       );
       return;
     }
+    if (this.expect !== '' && phone !== this.expect) {
+      this.refuseOther(phone);
+      return;
+    }
     const credentials = this.auth.serialize();
     this.settled = true;
     this.closeSocket()
@@ -145,6 +161,23 @@ export class WhatsappLogin {
       });
   }
 
+  private refuseOther(phone: string): void {
+    this.settled = true;
+    const sock = this.sock;
+    const message = `You linked +${phone}, but this channel is +${this.expect}. Nothing was changed. Scan the code with the phone of +${this.expect}.`;
+    (sock === null ? Promise.resolve() : sock.logout('Metro: another phone than the channel'))
+      .catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'whatsapp login: could not unlink the other phone');
+      })
+      .then(() => this.closeSocket())
+      .then(() => {
+        this.events.onFailed(message);
+      })
+      .catch((err: unknown) => {
+        log.warn({ err: errMsg(err) }, 'whatsapp login: failure report failed');
+      });
+  }
+
   private fail(message: string): void {
     if (this.settled) return;
     this.settled = true;

package/runtime/node_modules/@metro-labs/whatsapp/src/messages.ts

@@ -1,4 +1,4 @@
-import { jidNormalizedUser, type Contact, type WASocket } from 'baileys';
+import { jidNormalizedUser, type Contact, type WAMessage, type WASocket } from 'baileys';
 import { bindAppState, noteHistoryContact } from './app-state.js';
 import type { InboundHandlers } from './client-types.js';
 import type { History } from './history.js';
@@ -16,6 +16,20 @@ interface MessageHooks {
   self(): SelfRef;
 }
 
+const person = (jid: string | null | undefined): string | undefined =>
+  jid && (jid.endsWith('@s.whatsapp.net') || jid.endsWith('@lid')) ? jidNormalizedUser(jid) : undefined;
+
+const pair = (a: string, b: string): [string, string] => (a.endsWith('@lid') ? [b, a] : [a, b]);
+
+function noteSender(names: NameBook, m: WAMessage): void {
+  if (m.key.fromMe === true) return;
+  const name = m.pushName ?? m.verifiedBizName;
+  const sender = person(m.key.participant ?? m.key.remoteJid);
+  const alt = person(m.key.participantAlt ?? m.key.remoteJidAlt);
+  for (const jid of [sender, alt]) names.note(jid, name);
+  if (sender !== undefined && alt !== undefined) names.alias(...pair(sender, alt));
+}
+
 export function bindMessages(sock: Pick<WASocket, 'ev' | 'user'>, hooks: MessageHooks): void {
   const selfJid = (): string | undefined => sock.user?.id ? jidNormalizedUser(sock.user.id) : undefined;
   const noteContacts = (contacts: Partial<Contact>[]): void => {
@@ -37,18 +51,25 @@ export function bindMessages(sock: Pick<WASocket, 'ev' | 'user'>, hooks: Message
       const inbound = toInbound(hooks.accountId, m, hooks.self());
       if (!inbound) continue;
       hooks.names.note(inbound.senderJid, inbound.pushName);
+      noteSender(hooks.names, m);
       handlers.onMessage(inbound, m);
     }
   });
+  sock.ev.on('lid-mapping.update', ({ pn, lid }) => {
+    if (hooks.current()) hooks.names.alias(pn, lid);
+  });
   sock.ev.on('contacts.upsert', noteContacts);
   sock.ev.on('contacts.update', noteContacts);
   sock.ev.on('messaging-history.set', ({ contacts, messages, lidPnMappings }) => {
     if (!hooks.current()) return;
     noteContacts(contacts);
-    for (const { pn, lid } of lidPnMappings ?? []) hooks.history.alias(pn, lid);
+    for (const { pn, lid } of lidPnMappings ?? []) {
+      hooks.history.alias(pn, lid);
+      hooks.names.alias(pn, lid);
+    }
     for (const m of messages) {
       hooks.keys.remember(m.key);
-      if (m.key.fromMe !== true) hooks.names.note(m.key.participant ?? m.key.remoteJid, m.pushName);
+      noteSender(hooks.names, m);
     }
     hooks.history.ingest(messages, selfJid());
   });

package/runtime/node_modules/@metro-labs/whatsapp/src/names.ts

@@ -12,6 +12,7 @@ export const nameFiles = accountFiles('WHATSAPP_TOKEN_DIR', 'whatsapp-names-');
 export interface NameBook {
   note(jid: string | null | undefined, name: string | null | undefined): void;
   get(jid: string): string | undefined;
+  alias(pn: string | null | undefined, lid: string | null | undefined): void;
 }
 
 function loaded(file: string | undefined): Map<string, string> {
@@ -25,6 +26,15 @@ function loaded(file: string | undefined): Map<string, string> {
   }
 }
 
+const JID_RE = /^([^@:_]+)(?:_\d+)?(?::\d+)?@([^@]+)$/;
+
+export function idOf(jid: string | null | undefined): string | undefined {
+  const parts = JID_RE.exec(jid ?? '');
+  if (parts === null) return undefined;
+  const [, user = '', server = ''] = parts;
+  return `${user}@${server === 'c.us' ? 's.whatsapp.net' : server}`;
+}
+
 export function makeNameBook(file?: string): NameBook {
   const names = loaded(file);
   let timer: ReturnType<typeof setTimeout> | null = null;
@@ -37,22 +47,35 @@ export function makeNameBook(file?: string): NameBook {
       process.stderr.write(`whatsapp: could not save the names: ${errMsg(err)}\n`);
     }
   };
+  const schedule = (): void => {
+    if (file !== undefined && timer === null) {
+      timer = setTimeout(save, SAVE_DELAY_MS);
+      timer.unref();
+    }
+  };
+  const note = (raw: string | null | undefined, name: string | null | undefined): void => {
+    const clean = name?.trim() ?? '';
+    const jid = idOf(raw);
+    if (jid === undefined || clean === '' || names.get(jid) === clean) return;
+    names.delete(jid);
+    names.set(jid, clean);
+    if (names.size > MAX_NAMES) {
+      const oldest = names.keys().next().value;
+      if (oldest !== undefined) names.delete(oldest);
+    }
+    schedule();
+  };
   return {
-    note(jid, name) {
-      const clean = name?.trim() ?? '';
-      if (!jid || clean === '' || names.get(jid) === clean) return;
-      names.delete(jid);
-      names.set(jid, clean);
-      if (names.size > MAX_NAMES) {
-        const oldest = names.keys().next().value;
-        if (oldest !== undefined) names.delete(oldest);
-      }
-      if (file !== undefined && timer === null) {
-        timer = setTimeout(save, SAVE_DELAY_MS);
-        timer.unref();
-      }
+    note,
+    get: (jid) => names.get(idOf(jid) ?? jid),
+    alias(rawPn, rawLid) {
+      const pn = idOf(rawPn);
+      const lid = idOf(rawLid);
+      if (pn === undefined || lid === undefined) return;
+      const known = names.get(pn) ?? names.get(lid);
+      if (!names.has(pn)) note(pn, known);
+      if (!names.has(lid)) note(lid, known);
     },
-    get: (jid) => names.get(jid),
   };
 }
 
@@ -62,11 +85,19 @@ export interface ContactNames {
   phoneNumber?: string | null;
   name?: string | null;
   notify?: string | null;
+  verifiedName?: string | null;
 }
 
+const nonBlank = (value: string | null | undefined): string | undefined => (value?.trim() ? value : undefined);
+
+const isLid = (jid: string | null | undefined): jid is string => jid?.endsWith('@lid') === true;
+
 export function noteContact(book: NameBook, c: ContactNames): void {
-  const name = c.name ?? c.notify;
+  const name = nonBlank(c.name) ?? nonBlank(c.notify) ?? nonBlank(c.verifiedName);
   for (const jid of [c.id, c.lid, c.phoneNumber]) book.note(jid, name);
+  const lid = c.lid ?? (isLid(c.id) ? c.id : undefined);
+  const pn = c.phoneNumber ?? (isLid(c.id) ? undefined : c.id);
+  book.alias(pn, lid);
 }
 
 export const phoneOf = (jid: string | null | undefined): string | undefined => {

package/runtime/node_modules/@metro-labs/whatsapp/src/profile.ts

@@ -0,0 +1,158 @@
+import { jidNormalizedUser, type WASocket } from 'baileys';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { nonEmpty, type SenderProfile } from '@metro-labs/core/stations/sender-profile';
+import { phoneOf, type NameBook } from './names.js';
+
+export const NO_PICTURE_MS = 6 * 60 * 60_000;
+export const RATE_LIMITED_MS = 30 * 60_000;
+export const LOOKUP_BUDGET_MS = 6_000;
+export const PROFILE_READS = 4;
+const TRY_MS = 1_500;
+const NO_PICTURE_MAX = 2_000;
+const REFUSED = new Set([401, 403, 404]);
+const RATE_LIMIT_RE = /rate.?over.?limit|too many/i;
+const PICTURE_TYPES = ['image', 'preview'] as const;
+
+type ProfileSocket = Pick<WASocket, 'fetchStatus' | 'profilePictureUrl' | 'signalRepository'>;
+
+export interface PeerProfile {
+  profile: SenderProfile;
+  other: string | null;
+}
+
+export class PictureMemory {
+  private none = new Map<string, number>();
+  private limitedAt: number | null = null;
+
+  constructor(readonly now: () => number = Date.now) {}
+
+  known(jid: string): boolean {
+    const at = this.none.get(jid);
+    if (at === undefined) return false;
+    if (this.now() - at < NO_PICTURE_MS) return true;
+    this.none.delete(jid);
+    return false;
+  }
+
+  remember(jid: string): void {
+    this.none.delete(jid);
+    this.none.set(jid, this.now());
+    if (this.none.size <= NO_PICTURE_MAX) return;
+    const oldest = this.none.keys().next();
+    if (!oldest.done) this.none.delete(oldest.value);
+  }
+
+  limited(): boolean {
+    return this.limitedAt !== null && this.now() - this.limitedAt < RATE_LIMITED_MS;
+  }
+
+  limit(): void {
+    this.limitedAt = this.now();
+  }
+}
+
+type Failure = 'refused' | 'limited' | 'other';
+
+function failureOf(err: unknown): Failure {
+  const output = isRecord(err) && isRecord(err.output) ? err.output : {};
+  const code = typeof output.statusCode === 'number' ? output.statusCode : undefined;
+  if (code === 429 || RATE_LIMIT_RE.test(errMsg(err))) return 'limited';
+  return code !== undefined && REFUSED.has(code) ? 'refused' : 'other';
+}
+
+function within<T, F>(work: Promise<T>, ms: number, fallback: F): Promise<T | F> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<F>((resolve) => {
+    timer = setTimeout(() => {
+      resolve(fallback);
+    }, ms);
+  });
+  return Promise.race([work.catch(() => fallback), late]).finally(() => {
+    clearTimeout(timer);
+  });
+}
+
+async function otherIdOf(sock: ProfileSocket, jid: string): Promise<string | null> {
+  const mapping = sock.signalRepository.lidMapping;
+  const other = await within(jid.endsWith('@lid') ? mapping.getPNForLID(jid) : mapping.getLIDForPN(jid), TRY_MS, null);
+  return other === null ? null : jidNormalizedUser(other);
+}
+
+type Tried = { url: string } | 'none' | 'stop';
+
+async function pictureFor(sock: ProfileSocket, jid: string, memory: PictureMemory, deadline: number): Promise<Tried> {
+  for (const type of PICTURE_TYPES) {
+    const left = deadline - memory.now();
+    if (left <= 0) return 'stop';
+    try {
+      const url = nonEmpty(await sock.profilePictureUrl(jid, type, Math.min(TRY_MS, left)));
+      if (url !== undefined) return { url };
+    } catch (err) {
+      const failure = failureOf(err);
+      if (failure === 'limited') memory.limit();
+      if (failure !== 'refused') return 'stop';
+    }
+  }
+  memory.remember(jid);
+  return 'none';
+}
+
+export async function pictureOf(sock: ProfileSocket, jids: string[], memory: PictureMemory, deadline = memory.now() + LOOKUP_BUDGET_MS): Promise<string | undefined> {
+  for (const jid of jids) {
+    if (memory.limited()) return undefined;
+    if (memory.known(jid)) continue;
+    const tried = await pictureFor(sock, jid, memory, deadline);
+    if (tried === 'stop') return undefined;
+    if (tried !== 'none') return tried.url;
+  }
+  return undefined;
+}
+
+export async function readPeer(sock: ProfileSocket, jid: string, memory: PictureMemory): Promise<PeerProfile> {
+  const deadline = memory.now() + LOOKUP_BUDGET_MS;
+  const other = await otherIdOf(sock, jid);
+  const jids = other === null ? [jid] : [jid, other];
+  const [statuses, picture] = await Promise.all([within(sock.fetchStatus(jid), LOOKUP_BUDGET_MS, undefined), pictureOf(sock, jids, memory, deadline)]);
+  const status: unknown = statuses?.[0]?.status;
+  const about = nonEmpty(isRecord(status) ? status.status : undefined);
+  const phone = phoneOf(jid.endsWith('@lid') ? other : jid);
+  return {
+    other,
+    profile: {
+      id: jid,
+      ...(phone === undefined ? {} : { name: phone, address: phone }),
+      ...(about === undefined ? {} : { about }),
+      ...(picture === undefined ? {} : { avatar: picture }),
+    },
+  };
+}
+
+export function withName(peer: PeerProfile, names: NameBook): SenderProfile {
+  const { profile, other } = peer;
+  if (other !== null) names.alias(profile.id.endsWith('@lid') ? other : profile.id, profile.id.endsWith('@lid') ? profile.id : other);
+  const name = names.get(profile.id) ?? (other === null ? undefined : names.get(other));
+  return name === undefined ? profile : { ...profile, display_name: name };
+}
+
+export function limiter(max: number): <T>(run: () => Promise<T>) => Promise<T> {
+  let active = 0;
+  const waiting: (() => void)[] = [];
+  const release = (): void => {
+    const next = waiting.shift();
+    if (next === undefined) active -= 1;
+    else next();
+  };
+  return async <T>(run: () => Promise<T>): Promise<T> => {
+    if (active >= max)
+      await new Promise<void>((resolve) => {
+        waiting.push(resolve);
+      });
+    else active += 1;
+    try {
+      return await run();
+    } finally {
+      release();
+    }
+  };
+}

package/runtime/node_modules/@metro-labs/whatsapp/src/station.ts

@@ -24,6 +24,8 @@ export const whatsappStation: Station = {
   readsProfiles: true,
   resolvesSenders: true,
   discoversChannels: true,
+  reportsStatus: true,
+  pairAgain: { identity: 'phone' },
   forget: (accountId) => {
     tokenFiles.forget(accountId);
     nameFiles.forget(accountId);

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.316"
+  "version": "0.1.0-beta.317"
 }

package/runtime/sdk-runner/node_modules/@metro-labs/core/package.json

@@ -26,6 +26,7 @@
     "./lines": "./src/lines.ts",
     "./endpoints": "./src/endpoints.ts",
     "./stations/types": "./src/stations/types.ts",
+    "./stations/account-status": "./src/stations/account-status.ts",
     "./stations/channel-directory": "./src/stations/channel-directory.ts",
     "./stations/channel-pages": "./src/stations/channel-pages.ts",
     "./stations/account-files": "./src/stations/account-files.ts",

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/account-status.ts

@@ -0,0 +1,26 @@
+import { isRecord } from '../is-record.js';
+
+export const ACCOUNT_STATES = ['connected', 'connecting', 'logged_out', 'disconnected'] as const;
+
+export type AccountState = (typeof ACCOUNT_STATES)[number];
+
+export interface AccountStatus {
+  state: AccountState;
+  reason?: string;
+  since: number;
+}
+
+const REASON_MAX = 300;
+
+export function accountStatus(state: AccountState, reason?: string, since = Date.now()): AccountStatus {
+  const text = reason?.trim().slice(0, REASON_MAX) ?? '';
+  return text === '' ? { state, since } : { state, reason: text, since };
+}
+
+export function accountStatusOf(raw: unknown): AccountStatus | null {
+  if (!isRecord(raw)) return null;
+  const state = ACCOUNT_STATES.find((s) => s === raw.state);
+  const since = raw.since;
+  if (state === undefined || typeof since !== 'number' || !Number.isFinite(since)) return null;
+  return accountStatus(state, typeof raw.reason === 'string' ? raw.reason : undefined, since);
+}

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/stations/types.ts

@@ -114,6 +114,8 @@ export interface Station {
   readFilters?: ReadonlySet<ReadFilter>;
   approvals?: boolean;
   sendsFrames?: boolean;
+  reportsStatus?: boolean;
+  pairAgain?: { identity: string };
   attachmentMode: AttachmentMode;
   forget?: (accountId: string) => void;
   forgetExcept?: (keptAccountIds: readonly string[]) => void;

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.316",
+  "version": "0.1.0-beta.317",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",