@rikaidev/yomi 0.3.1 → 0.4.1

package/PRIVACY.md

@@ -19,6 +19,20 @@ The only data that leaves your device is whatever the agent surfaces in its
 replies to you — and in a cloud assistant, that surfaced text is processed by
 that assistant's model. Yomi itself makes no outbound copy of your messages.
 
+## The one non-LINE request Yomi makes
+
+At startup Yomi asks the public npm registry whether a newer version has been
+published, and tells the agent if so. This exists because a Desktop Extension
+(`.mcpb`) installed by hand never auto-updates — without the check you could
+sit on an old build, security fixes included, and never know.
+
+It sends **no message content and no account identifier**: it is a plain GET of
+a public package document. What it does reveal to the registry is that your IP
+address is running Yomi, and roughly which version. Nothing is uploaded.
+
+Set **`YOMI_NO_UPDATE_CHECK=1`** to turn it off; Yomi then makes no outbound
+request except to LINE itself.
+
 ## Excluding conversations
 
 You can exclude any conversation at any time, in plain language to the agent

package/README.md

@@ -36,6 +36,9 @@ reply, who ties your world together, and what has gone overdue.
 No official API, no bot account, no webhook. Yomi logs in as a secondary device
 on your own account.
 
+Guides: **[What is a LINE MCP server?](https://rikaidev.github.io/yomi/line-mcp/)**
+· **[LINE MCP 是什麼？Yomi、官方 Bot 與桌面自動化的差異](https://rikaidev.github.io/yomi/zh-tw/line-mcp/)**.
+
 ![license](https://img.shields.io/badge/license-MIT-blue) ![runtime](https://img.shields.io/badge/runtime-node%20%7C%20bun-black) ![protocol](https://img.shields.io/badge/MCP-stdio-green) ![npm](https://img.shields.io/badge/npm-@rikaidev%2Fyomi-red)
 
 > **Unofficial.** Yomi is an independent personal project, not affiliated with or

package/dist/auth/credential-store.js

@@ -16,6 +16,15 @@
  * KeychainService service name: see keychain.ts — writes go to Yomi's own
  * canonical namespace; a legacy namespace from before this split is read
  * as a fallback and migrated forward, never written to or deleted.
+ *
+ * The Keychain is machine-global: it is NOT scoped by YOMI_DATA_DIR, so on
+ * macOS an automated run that only redirected the data dir would still find —
+ * and act on — the developer's real LINE session (a stored login certificate
+ * is enough for `login` to start a device sign-in against the live account).
+ * `YOMI_NO_KEYCHAIN=1` forces the file backend so tests and smoke runs are
+ * genuinely isolated by pointing YOMI_DATA_DIR somewhere disposable. It is a
+ * testing escape hatch: setting it in normal use downgrades credential
+ * storage from the Keychain to a plain JSON file.
  */
 import { dirname, join } from 'node:path';
 import { getKeychainService } from './keychain.js';
@@ -188,7 +197,8 @@ export class CredentialStore {
         this.filePath = fallbackFilePath;
         this.cache = new Map();
         this.loaded = false;
-        this.secureStorageEnabled = process.platform === 'darwin';
+        this.secureStorageEnabled =
+            process.platform === 'darwin' && process.env.YOMI_NO_KEYCHAIN !== '1';
         this.keychainService = this.secureStorageEnabled
             ? getKeychainService()
             : null;

package/dist/mcp/client-capabilities.js

@@ -0,0 +1,55 @@
+import { CLIENT_CAPABILITIES_META_KEY } from '@modelcontextprotocol/server';
+/**
+ * The capabilities the CURRENT request's client declared.
+ *
+ * @param server - MCP Server instance (the legacy, handshake-scoped source).
+ * @param ctx - Request handler context (the modern, per-request source).
+ * @returns The declared capabilities, or undefined when the client declared
+ * none and no envelope carried any.
+ */
+export function clientCapabilitiesOf(server, ctx) {
+    // The envelope type is opaque (`RequestMetaEnvelope = {}`) — the SDK models
+    // it as a bag of reserved keys, so reaching the declared capabilities off it
+    // needs an index-signature view rather than a property access.
+    const envelope = ctx?.mcpReq.envelope;
+    return (envelope?.[CLIENT_CAPABILITIES_META_KEY] ?? server.getClientCapabilities());
+}
+/**
+ * Does the connected client accept form-mode elicitation (`elicitation/create`
+ * carrying a `requestedSchema`)?
+ *
+ * @param capabilities - Result of `server.getClientCapabilities()`.
+ * @returns True when the client declared `elicitation.form`, or declared a
+ * bare `elicitation` with no mode sub-keys at all (pre-2026-07-28 shape).
+ */
+export function supportsFormElicitation(capabilities) {
+    const elicitation = capabilities?.elicitation;
+    if (!elicitation || typeof elicitation !== 'object') {
+        return false;
+    }
+    if ('form' in elicitation && elicitation.form) {
+        return true;
+    }
+    // A client that named `url` and not `form` is url-only; one that named
+    // neither predates the split and can only have meant form.
+    return !('url' in elicitation && elicitation.url);
+}
+/**
+ * Does the connected client accept url-mode elicitation (`elicitation/create`
+ * with `mode: "url"`, answered out-of-band and closed by a
+ * `notifications/elicitation/complete`)?
+ *
+ * Not used by any flow yet — url mode has no observed client support, the
+ * same trap ./ui/login-app.ts documents for MCP Apps. Exported so a future
+ * url-mode path can gate on the real declaration rather than assume it.
+ *
+ * @param capabilities - Result of `server.getClientCapabilities()`.
+ * @returns True only when the client explicitly declared `elicitation.url`.
+ */
+export function supportsUrlElicitation(capabilities) {
+    const elicitation = capabilities?.elicitation;
+    if (!elicitation || typeof elicitation !== 'object') {
+        return false;
+    }
+    return 'url' in elicitation && Boolean(elicitation.url);
+}

package/dist/mcp/handlers/login-copy.js

@@ -0,0 +1,200 @@
+import { LINE_PIN_CODE_LIFETIME_MS } from '../../line/auth/pwless/index.js';
+/** LINE region codes offered on the login form. */
+export const LOGIN_REGIONS = ['TW', 'JP', 'TH', 'ID', 'US'];
+/** Where the toggle lives on the primary phone, in LINE's own words. */
+export const PRIMARY_DEVICE_SETTING_PATH = '設定 > 我的帳號 > 允許自其他裝置登入';
+/**
+ * The prerequisite as a single line, for texts that report on a login
+ * already in flight (the PIN and cert steps) rather than gating one.
+ */
+const PRIMARY_DEVICE_SETTING_NOTE = `0. This only works if the primary phone has ${PRIMARY_DEVICE_SETTING_PATH} ` +
+    '(Settings > Account > allow logging in from other devices; the label is ' +
+    'localized) enabled — without it LINE will not offer this device a sign-in ' +
+    'prompt at all.\n';
+/**
+ * Step-by-step instructions for turning the setting on, returned when the
+ * human says it is off or that they do not know where it is.
+ */
+const PRIMARY_DEVICE_SETTING_STEPS = 'On the PRIMARY phone (the one already logged in to this LINE account):\n\n' +
+    '1. Open LINE and go to the 主頁 / Home tab.\n' +
+    '2. Tap the gear icon in the top corner to open 設定 (Settings).\n' +
+    '3. Open 我的帳號 (Account).\n' +
+    '4. Turn ON 允許自其他裝置登入 (the toggle allowing login from other ' +
+    'devices — the exact wording is localized).\n\n' +
+    'This toggle is what lets LINE prompt a second device to sign in. With it ' +
+    'off, nothing at all appears on the phone and the login simply never ' +
+    'completes.';
+/** Answers offered by the pre-flight prerequisite check. */
+const PREREQ_ANSWERS = {
+    enabled: 'enabled',
+    notEnabled: 'not_enabled',
+    unsure: 'unsure',
+};
+/**
+ * The prerequisite question, in the 2026-07-28 `oneOf`-with-`title`
+ * single-select shape (`TitledSingleSelectEnumSchema`) so each choice carries
+ * human-facing text of its own, rather than an enum of bare machine values
+ * the client has to render raw.
+ */
+const PREREQ_SCHEMA_PROPERTY = {
+    type: 'string',
+    title: 'Is 允許自其他裝置登入 enabled on your primary phone?',
+    description: `On the phone already logged in to LINE: ${PRIMARY_DEVICE_SETTING_PATH}. ` +
+        'Without it, LINE never prompts this device and the login cannot finish.',
+    oneOf: [
+        { const: PREREQ_ANSWERS.enabled, title: 'Yes — it is already on' },
+        { const: PREREQ_ANSWERS.notEnabled, title: 'No / not yet — show me how' },
+        {
+            const: PREREQ_ANSWERS.unsure,
+            title: "I don't know where that setting is",
+        },
+    ],
+};
+/**
+ * Build the one form shown before a login starts: the prerequisite, plus
+ * `phone`/`region` when the caller did not supply them.
+ *
+ * Both live in ONE form on purpose — the human answers a single prompt, and
+ * the prerequisite is raised while it can still change the outcome.
+ *
+ * @param phone - Phone already supplied by the tool call, if any.
+ * @param region - Region already supplied by the tool call, if any.
+ * @returns The elicitation body, for `elicitInput` or `inputRequired.elicit`.
+ */
+export function buildPreflightForm(phone, region) {
+    const needsCredentials = !phone || !region;
+    const properties = {
+        primaryDeviceLogin: PREREQ_SCHEMA_PROPERTY,
+    };
+    const required = ['primaryDeviceLogin'];
+    if (needsCredentials) {
+        properties.phone = {
+            type: 'string',
+            title: 'Phone number',
+            description: 'E.164 form, e.g. +8869XXXXXXXX.',
+            ...(phone ? { default: phone } : {}),
+        };
+        properties.region = {
+            type: 'string',
+            title: 'Region',
+            enum: LOGIN_REGIONS,
+            ...(region ? { default: region } : {}),
+        };
+        required.push('phone', 'region');
+    }
+    return {
+        message: 'Yomi signs in as a SECOND LINE device. That requires ' +
+            `${PRIMARY_DEVICE_SETTING_PATH} to be enabled on the phone already ` +
+            'logged in — confirm that below' +
+            (needsCredentials
+                ? ', along with your number and region.'
+                : ' before the login starts.'),
+        requestedSchema: { type: 'object', properties, required },
+    };
+}
+/**
+ * Read an accepted pre-flight form back. Shared by every path so the answer
+ * is interpreted identically no matter how it was collected.
+ *
+ * @param content - The accepted form content (untrusted client input).
+ * @param phone - Phone supplied by the tool call, used when the form did not
+ * carry the field because it was already known.
+ * @param region - Region, same rule.
+ * @returns What the login should do next.
+ */
+export function readPreflightForm(content, phone, region) {
+    const answer = String(content?.primaryDeviceLogin ?? '');
+    if (answer !== PREREQ_ANSWERS.enabled) {
+        return { ok: false, reason: 'prerequisite', answer };
+    }
+    const collectedPhone = String(content?.phone ?? phone ?? '');
+    const collectedRegion = String(content?.region ?? region ?? '');
+    if (!collectedPhone || !collectedRegion) {
+        return { ok: false, reason: 'cancelled' };
+    }
+    return { ok: true, phone: collectedPhone, region: collectedRegion };
+}
+/**
+ * The numbered steps for acting on an issued PIN. Step 0 repeats the
+ * prerequisite even though the pre-flight form already asked about it: a
+ * human who answered "yes" without checking finds out here, while the code
+ * is still valid.
+ *
+ * @param pin - The PIN LINE just issued.
+ * @returns The steps, ending in a blank line.
+ */
+export function pinSteps(pin) {
+    const lifetimeSeconds = Math.round(LINE_PIN_CODE_LIFETIME_MS / 1000);
+    return (`LINE PIN:\n\n    ${pin}\n\n` +
+        PRIMARY_DEVICE_SETTING_NOTE +
+        '1. Open LINE on the primary phone. If a verification prompt does not ' +
+        'appear immediately, bringing the app to the foreground surfaces it.\n' +
+        `2. Enter this PIN and tick the device that is signing in, then tap ` +
+        `「用戶確認」 — LINE gives you ${lifetimeSeconds} seconds (about 3 ` +
+        'minutes) from when the code was shown to do this.\n' +
+        '3. LINE will then ask that same phone to approve this new device ' +
+        'signing in — approve it there.\n\n');
+}
+/**
+ * The steps when a stored login certificate skipped the PIN entirely — the
+ * flow is already waiting on phone approval of this device.
+ *
+ * @returns The steps, ending in a blank line.
+ */
+export function certSteps() {
+    return ('No PIN needed — LINE recognized a stored login certificate from a ' +
+        'previous login, so the PIN step was skipped.\n\n' +
+        PRIMARY_DEVICE_SETTING_NOTE +
+        '1. Bring the LINE app to the foreground on your primary phone — it ' +
+        'should prompt you to approve this new device signing in.\n' +
+        '2. Approve the device from there.\n\n');
+}
+/**
+ * The acknowledgement form shown alongside an issued PIN (or alongside the
+ * cert-skipped approval prompt).
+ *
+ * @param pin - The PIN, or `null` when a stored certificate skipped it.
+ * @returns The elicitation body.
+ */
+export function buildAcknowledgementForm(pin) {
+    return {
+        message: (pin ? pinSteps(pin) : certSteps()) +
+            'Acknowledge below once you have done this.',
+        requestedSchema: {
+            type: 'object',
+            properties: {
+                entered: {
+                    type: 'boolean',
+                    title: pin
+                        ? 'I entered the PIN and approved the device on my phone'
+                        : 'I approved the device on my phone',
+                },
+            },
+        },
+    };
+}
+/**
+ * Build the tool result returned when the human has not confirmed the
+ * prerequisite. Deliberately NOT a tool error: nothing failed, the login was
+ * simply never started, and the human has one concrete thing to do.
+ *
+ * @param answer - Which non-confirming answer they gave, for wording.
+ * @returns MCP tool result carrying the enabling steps and the retry.
+ */
+export function prerequisiteNotMetResult(answer) {
+    const lead = answer === PREREQ_ANSWERS.unsure
+        ? 'Login was not started — here is where that setting lives.\n\n'
+        : 'Login was not started, because LINE would never prompt the phone.\n\n';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: lead +
+                    PRIMARY_DEVICE_SETTING_STEPS +
+                    '\n\nOnce the toggle is on, call `login` again. Relay these steps ' +
+                    'to the human as they are — do not summarize the settings path ' +
+                    'away, it is the whole point.',
+            },
+        ],
+    };
+}

package/dist/mcp/handlers/login-mrtr.js

@@ -0,0 +1,150 @@
+/**
+ * `login` on a MCP 2026-07-28 connection: the multi-round-trip (MRTR) path.
+ *
+ * That revision removed the server→client request channel — `elicitInput`
+ * throws on a modern-era instance before any wire traffic (SDK:
+ * `_assertPushApiInServedEra`, "the 2026-07-28 revision has no server→client
+ * request channel"). The same conversation is instead carried by
+ * `input_required` RESULTS: the handler returns the elicitation it needs,
+ * the client fulfils it through its own `elicitation/create` handler, then
+ * RE-CALLS `login` with the answers in `inputResponses`.
+ *
+ * So this file is ./login.ts's pushed elicitation flow turned inside out —
+ * same three beats, one tool call each:
+ *
+ *   round 1  no responses          → ask the pre-flight form
+ *   round 2  `preflight` answered  → start the login, ask for PIN ack
+ *   round 3  `ack` answered        → await completion, return the profile
+ *
+ * The in-flight login survives between rounds in ./login-session.ts, exactly
+ * as it survives between `login` and `login_complete` on the fallback path.
+ *
+ * `requestState` (the other half of MRTR) is deliberately NOT used: it
+ * round-trips through the client and comes back attacker-controlled, so the
+ * spec requires integrity-protecting anything that influences behavior. The
+ * only state this flow needs is the pending login, which never leaves the
+ * server.
+ */
+import { acceptedContent, inputRequired, inputResponse, } from '@modelcontextprotocol/server';
+import { createCliLogger } from '../../util/log.js';
+import { buildAcknowledgementForm, buildPreflightForm, prerequisiteNotMetResult, readPreflightForm, } from './login-copy.js';
+import { finishPendingLogin, getLivePendingLogin, getPendingLogin, PIN_WAIT_TIMEOUT_MS, startPendingLogin, waitForPin, } from './login-session.js';
+import { jsonText, toolError } from './shared.js';
+const log = createCliLogger('Yomi');
+/** Keys this flow assigns to its embedded input requests. */
+const PREFLIGHT_KEY = 'preflight';
+const ACK_KEY = 'ack';
+/**
+ * Round 3 — the human says they have acted on their phone. Await the login
+ * `startPendingLogin` began in round 2.
+ *
+ * @returns The logged-in profile, or an honest error.
+ */
+async function completeRound() {
+    const pending = getPendingLogin();
+    if (!pending) {
+        return toolError('No login is pending — the attempt this acknowledgement belongs to has already finished or ' +
+            'expired (LINE gives the human about 3 minutes to act on a shown code). Calling `login` ' +
+            'again is safe and starts a fresh attempt.');
+    }
+    try {
+        const { mid, displayName } = await finishPendingLogin(pending);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: jsonText({ loggedIn: true, mid, displayName }),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return toolError(error?.message ?? String(error));
+    }
+}
+/**
+ * Round 2 — the pre-flight form came back accepted and confirming. Start
+ * (or reuse) the passwordless login and ask the human to act on the PIN.
+ *
+ * @param service - LineProtocolService (not yet authenticated).
+ * @param phone - Confirmed phone number.
+ * @param region - Confirmed region code.
+ * @returns An `input_required` result carrying the PIN acknowledgement form,
+ * or an honest error.
+ */
+async function startRound(service, phone, region) {
+    const active = getLivePendingLogin(Date.now());
+    if (active && (active.phone !== phone || active.region !== region)) {
+        // A live login for a DIFFERENT number is still in flight. Never hand
+        // back its PIN under this call's identity. Name nothing sensitive.
+        return toolError('A login for a different phone number is still in progress. Wait for its login code to expire ' +
+            '(LINE gives the human about 3 minutes to act on it) before starting a login for another number.');
+    }
+    const pending = active ?? startPendingLogin(service, phone, region);
+    const pin = await waitForPin(pending, PIN_WAIT_TIMEOUT_MS);
+    if (!pin && !pending.certSkippedPin) {
+        return toolError('LINE has not issued a login PIN within 20s. The attempt is still running in the background ' +
+            '(do not worry, nothing was lost) — call `login` again shortly to check for the PIN.');
+    }
+    log.warn('login.pin', {
+        action: pin ? 'returned_in_input_required' : 'skipped_cert_valid',
+    });
+    // The PIN travels inside the elicitation the client is about to render,
+    // and the login keeps running while the human acts on it — this handler
+    // returns immediately rather than blocking through LINE's ~3-minute
+    // window, so the human's clock starts now and not after a timeout.
+    return inputRequired({
+        inputRequests: {
+            [ACK_KEY]: inputRequired.elicit(buildAcknowledgementForm(pin)),
+        },
+    });
+}
+/**
+ * Handle `login` on a modern-era connection. Which round this call is comes
+ * from the responses it carries: none means round 1.
+ *
+ * @param service - LineProtocolService (not yet authenticated).
+ * @param args - Tool arguments.
+ * @param inputResponses - `ctx.mcpReq.inputResponses` from a retried call.
+ * Untrusted client input — read only through the SDK's response readers.
+ * @returns An `input_required` result, or a terminal tool result.
+ */
+export async function handleLoginMrtr(service, args, inputResponses) {
+    // Round 3 first: a client that accumulates responses across rounds would
+    // send both keys, and the later beat is the one to act on.
+    const ack = inputResponse(inputResponses, ACK_KEY);
+    if (ack.kind === 'elicit') {
+        if (ack.action !== 'accept') {
+            return toolError('Login was cancelled by the user.');
+        }
+        return await completeRound();
+    }
+    const preflight = inputResponse(inputResponses, PREFLIGHT_KEY);
+    if (preflight.kind === 'elicit') {
+        if (preflight.action !== 'accept') {
+            return toolError('Login was cancelled by the user.');
+        }
+        const outcome = readPreflightForm(acceptedContent(inputResponses, PREFLIGHT_KEY), args.phone, args.region);
+        if (!outcome.ok) {
+            if (outcome.reason === 'prerequisite') {
+                log.warn('login.prerequisite', { answer: outcome.answer });
+                return prerequisiteNotMetResult(outcome.answer);
+            }
+            return toolError('Login was cancelled by the user.');
+        }
+        return await startRound(service, outcome.phone, outcome.region);
+    }
+    // Round 1. Persisted credentials still pre-fill the form, so a returning
+    // user only confirms rather than retypes.
+    const phone = args.phone ??
+        (await service.credentialStore?.get?.('line_phone')) ??
+        undefined;
+    const region = args.region ??
+        (await service.credentialStore?.get?.('line_region')) ??
+        undefined;
+    return inputRequired({
+        inputRequests: {
+            [PREFLIGHT_KEY]: inputRequired.elicit(buildPreflightForm(phone, region)),
+        },
+    });
+}

package/dist/mcp/handlers/login-session.js

@@ -0,0 +1,132 @@
+import { runPwlessLogin } from '../../cli/login.js';
+import { LINE_PIN_CODE_LIFETIME_MS } from '../../line/auth/pwless/index.js';
+import { createCliLogger } from '../../util/log.js';
+const log = createCliLogger('Yomi');
+/**
+ * How long a live pending login may be reused by a later `login` call for
+ * the same phone/region, before treating it as stale and starting fresh.
+ *
+ * This is bound to LINE's real PIN code lifetime (~line/auth/pwless/index.ts,
+ * an external fact from LINE Help Center, ~3 minutes) — NOT to how long
+ * yomi's client is willing to keep polling (~16 minutes). A login started
+ * 90 seconds ago is still very much alive and its PIN is still valid; the
+ * only thing that actually kills a pending login early is LINE's own code
+ * expiring, so that is the correct bound for "is this still worth reusing".
+ */
+const PIN_WINDOW_MS = LINE_PIN_CODE_LIFETIME_MS;
+/** How long a `login` call waits for LINE to issue a PIN before giving up. */
+export const PIN_WAIT_TIMEOUT_MS = 20000;
+let pendingLogin = null;
+/** @returns The in-flight login, or null when none is pending. */
+export function getPendingLogin() {
+    return pendingLogin;
+}
+/**
+ * The in-flight login only if it is still worth reusing: started within
+ * LINE's PIN lifetime.
+ *
+ * @param now - Current epoch millis.
+ * @returns The live pending login, or null.
+ */
+export function getLivePendingLogin(now) {
+    if (!pendingLogin) {
+        return null;
+    }
+    return now - pendingLogin.startedAt < PIN_WINDOW_MS ? pendingLogin : null;
+}
+/**
+ * Start a new passwordless login in the background and register it as the
+ * one in-flight pending login.
+ *
+ * The stored promise is the actual `runPwlessLogin` promise, so a later call
+ * can await it and see the real success/failure. A `.catch()` is attached
+ * immediately (its result discarded, not stored) so an abandoned login — one
+ * nobody ever finishes — never surfaces as an unhandled rejection; this does
+ * not affect what `promise` itself resolves/rejects with.
+ *
+ * @param service - LineProtocolService (not yet authenticated).
+ * @param phone - Phone number in E.164 form.
+ * @param region - Region code.
+ * @returns The newly registered pending-login record.
+ */
+export function startPendingLogin(service, phone, region) {
+    let resolvePinReady = () => { };
+    const pinReady = new Promise((resolve) => {
+        resolvePinReady = resolve;
+    });
+    const pending = {
+        phone,
+        region,
+        pin: null,
+        certSkippedPin: false,
+        startedAt: Date.now(),
+        pinReady,
+    };
+    const onPin = (pin) => {
+        pending.pin = pin;
+        resolvePinReady();
+    };
+    const onBiometric = () => {
+        log.warn('login.waiting_biometric', {
+            action: 'approve the new device on your phone',
+        });
+        // Reaching biometric wait with no PIN ever set means a valid stored
+        // certificate skipped the PIN step entirely (see LinePwlessLogin.login,
+        // step 2-3) — resolve `pinReady` now so `waitForPin` doesn't block out
+        // its full timeout waiting for a PIN that will never arrive.
+        if (!pending.pin) {
+            pending.certSkippedPin = true;
+            resolvePinReady();
+        }
+    };
+    const promise = runPwlessLogin(service, phone, region, {
+        onPin,
+        onWaitingBiometric: onBiometric,
+    });
+    promise.catch(() => {
+        // Swallow here only to prevent an unhandled-rejection warning for a
+        // login nobody completes; the real error still surfaces to whoever
+        // awaits `promise` below.
+    });
+    pending.promise = promise;
+    pendingLogin = pending;
+    return pendingLogin;
+}
+/**
+ * Wait for a pending login's PIN to arrive, bounded by a timeout.
+ *
+ * @param pending - The pending login to wait on.
+ * @param timeoutMs - Maximum time to wait.
+ * @returns The PIN, or `null` if it did not arrive within `timeoutMs` (also
+ * the answer when a stored certificate skipped the PIN — check
+ * `certSkippedPin` to tell the two apart).
+ */
+export async function waitForPin(pending, timeoutMs) {
+    if (pending.pin) {
+        return pending.pin;
+    }
+    return await Promise.race([
+        pending.pinReady.then(() => pending.pin ?? null),
+        new Promise((resolve) => {
+            setTimeout(() => resolve(null), timeoutMs);
+        }),
+    ]);
+}
+/**
+ * Await the in-flight login to completion and clear it either way. Never
+ * touches credentials on the failure path — `runPwlessLogin` owns that.
+ *
+ * @param pending - The pending login to finish.
+ * @returns The logged-in profile.
+ * @throws Whatever `runPwlessLogin` failed with.
+ */
+export async function finishPendingLogin(pending) {
+    try {
+        const result = await pending.promise;
+        log.info('login.complete', { mid: result.mid });
+        return result;
+    }
+    finally {
+        pendingLogin = null;
+    }
+}