dsh-cherry-bridge 0.2.0 → 0.2.1

package/ui/src/App.tsx

@@ -20,8 +20,9 @@ import { useCallback, useEffect, useMemo, useState } from 'react'
 import { DeviceCard } from './DeviceCard'
 import { PairingWizard } from './PairingWizard'
 import { ToolScopePanel } from './ToolScopePanel'
-import { listDevices } from './api'
+import { REQUEST_TIMEOUT, listDevices } from './api'
 import { useT } from './i18n'
+import type { T } from './i18n'
 import { API_BASE } from './types'
 import type {
   DeviceState,
@@ -40,6 +41,8 @@ export interface AppProps {
   eventSourceFactory?: EventSourceFactory
   /** Transient verification-code lifetime, forwarded to the wizard. */
   codeLifetimeMs?: number
+  /** Run deadline (the exit for a lost terminal frame), forwarded to the wizard. */
+  runLifetimeMs?: number
   /**
    * The scope panel's HTTP seam. Defaults to the real same-origin client;
    * injected by tests in the same style as `eventSourceFactory`, so no test has
@@ -69,6 +72,19 @@ const defaultEventSourceFactory: EventSourceFactory = (url) => {
  */
 const EVENT_SOURCE_UNAVAILABLE = 'event-source-unavailable'
 
+/**
+ * One description for a cause, shared by the two catches below so they cannot
+ * drift. Two markers get the dictionary's own sentence — the missing
+ * `EventSource` and a request that never answered (`api.ts`'s ceiling) — because
+ * both are INTERNAL tokens that must never render; everything else is the
+ * foreign message, interpolated verbatim as data.
+ */
+function describeCause(t: T, cause: unknown): string {
+  if (cause instanceof Error && cause.message === EVENT_SOURCE_UNAVAILABLE) return t('app.eventSourceUnavailable')
+  if (cause instanceof Error && cause.message === REQUEST_TIMEOUT) return t('app.error.timeout')
+  return cause instanceof Error ? cause.message : String(cause)
+}
+
 /** Parses one SSE frame payload, ignoring a malformed one rather than crashing. */
 function parseFrame<T>(data: string): T | undefined {
   try {
@@ -81,6 +97,7 @@ function parseFrame<T>(data: string): T | undefined {
 export function App({
   eventSourceFactory = defaultEventSourceFactory,
   codeLifetimeMs,
+  runLifetimeMs,
   scopeClient,
 }: AppProps): ReturnType<typeof Object> {
   const t = useT()
@@ -101,13 +118,7 @@ export function App({
       // The opener's own token means "no EventSource here", which has a
       // sentence of its own in both dictionaries; anything else is a foreign
       // message and is interpolated verbatim (data, not copy).
-      setError(
-        cause instanceof Error && cause.message === EVENT_SOURCE_UNAVAILABLE
-          ? t('app.eventSourceUnavailable')
-          : cause instanceof Error
-            ? cause.message
-            : String(cause),
-      )
+      setError(describeCause(t, cause))
       return undefined
     }
 
@@ -142,7 +153,7 @@ export function App({
         setError(undefined)
       },
       (cause: unknown) => {
-        setError(cause instanceof Error ? cause.message : String(cause))
+        setError(describeCause(t, cause))
         setListed(true)
       },
     )
@@ -211,6 +222,7 @@ export function App({
         subscribed={subscribed}
         progress={progress}
         {...(codeLifetimeMs === undefined ? {} : { codeLifetimeMs })}
+        {...(runLifetimeMs === undefined ? {} : { runLifetimeMs })}
         onRunStart={startRun}
         onSettled={onSettled}
       />
@@ -221,7 +233,11 @@ export function App({
 
       <section className="cherry-panel" aria-labelledby="cherry-devices-title">
         <h3 id="cherry-devices-title">{t('app.devices.heading')}</h3>
-        {sorted.length === 0 && (
+        {/* Three states, not two: the list is EMPTY only once a read said so.
+            After a failed read it is UNKNOWN, and claiming 「暂无已配对设备」 beside
+            the error that says the read failed would contradict that error — so the
+            error line speaks alone. */}
+        {sorted.length === 0 && error === undefined && (
           <p className="cherry-hint">{listed ? t('app.devices.empty') : t('app.devices.loading')}</p>
         )}
         <ul className="cherry-cards">

package/ui/src/DeviceCard.tsx

@@ -10,10 +10,20 @@
  * `onSaved`, so the card shows what the archive holds rather than what the
  * browser hoped for. The live `state` keeps coming from SSE; the patch response
  * only seeds it.
+ *
+ * The addresses row is also where an address is FORGOTTEN (issue #204), and the
+ * marks it leaves are listed under their own label with a 恢复 each. One click
+ * is one committed action, never a draft: the two controls are INERT while the
+ * address editor is open, because that form PATCHes the whole host list and its
+ * draft is unconditionally sacred (see the resync effect) — a mark chosen
+ * underneath it would be re-sent by the next 保存地址, and the PATCH that names a
+ * forgotten host clears its mark in the same write. Freezing the controls is
+ * what keeps "commit or discard the edit first" true; it is not a stylistic
+ * preference.
  */
 import { useEffect, useState } from 'react'
 import type { ChangeEvent, FormEvent } from 'react'
-import { patchDevice, removeDevice } from './api'
+import { ApiError, REQUEST_TIMEOUT, forgetHosts, patchDevice, rememberHosts, removeDevice } from './api'
 import { useT } from './i18n'
 import { STATE_KEYS } from './types'
 import type { DeviceState, DeviceSummary } from './types'
@@ -98,19 +108,63 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
     setPortText(String(device.port))
   }, [device.displayName, device.hosts, device.port, editor])
 
-  /** Runs one mutation, mapping a refusal into the card's error line. */
+  /**
+   * Runs one mutation, mapping a refusal into the card's error line.
+   *
+   * A request that never answered arrives as `api.ts`'s internal marker — the
+   * page-wide ceiling (issue #180) — and a marker must never render. Every card
+   * action is a bounded call (停用 / 重命名 / 移除 are PATCH or DELETE), so this
+   * surface translates it like the other three do instead of echoing
+   * `cherry-remote.request-timeout` onto the page.
+   */
   const run = async (action: () => Promise<void>): Promise<void> => {
     setBusy(true)
     setError(undefined)
     try {
       await action()
     } catch (cause) {
-      setError(cause instanceof Error ? cause.message : String(cause))
+      setError(describeCause(cause))
     } finally {
       setBusy(false)
     }
   }
 
+  /**
+   * One refusal for a cause, so the two markers and the one translated code
+   * cannot drift between this card's arms.
+   *
+   * `ApiError` renders as `<code>: <server message>`, which is right for a
+   * diagnostic and wrong for `last-address`: forgetting the only candidate is a
+   * thing the operator can fix here, and the server's own prose is English on a
+   * Chinese page. Everything else keeps the server's verdict verbatim — that is
+   * what tells `invalid-payload` from `unreachable`.
+   */
+  const describeCause = (cause: unknown): string => {
+    if (cause instanceof ApiError && cause.code === 'last-address') return t('device.error.lastAddress')
+    if (cause instanceof Error && cause.message === REQUEST_TIMEOUT) return t('device.error.timeout')
+    return cause instanceof Error ? cause.message : String(cause)
+  }
+
+  /** Forgets ONE address: the store drops it and records the mark in one write. */
+  const forget = (host: string): void => {
+    void run(async () => {
+      onSaved(await forgetHosts(device.deviceId, [host]))
+    })
+  }
+
+  /**
+   * Lifts ONE mark. The server also drops the pooled connection on a change, so
+   * the very handshake that follows re-learns the address if the desktop still
+   * advertises it — without that, a desktop that stays connected would not
+   * re-handshake for as long as the link holds, and this button would look
+   * inert.
+   */
+  const remember = (host: string): void => {
+    void run(async () => {
+      onSaved(await rememberHosts(device.deviceId, [host]))
+    })
+  }
+
   const toggleEnabled = (): void => {
     const enabled = !device.enabled
     void run(async () => {
@@ -157,6 +211,14 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
     })
   }
 
+  /**
+   * A defensive empty list, the same choice `dialPort` makes for the required
+   * `ports` map: `GET /devices` always emits the key, but this card is one row
+   * in a list, and a record missing one field must not take the whole page down
+   * with a render throw — it shows a card without the mark instead.
+   */
+  const forgottenHosts = device.forgottenHosts ?? []
+
   // The record-level `port` alone would claim every host dials it, which is
   // false for a record whose map disagrees. `mixedPorts` decides whether the
   // card has anything to say beyond that single number; `addressList` is the
@@ -203,7 +265,45 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
 
       <dl className="cherry-card-facts">
         <dt>{t('device.field.addresses')}</dt>
-        <dd>{device.hosts.join(', ')}</dd>
+        <dd>
+          <ul className="cherry-address-list">
+            {device.hosts.map((host) => (
+              <li key={host}>
+                <span>{host}</span>
+                <button
+                  type="button"
+                  onClick={() => forget(host)}
+                  disabled={busy || editor === 'address'}
+                >
+                  {t('device.forget')}
+                </button>
+              </li>
+            ))}
+          </ul>
+        </dd>
+        {/* Only when the archive actually holds a mark: an empty row on every
+            card would be noise, and absence is the honest "none". */}
+        {forgottenHosts.length > 0 && (
+          <>
+            <dt>{t('device.field.forgotten')}</dt>
+            <dd>
+              <ul className="cherry-address-list">
+                {forgottenHosts.map((host) => (
+                  <li key={host}>
+                    <span>{host}</span>
+                    <button
+                      type="button"
+                      onClick={() => remember(host)}
+                      disabled={busy || editor === 'address'}
+                    >
+                      {t('device.remember')}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            </dd>
+          </>
+        )}
         <dt>{t('device.field.port')}</dt>
         <dd>{device.port}</dd>
         {mixedPorts && (
@@ -216,6 +316,8 @@ export function DeviceCard({ device, state, onSaved, onRemoved }: DeviceCardProp
         <dd className="cherry-mono">{device.deviceId}</dd>
       </dl>
 
+      {forgottenHosts.length > 0 && <p className="cherry-hint">{t('device.forgotten.hint')}</p>}
+
       {mixedPorts && <p className="cherry-hint">{t('device.ports.hint')}</p>}
 
       {editor === 'rename' && (

package/ui/src/PairingWizard.tsx

@@ -16,7 +16,7 @@
  */
 import { useEffect, useState } from 'react'
 import type { ChangeEvent, FormEvent } from 'react'
-import { startPairing } from './api'
+import { REQUEST_TIMEOUT, startPairing } from './api'
 import { useT } from './i18n'
 import { APPROVED_STAGE, STAGE_KEYS, TERMINAL_STAGES, VERIFICATION_CODE_STAGE } from './types'
 import type { PairingPhase, PairingProgressEvent } from './types'
@@ -24,6 +24,28 @@ import type { PairingPhase, PairingProgressEvent } from './types'
 /** The countdown the transient code display gets, in seconds. */
 export const DEFAULT_CODE_LIFETIME_MS = 120_000
 
+/**
+ * How long one run may sit in `waiting` before the wizard gives the form back.
+ *
+ * The server publishes a terminal stage on EVERY outcome (`src/httpApi.ts`
+ * `startPairing`), but the event stream carries no replay, so a single dropped
+ * frame loses the verdict for good — and nothing else clears `busy`: only a
+ * terminal frame or a refused POST does, and there is no cancel control. Without
+ * this bound a lost frame parks the wizard on 「配对进行中」 until a page reload.
+ *
+ * The bound must be comfortably past a REALISTIC live run: `src/pairing.ts`
+ * bounds the candidate walk to 30 s (`dialBudgetMs`) and the claim/poll phase to
+ * a FRESH 120 s anchored at the claim, so 150 s plus 30 s of margin.
+ *
+ * It is NOT past a pathological one, and it says so rather than pretending: two
+ * round trips inside that walk (`hello`, then the claim) are bounded only by
+ * JsonRpcClient's 60 s default request timeout, so a peer that stalls each just
+ * under it can keep a run legitimately working for ~270 s. A premature alarm is
+ * acceptable because it is not a verdict — it points at the device list, and a
+ * terminal frame arriving later replaces it (see `claimId` below).
+ */
+export const DEFAULT_RUN_LIFETIME_MS = 180_000
+
 export interface PairingWizardProps {
   /** True while a stream is open; submitting with no stream would lose the code. */
   subscribed: boolean
@@ -31,6 +53,8 @@ export interface PairingWizardProps {
   progress: PairingProgressEvent | undefined
   /** How long the verification code stays on screen. Injectable for tests. */
   codeLifetimeMs?: number
+  /** How long a run may wait for its terminal frame. Injectable for tests. */
+  runLifetimeMs?: number
   /**
    * Called when a NEW run is submitted, before `POST /pair`: the app retires the
    * previous run's frame here, so the settled render never has to compete with a
@@ -45,6 +69,7 @@ export function PairingWizard({
   subscribed,
   progress,
   codeLifetimeMs = DEFAULT_CODE_LIFETIME_MS,
+  runLifetimeMs = DEFAULT_RUN_LIFETIME_MS,
   onRunStart,
   onSettled,
 }: PairingWizardProps): ReturnType<typeof Object> {
@@ -66,6 +91,11 @@ export function PairingWizard({
   // unreachable. The verdict must be an INPUT to the settled render rather than
   // derived from a frame that is being cleared underneath it.
   const [verdict, setVerdict] = useState<string | undefined>(undefined)
+  // Set ONLY by the run deadline: `phase === 'failed'` with no stage behind it.
+  // Its own flag rather than an empty verdict, because the settled paragraph must
+  // NOT read as a verdict — the run may have been approved while its frame was
+  // lost, and the device list right below would contradict a "配对失败".
+  const [timedOut, setTimedOut] = useState(false)
 
   const stage = progress?.stage
   const frameClaimId = progress?.claimId
@@ -94,6 +124,10 @@ export function PairingWizard({
     // Terminal frame: the code is a transient display and goes away with it.
     if ((TERMINAL_STAGES as readonly string[]).includes(stage)) {
       setCode(undefined)
+      // A LATE frame outranks the deadline: `POST /pair` is fire-and-forget, so a
+      // frame can still arrive after the run deadline and the stage it carries is
+      // the truth — retiring the flag here is what lets that copy win the render.
+      setTimedOut(false)
       // Capture FIRST: `onSettled` is the app's chance to clear the frame, and
       // everything below must already be independent of it.
       setVerdict(stage)
@@ -111,6 +145,28 @@ export function PairingWizard({
     return () => clearTimeout(timer)
   }, [code, codeLifetimeMs])
 
+  useEffect(() => {
+    if (phase !== 'waiting') return undefined
+    // The countdown above bounds the CODE DISPLAY; this bounds the RUN. Same
+    // failure mode, different casualty: the code goes away on time, but `busy`
+    // would stay true forever and leave the submit button disabled with no
+    // cancel control. Everything the terminal branch does to the form is done
+    // here too, minus the verdict — and `claimId` is deliberately KEPT, so a
+    // terminal frame that arrives after the deadline still replaces this message
+    // with the truth instead of being filtered out as a stranger's.
+    const timer = setTimeout(() => {
+      setCode(undefined)
+      setTimedOut(true)
+      setPhase('failed')
+      setBusy(false)
+      // The same callback a terminal frame runs: it re-reads the device list,
+      // which is what makes "look below" honest — an approved pairing whose
+      // frame was lost shows up there.
+      onSettled?.()
+    }, runLifetimeMs)
+    return () => clearTimeout(timer)
+  }, [phase, runLifetimeMs, onSettled])
+
   const submit = (event: FormEvent): void => {
     event.preventDefault()
     const trimmed = payload.trim()
@@ -126,6 +182,7 @@ export function PairingWizard({
     // when the frame arrives. Clearing it at start (rather than relying on the
     // frame going away) keeps the settled paragraph correct for exactly one run.
     setVerdict(undefined)
+    setTimedOut(false)
     // ...and the APP retires the previous run's frame here rather than on settle,
     // so a batched terminal commit cannot take the label away with it.
     onRunStart?.()
@@ -137,7 +194,20 @@ export function PairingWizard({
       (cause: unknown) => {
         // A refusal leaves the wizard open with the payload intact: the user
         // fixes the paste rather than starting over.
-        setError(cause instanceof Error ? cause.message : String(cause))
+        //
+        // A HUNG request is not a refusal the user can read: its marker is an
+        // internal token, so it becomes the dictionary's own sentence (the same
+        // split as `app.eventSourceUnavailable`). Everything else is the
+        // server's or the transport's message, interpolated verbatim. The
+        // ceiling lives in `api.ts` `request()`, so the token is shared with the
+        // other surfaces; only this catch can see it for the pairing POST.
+        setError(
+          cause instanceof Error && cause.message === REQUEST_TIMEOUT
+            ? t('wizard.error.timeout')
+            : cause instanceof Error
+              ? cause.message
+              : String(cause),
+        )
         setPhase('idle')
         setBusy(false)
       },
@@ -206,9 +276,14 @@ export function PairingWizard({
           paragraph renders (see the `verdict` state above). */}
       {phase === 'failed' && (
         <p className="cherry-error" role="alert">
-          {t('wizard.failed', {
-            stage: STAGE_KEYS[verdict ?? ''] === undefined ? t('wizard.unknownError') : t(STAGE_KEYS[verdict ?? '']!),
-          })}
+          {timedOut
+            ? t('wizard.timedOut')
+            : t('wizard.failed', {
+                stage:
+                  STAGE_KEYS[verdict ?? ''] === undefined
+                    ? t('wizard.unknownError')
+                    : t(STAGE_KEYS[verdict ?? '']!),
+              })}
         </p>
       )}
       {error !== undefined && (

package/ui/src/ToolScopePanel.tsx

@@ -29,7 +29,7 @@
  * no tools" that changes nothing and triggers no write.
  */
 import { useCallback, useEffect, useMemo, useState } from 'react'
-import { ApiError, defaultScopeClient } from './api'
+import { ApiError, REQUEST_TIMEOUT, defaultScopeClient } from './api'
 import { useT } from './i18n'
 import type { T } from './i18n'
 import type {
@@ -148,7 +148,20 @@ interface SaveFailure {
   detail?: string
 }
 
-const describeCause = (cause: unknown): string => (cause instanceof Error ? cause.message : String(cause))
+/**
+ * The panel's own description of a failure.
+ *
+ * A request that never answered arrives as `api.ts`'s internal marker (the
+ * page-wide ceiling, issue #180), which must become a sentence before it reaches
+ * any of the three places this feeds — the read error, the save failure and the
+ * re-read error. Everything else is the server's own message, interpolated.
+ */
+const describeCause = (t: T, cause: unknown): string =>
+  cause instanceof Error && cause.message === REQUEST_TIMEOUT
+    ? t('scope.error.timeout')
+    : cause instanceof Error
+      ? cause.message
+      : String(cause)
 
 /**
  * D11's empty state for the current draft, or `undefined` when nothing may be
@@ -227,7 +240,7 @@ export function ToolScopePanel({ client = defaultScopeClient }: ToolScopePanelPr
         seedFromDocument(response)
       },
       (cause: unknown) => {
-        if (live) setLoadError(describeCause(cause))
+        if (live) setLoadError(describeCause(t, cause))
       },
     )
     return () => {
@@ -310,8 +323,8 @@ export function ToolScopePanel({ client = defaultScopeClient }: ToolScopePanelPr
           // An unknown code therefore falls to `SAVE_FAILED_KEY`'s template with
           // `{cause}` filled, not to a bare `保存失败：`.
           label: code === undefined
-            ? t(SAVE_FAILED_KEY, { cause: describeCause(cause) })
-            : t(SAVE_FAILURE_KEYS[code] ?? SAVE_FAILED_KEY, { cause: describeCause(cause) }),
+            ? t(SAVE_FAILED_KEY, { cause: describeCause(t, cause) })
+            : t(SAVE_FAILURE_KEYS[code] ?? SAVE_FAILED_KEY, { cause: describeCause(t, cause) }),
           detail: status === undefined ? undefined : t('scope.serverSaid', { code: code!, status }),
         })
       },
@@ -344,7 +357,7 @@ export function ToolScopePanel({ client = defaultScopeClient }: ToolScopePanelPr
       },
       (cause: unknown) => {
         setBusy(false)
-        setLoadError(describeCause(cause))
+        setLoadError(describeCause(t, cause))
       },
     )
   }, [client, seedFromDocument])

package/ui/src/api.ts

@@ -34,6 +34,35 @@ export class ApiError extends Error {
   }
 }
 
+/**
+ * The marker a request that never answered throws with.
+ *
+ * Internal token, NEVER copy: each surface renders its own sentence for it —
+ * `app.error.timeout`, `wizard.error.timeout`, `scope.error.timeout` — and this
+ * string only travels from `request()` to the catch block that recognizes it, the
+ * same split as `app.eventSourceUnavailable` (see `App.tsx`). That is what keeps
+ * an English literal off a Chinese page.
+ */
+export const REQUEST_TIMEOUT = 'cherry-remote.request-timeout'
+
+/**
+ * How long ANY call on this page may stay open, in milliseconds.
+ *
+ * None of these calls is slow: they are same-origin requests to the plugin's own
+ * HTTP face, and the one that looks slowest — a pairing START — does no I/O
+ * before it answers (`src/httpApi.ts` `startPairing` writes its 202 at once).
+ * A request still open after this long is a WEDGED transport, not a busy server,
+ * and it must not be allowed to strand a control: without a ceiling the pairing
+ * wizard's submit button (issue #173), a device card's buttons, the scope panel's
+ * save and the device list's "loading" state each wait for the life of the page
+ * (issue #180).
+ *
+ * So the ceiling lives in `request()`, where every call passes, rather than on
+ * one call site. Each surface turns the {@link REQUEST_TIMEOUT} marker into its
+ * own sentence.
+ */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 10_000
+
 /** Reads a JSON body without throwing on an empty (204) or non-JSON response. */
 async function readBody(response: Response): Promise<unknown> {
   const text = await response.text()
@@ -45,19 +74,41 @@ async function readBody(response: Response): Promise<unknown> {
   }
 }
 
-async function request(url: string, init?: RequestInit): Promise<unknown> {
-  const response = await fetch(url, {
-    ...init,
-    headers: { 'content-type': 'application/json', ...(init?.headers ?? {}) },
-  })
-  const body = await readBody(response)
-  if (!response.ok) {
-    const record = (body ?? {}) as { error?: unknown; message?: unknown }
-    const code = typeof record.error === 'string' ? record.error : `http-${response.status}`
-    const message = typeof record.message === 'string' ? record.message : code
-    throw new ApiError(response.status, code, message)
+/**
+ * One bounded request. `timeoutMs` exists so a test can prove the ceiling
+ * without waiting for it; production always takes {@link DEFAULT_REQUEST_TIMEOUT_MS}.
+ */
+async function request(
+  url: string,
+  init?: RequestInit,
+  timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+): Promise<unknown> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetch(url, {
+      ...init,
+      headers: { 'content-type': 'application/json', ...(init?.headers ?? {}) },
+      // We own this signal: no caller supplies one. An abort tears the body read
+      // down with the transport, which is why it sits inside the same `try`.
+      signal: controller.signal,
+    })
+    const body = await readBody(response)
+    if (!response.ok) {
+      const record = (body ?? {}) as { error?: unknown; message?: unknown }
+      const code = typeof record.error === 'string' ? record.error : `http-${response.status}`
+      const message = typeof record.message === 'string' ? record.message : code
+      throw new ApiError(response.status, code, message)
+    }
+    return body
+  } catch (cause) {
+    // An abort THIS function caused. A refusal arrives with the signal still
+    // clear and keeps its `ApiError` code, so nothing is masked as a timeout.
+    if (controller.signal.aborted) throw new Error(REQUEST_TIMEOUT)
+    throw cause
+  } finally {
+    clearTimeout(timer)
   }
-  return body
 }
 
 /** `GET /devices` — the full card list, states projected server-side. */
@@ -72,12 +123,22 @@ export async function listDevices(): Promise<DeviceSummary[]> {
  * It deliberately does NOT wait for approval: the 6-digit code and the verdict
  * arrive as `pairing-progress` SSE frames, which is why the caller must already
  * be subscribed when this resolves.
+ *
+ * Bounded like every other call (see {@link DEFAULT_REQUEST_TIMEOUT_MS});
+ * `timeoutMs` exists only so a test can prove the ceiling without waiting.
  */
-export async function startPairing(payload: string, name?: string): Promise<{ claimId?: string }> {
-  const body = await request(`${API_BASE}/pair`, {
-    method: 'POST',
-    body: JSON.stringify(name === undefined || name === '' ? { payload } : { payload, name }),
-  })
+export async function startPairing(
+  payload: string,
+  options: { name?: string; timeoutMs?: number } = {},
+): Promise<{ claimId?: string }> {
+  const { name } = options
+  // `undefined` deliberately falls through to `request`'s own default, so the
+  // production ceiling is exercised by the same parameter every other call uses.
+  const body = await request(
+    `${API_BASE}/pair`,
+    { method: 'POST', body: JSON.stringify(name === undefined || name === '' ? { payload } : { payload, name }) },
+    options.timeoutMs,
+  )
   return (body ?? {}) as { claimId?: string }
 }
 
@@ -90,6 +151,39 @@ export async function patchDevice(deviceId: string, patch: DevicePatch): Promise
   return body as DeviceSummary
 }
 
+/**
+ * `POST /devices/:id/forget` — stop dialing these addresses AND record them so
+ * the desktop cannot advertise them back (issue #185).
+ *
+ * The answer is the SAME record shape {@link patchDevice} returns, which is why
+ * the card hands either body to the same `onSaved`. The action is its own
+ * request on purpose: folding it into the PATCH would make "replace the dial
+ * list" and "forget one address" one body with an ordering to define.
+ */
+export async function forgetHosts(deviceId: string, hosts: string[]): Promise<DeviceSummary> {
+  const body = await request(`${API_BASE}/devices/${encodeURIComponent(deviceId)}/forget`, {
+    method: 'POST',
+    body: JSON.stringify({ hosts }),
+  })
+  return body as DeviceSummary
+}
+
+/**
+ * `POST /devices/:id/remember` — lift the marks.
+ *
+ * It does NOT dial the address again: the record's `hosts` is untouched, and
+ * the address returns when the desktop next advertises it. Putting it back into
+ * the dial list immediately stays the PATCH's job (that PATCH clears the mark in
+ * the same write).
+ */
+export async function rememberHosts(deviceId: string, hosts: string[]): Promise<DeviceSummary> {
+  const body = await request(`${API_BASE}/devices/${encodeURIComponent(deviceId)}/remember`, {
+    method: 'POST',
+    body: JSON.stringify({ hosts }),
+  })
+  return body as DeviceSummary
+}
+
 /** `DELETE /devices/:id` — 204, no body. */
 export async function removeDevice(deviceId: string): Promise<void> {
   await request(`${API_BASE}/devices/${encodeURIComponent(deviceId)}`, { method: 'DELETE' })