@linxin666/dsh-remote-web-ui 0.1.14 → 0.1.16

package/src/client/settings-form.ts

@@ -1,10 +1,11 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
  * Staged form model behind the plugin settings card. A card stages what the
  * user types and writes it only when they save — the settings write is a
  * durable, revision-fenced document mutation, so staging keeps what is on
- * screen exactly what a save would store. Mirrors the official
- * ui-plugin-config card-store pattern in a self-contained slice: this
- * package must not depend on a sibling UI package.
+ * screen exactly what a save would store. Family-shared slice inlined into
+ * each plugin's client bundle; mirrors the official ui-plugin-config
+ * card-store pattern.
  */
 
 import type { SettingsScope, SettingsScopeSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
@@ -19,6 +20,14 @@ export type FieldWrite =
 export interface FieldSpec {
   /** Field name inside the namespace section. */
   field: string
+  /**
+   * Whether the Host treats this field as a secret and redacts its value from
+   * the read-back (role('secret') in the section schema). Redacted secrets are
+   * never compared against the draft on save; the field lands when the scope
+   * reports the write succeeded (its secret-set marker under the bridge), so
+   * a successful secret save is not misreported as failed.
+   */
+  secret?: boolean
   /** Render a stored value as draft text; the empty string when the section carries none. */
   format: (value: unknown) => string
   /**
@@ -60,6 +69,12 @@ export interface CardShell {
   saving: boolean
   /** Whether the last save did not land as staged; cleared by the next edit or save. */
   failed: boolean
+  /**
+   * The rejection code/message the Host returned for the last failed save,
+   * surfaced next to the generic failure text. Undefined while no save has
+   * failed (or the failure carried no server reason).
+   */
+  failedReason?: string
 }
 
 /** The write actions the card's slot entry injects. */
@@ -86,12 +101,63 @@ interface StagedEdit {
 interface PlannedWrite {
   /** Field this entry writes. */
   field: string
+  /** The durable write this entry performs, described for a batched scope. */
+  op: BatchedWrite
   /** Perform the write and report whether the Host holds the staged value afterwards. */
   run: (() => Promise<boolean>) | undefined
 }
 
-/** A whole-number field. An empty draft clears the field; any other draft that is not a finite number blocks the save. */
-export function numberField(field: string): FieldSpec {
+/** One durable write a batched settings scope performs. */
+export interface BatchedWrite {
+  /** Field this entry writes. */
+  field: string
+  /** set stores a value; unset drops the leaf. */
+  op: 'set' | 'unset'
+  /** Value for op set (absent for unset). */
+  value?: unknown
+}
+
+/** Per-field outcome of one batched scope write. */
+export interface BatchedFieldResult {
+  /** Field this entry writes. */
+  field: string
+  /** Whether the Host accepted this field's write (per the read-back view). */
+  landed: boolean
+}
+
+/**
+ * Result of a batched scope write. The bridge scope posts every planned write
+ * in one /mutate so the Host validate hook judges baseURL+model together; a
+ * batched refusal fails the whole save rather than per-field.
+ */
+export interface BatchResult {
+  /** Whether the whole mutate was accepted. */
+  ok: boolean
+  /** Per-field success, in the request order (always present when ok). */
+  fields: BatchedFieldResult[]
+  /** Host rejection code (mutate refused). */
+  code?: string
+  /** Host rejection message (mutate refused). */
+  message?: string
+}
+
+/** The optional batch surface the bridge scope adds over the SettingsScope contract. */
+interface BatchedSettingsScope {
+  /** Write every operation in one scope mutation, reporting per-field success. */
+  mutate: (writes: BatchedWrite[]) => Promise<BatchResult>
+}
+
+/** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
+export interface NumberConstraints {
+  /** The accepted value must be a whole number. */
+  integer?: boolean
+  /** The accepted value must be at least this. */
+  min?: number
+}
+
+/** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints blocks the save. */
+export function numberField(field: string, constraints: NumberConstraints = {}): FieldSpec {
+  const { integer = false, min } = constraints
   return {
     field,
     format: value => typeof value === 'number' ? String(value) : '',
@@ -99,7 +165,10 @@ export function numberField(field: string): FieldSpec {
       const trimmed = text.trim()
       if (trimmed === '') return { kind: 'clear' }
       const parsed = Number(trimmed)
-      return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined
+      if (!Number.isFinite(parsed)) return undefined
+      if (integer && !Number.isInteger(parsed)) return undefined
+      if (min !== undefined && parsed < min) return undefined
+      return { kind: 'set', value: parsed }
     },
   }
 }
@@ -116,19 +185,43 @@ export function textField(field: string): FieldSpec {
   }
 }
 
+/**
+ * A free-text field the Host treats as a secret and redacts from the read-back
+ * (role('secret') in the section schema). The card still edits it like text,
+ * but a save never compares the redacted value back and relies on the scope
+ * reporting the write landed.
+ */
+export function secretField(field: string): FieldSpec {
+  return { ...textField(field), secret: true }
+}
+
 /** A boolean field, edited through true/false draft text. */
 export function booleanField(field: string): FieldSpec {
   return {
     field,
     format: value => typeof value === 'boolean' ? String(value) : '',
     parse: (text) => {
-      if (text === 'true') return { kind: 'set', value: true }
-      if (text === 'false') return { kind: 'set', value: false }
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      if (trimmed === 'true') return { kind: 'set', value: true }
+      if (trimmed === 'false') return { kind: 'set', value: false }
       return undefined
     },
   }
 }
 
+/** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
+export function choiceField(field: string, choices: readonly string[]): FieldSpec {
+  return {
+    field,
+    format: value => typeof value === 'string' && choices.includes(value) ? value : '',
+    parse: (text) => {
+      if (text === '') return { kind: 'clear' }
+      return choices.includes(text) ? { kind: 'set', value: text } : undefined
+    },
+  }
+}
+
 /**
  * Stages one card's edits over one settings namespace and writes them on save.
  *
@@ -143,6 +236,7 @@ export class CardForm<T> {
   private readonly listeners = new Set<() => void>()
   private saving = false
   private failed = false
+  private failedReason: string | undefined
 
   /** @param scope - the bound settings scope for this card's namespace. */
   constructor(
@@ -172,6 +266,7 @@ export class CardForm<T> {
       invalid: plan.some(item => item.run === undefined),
       saving: this.saving,
       failed: this.failed,
+      ...this.failedReason === undefined ? {} : { failedReason: this.failedReason },
     }
   }
 
@@ -202,6 +297,7 @@ export class CardForm<T> {
         if (this.staged.size === 0 && !this.failed) return
         this.staged.clear()
         this.failed = false
+        this.failedReason = undefined
         this.publish()
       },
     }
@@ -209,25 +305,57 @@ export class CardForm<T> {
 
   /**
    * Write every staged edit, then re-seed from what the Host accepted.
+   *
+   * When the scope carries the optional batch surface (the dsh-web-ui
+   * bridge scope), every planned write rides one mutation so cross-field
+   * validate hooks (baseURL+model) judge the batch as a unit instead of
+   * deadlocking on per-field writes. Otherwise the per-field loop runs.
+   * A field lands only when the Host reports it held the staged value; a
+   * landed field's draft is dropped, a failed one stays staged for the user.
    * @returns settlement after every write and the read-back.
    */
   async save(): Promise<void> {
     const plan = this.plan()
-    const writes = plan.flatMap(item => item.run === undefined ? [] : [item.run])
-    if (plan.length === 0 || this.saving || writes.length !== plan.length) return
+    const valid = plan.filter(item => item.run !== undefined)
+    if (plan.length === 0 || this.saving || valid.length !== plan.length) return
+    const plannedWrites = valid.map(item => item.op)
+    // Snapshot the fields this save writes, so edits staged while it is in
+    // flight survive: only the staged keys this save actually wrote are cleared.
+    const fields = new Set(plan.map(item => item.field))
     this.saving = true
     this.failed = false
+    this.failedReason = undefined
     this.publish()
-    let landed = true
-    for (const write of writes) {
-      landed = await write() && landed
+    const landed = new Set<string>()
+    const batch = this.batchedScope()
+    if (batch !== undefined) {
+      const result = await batch.mutate(plannedWrites)
+      if (result.ok) {
+        for (const field of result.fields) {
+          if (field.landed) landed.add(field.field)
+        }
+      } else {
+        this.failedReason = result.message
+      }
+    } else {
+      for (const item of valid) {
+        if (await item.run!()) landed.add(item.field)
+      }
+    }
+    for (const field of fields) {
+      if (landed.has(field)) this.staged.delete(field)
     }
-    if (landed) this.staged.clear()
     this.saving = false
-    this.failed = !landed
+    this.failed = landed.size !== fields.size
     this.publish()
   }
 
+  /** The scope's batch surface when it supports one; undefined conservatively otherwise. */
+  private batchedScope(): BatchedSettingsScope | undefined {
+    const candidate = this.scope as unknown as BatchedSettingsScope | undefined
+    return typeof candidate?.mutate === 'function' ? candidate : undefined
+  }
+
   /**
    * Every staged edit a save would write. An entry whose draft is not a value
    * its field accepts carries no write: the form is still dirty, and the save
@@ -240,14 +368,14 @@ export class CardForm<T> {
     for (const [field, staged] of this.staged) {
       const spec = this.specOf(field)
       if (staged.clear) {
-        if (this.stored(field)) plan.push({ field, run: () => this.clear(field) })
+        if (this.stored(field)) plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) })
         continue
       }
       if (staged.text === spec.format(this.sectionValue(field))) continue
       const write = spec.parse(staged.text)
-      if (write === undefined) plan.push({ field, run: undefined })
-      else if (write.kind === 'clear') plan.push({ field, run: () => this.clear(field) })
-      else plan.push({ field, run: () => this.store(field, write.value) })
+      if (write === undefined) plan.push({ field, op: { field, op: 'unset' }, run: undefined })
+      else if (write.kind === 'clear') plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) })
+      else plan.push({ field, op: { field, op: 'set', value: write.value }, run: () => this.store(field, write.value) })
     }
     return plan
   }
@@ -259,12 +387,18 @@ export class CardForm<T> {
 
   private async store(field: string, value: unknown): Promise<boolean> {
     await this.scope.set(field, value)
+    // A redacted secret never appears in the user layer read-back; judging it
+    // by value would misreport a successful secret save as failed. The bridge
+    // reports secret writes through its secret-set markers (batch path); on
+    // the per-field path the scope resolved, so the write is landed.
+    if (this.specOf(field).secret) return true
     return this.userLayer()?.[field] === value
   }
 
   private stage(field: string, edit: StagedEdit): void {
     this.staged.set(field, edit)
     this.failed = false
+    this.failedReason = undefined
     this.publish()
   }
 

package/src/index.ts

@@ -27,7 +27,7 @@ import {
   fetchLatestVersion,
   resolveAnchorManifest,
   resolveUpdateTarget,
-  runUpdate,
+  runUpdateVerified,
   type UpdateRunResult,
 } from './update.ts'
 import { makeUpdateRoutes } from './update-routes.ts'
@@ -238,19 +238,26 @@ export function apply(ctx: Context, config?: Config): void {
   }
   // ── remote update ────────────────────────────────────────────────────────
   // The dsh-web-ui self-update surface: probe the npm registry for family
-  // releases and run `pnpm update` in the owning profile. Resolutions anchor
-  // on the host process's own module graph, so the update always targets the
-  // profile the running web GUI was booted from. The probe path resolves once
-  // (the anchor stays the same package across updates); versions are re-read
-  // from disk per check.
+  // releases and run `pnpm update --latest` in the owning profile. Resolutions
+  // anchor on the host process's own module graph, so the update always
+  // targets the profile the running web GUI was booted from. The anchor path
+  // is re-resolved per operation: pnpm removes the old version's .pnpm
+  // directory on update, so a boot-time captured path would fail to read
+  // after a successful update; versions are re-read from disk per check.
   const requireFromHost = createRequire(import.meta.url)
-  const anchorManifestPath = resolveAnchorManifest(specifier => requireFromHost.resolve(specifier))
+  const resolveAnchorPath = (): string | undefined => resolveAnchorManifest(specifier => {
+    try {
+      return requireFromHost.resolve(specifier)
+    } catch {
+      return undefined
+    }
+  })
   const updateRoutes = makeUpdateRoutes({
     // Control endpoints are host-surface only: a LAN/phone origin must never
     // trigger a real install on this machine.
     fence: request => isTrustedApiRequest(request, []),
     check: () => checkUpdates({
-      anchorManifestPath,
+      anchorManifestPath: resolveAnchorPath(),
       resolve: specifier => {
         try {
           return requireFromHost.resolve(specifier)
@@ -261,7 +268,7 @@ export function apply(ctx: Context, config?: Config): void {
       fetchLatest: name => fetchLatestVersion(name, fetch),
     }),
     run: async (): Promise<UpdateRunResult> => {
-      const target = resolveUpdateTarget({ anchorManifestPath })
+      const target = resolveUpdateTarget({ anchorManifestPath: resolveAnchorPath() })
       if ('error' in target) {
         const code = target.error
         return {
@@ -272,7 +279,24 @@ export function apply(ctx: Context, config?: Config): void {
           errorCode: code,
         }
       }
-      return runUpdate({ profileDir: target.profileDir, packages: target.packages })
+      // Verify the versions actually moved after a green pnpm exit: the pnpm
+      // 11 minimumReleaseAge gate can silently keep the installed versions
+      // (same-day releases), which a plain exit-0 check would report as
+      // success — the user then restarts and nothing changed.
+      return runUpdateVerified({
+        run: { profileDir: target.profileDir, packages: target.packages },
+        check: {
+          anchorManifestPath: resolveAnchorPath(),
+          resolve: specifier => {
+            try {
+              return requireFromHost.resolve(specifier)
+            } catch {
+              return undefined
+            }
+          },
+          fetchLatest: name => fetchLatestVersion(name, fetch),
+        },
+      })
     },
   })
   const routes = [

package/src/mobile/mux.test.ts

@@ -80,8 +80,9 @@ describe('MuxClient polling fallback', () => {
     await vi.advanceTimersByTimeAsync(400)
     expect(pollLatest).not.toHaveBeenCalled()
 
-    // Past the stall threshold the first poll runs and emits seq 0.
-    await vi.advanceTimersByTimeAsync(700) // 1100ms total -> first stall-checker tick
+    // The single tick (400 ms) crosses the 800 ms stall threshold at 1200 ms:
+    // the same tick then runs the first poll and emits seq 0.
+    await vi.advanceTimersByTimeAsync(800) // 1200ms total -> first stall crossing tick
     expect(pollLatest).toHaveBeenCalledWith('s1')
     expect(frames).toHaveLength(1)
     expect(frames[0]).toMatchObject({ type: 'session/event', sessionId: 's1' })
@@ -104,7 +105,7 @@ describe('MuxClient polling fallback', () => {
     client.start()
     client.observe('s1')
 
-    await vi.advanceTimersByTimeAsync(1100) // first poll -> 3 events
+    await vi.advanceTimersByTimeAsync(1200) // first poll -> 3 events
     expect(frames).toHaveLength(3)
 
     await vi.advanceTimersByTimeAsync(400) // second poll -> same page, nothing new
@@ -119,7 +120,7 @@ describe('MuxClient polling fallback', () => {
     client.start()
     client.observe('s1')
 
-    await vi.advanceTimersByTimeAsync(1100)
+    await vi.advanceTimersByTimeAsync(1200)
     expect(pollLatest).toHaveBeenCalled()
 
     client.observe(undefined)
@@ -136,7 +137,7 @@ describe('MuxClient polling fallback', () => {
     client.start()
     client.observe('s1')
 
-    await vi.advanceTimersByTimeAsync(1100)
+    await vi.advanceTimersByTimeAsync(1200)
     expect(pollLatest).toHaveBeenCalled()
 
     client.stop()
@@ -156,7 +157,7 @@ describe('MuxClient polling fallback', () => {
     client.observe('s1')
 
     // Stall into polling.
-    await vi.advanceTimersByTimeAsync(1100)
+    await vi.advanceTimersByTimeAsync(1200)
     expect(pollLatest).toHaveBeenCalledTimes(1)
 
     // A live mux frame proves SSE delivers again -> fallback stops.
@@ -169,4 +170,81 @@ describe('MuxClient polling fallback', () => {
     expect(live[0]).toMatchObject({ type: 'session/subscribed', sessionId: 's1' })
     client.stop()
   })
+
+  it('drives the whole lifecycle on a single scheduler tick (one interval)', async () => {
+    const { factory } = makeSources()
+    const setIntervalSpy = vi.spyOn(globalThis, 'setInterval')
+    try {
+      const pages = [pageOf([0]), pageOf([0, 1])]
+      const pollLatest = vi.fn(async (_sessionId: string) => pages.shift() ?? pageOf([]))
+      const client = new MuxClient('/m/api/events.mux', {
+        sourceFactory: factory,
+        pollLatest,
+        stallThresholdMs: 1500,
+        pollIntervalMs: 2000,
+      })
+      client.start()
+      client.observe('s1')
+
+      // Exactly one interval is ever created: the single tick scheduler.
+      expect(setIntervalSpy).toHaveBeenCalledTimes(1)
+
+      // The tick fires below the stall threshold without polling.
+      await vi.advanceTimersByTimeAsync(1000)
+      expect(pollLatest).not.toHaveBeenCalled()
+
+      // The same interval arms the fallback once silence passes the threshold
+      // (tick at 2000 crosses 1500) and runs the first poll immediately.
+      await vi.advanceTimersByTimeAsync(1100) // 2100ms total
+      expect(pollLatest).toHaveBeenCalledTimes(1)
+      expect(setIntervalSpy).toHaveBeenCalledTimes(1) // still one timer
+
+      // Subsequent polls ride the same tick at the poll cadence (2000 ms).
+      await vi.advanceTimersByTimeAsync(2000)
+      expect(pollLatest).toHaveBeenCalledTimes(2)
+      client.stop()
+    } finally {
+      setIntervalSpy.mockRestore()
+    }
+  })
+
+  it('paces polls on the tick only after the stall phase ends', async () => {
+    const { factory } = makeSources()
+    const pages = [pageOf([0]), pageOf([0, 1]), pageOf([0, 1, 2]), pageOf([0, 1, 2, 3])]
+    const pollLatest = vi.fn(async (_sessionId: string) => pages.shift() ?? pageOf([]))
+    const client = new MuxClient('/m/api/events.mux', {
+      sourceFactory: factory,
+      pollLatest,
+      stallThresholdMs: 800,
+      pollIntervalMs: 400,
+    })
+    client.start()
+    client.observe('s1')
+
+    // At 1200 ms the stall threshold is crossed on this single 400 ms tick.
+    await vi.advanceTimersByTimeAsync(1200)
+    expect(pollLatest).toHaveBeenCalledTimes(1)
+
+    // Each subsequent 400 ms tick is a poll, matching the poll cadence.
+    await vi.advanceTimersByTimeAsync(400)
+    await vi.advanceTimersByTimeAsync(400)
+    await vi.advanceTimersByTimeAsync(400)
+    expect(pollLatest).toHaveBeenCalledTimes(4)
+    client.stop()
+  })
+
+  it('observe() already in the stall window starts the single-tick poller immediately', async () => {
+    const { factory } = makeSources()
+    const pollLatest = vi.fn(async (_sessionId: string) => pageOf([0]))
+    const client = new MuxClient('/m/api/events.mux', baseOptions(pollLatest, factory))
+    client.start()
+    // Advance well past the stall threshold while nothing is observed.
+    await vi.advanceTimersByTimeAsync(2000)
+    expect(pollLatest).not.toHaveBeenCalled()
+
+    // Observing a session now is already in the stall window: poll right away.
+    client.observe('s1')
+    expect(pollLatest).toHaveBeenCalledTimes(1)
+    client.stop()
+  })
 })

package/src/mobile/mux.ts

@@ -66,6 +66,12 @@ type SessionEventFrame = Extract<MuxFrame, { type: 'session/event' }>
 
 const DEFAULT_POLL_INTERVAL_MS = 3000
 const DEFAULT_STALL_THRESHOLD_MS = 12000
+/**
+ * Stall-check granularity: the single scheduler tick runs at least this
+ * often so fallback arms within a second of the stall threshold passing,
+ * while the poll cadence itself stays {@link MuxClientOptions.pollIntervalMs}.
+ */
+const STALL_CHECK_MS = 1000
 /** Poll window: enough recent events to cover a few seconds of agent output. */
 const DEFAULT_POLL_PAGE_SIZE = 50
 
@@ -98,9 +104,11 @@ export class MuxClient {
   private sseAlive = false
   /** Per-session highest event seq already emitted, for poll dedup. */
   private readonly pollWatermark = new Map<string, number>()
-  private stallTimer: ReturnType<typeof setInterval> | undefined
-  private pollTimer: ReturnType<typeof setInterval> | undefined
+  /** Single scheduler tick: both the stall check and the poll cadence ride this one interval. */
+  private tickTimer: ReturnType<typeof setInterval> | undefined
   private polling = false
+  /** Epoch ms of the next due poll while polling (kept on the same tick timer). */
+  private nextPollAt = 0
 
   /**
    * @param url - the mobile events endpoint (browser-relative).
@@ -120,16 +128,17 @@ export class MuxClient {
     this.stopped = false
     this.lastDataAt = this.now()
     if (this.source === undefined) this.connect()
-    this.startStallChecker()
+    this.startTick()
   }
 
   /** Close for good. */
   stop(): void {
     this.stopped = true
-    this.stopStallChecker()
+    this.stopTick()
     this.stopPolling()
     this.closeSource()
     this.observeSessionId = undefined
+    this.nextPollAt = 0
   }
 
   /** Subscribe to validated frames; returns an unsubscribe function. */
@@ -176,40 +185,52 @@ export class MuxClient {
     }
   }
 
-  private startStallChecker(): void {
-    this.stopStallChecker()
-    this.stallTimer = setInterval(() => {
-      if (this.stopped) return
-      if (this.observeSessionId === undefined) return
-      if (this.polling) return
-      // A live SSE channel only goes silent while the agent idles; never
-      // poll against it. Fallback arms again only via onerror or a stream
-      // that has never delivered.
-      if (this.sseAlive) return
-      if ((this.now() - this.lastDataAt) > this.stallThresholdMs) this.startPolling()
-    }, 1000)
+  /**
+   * The single scheduler tick is the only interval this client owns. One
+   * timer (at the finer of the stall-check and poll cadences) both arms the
+   * polling fallback once the stall threshold passes and drives each poll at
+   * {@link MuxClientOptions.pollIntervalMs} — one timer instead of two.
+   */
+  private startTick(): void {
+    if (this.tickTimer !== undefined) return
+    const cadence = Math.min(this.pollIntervalMs, STALL_CHECK_MS)
+    this.tickTimer = setInterval(() => { this.tick() }, cadence)
+  }
+
+  private stopTick(): void {
+    if (this.tickTimer !== undefined) {
+      clearInterval(this.tickTimer)
+      this.tickTimer = undefined
+    }
   }
 
-  private stopStallChecker(): void {
-    if (this.stallTimer !== undefined) {
-      clearInterval(this.stallTimer)
-      this.stallTimer = undefined
+  private tick(): void {
+    if (this.stopped) return
+    if (this.observeSessionId === undefined) return
+    if (this.polling) {
+      // The stall phase has ended; the same tick now paces the polls.
+      if (this.now() >= this.nextPollAt) {
+        this.nextPollAt = this.now() + this.pollIntervalMs
+        void this.pollTick()
+      }
+      return
     }
+    // A live SSE channel only goes silent while the agent idles; never poll
+    // against it. Fallback arms again only via onerror or a stream that has
+    // never delivered.
+    if (this.sseAlive) return
+    if ((this.now() - this.lastDataAt) > this.stallThresholdMs) this.startPolling()
   }
 
   private startPolling(): void {
     if (this.polling || this.stopped) return
     this.polling = true
+    this.nextPollAt = this.now() + this.pollIntervalMs
     void this.pollTick()
-    this.pollTimer = setInterval(() => { void this.pollTick() }, this.pollIntervalMs)
   }
 
   private stopPolling(): void {
     this.polling = false
-    if (this.pollTimer !== undefined) {
-      clearInterval(this.pollTimer)
-      this.pollTimer = undefined
-    }
   }
 
   /**

package/src/mobile-api.ts

@@ -49,6 +49,8 @@ const MOBILE_PREFERENCES_METHOD = 'mobile.preferences'
 
 /** One session.list page (thin phones load incrementally). */
 const SESSION_PAGE_SIZE = 20
+/** SSE keep-alive ping cadence for the live mux stream (single connection). */
+const DEFAULT_EVENTS_HEARTBEAT_MS = 15_000
 
 /** Encode one list position as an opaque continuation cursor. */
 function sessionListCursor(updatedAt: number, sessionId: string): string {
@@ -78,6 +80,8 @@ export interface MobileApiDeps {
   apiProxy: ApiProxy
   /** The resolved mobile composer preference (live per request). */
   mobileEnterToSend: () => boolean
+  /** SSE keep-alive ping cadence for the mux stream (default 15000 ms; test seam). */
+  eventsHeartbeatMs?: number
 }
 
 /** Mobile API route paths. */
@@ -97,6 +101,7 @@ const MOBILE_API_METHOD_PREFIX = `${MOBILE_API_PREFIX}/`
  */
 export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
   const { service, apiProxy, mobileEnterToSend } = deps
+  const eventsHeartbeatMs = deps.eventsHeartbeatMs ?? DEFAULT_EVENTS_HEARTBEAT_MS
 
   /** The phone gate: a live paired-device cookie, or nothing else proceeds. */
   const gateOk = (req: IncomingMessage): boolean => {
@@ -190,7 +195,7 @@ export function makeMobileApiRoutes(deps: MobileApiDeps): WebRoute[] {
       } catch {
         // The write failed; the close handler tears the subscription down.
       }
-    }, 15_000)
+    }, eventsHeartbeatMs)
     const onClose = (): void => {
       if (closed) return
       closed = true