dsh-cherry-bridge 0.2.0 → 0.2.1

package/src/httpApi.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto'
-import { QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
+import { LastCandidateHostError, QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
 import type { DeviceRecord } from './deviceStore.js'
 import type { DeviceStore } from './deviceStore.js'
 import type { DeviceState, EffectiveLimits } from './connection.js'
@@ -119,6 +119,14 @@ export interface DeviceSummary {
   security: Record<string, 'ws' | 'wss'>
   /** The port each host is dialed with (issue #135); see `DeviceRecord`. */
   ports: Record<string, number>
+  /**
+   * The addresses the operator has forgotten (issue #185): not dialed, and not
+   * re-learned until `cherry_devices` remembers them (or a PATCH puts one back
+   * into `hosts`, which clears its mark). Reported beside the address maps for
+   * the same reason they are: it is archive state an operator edits, not a
+   * credential.
+   */
+  forgottenHosts: string[]
 }
 
 /** The `device-state` SSE payload. */
@@ -592,11 +600,17 @@ function parsePatch(body: Record<string, unknown>): DevicePatch {
       if (typeof entry !== 'string') throw new PatchError('hosts entries must be strings')
       return normalizeHost(entry)
     })
-    // Checked AFTER normalization: `[::1]` and `::1` collapse to one host. The
-    // scheme/port maps are keyed by host, so a duplicate has no single entry
-    // and silently last-wins — an ambiguous record, not an edit.
-    if (new Set(patch.hosts).size !== patch.hosts.length) {
-      throw new PatchError('hosts must not contain duplicates')
+    // Checked AFTER normalization: `[::1]` and `::1` collapse to one host, and
+    // host comparison is CASE-INSENSITIVE everywhere else on this face (the
+    // learn merge, the forget/remember matching, the mark clearing), so
+    // `NAS.example` and `nas.example` are one address too. The scheme/port maps
+    // are keyed by host, so a duplicate has no single entry and silently
+    // last-wins — an ambiguous record, not an edit.
+    const seen = new Set<string>()
+    for (const host of patch.hosts) {
+      const key = host.toLowerCase()
+      if (seen.has(key)) throw new PatchError('hosts must not contain duplicates')
+      seen.add(key)
     }
   }
 
@@ -1017,6 +1031,28 @@ async function handleRequest(req: HttpRequestLike, res: HttpResponseLike, route:
       return
     }
 
+    // The two endpoint actions (issue #204) sit UNDER the device resource
+    // because that is what they act on: they are the page's door onto #185's
+    // forget/remember, one action per request, so a "patch AND forget" body
+    // with a contradictory ordering never exists.
+    if (first === 'devices' && match.segments.length === 3 && second !== undefined) {
+      const deviceId = decodeSegment(second)
+      if (deviceId === undefined) {
+        writeError(res, 400, 'invalid-request', 'device id is not valid URL encoding')
+        return
+      }
+      const action = match.segments[2]
+      if (action !== 'forget' && action !== 'remember') {
+        writeError(res, 404, 'not-found', 'unknown route')
+        return
+      }
+      if (method !== 'POST') {
+        writeError(res, 405, 'method-not-allowed', 'POST only')
+        return
+      }
+      return await changeEndpoints(req, res, route, deviceId, action)
+    }
+
     if (first === 'pair' && match.segments.length === 1) {
       if (method !== 'POST') {
         writeError(res, 405, 'method-not-allowed', 'POST only')
@@ -1071,7 +1107,23 @@ async function handleRequest(req: HttpRequestLike, res: HttpResponseLike, route:
 }
 
 function listDevices(res: HttpResponseLike, route: RouteContext): void {
-  const devices: DeviceSummary[] = route.deps.store.list().map((device) => ({
+  writeJson(
+    res,
+    200,
+    route.deps.store.list().map((device) => deviceSummary(route, device)),
+  )
+}
+
+/**
+ * One device as the browser sees it: the public archive projection, never a
+ * credential.
+ *
+ * ONE builder, because FOUR faces answer this shape — `GET /devices`, the
+ * `PATCH`, and the two endpoint actions of issue #204 — and a hand-written copy
+ * per face is how a field ends up on one and not the others.
+ */
+function deviceSummary(route: RouteContext, device: DeviceRecord): DeviceSummary {
+  return {
     deviceId: device.deviceId,
     displayName: device.displayName,
     state: projectState(device, route.deps.connect),
@@ -1080,8 +1132,10 @@ function listDevices(res: HttpResponseLike, route: RouteContext): void {
     port: device.port,
     security: { ...device.security },
     ports: { ...device.ports },
-  }))
-  writeJson(res, 200, devices)
+    // An empty list is the honest "none", not an absent key: the page renders
+    // the forgotten row only when it is non-empty.
+    forgottenHosts: [...(device.forgottenHosts ?? [])],
+  }
 }
 
 /**
@@ -1407,8 +1461,20 @@ async function patchDevice(
       : patch.hosts === undefined
         ? previousPorts
         : portsFor(patch.hosts, previousPorts, previousPort)
+  // A host the operator puts BACK into `hosts` is dialed again, so its forget
+  // mark must go: `hosts` and `forgottenHosts` are disjoint by contract, and an
+  // explicit list is intent to dial. A PATCH that does not touch `hosts`
+  // (displayName/enabled/port) leaves every mark alone. Case-insensitive, the
+  // same comparison the learn merge uses.
+  const nextForgotten =
+    patch.hosts === undefined || existing.forgottenHosts === undefined
+      ? undefined
+      : existing.forgottenHosts.filter(
+          (host) => !patch.hosts!.some((nextHost) => nextHost.toLowerCase() === host.toLowerCase()),
+        )
   const next: DeviceRecord = {
     ...existing,
+    ...(nextForgotten === undefined ? {} : { forgottenHosts: nextForgotten }),
     ...(patch.displayName === undefined ? {} : { displayName: patch.displayName }),
     ...(patch.enabled === undefined ? {} : { enabled: patch.enabled }),
     // hosts is WHOLE-REPLACE: the patch wins outright, never merges. The
@@ -1473,22 +1539,14 @@ async function patchDevice(
 
   // The response and the SSE frame always report the projection of the record
   // we just wrote: a disabled device is `disabled` regardless of what its
-  // connection last said, and an enabled one reports its live state.
-  const state = projectState(next, route.deps.connect)
+  // connection last said, and an enabled one reports its live state. ONE
+  // projection feeds both, so the frame and the body cannot disagree.
+  const summary = deviceSummary(route, next)
   if (patch.enabled !== undefined && patch.enabled !== previousEnabled) {
-    route.hub.publish('device-state', { deviceId, state })
+    route.hub.publish('device-state', { deviceId, state: summary.state })
   }
 
-  writeJson(res, 200, {
-    deviceId: next.deviceId,
-    displayName: next.displayName,
-    state,
-    enabled: next.enabled,
-    hosts: [...next.hosts],
-    port: next.port,
-    security: { ...next.security },
-    ports: { ...next.ports },
-  })
+  writeJson(res, 200, summary)
 }
 
 function warnConnect(deviceId: string): (error: unknown) => void {
@@ -1511,12 +1569,129 @@ function sameHosts(a: readonly string[], b: readonly string[]): boolean {
   return a.length === b.length && a.every((host, index) => host === b[index])
 }
 
+/**
+ * `POST /devices/:id/forget` and `POST /devices/:id/remember` (issue #204): the
+ * settings page's door onto #185's endpoint maintenance, which until now only
+ * the `cherry_devices` tool could open.
+ *
+ * One action per request, and the action IS the request: there is no composite
+ * "patch the record AND forget a host" body whose ordering would have to be
+ * defined. Every judgement is the store's — the last-candidate refusal, the
+ * case-insensitive matching, the disjointness of `hosts`/`forgottenHosts` — so
+ * the two doors share ONE set of STORE rules; this route only maps the verdicts
+ * onto HTTP and answers the projection the PATCH answers. (The BODY PARSERS do
+ * differ on purpose — see `parseEndpointHosts`.)
+ *
+ * EVICTION on a change, exactly like the tool's own arm and a PATCH's address
+ * maintenance, and for a DIFFERENT reason on each action — which is why both
+ * are stated here rather than waved through as "parity":
+ *
+ *  - FORGET: a pooled connection CAPTURES its record at construction, so the
+ *    socket built before this write would keep dialing the host we just forgot.
+ *    (The mark itself is honoured by the store's learn merge, so a reconnect is
+ *    about the DIAL LIST, not about suppressing the address.)
+ *  - REMEMBER: learning happens only INSIDE a handshake, against a clone of the
+ *    stored record. Without the eviction a desktop that stays connected would
+ *    not re-handshake for as long as the link holds, so the restored address
+ *    would come back only after some later flap — the button would look inert.
+ *
+ * The cost is real and inherited from the tool's arm: an eviction disposes the
+ * subscription layer and closes a healthy socket, so a write can drop an
+ * in-flight command's link. One operator click now reaches that churn; that is
+ * the price of "the archive is the truth" for a live connection.
+ */
+async function changeEndpoints(
+  req: HttpRequestLike,
+  res: HttpResponseLike,
+  route: RouteContext,
+  deviceId: string,
+  action: 'forget' | 'remember',
+): Promise<void> {
+  const existing = route.deps.store.list().find((device) => device.deviceId === deviceId)
+  if (existing === undefined) {
+    writeError(res, 404, 'not-found', `no device ${deviceId}`)
+    return
+  }
+
+  let hosts: string[]
+  try {
+    hosts = parseEndpointHosts(await readJsonBody(req))
+  } catch (error) {
+    writeError(res, 400, 'invalid-request', error instanceof Error ? error.message : String(error))
+    return
+  }
+
+  try {
+    if (action === 'forget') {
+      const { removed, marked } = route.deps.store.forgetEndpoints(deviceId, hosts)
+      if (removed.length > 0 || marked.length > 0) evict(route, deviceId)
+    } else {
+      const { restored } = route.deps.store.rememberEndpoints(deviceId, hosts)
+      if (restored.length > 0) evict(route, deviceId)
+    }
+  } catch (error) {
+    // Quarantine first, and distinctly: it is not the request's fault (the 400s
+    // below) and the browser cannot fix it — the archive is READ-ONLY until a
+    // human moves the bad file aside. A store that was ALREADY quarantined
+    // never reaches this arm: its view is empty, so the `list()` above answered
+    // 404 before any write — the same precedence PATCH and DELETE have. This is
+    // the defence for a store that begins refusing after that read, and it is
+    // what keeps a damaged archive from being reported as a bad request.
+    if (writeQuarantineRefusal(res, route, error)) return
+    // The tool's own code for the same refusal, so the page can translate it by
+    // code rather than by prose.
+    if (error instanceof LastCandidateHostError) {
+      writeError(res, 400, 'last-address', error.message)
+      return
+    }
+    writeError(res, 400, 'invalid-device', error instanceof Error ? error.message : String(error))
+    return
+  }
+
+  // The projection of the record we just wrote, never the object we read before
+  // the write: `REMOVED from a declined call` and `UNCHANGED by a no-op` are
+  // both answered from the archive's current row.
+  const fresh = route.deps.store.list().find((device) => device.deviceId === deviceId)
+  writeJson(res, 200, deviceSummary(route, fresh ?? existing))
+}
+
+/**
+ * The body of an endpoint action: `{hosts: [...]}`, non-empty, every entry
+ * normalized the same way the PATCH normalizes an address.
+ *
+ * The normalization is not cosmetic: an IPv6 literal is stored bare but a
+ * browser copy-pastes it bracketed, and the store matches by host spelling —
+ * so `[::1]` would be treated as an address the record does not dial and merely
+ * marked, leaving the real `::1` in `hosts`. The PATCH's rule is reused for the
+ * spelling (same `normalizeHost`), and deliberately NOT for its duplicate
+ * refusal: a repeated host in an action body names one host twice, which the
+ * store's own sets collapse, while the PATCH's duplicates would build an
+ * ambiguous record (`hosts`, `security` and `ports` are keyed by host).
+ */
+function parseEndpointHosts(body: Record<string, unknown>): string[] {
+  const hosts = body['hosts']
+  if (!Array.isArray(hosts) || hosts.length === 0) {
+    throw new PatchError('hosts must be a non-empty array')
+  }
+  return hosts.map((entry) => {
+    if (typeof entry !== 'string') throw new PatchError('hosts entries must be strings')
+    return normalizeHost(entry)
+  })
+}
+
 /**
  * The scheme map for a WHOLE-REPLACE host list (issue #126): each named host
  * keeps the scheme it was dialed with, a host the list just gained defaults to
  * `ws`, and hosts the list dropped leave no entry behind. An edit is an
  * address edit, not a scheme edit — re-typing the same host must not silently
  * demote a TLS-proxied desktop to a plain dial.
+ *
+ * "The same host" is CASE-INSENSITIVE (issue #189), the same comparison the
+ * learn merge, the forget/remember actions and the mark clearing already use:
+ * `NAS.example` and `nas.example` are one address, so a PATCH that re-types
+ * the case keeps the remembered scheme instead of resetting it to `ws`.
+ * `sameHosts`/`sameSecurity` stay EXACT on purpose — they decide whether an
+ * address edit happened at all, and a new spelling IS a change to persist.
  */
 function securityFor(
   hosts: readonly string[],
@@ -1524,12 +1699,42 @@ function securityFor(
 ): Record<string, 'ws' | 'wss'> {
   // `Object.hasOwn`, never `previous[host] ?? 'ws'`: a host named `constructor`
   // (or `__proto__`/`toString`) would otherwise inherit a FUNCTION from
-  // Object.prototype and poison the map the store then rejects.
+  // Object.prototype and poison the map the store then rejects. The index is
+  // built from OWN entries only, so it is safe for the same reason.
+  const remembered = indexByHost(previous)
   return Object.fromEntries(
-    hosts.map((host) => [host, Object.hasOwn(previous, host) ? previous[host] : 'ws']),
+    hosts.map((host) => [host, exactOrRemembered(previous, remembered, host) ?? 'ws']),
   )
 }
 
+/**
+ * A case-insensitive index over a per-host map (issue #189).
+ *
+ * FIRST spelling wins on a collision. A hand-edited archive CAN hold two
+ * spellings of one host (the store does not reject it, and this face does not
+ * touch `previous`), so callers look their exact spelling up FIRST and consult
+ * this index only as the fallback: a surviving spelling therefore keeps its
+ * OWN entry, and the collision rule only decides what a THIRD spelling
+ * inherits.
+ */
+function indexByHost<T>(previous: Record<string, T>): Map<string, T> {
+  const index = new Map<string, T>()
+  for (const [host, value] of Object.entries(previous)) {
+    const key = host.toLowerCase()
+    if (!index.has(key)) index.set(key, value)
+  }
+  return index
+}
+
+/** The exact spelling's entry, else the case-insensitive one, else nothing. */
+function exactOrRemembered<T>(
+  previous: Record<string, T>,
+  remembered: Map<string, T>,
+  host: string,
+): T | undefined {
+  return Object.hasOwn(previous, host) ? previous[host] : remembered.get(host.toLowerCase())
+}
+
 /**
  * The port map for a host list (issue #135): each named host keeps the port it
  * was dialed with, a host the list just gained defaults to `fallback` (the
@@ -1537,16 +1742,18 @@ function securityFor(
  *
  * `previous` is empty when the caller is re-pointing EVERY host (a CHANGED
  * `port` patch): there is no remembered entry to keep, by design — one port
- * field on this face must move the whole list. Same `Object.hasOwn` rule as
- * `securityFor`: an inherited function is not a remembered port.
+ * field on this face must move the whole list. Same `Object.hasOwn`/
+ * case-insensitive rules as `securityFor` (issue #189): a re-typed spelling
+ * keeps its own port, and an inherited function is never a remembered port.
  */
 function portsFor(
   hosts: readonly string[],
   previous: Record<string, number>,
   fallback: number,
 ): Record<string, number> {
+  const remembered = indexByHost(previous)
   return Object.fromEntries(
-    hosts.map((host) => [host, Object.hasOwn(previous, host) ? previous[host] : fallback]),
+    hosts.map((host) => [host, exactOrRemembered(previous, remembered, host) ?? fallback]),
   )
 }
 

package/src/index.ts

@@ -489,6 +489,19 @@ function connectionFor(deviceId: string): DeviceConnection {
     // Spread-if-present, never `wsOptions: undefined`: the option is optional,
     // and an absent key is the honest "no override" (Node's trust store).
     ...(state.wsTls === undefined ? {} : { wsOptions: state.wsTls }),
+    // The archive write-back (issue #143). The connection has already merged the
+    // addresses into its OWN record — this instance's next reconnect dials them
+    // — so the only job here is durability. It goes through
+    // `DeviceStore.learnEndpoints`, NOT `upsert(record)`: the store's record
+    // carries the token of the PAIRING while the connection's mirrors the live
+    // one, and an `upsert` of the connection's copy would put a
+    // connection-scoped credential into the archive.
+    onAdvertisedEndpoints: (endpoints) => {
+      // `record` is THIS connection's clone: its `desktopIdentity` is the pin the
+      // answer was validated against, so a re-pair under the same deviceId cannot
+      // receive an address learned from the previous pairing.
+      state.store.learnEndpoints(deviceId, endpoints, record.desktopIdentity)
+    },
   })
   state.connectionsBuilt += 1
   connection.onState((deviceState: DeviceState) => {

package/src/tools.ts

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto'
 import { DeviceUnavailableError, RpcDeadlineExceededError } from './connection.js'
 import type { DeviceConnection, DeviceState } from './connection.js'
 import type { DeviceRecord, DeviceResolution, DeviceStore } from './deviceStore.js'
-import { QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
+import { LastCandidateHostError, QUARANTINE_RECOVERY, QuarantinedArchiveError } from './deviceStore.js'
 import {
   DEVICE_SETTLE_WAIT_MS,
   INTERACTIONS_LIST_PAGE_CLAMP,
@@ -111,6 +111,13 @@ export interface CherryDeviceView {
   enabled: boolean
   hosts: string[]
   port: number
+  /**
+   * The addresses the operator has FORGOTTEN (issue #185): not dialed, and not
+   * re-learned from the desktop's advertisements until they are remembered.
+   * Always present on a view (empty when nothing was ever forgotten) so a
+   * caller never has to distinguish "absent" from "none".
+   */
+  forgottenHosts: string[]
 }
 
 /** The shared `{device, state}` verdict (spec §6: 设备离线). */
@@ -1216,8 +1223,11 @@ export interface CherryToolsDeps {
    * `DeviceConnection` captures its record at construction, so a pooled
    * instance can never observe an edited address or a flipped `enabled` flag.
    *
-   * `cherry_unpair` is the other caller: it evicts (drop + close) and then
-   * removes the archive entry, so no live socket outlives its record.
+   * `cherry_unpair` evicts (drop + close) and then removes the archive entry,
+   * so no live socket outlives its record, and `cherry_devices`' `forget` /
+   * `remember` actions evict ON A CHANGE for the same reason: a pooled
+   * connection captured the pre-write record, so a forget that only rewrote the
+   * archive would keep dialing the address (and locally re-learning it).
    */
   evict(deviceId: string): void | Promise<void>
   /**
@@ -1642,6 +1652,59 @@ function optionalString(value: unknown): string | undefined {
   return typeof value === 'string' && value !== '' ? value : undefined
 }
 
+/**
+ * The `hosts` argument of `cherry_devices`' write actions (issue #185): a
+ * non-empty list of non-empty host names, with no case-variant duplicate.
+ *
+ * Each rule is a state the store would have to interpret: an empty name can
+ * never match a dialed host, and two spellings of one host would make "is this
+ * address forgotten?" depend on which entry a comparison hit first. Values are
+ * TRIMMED here (the model-facing surface is where a stray space is caught);
+ * the archive then stores the spelling it already had for a dialed host.
+ */
+function hostListArgument(value: unknown): string[] | Record<string, unknown> {
+  if (!Array.isArray(value) || value.length === 0) {
+    return { error: 'invalid-hosts', message: '`hosts` must be a non-empty array of host names' }
+  }
+  const hosts: string[] = []
+  const seen = new Set<string>()
+  for (const entry of value) {
+    if (typeof entry !== 'string' || entry.trim() === '') {
+      return { error: 'invalid-hosts', message: '`hosts` entries must be non-empty strings' }
+    }
+    let host = entry.trim()
+    // The archive stores BARE hosts, and the PATCH path unwraps a bracketed
+    // IPv6 literal (`normalizeHost`). This face must agree: a mark for
+    // `[fd00::1]` would never match the `fd00::1` a dial or an advertisement
+    // carries, so it would be a mark with no effect. The ceiling mirrors the
+    // PATCH path's `HOST_MAX`.
+    if (host.startsWith('[') && host.endsWith(']')) {
+      try {
+        new URL(`http://${host}/`)
+      } catch {
+        return {
+          error: 'invalid-hosts',
+          message: `\`hosts\` entry "${host}" is not a valid IPv6 literal`,
+        }
+      }
+      host = host.slice(1, -1)
+    }
+    if (host.length > 256) {
+      return { error: 'invalid-hosts', message: '`hosts` entry exceeds 256 characters' }
+    }
+    const key = host.toLowerCase()
+    if (seen.has(key)) {
+      return {
+        error: 'invalid-hosts',
+        message: `\`hosts\` names "${host}" more than once (host names are case-insensitive)`,
+      }
+    }
+    seen.add(key)
+    hosts.push(host)
+  }
+  return hosts
+}
+
 /**
  * The peer's `agent.messages.send` refusal for a STALE `expectedIdleRevision`,
  * in the exact shape Cherry Studio answers it: a `rejected` receipt whose
@@ -2729,25 +2792,100 @@ export class CherryToolEngine {
       description:
         'List every paired Cherry Studio desktop with its connection state ' +
         '(connected/connecting/offline/disabled/identity-mismatch). An optional `device` ' +
-        'narrows the list to one device (display name prefix or deviceId).',
+        'narrows the list to one device (display name prefix or deviceId). ' +
+        '`action: "forget"` removes the named `hosts` from that device\'s dial candidates AND ' +
+        'stops the desktop\'s advertisements from adding them back; `action: "remember"` lifts ' +
+        'that mark, so the next handshake may learn them again. Both write actions require ' +
+        '`device` and `hosts`.',
       parameters: {
         type: 'object',
         properties: {
           device: { type: 'string', description: 'Optional device selector: exact deviceId, or a unique prefix of a deviceId or display name.' },
+          action: {
+            type: 'string',
+            enum: ['list', 'forget', 'remember'],
+            description:
+              'What to do: `list` (the default) reads the devices; `forget`/`remember` edit ONE ' +
+              "device's forgotten addresses and require `device` and `hosts`.",
+          },
+          hosts: {
+            type: 'array',
+            items: { type: 'string' },
+            description:
+              'For `forget`/`remember`: the host names to act on, matched case-insensitively. ' +
+              '`forget` refuses to remove the last remaining address.',
+          },
         },
         additionalProperties: false,
       },
       execute: async (args) => {
+        const action = optionalString(args['action']) ?? 'list'
+        if (action !== 'list' && action !== 'forget' && action !== 'remember') {
+          return {
+            error: 'invalid-action',
+            message: '`action` accepts exactly "list", "forget" or "remember"',
+          } satisfies Record<string, unknown>
+        }
         const selector = optionalString(args['device'])
-        const quarantined = this.#quarantineVerdict()
-        if (quarantined !== undefined) return quarantined
+        if (action === 'list') {
+          const quarantined = this.#quarantineVerdict()
+          if (quarantined !== undefined) return quarantined
+          if (selector === undefined) {
+            const records = this.#deps.store.list()
+            return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) }
+          }
+          const selected = this.#selectRecords(selector)
+          if (!Array.isArray(selected)) return selected
+          return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) }
+        }
         if (selector === undefined) {
-          const records = this.#deps.store.list()
-          return { devices: await Promise.all(records.map((record) => this.#deviceView(record))) }
+          return {
+            error: 'device-required',
+            message:
+              '`action` "forget"/"remember" needs `device`: a selector that names exactly one device',
+          } satisfies Record<string, unknown>
         }
+        const hosts = hostListArgument(args['hosts'])
+        if (!Array.isArray(hosts)) return hosts
+        const quarantined = this.#quarantineVerdict()
+        if (quarantined !== undefined) return quarantined
         const selected = this.#selectRecords(selector)
         if (!Array.isArray(selected)) return selected
-        return { devices: await Promise.all(selected.map((record) => this.#deviceView(record))) }
+        const record = selected[0]!
+        let removed: string[] = []
+        let marked: string[] = []
+        let restored: string[] = []
+        try {
+          if (action === 'forget') {
+            ;({ removed, marked } = this.#deps.store.forgetEndpoints(record.deviceId, hosts))
+          } else {
+            ;({ restored } = this.#deps.store.rememberEndpoints(record.deviceId, hosts))
+          }
+        } catch (error) {
+          if (error instanceof LastCandidateHostError) {
+            return {
+              error: 'last-address',
+              device: record.deviceId,
+              message: error.message,
+            } satisfies Record<string, unknown>
+          }
+          throw error
+        }
+        const changed = removed.length > 0 || marked.length > 0 || restored.length > 0
+        // ADDRESS MAINTENANCE reaches the LIVE connection, exactly like the HTTP
+        // PATCH's eviction: a pooled `DeviceConnection` captures its record at
+        // construction, so an instance built before this write would keep
+        // dialing the forgotten host and locally re-adding it on every
+        // reconnect. Evicting drops that socket and makes the next `connect()`
+        // rebuild from the archive we just wrote.
+        if (changed) await this.#deps.evict(record.deviceId)
+        // The resolved record is STALE (hosts/forgottenHosts moved), so the
+        // view is built from the archive's current row, never from the object
+        // the selector handed us.
+        const fresh = this.#deps.store.list().find((entry) => entry.deviceId === record.deviceId)
+        if (fresh === undefined) return this.#notFoundVerdict(selector)
+        const device = await this.#deviceView(fresh)
+        return action === 'forget' ? { device, removed, marked } : { device, restored }
       },
     })
   }
@@ -2814,6 +2952,7 @@ export class CherryToolEngine {
       enabled: record.enabled,
       hosts: record.hosts,
       port: record.port,
+      forgottenHosts: record.forgottenHosts ?? [],
     }
   }
 

package/ui/AGENTS.md

@@ -18,6 +18,27 @@ with its source. Loaded automatically when a file tool touches `ui/**`.
 - **HTTP lives in `api.ts`** (same-origin `/cherry-remote/api`); a component
   never fetches directly. Both seams are injected for tests
   (`eventSourceFactory`, `scopeClient`), so no test stands up a server.
+- **A run always ends, and the deadline is not a verdict.** The server publishes
+  a terminal stage on every outcome, but the stream has no replay, so one lost
+  frame would otherwise park the wizard on 「配对进行中」 with the submit button
+  disabled and no cancel. The run deadline (`runLifetimeMs`, same injection
+  style as `codeLifetimeMs`) restores the form and re-reads the device list;
+  its copy points at that list instead of claiming failure, and it keeps
+  `claimId` so a terminal frame that arrives late still wins. Arm it on the
+  `waiting` phase only — never at mount.
+- **The bundle carries the SOURCE COMMENTS.** `ui/vite.config.ts` sets
+  `minify: false`, so the docblocks that hold most of this page's reasoning ship
+  inside `lib/client.js`: a comment-only edit in `ui/src/**` changes the
+  artifact's bytes and needs the rebuild in the same commit. Two follow-ons from
+  that: `artifactFreshness` compares against `git show HEAD:<path>`, so it only
+  goes green once the rebuild is COMMITTED — running the full suite before
+  committing reports it red for the same reason its sibling case ("neither check
+  mutates the committed artifacts") is red. Neither red is a real failure.
+- **A per-host action is INERT while a whole-list editor is open.** The address
+  editor's draft is sacred (the card does not reseed it while an editor is
+  open), so a 忘记/恢复 chosen under it would be re-sent by the next 保存地址 — and
+  that PATCH clears the mark for any host it names. Hence
+  `disabled={busy || editor === 'address'}` on both controls, pinned by `#204m`.
 - **jsdom only.** `tests/unit/ui.test.ts` and `uiScopePanel.test.ts` render the
   page; a browser-only API needs a fake in the test, not a guard in the page.