@linxin666/dsh-remote-web-ui 0.3.23 → 0.4.0

package/src/client/pair-api.ts

@@ -53,7 +53,7 @@ export async function readPairGatePolicy(): Promise<PairGatePolicy> {
 }
 
 /** accept() refusal codes. */
-export type AcceptFailure = { ok: false; code: 'invalid' | 'used' | 'forbidden' }
+export type AcceptFailure = { ok: false; code: 'invalid' | 'forbidden' }
 
 /** One auto-tunnel status frame (absent while the feature is off). */
 export interface TunnelStatusFrame {
@@ -145,8 +145,9 @@ export async function acceptPair(token: string): Promise<{ ok: true } | AcceptFa
     body: JSON.stringify({ token }),
   })
   if (response.ok) return { ok: true }
-  if (response.status === 404) return { ok: false, code: 'invalid' }
-  if (response.status === 409) return { ok: false, code: 'used' }
+  // 409 is the legacy "already used" answer a pre-bearer-token host could send;
+  // it means the same thing to the caller as a 404.
+  if (response.status === 404 || response.status === 409) return { ok: false, code: 'invalid' }
   return { ok: false, code: 'forbidden' }
 }
 
@@ -170,9 +171,25 @@ export async function revokePair(deviceId: string): Promise<void> {
   if (!response.ok) throw new Error(`remote-web-ui: revoke failed with ${String(response.status)}`)
 }
 
-/** Presence heartbeat from a paired phone (unpaired heartbeats 401 harmlessly). */
-export async function sendHeartbeat(): Promise<void> {
-  await fetch('/api/pair/heartbeat', { method: 'POST' })
+/**
+ * Presence heartbeat from a paired phone.
+ * @returns the response status, so the caller can stop polling once the server
+ *   proves this page is not paired (see {@link shouldStopHeartbeat}).
+ */
+export async function sendHeartbeat(): Promise<number> {
+  const response = await fetch('/api/pair/heartbeat', { method: 'POST' })
+  return response.status
+}
+
+/**
+ * Whether a heartbeat answer means "this page can never be accepted again" and
+ * the 10 s wake source should stop: 401 (unpaired, or the device was revoked)
+ * and 403 (the fence refused it) are permanent for this page, while a network
+ * error or a 5xx is transient and keeps the cadence.
+ * @param status - the heartbeat response status.
+ */
+export function shouldStopHeartbeat(status: number): boolean {
+  return status === 401 || status === 403
 }
 
 /** Whether the current page URL carries a pairing token. */
@@ -210,13 +227,36 @@ export interface LanBindFrame {
   pendingRestart?: boolean
 }
 
+/** A failed LAN-bind read, carrying the HTTP status when the server answered. */
+export class LanBindStatusError extends Error {
+  /**
+   * @param status - the response status, or undefined when the request failed
+   *   before a response (network error).
+   * @param message - the diagnostic message.
+   */
+  constructor(public readonly status: number | undefined, message: string) {
+    super(message)
+    this.name = 'LanBindStatusError'
+  }
+}
+
 /** Read the LAN-bind facts (loopback-only endpoint). */
 export async function readLanBindStatus(): Promise<LanBindFrame> {
   const response = await fetch('/api/pair/lan-bind')
-  if (!response.ok) throw new Error(`remote-web-ui: lan-bind status failed with ${String(response.status)}`)
+  if (!response.ok) throw new LanBindStatusError(response.status, `remote-web-ui: lan-bind status failed with ${String(response.status)}`)
   return await response.json() as LanBindFrame
 }
 
+/**
+ * Whether a LAN-bind status failure means this origin can never read the
+ * endpoint (401/403 from the loopback-only fence), so a poll should stop
+ * instead of retrying a known refusal; a transient error keeps the cadence.
+ * @param status - the response status, or undefined for a network failure.
+ */
+export function shouldStopLanBindPoll(status: number | undefined): boolean {
+  return status === 401 || status === 403
+}
+
 /** Human-readable expiry clock, e.g. "10:35". */
 export function formatClock(epochMs: number): string {
   const date = new Date(epochMs)

package/src/client/plugin-card-seat.ts

@@ -0,0 +1,192 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/plugin-card-seat.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Family plugin-card seat.
+ *
+ * A family plugin contributes its settings card to whichever plugin-card seat
+ * the running host actually renders:
+ *
+ * - `web-ui.plugin.item` — the list seat declared by the dsh-web-settings
+ *   group section (this family's own first-level "Web UI plugins" section);
+ * - `plugins.bundle.config` — the official keyed seat of the harness's plugin
+ *   manager page, keyed by the bundle's package name and rendered on that
+ *   bundle's page. alpha.2 removed the `settings.plugin.item` keyed seat of the
+ *   `ui-settings-plugins` tab that this helper used before, so a card keyed by
+ *   its settings namespace has no seat to land in any more.
+ *
+ * SEAT SELECTION IS NOT A DECLARATION PROBE. The official plugin surface
+ * belongs to the harness bundle and declares its seats before any external
+ * plugin's `apply()` runs, so "is the official seat declared?" answers yes even
+ * in the deployment whose whole point is the family group. Choosing on that
+ * probe sends every family card to the official page and leaves the group's own
+ * section permanently empty — the family of reports where the section renders
+ * its heading and zero cards.
+ *
+ * The signal that actually distinguishes the two deployments is whether
+ * dsh-web-settings is loaded: it is the package that owns the group section and
+ * it publishes the `webUiSettings` service during `apply()`, which every
+ * family plugin already reads for its settings form. Group loaded -> the family
+ * seat; group absent -> the official seat.
+ *
+ * The decision is re-evaluated on every `slots/changed` because the group may
+ * apply after this plugin (the family aggregate orders it first, a profile that
+ * installs the group separately need not): the initial contribution goes to the
+ * official seat, then moves to the family seat the moment the group's section
+ * registers. The entry is disposed before the replacement is registered, so a
+ * card is never in two seats at once.
+ *
+ * The shared tree has no client-SDK dependency, so this module reads its
+ * context through the structural shape below; callers pass the plugin's own
+ * `ctx`.
+ */
+
+/** The family list seat key. */
+export const FAMILY_PLUGIN_CARD_SEAT = 'web-ui.plugin.item'
+
+/** The official keyed plugin-card seat key (the alpha.2 bundle-configuration seat). */
+export const OFFICIAL_PLUGIN_CARD_SEAT = 'plugins.bundle.config'
+
+/** The service dsh-web-settings publishes while it is loaded. */
+export const FAMILY_GROUP_SERVICE = 'webUiSettings'
+
+/** The slot-registry member this helper uses (structurally satisfied by ctx.slots). */
+export interface PluginCardSlots {
+  /** Contribution of one card entry. */
+  register(options: never, component: never): unknown
+}
+
+/** The slice of the client context a card contribution needs. */
+export interface PluginCardContext {
+  slots: PluginCardSlots
+  /** Service lookup; absent on a context double that only models the slots. */
+  get?(name: string): unknown
+  /** Event subscription seat; absent on an event-less test double. */
+  on?(event: string, listener: (...args: never[]) => void): unknown
+}
+
+/** Owner share of a family list-seat card (that seat supplies nothing). */
+export interface SettingsPluginItemOwnerProps {
+  /** Marker field: card owner props are intentionally empty. */
+  children?: never
+}
+
+/** One family plugin's card contribution. */
+export interface PluginCardSeat {
+  /**
+   * Npm package name of the bundle this card configures; the official keyed
+   * seat dispatches on it. Every family package ships its own bundle patch, so
+   * a standalone install lists that package as the bundle whose page renders
+   * this card.
+   */
+  bundle: string
+  /** Family list-seat entry id. */
+  id: string
+  /** Family list-seat sort order. */
+  order?: number
+  /** Family list-seat display label; the official keyed seat carries none. */
+  label?: () => string
+  /** Locale namespace the card renders with. */
+  locale: string
+  /** Business-face factory of the registration. */
+  inject?: () => object
+  /**
+   * The card component. Its props type is the seat's composed shape, which is
+   * chosen at runtime, so the helper takes it erased; the registrant keeps its
+   * own precise typing at the call site.
+   */
+  component: unknown
+}
+
+/**
+ * Whether the family group (dsh-web-settings) is loaded in this page. The
+ * service is the group package's own contract, so the probe cannot be fooled
+ * by a harness release that starts declaring the official seat differently.
+ */
+export function familyGroupLoaded(ctx: PluginCardContext): boolean {
+  const get = ctx.get
+  if (typeof get !== 'function') return false
+  try {
+    return get.call(ctx, FAMILY_GROUP_SERVICE) !== undefined
+  } catch {
+    // A context that refuses the lookup: treat the group as absent, which
+    // falls back to the official seat the harness declares.
+    return false
+  }
+}
+
+/** Report a refused registration instead of leaving the user with no card. */
+function warnRefusedSeat(seat: string, error: unknown): void {
+  try {
+    console.warn(`[dsh-web] plugin card registration into "${seat}" was refused; the card will not render`, error)
+  } catch {
+    // Best-effort console write; a failed warning must not break the plugin.
+  }
+}
+
+/**
+ * Contribute one family plugin card to the seat this host renders, following
+ * the group if it loads later. The entry is disposed and re-registered on a
+ * seat change, never duplicated.
+ * @param ctx - client context (its slot registry decides the seat).
+ * @param seat - the card contribution.
+ */
+export function installPluginCard(ctx: PluginCardContext, seat: PluginCardSeat): void {
+  const slots = ctx.slots
+  const component = seat.component as never
+  const inject = seat.inject as never
+
+  let dispose: (() => void) | undefined
+  let current: string | undefined
+  /**
+   * Re-entrancy latch. The registry emits a change event synchronously from
+   * inside both `register` and the previous entry's disposer, so an unguarded
+   * reconcile would re-enter itself mid-move and register the card twice into
+   * the seat it is leaving ("already has an entry for key ...").
+   */
+  let reconciling = false
+
+  /** Reconcile the contribution with the currently live seat (no-op when unchanged). */
+  const reconcile = (): void => {
+    if (reconciling) return
+    const target = familyGroupLoaded(ctx) ? FAMILY_PLUGIN_CARD_SEAT : OFFICIAL_PLUGIN_CARD_SEAT
+    if (current === target) return
+    reconciling = true
+    const previous = dispose
+    dispose = undefined
+    current = undefined
+    previous?.()
+    try {
+      dispose = slots.register((target === FAMILY_PLUGIN_CARD_SEAT
+        ? {
+          name: FAMILY_PLUGIN_CARD_SEAT,
+          id: seat.id,
+          ...(seat.order === undefined ? {} : { order: seat.order }),
+          ...(seat.label === undefined ? {} : { label: seat.label }),
+          locale: seat.locale,
+          ...(seat.inject === undefined ? {} : { inject }),
+        }
+        : {
+          name: OFFICIAL_PLUGIN_CARD_SEAT,
+          key: seat.bundle,
+          locale: seat.locale,
+          ...(seat.inject === undefined ? {} : { inject }),
+        }) as never, component) as () => void
+      current = target
+    } catch (error) {
+      warnRefusedSeat(target, error)
+    } finally {
+      reconciling = false
+    }
+  }
+
+  if (typeof ctx.on === 'function') {
+    try {
+      ctx.on('slots/changed', () => { reconcile() })
+    } catch {
+      // An event seat that refuses the subscription leaves the initial
+      // decision in place; the card still renders in the seat chosen below.
+    }
+  }
+  // The initial decision: the group, when it is already loaded (the aggregate
+  // order), otherwise the official seat the harness declares.
+  reconcile()
+}

package/src/client/remote-channel.ts

@@ -62,7 +62,11 @@ export function remoteChannelRequired(
  * @returns true for localhost, IPv6 loopback, or any 127/8 literal.
  */
 export function isLoopbackHostname(hostname: string): boolean {
-  if (hostname === 'localhost' || hostname === '::1') return true
+  // WHATWG location.hostname keeps IPv6 literals bracketed ("[::1]"); the
+  // host-side shared predicate accepts that spelling, so this browser copy must
+  // too, or an IPv6-loopback origin is judged remote and rewrites every call
+  // onto the gated channel where it can never pair.
+  if (hostname === 'localhost' || hostname === '::1' || hostname === '[::1]') return true
   const parts = hostname.split('.')
   return parts.length === 4 && parts[0] === '127' && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
 }
@@ -228,8 +232,16 @@ export function installRemoteChannel(window: ChannelWindow, options: RemoteChann
     if (device === null) return init
     const headers = init?.headers
     if (typeof Headers !== 'undefined' && headers instanceof Headers) {
-      try { headers.set(RULES.deviceHeader, device) } catch { /* ignore */ }
-      return init
+      // Copy instead of mutating: the instance belongs to the caller, which may
+      // reuse it for a request this channel does not rewrite (the device
+      // credential must not ride along there).
+      try {
+        const copy = new Headers(headers)
+        copy.set(RULES.deviceHeader, device)
+        return { ...init, headers: copy }
+      } catch {
+        return init
+      }
     }
     if (typeof headers === 'object' && headers !== null) {
       return { ...init, headers: { ...(headers as Record<string, string>), [RULES.deviceHeader]: device } } as RequestInit
@@ -253,7 +265,10 @@ export function installRemoteChannel(window: ChannelWindow, options: RemoteChann
         ? rewritten.toString()
         : new Request(rewritten, input)
       return Promise.resolve(originalFetch.call(window, next, attach(init))).then(async (response) => {
-        if (await isUnpairedDenied(response.clone())) options.onUnpaired?.()
+        // The clone tees the response body; only the 403 branch inspects it, so
+        // every other status skips the copy (a large upload or session dump
+        // would otherwise be duplicated per gated request).
+        if (response.status === 403 && await isUnpairedDenied(response.clone())) options.onUnpaired?.()
         else options.onPaired?.()
         return response
       })

package/src/client/remote.module.css

@@ -784,6 +784,44 @@
   gap: 4px;
 }
 
+/* ── Wide foot row ─────────────────────────────────────────────────────────
+
+   The official Settings trigger owns a whole row while the footer actions
+   stack above it, so the trigger's right half sits empty. On the wide column
+   the two share one line (the Settings trigger, then the update and remote
+   triggers) and every other foot
+   child (the usage glance card, another plugin's block) keeps a full row of
+   its own above them. The rail (data-sidebar-collapsed on the frame) keeps
+   the shell's stacked foot, where the circles stack by design. The shell owns
+   the container classes; the semantic suffixes survive its rebuilds. */
+:global([data-dsh-frame]:not([data-sidebar-collapsed])) [class*='footArea'] {
+  flex-direction: row;
+  flex-wrap: wrap;
+  align-items: center;
+}
+
+:global([data-dsh-frame]:not([data-sidebar-collapsed])) [class*='footArea'] > :not([class*='settingsArea']):not([class*='footerActions']) {
+  flex: 1 1 100%;
+  min-width: 0;
+}
+
+:global([data-dsh-frame]:not([data-sidebar-collapsed])) [class*='settingsArea'] {
+  order: 1;
+  /* Content-sized basis: the trigger's own width forces it onto the line after
+     a full-width sibling, then flex-shrink gives the actions their space. */
+  flex: 1 1 auto;
+  width: auto;
+  min-width: 0;
+}
+
+:global([data-dsh-frame]:not([data-sidebar-collapsed])) [class*='footerActions'] {
+  order: 2;
+  flex: none;
+  width: auto;
+  min-width: 0;
+  align-items: center;
+}
+
 /* ── update panel extras ─────────────────────────────────────────────── */
 
 .updateStatus {

package/src/client/settings-form.ts

@@ -8,7 +8,7 @@
  * card-store pattern.
  */
 
-import type { SettingsScope, SettingsScopeSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { ConfigForm, ConfigFormSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
 
@@ -114,7 +114,7 @@ interface PlannedWrite {
   judge: (() => boolean) | undefined
 }
 
-/** One durable write inside the save's atomic scope mutation. */
+/** One durable write inside the save's atomic form mutation. */
 export interface BatchedWrite {
   /** Field this entry writes. */
   field: string
@@ -211,34 +211,34 @@ export class CardForm<T> {
   private readonly specs: Map<string, FieldSpec>
   private readonly staged = new Map<string, StagedEdit>()
   private readonly listeners = new Set<() => void>()
-  /** The scope subscription installed in the constructor; released by dispose(). */
-  private readonly disposeScope: () => void
+  /** The form subscription installed in the constructor; released by dispose(). */
+  private readonly disposeForm: () => void
   private disposed = false
   private saving = false
   private failed = false
   private failedReason: string | undefined
 
-  /** @param scope - the bound settings scope for this card's namespace. */
+  /** @param scope - the bound configuration form for this card's namespace. */
   constructor(
-    private readonly scope: SettingsScope<T>,
+    private readonly scope: ConfigForm<T>,
     specs: FieldSpec[],
   ) {
     this.specs = new Map(specs.map(spec => [spec.field, spec]))
-    this.disposeScope = scope.subscribe(() => { this.publish() })
+    this.disposeForm = scope.subscribe(() => { this.publish() })
   }
 
   /**
-   * Release the scope subscription and every bound store listener. The card
+   * Release the form subscription and every bound store listener. The card
    * must call this on teardown; later calls are no-ops.
    */
   dispose(): void {
     if (this.disposed) return
     this.disposed = true
-    this.disposeScope()
+    this.disposeForm()
     this.listeners.clear()
   }
 
-  /** Publish a projection of this form, rebuilt whenever the scope or a draft changes. */
+  /** Publish a projection of this form, rebuilt whenever the form or a draft changes. */
   bind<S>(project: () => S): SnapshotStore<S> {
     const store = createSnapshotStore(project())
     this.listeners.add(() => { store.set(project()) })
@@ -295,19 +295,19 @@ export class CardForm<T> {
   }
 
   /**
-   * Write every staged edit in one atomic scope mutation, then re-seed from
+   * Write every staged edit in one atomic form mutation, then re-seed from
    * what the Host accepted.
    *
    * The whole batch rides one mutate, so cross-field validate hooks
    * (baseURL+model) judge it as a unit: the Host either applies every write
-   * or refuses the batch. The 0.1.2 scope contract never rejects a refused
-   * mutation — the scope recovers with a fresh Host view and resolves — so
-   * resolution alone proves nothing: the outcome is judged by reading the
-   * settled snapshot back, one planned write at a time, and one missed write
-   * fails the whole save. A scope that still rejects on refusal (the dsh-web
-   * bridge scope) reports through the same failure path with its rejection
-   * message. A save that did not land keeps its drafts, so the user can
-   * correct them instead of retyping.
+   * or refuses the batch. The form contract answers a refusal or a skipped
+   * write with `false` (it recovers with a fresh Host view instead of
+   * throwing), so the outcome is judged twice: the answer itself, and then the
+   * settled snapshot read back one planned write at a time. One missed write
+   * fails the whole save. A transport that rejects instead (the dsh-web bridge
+   * controller on a dead connection) reports through the same failure path
+   * with its rejection message. A save that did not land keeps its drafts, so
+   * the user can correct them instead of retyping.
    * @returns settlement after the mutation and the read-back.
    */
   async save(): Promise<void> {
@@ -323,30 +323,33 @@ export class CardForm<T> {
     this.failed = false
     this.failedReason = undefined
     this.publish()
-    // One atomic namespace mutation: the 0.1.2 scope contract takes ordered
-    // path operations, so the whole staged batch is validated, persisted, and
+    // One atomic namespace mutation: the form contract takes ordered path
+    // operations, so the whole staged batch is validated, persisted, and
     // recovered together — either every write lands or none does.
     const ops: Array<{ op: 'set'; path: string[]; value: string | number | boolean } | { op: 'unset'; path: string[] }> = valid.map(item => item.op.op === 'set'
       ? { op: 'set', path: [item.field], value: (item.op as { value: string | number | boolean }).value }
       : { op: 'unset', path: [item.field] })
     let failedReason: string | undefined
+    let accepted = false
     try {
-      await this.scope.mutate(ops)
+      accepted = await this.scope.mutate(ops)
     } catch (error) {
       failedReason = error instanceof Error ? error.message : String(error)
     }
-    // The 0.1.2 scope resolves even a refused mutation (it recovers with a
-    // fresh view instead of throwing), so resolution alone proves nothing:
-    // judge every planned write against the settled snapshot. The mutation is
-    // atomic, so one missed write fails the whole save and keeps the drafts.
-    const landed = failedReason === undefined && valid.every(item => item.judge())
+    // `false` is the contract's refusal/skip answer, and the form still
+    // resolves after a refusal (it recovers with a fresh view), so the answer
+    // alone is not enough: judge every planned write against the settled
+    // snapshot as well. The mutation is atomic, so one missed write fails the
+    // whole save and keeps the drafts.
+    const landed = accepted && failedReason === undefined && valid.every(item => item.judge())
     for (const [field, before] of pending) {
       if (landed && this.staged.get(field) === before) this.staged.delete(field)
     }
     this.saving = false
     this.failed = !landed
-    // A read-back failure carries no server reason: the card surfaces its
-    // generic failure copy; a rejecting scope (the bridge) adds its message.
+    // A refused or unlanded batch carries no server reason: the card surfaces
+    // its generic failure copy; a rejecting transport (the bridge) adds its
+    // message.
     this.failedReason = failedReason
     this.publish()
   }
@@ -381,7 +384,7 @@ export class CardForm<T> {
    */
   private landedSet(field: string, value: unknown): boolean {
     // A redacted secret never appears in any wire view layer: the Host strips
-    // role('secret') fields and reports them through a sidecar the scope
+    // role('secret') fields and reports them through a sidecar the form
     // snapshot does not expose, so there is nothing to compare the draft
     // against. Settling is the only signal the form has; the rest of the
     // batch, when one exists, still carries the atomic verdict by read-back.
@@ -412,7 +415,7 @@ export class CardForm<T> {
     return spec
   }
 
-  private snapshotOf(): SettingsScopeSnapshot<T> {
+  private snapshotOf(): ConfigFormSnapshot<T> {
     return this.scope.getSnapshot()
   }
 

package/src/console-output.ts

@@ -0,0 +1,97 @@
+// Generated by scripts/sync-shared.mjs from shared/host/console-output.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Console-output capture shared by the family's Host halves.
+ *
+ * A child process's stdout/stderr are raw bytes, and on Windows a console
+ * program writes the OEM code page (CP936/GBK on a zh-CN system), not UTF-8.
+ * Decoding each chunk on its own corrupts the text twice over: the
+ * encoding is guessed wrong, and a multi-byte character split across two reads
+ * decodes into two replacement characters. This capture accumulates raw bytes
+ * under a byte budget and decodes exactly once, at read time.
+ */
+
+/** Bounded byte accumulator for one child process's interleaved stdout/stderr. */
+export interface OutputCapture {
+  /** Append one raw chunk (the bytes are copied into the budget). */
+  push(chunk: Uint8Array): void
+  /**
+   * Decode everything captured so far. Idempotent, so a caller may read the
+   * tail both after a failure branch and at settlement.
+   */
+  read(): string
+}
+
+/** Count the U+FFFD replacement characters one candidate decode produced. */
+function replacementCount(text: string): number {
+  let count = 0
+  for (const character of text) {
+    if (character === '\uFFFD') count += 1
+  }
+  return count
+}
+
+/**
+ * Decode one console byte buffer. Strict UTF-8 wins whenever it is valid;
+ * otherwise the bytes are not UTF-8 at all and the console wrote its own code
+ * page, so the candidate that loses the least text is taken.
+ * @param bytes - the captured bytes.
+ * @returns the decoded text.
+ */
+export function decodeConsoleBytes(bytes: Uint8Array): string {
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  } catch {
+    // Not valid UTF-8. Prefer whichever candidate leaves the fewest
+    // replacement characters so real UTF-8 text carrying one bad byte is not
+    // rewritten wholesale as GBK gibberish; without the legacy code page
+    // (small-ICU builds) the lenient UTF-8 pass is all that is left.
+    let best: string | undefined
+    let bestLoss = Number.POSITIVE_INFINITY
+    for (const label of ['gbk', 'utf-8']) {
+      let text: string
+      try {
+        text = new TextDecoder(label).decode(bytes)
+      } catch {
+        continue
+      }
+      const loss = replacementCount(text)
+      if (loss < bestLoss) {
+        best = text
+        bestLoss = loss
+      }
+    }
+    /* v8 ignore next 3 -- reachable only without the legacy code page AND without the lenient pass */
+    if (best === undefined) return Buffer.from(bytes).toString('utf8')
+    return best
+  }
+}
+
+/**
+ * Create a capture bounded to a byte budget. Overflow drops from the FRONT
+ * (the tail is what carries a failure reason), and the cut never lands inside
+ * a character: leading UTF-8 continuation bytes are dropped with it, and a
+ * legacy code page's dangling lead byte — indistinguishable from a real byte
+ * without knowing the encoding until the whole buffer is decoded — is removed
+ * with the one replacement character it produced, so an over-long stream still
+ * reads cleanly at the seam.
+ * @param maxBytes - maximum retained bytes.
+ * @returns the capture.
+ */
+export function createOutputCapture(maxBytes: number): OutputCapture {
+  let buffer = Buffer.alloc(0)
+  let trimmed = false
+  return {
+    push(chunk: Uint8Array): void {
+      buffer = buffer.length === 0 ? Buffer.from(chunk) : Buffer.concat([buffer, Buffer.from(chunk)])
+      if (buffer.length <= maxBytes) return
+      let start = buffer.length - maxBytes
+      while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) start += 1
+      buffer = Buffer.from(buffer.subarray(start))
+      trimmed = true
+    },
+    read(): string {
+      const text = decodeConsoleBytes(buffer)
+      return trimmed && text.startsWith('\uFFFD') ? text.slice(1) : text
+    },
+  }
+}

package/src/http.ts

@@ -2,7 +2,9 @@
 /**
  * Shared JSON body/response helpers for the host route families: one strict
  * bounded body reader, one lenient bounded body reader, one JSON object
- * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * narrow, one JSON writer, and the outbound request-init helper that keeps a
+ * host fetch body decodable (withIdentityEncoding). Previously the readers
+ * were copy-pasted across the
  * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
  * family's route module) with drifting contracts: body caps ranging 4 KiB to
  * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
@@ -88,6 +90,26 @@ export function asJsonObject(value: unknown): Record<string, unknown> | undefine
   return isJsonObject(value) ? value : undefined
 }
 
+/**
+ * Request init that asks a remote origin for an uncompressed body.
+ *
+ * The DSH host boots `@deepseek-ai/dsh-http-proxy`, whose top-level import of
+ * the npm `undici` copy replaces the legacy `undici.globalDispatcher.1` slot
+ * Node's built-in `fetch()` reads. That cross-major wrapper drops the
+ * `content-encoding` header and automatic decompression, so a plain fetch
+ * resolves to raw gzip/brotli/zstd bytes — compressed noise no JSON or text
+ * consumer can read. Every host fetch that parses a remote body must request
+ * identity encoding. Caller headers survive; `accept-encoding` is forced to
+ * `identity` because a caller value has no decoder behind it in this host.
+ * @param init - the caller's request init (signal, headers, method, ...).
+ * @returns a copy with `accept-encoding: identity` merged in.
+ */
+export function withIdentityEncoding(init: RequestInit = {}): RequestInit {
+  const headers = new Headers(init.headers)
+  headers.set('accept-encoding', 'identity')
+  return { ...init, headers }
+}
+
 /**
  * Write one JSON response. Default headers are the family defaults
  * (content-type and referrer-policy); caller headers are appended or