@moxxy/plugin-channel-imessage 0.29.0

package/src/channel.test.ts

@@ -0,0 +1,256 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { ImessageChannel } from './channel.js';
+import type { BlueBubblesClientLike } from './bluebubbles-client.js';
+import {
+  IMESSAGE_ALLOWED_HANDLES_KEY,
+  IMESSAGE_OWNER_HANDLES_KEY,
+  IMESSAGE_SERVER_PASSWORD_KEY,
+  IMESSAGE_SERVER_URL_KEY,
+} from './keys.js';
+import { MAX_INBOUND_TEXT_CHARS } from './schema.js';
+
+const OWNER = '+19998887777';
+const FRIEND = '+15550001111';
+const STRANGER = '+14440002222';
+const chatFor = (handle: string): string => `iMessage;-;${handle}`;
+
+function stubVault(seed: Record<string, string> = {}): VaultStore {
+  const map = new Map(Object.entries(seed));
+  return {
+    get: async (k: string) => map.get(k) ?? null,
+    set: async (k: string, v: string) => {
+      map.set(k, v);
+    },
+    has: async (k: string) => map.has(k),
+    delete: async (k: string) => map.delete(k),
+  } as unknown as VaultStore;
+}
+
+function makeFakeSession(opts: { hangTurns?: boolean } = {}) {
+  const listeners = new Set<(e: unknown) => void>();
+  const prompts: string[] = [];
+  let release: (() => void) | null = null;
+  const session = {
+    tools: { list: () => [{ name: 'Read' }, { name: 'Grep' }] },
+    transcribers: { tryGetActive: () => null },
+    setPermissionResolver: vi.fn(),
+    log: {
+      subscribe: (fn: (e: unknown) => void) => {
+        listeners.add(fn);
+        return () => listeners.delete(fn);
+      },
+    },
+    runTurn(prompt: string) {
+      prompts.push(prompt);
+      const hang = opts.hangTurns;
+      return (async function* () {
+        if (hang) {
+          await new Promise<void>((resolve) => {
+            release = resolve;
+          });
+        }
+      })();
+    },
+  };
+  return {
+    session: session as unknown as Session,
+    raw: session,
+    prompts,
+    releaseTurn: () => release?.(),
+  };
+}
+
+class FakeClient implements BlueBubblesClientLike {
+  sends: Array<{ chatGuid: string; message: string }> = [];
+  pinged = false;
+  connected = false;
+  closed = false;
+  private readonly listeners = new Set<(raw: unknown) => void>();
+  private n = 0;
+
+  async ping(): Promise<void> {
+    this.pinged = true;
+  }
+  async connect(): Promise<void> {
+    this.connected = true;
+  }
+  onMessage(listener: (raw: unknown) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  async sendText(chatGuid: string, message: string): Promise<{ guid: string | null; tempGuid: string }> {
+    this.sends.push({ chatGuid, message });
+    const i = ++this.n;
+    return { guid: `guid-${i}`, tempGuid: `temp-${i}` };
+  }
+  close(): void {
+    this.closed = true;
+  }
+  /** Push one inbound `new-message` payload into the channel. */
+  receive(raw: unknown): void {
+    for (const listener of this.listeners) listener(raw);
+  }
+}
+
+function makeChannel(overrides: { vault?: VaultStore; hangTurns?: boolean; allowedTools?: string[] } = {}) {
+  const client = new FakeClient();
+  const fake = makeFakeSession({ ...(overrides.hangTurns ? { hangTurns: true } : {}) });
+  const channel = new ImessageChannel({
+    vault:
+      overrides.vault ??
+      stubVault({
+        [IMESSAGE_SERVER_URL_KEY]: 'http://localhost:1234',
+        [IMESSAGE_SERVER_PASSWORD_KEY]: 'secret',
+        [IMESSAGE_ALLOWED_HANDLES_KEY]: JSON.stringify([FRIEND]),
+        [IMESSAGE_OWNER_HANDLES_KEY]: JSON.stringify([OWNER]),
+      }),
+    ...(overrides.allowedTools ? { allowedTools: overrides.allowedTools } : {}),
+    clientFactory: () => client,
+  });
+  return { channel, client, fake };
+}
+
+const inbound = (opts: {
+  chatGuid: string;
+  text?: string;
+  isFromMe?: boolean;
+  sender?: string;
+  guid?: string;
+}): Record<string, unknown> => ({
+  guid: opts.guid ?? 'msg-1',
+  text: opts.text ?? 'hi',
+  isFromMe: opts.isFromMe ?? false,
+  ...(opts.sender ? { handle: { address: opts.sender } } : {}),
+  chats: [{ guid: opts.chatGuid }],
+});
+
+describe('ImessageChannel start()', () => {
+  it('pings, connects and swaps in the allow-list resolver on the session', async () => {
+    const { channel, client, fake } = makeChannel({ allowedTools: ['Read'] });
+    const handle = await channel.start({ session: fake.session });
+    expect(client.pinged).toBe(true);
+    expect(client.connected).toBe(true);
+    expect(fake.raw.setPermissionResolver).toHaveBeenCalledWith(channel.permissionResolver);
+    expect(channel.permissionResolver.name).toBe('imessage-allow-list');
+    await handle.stop();
+  });
+
+  it('throws a friendly error when the server is not configured', async () => {
+    const fake = makeFakeSession();
+    const channel = new ImessageChannel({ vault: stubVault(), clientFactory: () => new FakeClient() });
+    await expect(channel.start({ session: fake.session })).rejects.toThrow(/No BlueBubbles server configured/);
+  });
+});
+
+describe('inbound gating (every session-reaching path)', () => {
+  it('runs a turn for an allow-listed sender and replies to their chat', async () => {
+    const { channel, client, fake } = makeChannel();
+    const handle = await channel.start({ session: fake.session });
+    client.receive(inbound({ chatGuid: chatFor(FRIEND), sender: FRIEND, text: 'hello moxxy' }));
+    await vi.waitFor(() => expect(fake.prompts).toEqual(['hello moxxy']));
+    await vi.waitFor(() => {
+      expect(client.sends.at(-1)).toEqual({ chatGuid: chatFor(FRIEND), message: '(no output)' });
+    });
+    await handle.stop();
+  });
+
+  it('silently drops senders that are not allow-listed', async () => {
+    const { channel, client, fake } = makeChannel();
+    const handle = await channel.start({ session: fake.session });
+    client.receive(inbound({ chatGuid: chatFor(STRANGER), sender: STRANGER, text: 'let me in' }));
+    await new Promise((r) => setTimeout(r, 20));
+    expect(fake.prompts).toEqual([]);
+    expect(client.sends).toEqual([]); // no reply — a reply would leak the bot's existence
+    await handle.stop();
+  });
+
+  it('drops group messages (v1 is direct-message only)', async () => {
+    const { channel, client, fake } = makeChannel();
+    const handle = await channel.start({ session: fake.session });
+    client.receive(inbound({ chatGuid: 'iMessage;+;chat123', sender: FRIEND, text: 'in a group' }));
+    await new Promise((r) => setTimeout(r, 20));
+    expect(fake.prompts).toEqual([]);
+    await handle.stop();
+  });
+
+  it('accepts the owner self-chat and replies into it', async () => {
+    const { channel, client, fake } = makeChannel();
+    const handle = await channel.start({ session: fake.session });
+    client.receive(inbound({ chatGuid: chatFor(OWNER), isFromMe: true, text: 'remind me to stretch' }));
+    await vi.waitFor(() => expect(fake.prompts).toEqual(['remind me to stretch']));
+    await vi.waitFor(() => {
+      expect(client.sends.at(-1)).toEqual({ chatGuid: chatFor(OWNER), message: '(no output)' });
+    });
+    await handle.stop();
+  });
+
+  it("ignores the owner's outbound messages to other people (isFromMe foreign chat)", async () => {
+    const { channel, client, fake } = makeChannel();
+    const handle = await channel.start({ session: fake.session });
+    client.receive(inbound({ chatGuid: chatFor(FRIEND), isFromMe: true, text: 'private chat' }));
+    await new Promise((r) => setTimeout(r, 20));
+    expect(fake.prompts).toEqual([]);
+    await handle.stop();
+  });
+
+  it('drops echoes of its own replies (loop protection)', async () => {
+    const { channel, client, fake } = makeChannel();
+    const handle = await channel.start({ session: fake.session });
+
+    // One self-chat turn: the channel records its send ids (guid-1 / temp-1).
+    client.receive(inbound({ chatGuid: chatFor(OWNER), isFromMe: true, text: 'first', guid: 'in-1' }));
+    await vi.waitFor(() => expect(client.sends.length).toBe(1));
+
+    // BlueBubbles echoes our reply back as a new-message with our guid — must
+    // NOT trigger a turn (it would loop into itself in the self-chat).
+    client.receive(inbound({ chatGuid: chatFor(OWNER), isFromMe: true, text: '(no output)', guid: 'guid-1' }));
+    await new Promise((r) => setTimeout(r, 20));
+    expect(fake.prompts).toEqual(['first']);
+
+    // A genuinely new self-chat message still gets through.
+    client.receive(inbound({ chatGuid: chatFor(OWNER), isFromMe: true, text: 'second', guid: 'in-2' }));
+    await vi.waitFor(() => expect(fake.prompts).toEqual(['first', 'second']));
+    await handle.stop();
+  });
+
+  it('drops schema-invalid and oversized payloads without crashing', async () => {
+    const { channel, client, fake } = makeChannel();
+    const handle = await channel.start({ session: fake.session });
+    client.receive(null);
+    client.receive('garbage');
+    client.receive({ guid: 'x' }); // no chats
+    client.receive(inbound({ chatGuid: chatFor(FRIEND), sender: FRIEND, text: 'x'.repeat(MAX_INBOUND_TEXT_CHARS + 1) }));
+    await new Promise((r) => setTimeout(r, 20));
+    expect(fake.prompts).toEqual([]);
+    // Still alive: a valid message afterwards works.
+    client.receive(inbound({ chatGuid: chatFor(FRIEND), sender: FRIEND, text: 'still alive?' }));
+    await vi.waitFor(() => expect(fake.prompts).toEqual(['still alive?']));
+    await handle.stop();
+  });
+
+  it('refuses overlapping turns with a busy reply (single-flight)', async () => {
+    const { channel, client, fake } = makeChannel({ hangTurns: true });
+    const handle = await channel.start({ session: fake.session });
+    client.receive(inbound({ chatGuid: chatFor(FRIEND), sender: FRIEND, text: 'long task' }));
+    await vi.waitFor(() => expect(fake.prompts).toEqual(['long task']));
+    client.receive(inbound({ chatGuid: chatFor(FRIEND), sender: FRIEND, text: 'impatient follow-up', guid: 'm2' }));
+    await vi.waitFor(() => {
+      expect(client.sends.some((s) => s.message.includes('still working'))).toBe(true);
+    });
+    expect(fake.prompts).toEqual(['long task']);
+    fake.releaseTurn();
+    await handle.stop();
+  });
+});
+
+describe('lifecycle', () => {
+  it('stop() closes the client and resolves running', async () => {
+    const { channel, client, fake } = makeChannel();
+    const handle = await channel.start({ session: fake.session });
+    await handle.stop('test');
+    expect(client.closed).toBe(true);
+    await expect(handle.running).resolves.toBeUndefined();
+  });
+});

package/src/channel.ts

@@ -0,0 +1,352 @@
+import { newTurnId } from '@moxxy/core';
+import { TurnCoordinator, resolveSecret } from '@moxxy/channel-kit';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type {
+  Channel,
+  ChannelHandle,
+  ChannelStartOptsBase,
+  MoxxyEvent,
+  PermissionResolver,
+} from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import {
+  IMESSAGE_ALLOWED_HANDLES_KEY,
+  IMESSAGE_OWNER_HANDLES_KEY,
+  IMESSAGE_SERVER_PASSWORD_ENV,
+  IMESSAGE_SERVER_PASSWORD_KEY,
+  IMESSAGE_SERVER_URL_ENV,
+  IMESSAGE_SERVER_URL_KEY,
+  normalizeHandle,
+  parseHandleList,
+} from './keys.js';
+import { gateInboundMessage } from './message-gate.js';
+import { buildImessagePermissionResolver } from './permission.js';
+import {
+  BlueBubblesClient,
+  type BlueBubblesClientLike,
+  type BlueBubblesClientOptions,
+} from './bluebubbles-client.js';
+import { runImessageTurn } from './channel/turn-runner.js';
+import { splitForImessage } from './channel/chunker.js';
+
+/** Bound on remembered own-send ids (guid + tempGuid) for the echo drop. */
+const MAX_SENT_IDS = 256;
+
+/** Rate limit for "dropped inbound message" warnings. */
+const DROP_WARN_INTERVAL_MS = 5_000;
+
+/** Message when the server URL / password isn't configured yet. */
+const NOT_CONFIGURED_MESSAGE =
+  'No BlueBubbles server configured. Run `moxxy channels imessage setup` (or set ' +
+  `${IMESSAGE_SERVER_URL_ENV} + ${IMESSAGE_SERVER_PASSWORD_ENV}).`;
+
+export interface ImessageChannelLogger {
+  debug?(msg: string, meta?: Record<string, unknown>): void;
+  info?(msg: string, meta?: Record<string, unknown>): void;
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+  error?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export interface ImessageStartOpts extends ChannelStartOptsBase {
+  readonly session: Session;
+  /** Override the autonomous tool allow-list at start. */
+  readonly allowedTools?: ReadonlyArray<string>;
+}
+
+export interface ImessageChannelOptions {
+  readonly vault: VaultStore;
+  /** Server URL override; beats env + vault. */
+  readonly serverUrl?: string;
+  /** Server password override; beats env + vault. */
+  readonly password?: string;
+  /** Tools the model may call autonomously. `['*']` allows every registered tool. */
+  readonly allowedTools?: ReadonlyArray<string>;
+  /** Extra allow-listed handles, merged with the vault allow-list. */
+  readonly allowedHandles?: ReadonlyArray<string>;
+  /** Extra owner handles (self-chat identities), merged with the vault list. */
+  readonly ownerHandles?: ReadonlyArray<string>;
+  readonly logger?: ImessageChannelLogger;
+  /** Test seam: build the BlueBubbles transport (production uses the real one). */
+  readonly clientFactory?: (opts: BlueBubblesClientOptions) => BlueBubblesClientLike;
+}
+
+export class ImessageChannel implements Channel<ImessageStartOpts> {
+  readonly name = 'imessage';
+  /**
+   * Installed on the session by the CLI dispatcher. Replaced in `start()` once
+   * the live tool registry is available for `['*']` expansion; until then it
+   * denies everything (safe default before start).
+   */
+  permissionResolver: PermissionResolver;
+
+  private readonly opts: ImessageChannelOptions;
+  private session: Session | null = null;
+  private model: string | undefined;
+
+  private client: BlueBubblesClientLike | null = null;
+  private readonly allowedHandles = new Set<string>();
+  private readonly ownerHandles = new Set<string>();
+
+  // Single-flight turn state + the bounded own-turn-id set the foreign-turn
+  // mirror gate filters on (invariant #8).
+  private readonly turns = new TurnCoordinator();
+  private lastChatGuid: string | null = null;
+  private logUnsub: (() => void) | null = null;
+
+  /**
+   * guid + tempGuid of messages WE sent. BlueBubbles emits `new-message` for
+   * the account's own sends too (our replies come back `isFromMe`), so any
+   * inbound whose id is in this set is an echo of ourselves and must be dropped
+   * (loop protection).
+   */
+  private readonly sentIds = new Set<string>();
+
+  private handle: ChannelHandle | null = null;
+  private runningSettled = false;
+  private resolveRunning: (() => void) | null = null;
+  private stopping = false;
+  private lastDropWarnAt = 0;
+
+  constructor(opts: ImessageChannelOptions) {
+    this.opts = opts;
+    // Pre-start: deny-all (replaced with the real allow-list resolver in start()).
+    this.permissionResolver = buildImessagePermissionResolver({
+      allowedTools: [],
+      allToolNames: [],
+      ...(opts.logger ? { logger: opts.logger } : {}),
+    });
+  }
+
+  async start(startOpts: ImessageStartOpts): Promise<ChannelHandle> {
+    if (this.handle) return this.handle;
+    this.session = startOpts.session;
+    this.model = startOpts.model;
+
+    // Config: explicit option → env → vault (shared channel-kit precedence).
+    const serverUrl =
+      this.opts.serverUrl ??
+      (await resolveSecret(this.opts.vault, {
+        envVar: IMESSAGE_SERVER_URL_ENV,
+        vaultKey: IMESSAGE_SERVER_URL_KEY,
+      }));
+    const password =
+      this.opts.password ??
+      (await resolveSecret(this.opts.vault, {
+        envVar: IMESSAGE_SERVER_PASSWORD_ENV,
+        vaultKey: IMESSAGE_SERVER_PASSWORD_KEY,
+      }));
+    if (!serverUrl || !password) throw new Error(NOT_CONFIGURED_MESSAGE);
+
+    // Allow-list (OTHER people) + owner handles (self-chat), from vault + options.
+    this.rebuildHandleSet(
+      this.allowedHandles,
+      parseHandleList(await this.opts.vault.get(IMESSAGE_ALLOWED_HANDLES_KEY)),
+      this.opts.allowedHandles,
+    );
+    this.rebuildHandleSet(
+      this.ownerHandles,
+      parseHandleList(await this.opts.vault.get(IMESSAGE_OWNER_HANDLES_KEY)),
+      this.opts.ownerHandles,
+    );
+
+    // Swap in the real autonomous allow-list resolver now that the tool registry
+    // is live (mirrors Signal; `['*']` expands here).
+    const allowedTools = startOpts.allowedTools ?? this.opts.allowedTools ?? [];
+    const allToolNames = this.session.tools.list().map((t) => t.name);
+    this.permissionResolver = buildImessagePermissionResolver({
+      allowedTools,
+      allToolNames,
+      ...(this.opts.logger ? { logger: this.opts.logger } : {}),
+    });
+    this.session.setPermissionResolver(this.permissionResolver);
+
+    // Mirror-to-last-chat: post assistant prose for turns this channel did NOT
+    // initiate (a co-attached surface ran one) into the last chat served.
+    this.logUnsub = this.session.log.subscribe((event) => this.mirrorForeignTurn(event));
+
+    const running = new Promise<void>((resolve) => {
+      this.resolveRunning = resolve;
+    });
+
+    const client = this.makeClient({ serverUrl, password });
+    this.client = client;
+    try {
+      // Reachability + auth probe deferred to here (NOT isAvailable): surfaces a
+      // friendly error if the localhost BlueBubbles server isn't up.
+      await client.ping();
+      await client.connect();
+    } catch (err) {
+      this.logUnsub?.();
+      this.logUnsub = null;
+      this.client = null;
+      throw err;
+    }
+    client.onMessage((raw) => this.handleInbound(raw));
+
+    this.handle = {
+      running,
+      stop: async (reason = 'shutdown') => {
+        this.stopping = true;
+        // Abort the in-flight turn FIRST so the model loop stops the moment the
+        // operator asks to shut down. The autonomous allow-list resolver has no
+        // pending operator prompts, so there is nothing to abortAll.
+        this.turns.abort(reason);
+        this.logUnsub?.();
+        this.logUnsub = null;
+        const client = this.client;
+        this.client = null;
+        client?.close();
+        this.settleRunning();
+      },
+    };
+    this.opts.logger?.info?.('imessage: channel started', {
+      allowedHandles: this.allowedHandles.size,
+      ownerHandles: this.ownerHandles.size,
+    });
+    return this.handle;
+  }
+
+  // -------------------------------------------------------------------------
+  // Inbound
+  // -------------------------------------------------------------------------
+
+  /** Every inbound `new-message` funnels through the one gate. */
+  private handleInbound(raw: unknown): void {
+    if (this.stopping) return;
+    const verdict = gateInboundMessage(
+      {
+        ownerHandles: this.ownerHandles,
+        allowedHandles: this.allowedHandles,
+        isOwnSend: (id) => this.sentIds.has(id),
+      },
+      raw,
+    );
+    if (!verdict.ok) {
+      this.warnDrop(verdict.reason);
+      return;
+    }
+    this.dispatchInBackground(this.processMessage(verdict.chatGuid, verdict.text), 'new-message');
+  }
+
+  /** Busy gate, then one coordinated turn. */
+  private async processMessage(chatGuid: string, text: string): Promise<void> {
+    if (!this.session) return;
+    // Atomic single-flight guard (the coordinator claims the slot BEFORE any
+    // await); the turnId minted here is recorded as an own-turn id — that's what
+    // mirrorForeignTurn filters on (invariant #8).
+    const lease = this.turns.begin(newTurnId());
+    if (!lease) {
+      await this.sendText(chatGuid, 'I am still working on the previous prompt. One moment…');
+      return;
+    }
+    this.lastChatGuid = chatGuid;
+    try {
+      await runImessageTurn(
+        {
+          session: this.session,
+          send: (t) => this.sendText(chatGuid, t),
+          ...(this.opts.logger ? { logger: this.opts.logger } : {}),
+        },
+        {
+          text,
+          ...(this.model ? { model: this.model } : {}),
+          controller: lease.controller,
+          turnId: lease.turnId,
+        },
+      );
+    } finally {
+      lease.end();
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Outbound
+  // -------------------------------------------------------------------------
+
+  /** Send one message and record its ids for the echo drop. */
+  private async sendText(chatGuid: string, text: string): Promise<void> {
+    const client = this.client;
+    if (!client) throw new Error('imessage client is not connected');
+    const { guid, tempGuid } = await client.sendText(chatGuid, text);
+    this.recordSent(tempGuid);
+    if (guid) this.recordSent(guid);
+  }
+
+  private recordSent(id: string): void {
+    this.sentIds.add(id);
+    if (this.sentIds.size > MAX_SENT_IDS) {
+      const oldest = this.sentIds.values().next().value;
+      if (oldest !== undefined) this.sentIds.delete(oldest);
+    }
+  }
+
+  /**
+   * Post the assistant's prose for a turn this channel did not initiate.
+   * Skipped for our own turnIds (robust to async ordering / replay, invariant
+   * #8) and while a turn of ours is streaming via the chunked sender.
+   */
+  private mirrorForeignTurn(event: MoxxyEvent): void {
+    const text = this.turns.mirrorText(event);
+    if (text == null) return;
+    const chatGuid = this.lastChatGuid;
+    if (!chatGuid || !this.client) return;
+    void (async () => {
+      for (const part of splitForImessage(text)) {
+        await this.sendText(chatGuid, part);
+      }
+    })().catch((err) => {
+      this.opts.logger?.warn?.('imessage: mirror failed', { err: String(err) });
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Plumbing
+  // -------------------------------------------------------------------------
+
+  private makeClient(opts: { serverUrl: string; password: string }): BlueBubblesClientLike {
+    const clientOpts: BlueBubblesClientOptions = {
+      serverUrl: opts.serverUrl,
+      password: opts.password,
+      ...(this.opts.logger ? { logger: this.opts.logger } : {}),
+    };
+    const factory = this.opts.clientFactory ?? ((o) => new BlueBubblesClient(o));
+    return factory(clientOpts);
+  }
+
+  private rebuildHandleSet(
+    target: Set<string>,
+    fromVault: ReadonlyArray<string>,
+    fromOptions: ReadonlyArray<string> | undefined,
+  ): void {
+    target.clear();
+    for (const handle of fromVault) target.add(handle);
+    for (const handle of fromOptions ?? []) {
+      const normalized = normalizeHandle(handle);
+      if (normalized.length > 0) target.add(normalized);
+    }
+  }
+
+  /**
+   * Run a handler detached from the socket read loop (an inbound handler that
+   * awaited a whole turn would park delivery for its duration). Errors are
+   * logged here — nothing upstream awaits this promise.
+   */
+  private dispatchInBackground(work: Promise<void>, kind: string): void {
+    void work.catch((err) => {
+      this.opts.logger?.warn?.('imessage: handler failed', { kind, err: String(err) });
+    });
+  }
+
+  private warnDrop(reason: string): void {
+    const now = Date.now();
+    if (now - this.lastDropWarnAt < DROP_WARN_INTERVAL_MS) return;
+    this.lastDropWarnAt = now;
+    this.opts.logger?.debug?.('imessage: dropped inbound message', { reason });
+  }
+
+  private settleRunning(): void {
+    if (this.runningSettled) return;
+    this.runningSettled = true;
+    this.resolveRunning?.();
+  }
+}