dsh-cherry-bridge 0.2.0 → 0.2.2

package/src/subscriptions.ts

@@ -2,6 +2,7 @@ import { JsonRpcRequestError } from './rpc/jsonRpcClient.js'
 import type { JsonRpcClient } from './rpc/jsonRpcClient.js'
 import { DEFAULT_PER_SESSION_CACHE_BYTES } from './defaults.js'
 import { failureText } from './text.js'
+import { remoteLimits } from '@cherrystudio/remote-protocol'
 import type { AgentCursor, AgentEvent } from '@cherrystudio/remote-protocol/agent'
 
 /**
@@ -40,6 +41,27 @@ const DEFAULT_CHECKPOINT_MS = 300_000
  */
 const MAX_RECOVERY_ATTEMPTS = 4
 
+/**
+ * ACK WATERMARK (issue #212). The peer delivers `agent.events` only while the
+ * bytes it has sent since our last `agent.subscriptions.ack` stay inside
+ * `remoteLimits.unackedBytes`; past that it HOLDS the stream — silently, with
+ * the subscription still live — and a held batch can be a run's terminal.
+ *
+ * This layer used to ack ONLY from `cherry_events`, so a waiter (which by
+ * design consumes without acking) parked on a buffer that stopped advancing
+ * just under one window: a real 240 s wait answered `timeout` with the finished
+ * text, its cursor frozen at 666 events ≈ 262144 bytes.
+ *
+ * The layer therefore acks what it has ALREADY BUFFERED (the bytes are in
+ * memory; acking does not lose them) once a quarter of the peer's window has
+ * accumulated. A retry cooldown keeps a refusing peer from turning every batch
+ * into a round trip.
+ */
+/** First retry delay after a refused auto-ack; doubles per attempt. */
+const AUTO_ACK_RETRY_MS = 3_000
+/** Ceiling for the doubling retry, so a permanently refusing peer is quiet. */
+const AUTO_ACK_RETRY_MAX_MS = 30_000
+
 export type ReadResult = { events: AgentEvent[]; nextCursor: AgentCursor } | { error: 'cursor-out-of-window' }
 
 export interface SessionSubscriptionsOptions {
@@ -60,6 +82,20 @@ export interface SessionSubscriptionsOptions {
    * default 300_000). Only bounds recovery retries; the peer is authoritative.
    */
   checkpointMs?: number
+  /**
+   * The peer's hello-advertised un-acked delivery window in bytes (protocol
+   * `remoteLimits.unackedBytes`, 262144 in the pinned package). Past that much
+   * delivered-but-unacknowledged traffic the desktop HOLDS its event stream
+   * (issue #212), so the layer acks its buffer at a quarter of this value.
+   *
+   * Omitted falls back to the pinned protocol constant. A peer that does not
+   * advertise the key is treated as the pinned generation — the same
+   * conservative rule the other negotiated limits follow.
+   *
+   * A FUNCTION is read at every watermark check, so a layer that outlives a
+   * reconnect picks up the new hello's value instead of pinning the first one.
+   */
+  unackedBytes?: number | (() => number | undefined)
 }
 
 /** Peer-side subscription phases (mirrors the real peer's internal state). */
@@ -108,6 +144,31 @@ interface SessionState {
   cursor: AgentCursor
   buffer: CachedEvent[]
   bytes: number
+  /**
+   * Bytes appended since the last ack we sent (issue #212). Drives
+   * {@link SessionSubscriptions.#maybeAutoAck}; kept separate from `bytes`,
+   * which measures what the CACHE holds rather than what the peer may still
+   * consider un-acknowledged.
+   */
+  bytesSinceAck: number
+  /** One auto-ack in flight at a time; a second would only duplicate a cursor. */
+  ackInFlight: boolean
+  /** Cooldown after a refused auto-ack (`AUTO_ACK_RETRY_MS`, doubling). */
+  ackRetryAt: number
+  /**
+   * Current retry delay: `AUTO_ACK_RETRY_MS` after the first refusal, doubled
+   * on every further one up to `AUTO_ACK_RETRY_MAX_MS`. Reset on a success, so
+   * a peer that recovers is back to prompt retries.
+   */
+  ackRetryDelay: number
+  /**
+   * The ARMED retry behind `ackRetryAt`. An ack failure is the one case where
+   * no further event will arrive to re-trigger the watermark check — the peer
+   * is holding at its window — so the retry cannot wait for traffic (issue
+   * #212's own failure mode, one ack later). Cleared by {@link #installReplay},
+   * {@link #installCheckpoint} and {@link SessionSubscriptions.dispose}.
+   */
+  ackRetryTimer?: ReturnType<typeof setTimeout>
   /**
    * The oldest stream position this session still TRACKS: the baseline the
    * subscription started from, advanced whenever old events are dropped. It is
@@ -189,6 +250,8 @@ export class SessionSubscriptions {
   readonly #limit: number
   readonly #perSessionCacheBytes: number
   readonly #checkpointMs: number
+  /** Where the peer's window comes from; see {@link SessionSubscriptionsOptions.unackedBytes}. */
+  readonly #unackedSource: number | (() => number | undefined) | undefined
   readonly #sessions = new Map<string, SessionState>()
   /**
    * Insertion order IS the eviction order, and it is SUBSCRIPTION recency, not
@@ -211,6 +274,7 @@ export class SessionSubscriptions {
     this.#limit = Math.max(1, Math.floor(positive(opts.subscriptionsLimit, DEFAULT_SUBSCRIPTIONS_LIMIT)))
     this.#perSessionCacheBytes = positive(opts.perSessionCacheBytes, DEFAULT_PER_SESSION_CACHE_BYTES)
     this.#checkpointMs = positive(opts.checkpointMs, DEFAULT_CHECKPOINT_MS)
+    this.#unackedSource = opts.unackedBytes
   }
 
   /**
@@ -316,6 +380,7 @@ export class SessionSubscriptions {
       // session that will not stay subscribed.
       console.info(`[cherry-remote] re-subscribing session ${sessionId} (replacing its live subscription)`)
       await this.#closeSubscription(existing.subscriptionId)
+      this.#cancelAckRetry(existing)
       this.#rejectWaiters(existing, new Error(`session ${sessionId} re-subscribed`))
       this.#sessions.delete(sessionId)
     }
@@ -424,13 +489,24 @@ export class SessionSubscriptions {
   /**
    * Advances the peer's view of this session: `agent.subscriptions.ack` with
    * the delivered cursor. The peer only accepts a cursor inside the window it
-   * actually delivered (an out-of-window ack is its CONFLICT), so this is
-   * called with the cursor a consumer has durably processed.
+   * actually delivered (an out-of-window ack is its CONFLICT).
+   *
+   * Two callers, one contract — "this position is accounted for, keep sending":
+   * `cherry_events` passes the cursor a CONSUMER has processed, and
+   * {@link #maybeAutoAck} passes the BUFFER frontier because the events are
+   * retained here (see that method for why an ack cannot lose replay).
    */
   async ack(sessionId: string, cursor?: AgentCursor): Promise<void> {
     const state = this.#sessions.get(sessionId)
     if (state === undefined) return
-    const applied = cursor ?? state.cursor
+    // COALESCED TO THE FRONTIER. The peer keeps ONE `lastAck` per subscription
+    // and refuses a lower position, so an explicit ack carrying what a consumer
+    // has processed would lose a race against the layer's own ack and be
+    // answered CONFLICT — which the caller treats as a broken subscription.
+    // The buffer already holds everything up to `state.cursor`, so acking the
+    // frontier is both safe (an ack only frees flow control) and monotone.
+    const requested = cursor === undefined ? state.cursor : cursor
+    const applied = Number(requested.seq) > Number(state.cursor.seq) ? requested : state.cursor
     await this.#rpc.request('agent.subscriptions.ack', {
       subscriptionId: state.subscriptionId,
       cursor: applied,
@@ -484,6 +560,7 @@ export class SessionSubscriptions {
     this.#closed = true
     const ids = [...this.#sessions.values()].map((state) => state.subscriptionId)
     for (const state of this.#sessions.values()) {
+      this.#cancelAckRetry(state)
       const error = new Error('SessionSubscriptions disposed')
       for (const waiter of state.waiters.splice(0)) waiter.reject(error)
     }
@@ -590,7 +667,10 @@ export class SessionSubscriptions {
    */
   #installReplay(sessionId: string, descriptor: Extract<SubscribeDescriptor, { mode: 'replay' }>): void {
     const previous = this.#sessions.get(sessionId)
-    if (previous !== undefined) this.#rejectWaiters(previous, new Error(`session ${sessionId} re-subscribed`))
+    if (previous !== undefined) {
+      this.#cancelAckRetry(previous)
+      this.#rejectWaiters(previous, new Error(`session ${sessionId} re-subscribed`))
+    }
     this.#sessions.delete(sessionId)
     // Re-inserting moves the session to the MRU end of the Map's order.
     this.#sessions.set(sessionId, {
@@ -598,6 +678,11 @@ export class SessionSubscriptions {
       cursor: descriptor.highWatermark,
       buffer: [],
       bytes: 0,
+      bytesSinceAck: 0,
+      ackInFlight: false,
+      ackRetryAt: 0,
+      ackRetryDelay: AUTO_ACK_RETRY_MS,
+      ackRetryTimer: undefined,
       windowStart: Number(descriptor.highWatermark.seq),
       // A fresh window: nothing has been dropped from it, so the baseline is a
       // position this layer may serve (issue #2).
@@ -723,13 +808,21 @@ export class SessionSubscriptions {
     items: Array<{ kind: string; value: unknown }>,
   ): void {
     const previous = this.#sessions.get(sessionId)
-    if (previous !== undefined) this.#rejectWaiters(previous, new Error(`session ${sessionId} recovered`))
+    if (previous !== undefined) {
+      this.#cancelAckRetry(previous)
+      this.#rejectWaiters(previous, new Error(`session ${sessionId} recovered`))
+    }
     this.#sessions.delete(sessionId)
     this.#sessions.set(sessionId, {
       subscriptionId: descriptor.subscriptionId,
       cursor: descriptor.checkpoint.cursor,
       buffer: [],
       bytes: 0,
+      bytesSinceAck: 0,
+      ackInFlight: false,
+      ackRetryAt: 0,
+      ackRetryDelay: AUTO_ACK_RETRY_MS,
+      ackRetryTimer: undefined,
       windowStart: Number(descriptor.checkpoint.cursor.seq),
       // A fresh window: nothing has been dropped from it, so the baseline is a
       // position this layer may serve (issue #2).
@@ -801,6 +894,7 @@ export class SessionSubscriptions {
           `${sessionId}`,
       )
       // The entry is removed outright, so no `live` flag needs clearing.
+      this.#cancelAckRetry(state)
       this.#rejectWaiters(state, new Error(`session ${sessionId} evicted by LRU`))
       this.#sessions.delete(sessionId)
       // AWAITED: the peer must observe the close before the next subscribe.
@@ -907,6 +1001,7 @@ export class SessionSubscriptions {
       const bytes = eventBytes(event)
       state.buffer.push({ cursor, event, bytes })
       state.bytes += bytes
+      state.bytesSinceAck += bytes
       state.cursor = cursor
       appended += 1
     }
@@ -915,6 +1010,106 @@ export class SessionSubscriptions {
     // Waking on a wholly stale batch would make a parked waiter re-judge state
     // that has not moved; only real progress is a wake.
     if (appended > 0) this.#wakeWaiters(state)
+    // The wake comes FIRST: a waiter that can settle from what just arrived
+    // must not wait behind an ack round trip.
+    if (appended > 0) this.#maybeAutoAck(sessionId, state)
+  }
+
+  /**
+   * Sends `agent.subscriptions.ack` once the un-acked bytes approach the peer's
+   * window, so the peer keeps delivering (issue #212).
+   *
+   * WHAT IS BEING ACKED is "everything in this layer's buffer", not "everything
+   * a caller has consumed". That is safe against the pinned peer because an ack
+   * does exactly one thing: it frees FLOW CONTROL — the desktop decrements its
+   * un-acked budget and advances `lastAck` (`agentSubscriptions.ts`). Replay
+   * retention lives on the journal (`replayBytes`/`replayMs`) and is not
+   * touched by an ack, so a `read`/`cherry_events`/re-subscribe from a cursor
+   * below the acked position is still served — by the local buffer here and by
+   * the journal there. The ack's own doc comment states the same contract.
+   *
+   * The ack is fire-and-forget with its failure SURFACED (a refused ack must be
+   * visible, not swallowed). A refusal also ARMS A TIMER: once the peer is
+   * holding at its window no further event arrives, so a retry that waited for
+   * traffic would never fire and the wait would time out exactly as in issue
+   * #212.
+   */
+  #maybeAutoAck(sessionId: string, state: SessionState): void {
+    if (state.bytesSinceAck < this.#ackWatermark()) return
+    if (state.ackInFlight) return
+    if (Date.now() < state.ackRetryAt) return
+    state.ackInFlight = true
+    // The bytes covered by THIS ack. Events that arrive while it is in flight
+    // stay counted, so the next window starts from the right place.
+    const covered = state.bytesSinceAck
+    void this.ack(sessionId)
+      .then(() => {
+        state.bytesSinceAck = Math.max(0, state.bytesSinceAck - covered)
+        // A peer that answers ack again gets prompt retries next time.
+        state.ackRetryDelay = AUTO_ACK_RETRY_MS
+      })
+      .catch((error: unknown) => {
+        // THIS attempt's delay, then the next one doubles: a peer that refuses
+        // every ack (a wedged controller, a link about to drop) must not log a
+        // line every few seconds for the life of the layer.
+        const delay = state.ackRetryDelay
+        state.ackRetryAt = Date.now() + delay
+        state.ackRetryDelay = Math.min(delay * 2, AUTO_ACK_RETRY_MAX_MS)
+        console.warn(`[cherry-remote] auto-ack for session ${sessionId} failed: ${failureText(error)}`)
+        // ARMED HERE, not on the next batch: a peer holding at its window sends
+        // nothing more, so traffic-driven retry is no retry at all.
+        this.#armAckRetry(sessionId, state, delay)
+      })
+      .finally(() => {
+        state.ackInFlight = false
+        // RE-JUDGE: batches can arrive WHILE the ack was in flight (the peer
+        // flushes on the ack, so this is the common case), and those batches
+        // were refused a trigger by `ackInFlight`. Without this second look the
+        // layer could sit with bytes over the watermark and no event left to
+        // trigger it — the peer holding, exactly as in issue #212.
+        if (this.#closed || this.#sessions.get(sessionId) !== state) return
+        this.#maybeAutoAck(sessionId, state)
+      })
+  }
+
+  /**
+   * Quarter of the peer's window, read from the CURRENT source so a layer that
+   * outlives a reconnect follows the new hello instead of its first answer.
+   * Falls back to the pinned protocol constant when nothing is advertised.
+   */
+  #ackWatermark(): number {
+    const source = this.#unackedSource
+    const advertised = typeof source === 'function' ? source() : source
+    return Math.max(1, Math.floor(positive(advertised, remoteLimits.unackedBytes) / 4))
+  }
+
+  /** Disarms the retry, if any (idempotent; safe on a state being replaced). */
+  #cancelAckRetry(state: SessionState): void {
+    if (state.ackRetryTimer === undefined) return
+    clearTimeout(state.ackRetryTimer)
+    state.ackRetryTimer = undefined
+  }
+
+  /**
+   * One timer-driven retry after a refused ack. At most one is armed per
+   * session; it no-ops when the state it was armed for is no longer current
+   * (a re-subscribe, a checkpoint recovery or `dispose`).
+   */
+  #armAckRetry(sessionId: string, state: SessionState, delayMs: number): void {
+    if (this.#closed) return
+    if (state.ackRetryTimer !== undefined) return
+    const timer = setTimeout(() => {
+      state.ackRetryTimer = undefined
+      if (this.#closed || this.#sessions.get(sessionId) !== state) return
+      // CLEARED HERE, not left to the wall clock: a clock stepped backwards
+      // would otherwise make `#maybeAutoAck` return early and arm nothing — a
+      // retry silently lost while the peer holds, which is #212 again.
+      state.ackRetryAt = 0
+      this.#maybeAutoAck(sessionId, state)
+    }, delayMs)
+    // Never hold the process open on a retry that is only about flow control.
+    timer.unref?.()
+    state.ackRetryTimer = timer
   }
 
   /**
@@ -937,6 +1132,7 @@ export class SessionSubscriptions {
         `[cherry-remote] subscription for session ${sessionId} reset by the peer ` +
           `(${String(params['reason'] ?? 'unspecified')}); re-subscribe required`,
       )
+      this.#cancelAckRetry(state)
       this.#rejectWaiters(state, new Error(`session ${sessionId} reset by the peer`))
       this.#sessions.delete(sessionId)
       return

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 ?? [],
     }
   }
 
@@ -3938,9 +4077,13 @@ export class CherryToolEngine {
           } satisfies CherryCursorOutOfWindow
         }
 
-        // ACK AFTER DELIVERY (controller ruling ④): the peer may only advance
-        // its view once the caller actually holds these events. A failing ack
-        // is logged, never allowed to swallow the delivered events.
+        // ACK AFTER DELIVERY (controller ruling ④): this EXPLICIT ack reports
+        // the position the caller has just been handed. The layer ALSO acks its
+        // own buffer on a byte watermark (issue #212, subscriptions
+        // `#maybeAutoAck`), because the peer holds the stream past its un-acked
+        // window. The peer keeps ONE `lastAck` and refuses a lower position, so
+        // both sites coalesce to the buffer frontier — see `ack()`.
+        // A failing ack is logged, never allowed to swallow the delivered events.
         // A FAILING ACK ALSO RE-ENSURES THE SESSION (v0.1.3 UltraReview P3-3).
         // The ack is the peer's verdict on the SUBSCRIPTION, not on the
         // delivery: a refused ack says the cursor is outside the window this
@@ -5902,8 +6045,9 @@ export class CherryToolEngine {
    * dimension and deliberately does NOT settle a wait (Task 13 asserts the two
    * layers separately).
    *
-   * Waiters never ack: they consume the projection and leave the peer's view
-   * untouched.
+   * Waiters do not ack what they fold. The subscription LAYER acks its own
+   * buffer on a byte watermark (issue #212) so the peer keeps delivering past
+   * its un-acked window; that ack is about flow control, not consumption.
    *
    * A wait can also end because the LINK went away — the plugin was torn down,
    * the device was unpaired, or the connection closed. That is not a timeout and

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.