chainlesschain 0.162.160 → 0.162.161

package/src/lib/backpressure-policy.js

@@ -0,0 +1,105 @@
+/**
+ * Outbound backpressure policy — bounds server→client buffering when a
+ * consumer drains too slowly, so a stuck WS client can't grow the sender's
+ * memory without limit (the classic slow-consumer blowup) and the UI degrades
+ * explicitly instead of freezing.
+ *
+ * Pure + deterministic (no transport, no timers): the caller feeds the
+ * transport's current queued-byte count (e.g. `ws.bufferedAmount`) and a frame
+ * class; the policy decides send-vs-drop with hysteresis and reports the
+ * lag-episode transitions the caller turns into a notice.
+ *
+ * Designed to compose with EventReplayBuffer (event-seq-replay.js): a dropped
+ * *droppable* frame should still be RECORDED (it gets a seq and stays in the
+ * bounded replay buffer), just not sent. The seq gap on the next *sent* frame
+ * then trips the consumer's SeqGapTracker, which requests replaySince — so the
+ * dropped frames are recovered once the consumer catches up (or a truncated
+ * replay tells it to full-resync). Critical frames are never dropped.
+ */
+
+const DEFAULT_HIGH_WATER_BYTES = 4 << 20; // 4 MiB queued → consumer is behind
+const DEFAULT_LOW_WATER_BYTES = 1 << 20; // 1 MiB → considered caught up again
+
+/** A frame that must always be delivered (lifecycle, errors, acks). */
+export const CRITICAL = "critical";
+/** A frame safe to drop under pressure and recover via replay/resync. */
+export const DROPPABLE = "droppable";
+
+export class BackpressurePolicy {
+  constructor({
+    highWaterBytes = DEFAULT_HIGH_WATER_BYTES,
+    lowWaterBytes = DEFAULT_LOW_WATER_BYTES,
+  } = {}) {
+    const high = Math.max(
+      1,
+      Math.floor(highWaterBytes) || DEFAULT_HIGH_WATER_BYTES,
+    );
+    // Low water must sit below high water or hysteresis collapses to a flapping
+    // single threshold; clamp it to at most high-1.
+    const low = Math.min(Math.max(0, Math.floor(lowWaterBytes) || 0), high - 1);
+    this._high = high;
+    this._low = low;
+    this._lagging = false;
+    this._dropped = 0; // dropped since the CURRENT lag episode started
+    this._droppedTotal = 0; // dropped across the whole connection
+  }
+
+  /** True while the consumer is behind (buffered ≥ high, until it drains ≤ low). */
+  get lagging() {
+    return this._lagging;
+  }
+
+  /** Frames dropped across the whole connection. */
+  get droppedTotal() {
+    return this._droppedTotal;
+  }
+
+  /**
+   * Decide what to do with one outbound frame.
+   * @param {number} bufferedBytes transport's currently-queued bytes
+   *   (`ws.bufferedAmount`); non-finite → treated as 0 (never lags).
+   * @param {"critical"|"droppable"} frameClass
+   * @returns {{send:boolean, drop:boolean, lagStarted:boolean, lagEnded:boolean,
+   *   dropped:number}} `dropped` = count dropped in the episode that just
+   *   started/ended (for the caller's notice); `send:false` only ever for a
+   *   droppable frame while lagging.
+   */
+  evaluate(bufferedBytes, frameClass) {
+    const b = Number.isFinite(bufferedBytes) ? bufferedBytes : 0;
+    let lagStarted = false;
+    let lagEnded = false;
+
+    if (!this._lagging && b >= this._high) {
+      this._lagging = true;
+      this._dropped = 0;
+      lagStarted = true;
+    } else if (this._lagging && b <= this._low) {
+      this._lagging = false;
+      lagEnded = true;
+    }
+
+    // While lagging, shed droppable frames to let the buffer drain; critical
+    // frames (and everything while not lagging) always go out.
+    if (this._lagging && frameClass === DROPPABLE) {
+      this._dropped += 1;
+      this._droppedTotal += 1;
+      return {
+        send: false,
+        drop: true,
+        lagStarted,
+        lagEnded,
+        dropped: this._dropped,
+      };
+    }
+
+    // `dropped` carries the episode's running count so a lag-end notice can
+    // report how many droppable frames were shed.
+    return {
+      send: true,
+      drop: false,
+      lagStarted,
+      lagEnded,
+      dropped: this._dropped,
+    };
+  }
+}

package/src/lib/capability-negotiation.js

@@ -0,0 +1,212 @@
+/**
+ * Bidirectional capability negotiation with N / N-1 downgrade for Agent
+ * Protocol (agent-sdk docs/PROTOCOL.md §1.3).
+ *
+ * The CLI advertises what it can speak one-directionally (buildAgentCapabilities
+ * → `cc agent --capabilities`, and the `system/init` line's protocol_version).
+ * That is not negotiation: a client (VS Code / JetBrains panel) had no way to
+ * announce what IT understands, and the CLI had no rule to pick a common level
+ * or step DOWN when the two disagree. When the protocol later grows a v2 line
+ * shape, a v1-only client would silently mis-parse it.
+ *
+ * This module is the missing algorithm. A client MAY send a `hello` as its
+ * first stream-json input line:
+ *   {"type":"hello","protocol_version":2,"min_protocol_version":1,
+ *    "features":["event_seq","trace_id"]}
+ * The CLI negotiates it against its own offer and echoes the agreed level as a
+ * `system/negotiated` line, then honors it for the rest of the run.
+ *
+ * Rules:
+ *   - agreedVersion = min(server.max, client.max)  — never above what either
+ *     can parse.
+ *   - Incompatible when agreedVersion < max(server.min, client.min): the two
+ *     version ranges don't overlap. ok:false — the caller keeps a safe baseline
+ *     or errors out; it never speaks a version the peer can't read.
+ *   - effective features = the server-offered features the client also accepts
+ *     (intersection), minus any whose minimum protocol version is above the
+ *     agreed version (an N-only field is dropped for an N-1 session).
+ *   - No client offer at all → legacy client that predates negotiation. The
+ *     additive fields are defined "consumers MUST tolerate absence AND
+ *     presence" (docs/PROTOCOL.md §1.2.1), so we keep FULL behavior unchanged
+ *     (byte-for-byte) and mark clientAware:false. Negotiation only ever
+ *     RESTRICTS when a client explicitly narrows the set.
+ *
+ * Pure: no fs / process / clock. The same algorithm is mirrored in the Java
+ * twin (jetbrains-plugin CapabilityNegotiation.java); both read the shared
+ * fixture __tests__/fixtures/capability-negotiation-cases.json.
+ */
+
+/** The current protocol version the CLI speaks (mirror of PROTOCOL_VERSION). */
+export const PROTOCOL_VERSION = 1;
+
+/**
+ * The oldest protocol version the CLI can still speak end-to-end (the N-1 in
+ * "N / N-1"). At v1 there is no older line shape, so min === current; once v2
+ * ships this drops to 1 so a v1-only client negotiates a v1 session.
+ */
+export const PROTOCOL_MIN_VERSION = 1;
+
+/**
+ * The wire-protocol features subject to negotiation — the additive per-line
+ * fields a client may or may not understand. Runtime capabilities (bare,
+ * worktree, mcp, …) are NOT negotiated: they change what the CLI can do, not
+ * the shape of a line the client must parse.
+ */
+export const PROTOCOL_FEATURES = ["event_seq", "tool_use_id", "trace_id"];
+
+/**
+ * Minimum protocol version a feature requires. Empty today (every current
+ * feature is a v1 additive field). When a v2 field lands, add it here so an
+ * N-1 (v1) session drops it automatically.
+ * @type {Record<string, number>}
+ */
+export const FEATURE_MIN_VERSION = {};
+
+function intOr(value, fallback) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+/**
+ * Coerce a features declaration into a sorted, de-duplicated array of keys.
+ * Accepts an array of strings, or an object whose truthy keys are the features
+ * (the nested manifest shape). Anything else → [].
+ * @returns {string[]}
+ */
+export function normalizeFeatureList(input) {
+  let keys;
+  if (Array.isArray(input)) {
+    keys = input.filter((k) => typeof k === "string" && k);
+  } else if (input && typeof input === "object") {
+    keys = Object.keys(input).filter((k) => input[k]);
+  } else {
+    return [];
+  }
+  return [...new Set(keys)].sort();
+}
+
+/**
+ * Extract the server's negotiation offer from a `cc agent --capabilities`
+ * manifest (buildAgentCapabilities output). Only the negotiable wire features
+ * the manifest advertises truthy are offered.
+ * @param {object} manifest
+ * @returns {{protocolVersion:number, minProtocolVersion:number, features:string[]}}
+ */
+export function buildServerOffer(manifest = {}) {
+  const protocolVersion = intOr(manifest.protocol_version, PROTOCOL_VERSION);
+  const minProtocolVersion = intOr(
+    manifest.min_protocol_version,
+    Math.min(PROTOCOL_MIN_VERSION, protocolVersion),
+  );
+  const advertised = normalizeFeatureList(manifest.features);
+  const features = PROTOCOL_FEATURES.filter((f) => advertised.includes(f));
+  return { protocolVersion, minProtocolVersion, features };
+}
+
+/**
+ * Negotiate the effective protocol version + feature set between a server offer
+ * and a client offer.
+ *
+ * @param {{protocolVersion:number, minProtocolVersion?:number, features:string[]}} server
+ * @param {null|{protocolVersion?:number, minProtocolVersion?:number, features?:string[]}} clientOffer
+ * @param {object} [opts]
+ * @param {Record<string,number>} [opts.featureMinVersion=FEATURE_MIN_VERSION]
+ * @returns {{
+ *   ok:boolean, agreedVersion:(number|null), features:string[],
+ *   downgraded:boolean, disabledFeatures:string[], clientAware:boolean,
+ *   reason:(string|null)
+ * }}
+ */
+export function negotiateProtocol(server = {}, clientOffer = null, opts = {}) {
+  const featureMinVersion = opts.featureMinVersion || FEATURE_MIN_VERSION;
+  const serverMax = intOr(server.protocolVersion, PROTOCOL_VERSION);
+  const serverMin = intOr(server.minProtocolVersion, serverMax);
+  const serverFeatures = normalizeFeatureList(server.features);
+
+  const versionOk = (f, v) => (featureMinVersion[f] || 0) <= v;
+
+  // No client offer → legacy peer. Keep full behavior (only version-gate the
+  // server's own features against its own max), byte-for-byte unchanged.
+  if (clientOffer == null) {
+    return {
+      ok: true,
+      agreedVersion: serverMax,
+      features: serverFeatures.filter((f) => versionOk(f, serverMax)),
+      downgraded: false,
+      disabledFeatures: [],
+      clientAware: false,
+      reason: null,
+    };
+  }
+
+  const clientMax = intOr(clientOffer.protocolVersion, serverMax);
+  const clientMin = intOr(clientOffer.minProtocolVersion, clientMax);
+  const agreedVersion = Math.min(serverMax, clientMax);
+  const floor = Math.max(serverMin, clientMin);
+
+  if (agreedVersion < floor) {
+    return {
+      ok: false,
+      agreedVersion: null,
+      features: [],
+      downgraded: true,
+      disabledFeatures: [...serverFeatures].sort(),
+      clientAware: true,
+      reason:
+        `no common protocol version (server ${serverMin}-${serverMax}, ` +
+        `client ${clientMin}-${clientMax})`,
+    };
+  }
+
+  // A client that omits `features` accepts whatever the agreed version offers;
+  // a client that sends the array narrows to the intersection.
+  const clientFeatures =
+    clientOffer.features === undefined
+      ? null
+      : new Set(normalizeFeatureList(clientOffer.features));
+
+  const enabled = [];
+  const disabled = [];
+  for (const f of serverFeatures) {
+    const okVersion = versionOk(f, agreedVersion);
+    const okClient = clientFeatures == null || clientFeatures.has(f);
+    if (okVersion && okClient) enabled.push(f);
+    else disabled.push(f);
+  }
+
+  return {
+    ok: true,
+    agreedVersion,
+    features: enabled.sort(),
+    downgraded: agreedVersion < serverMax || disabled.length > 0,
+    disabledFeatures: disabled.sort(),
+    clientAware: true,
+    reason: null,
+  };
+}
+
+/** Feature key → the stream line field it gates. */
+const FEATURE_TO_FIELD = {
+  event_seq: "seq",
+  trace_id: "trace_id",
+  tool_use_id: "tool_use_id",
+};
+
+/**
+ * Fold a negotiation result into a live field-gate the emitter reads per line:
+ * a field stays stamped only if its feature survived negotiation. On an
+ * incompatible (ok:false) result nothing is changed (the caller keeps its safe
+ * baseline). Mutates `gate` in place and returns it.
+ *
+ * @param {{features:string[], ok:boolean}} result
+ * @param {{seq?:boolean, trace_id?:boolean, tool_use_id?:boolean}} gate
+ */
+export function applyNegotiationToGate(result, gate = {}) {
+  if (!result || result.ok === false) return gate;
+  const enabled = new Set(result.features || []);
+  for (const feature of PROTOCOL_FEATURES) {
+    const field = FEATURE_TO_FIELD[feature];
+    if (field) gate[field] = enabled.has(feature);
+  }
+  return gate;
+}

package/src/lib/credential-guard.js

@@ -213,6 +213,17 @@ const PRINT_COMMANDS = new Set([
 const SECRET_VAR_RE =
   /(?:^|_)(KEY|KEYS|TOKEN|SECRET|SECRETS|PASSWORD|PASSWD|PASSPHRASE|CREDENTIAL|CREDENTIALS|PRIVATE|APIKEY|ACCESSKEY)(?:_|$)/i;
 
+/**
+ * True when an environment-variable NAME looks like it holds a secret
+ * (ANTHROPIC_API_KEY, GITHUB_TOKEN, DB_PASSWORD, …). Shared single source of
+ * truth so the credential READ guard and the credential PROXY
+ * ([[credential-proxy.js]] — which keeps secrets out of subprocess envs)
+ * classify identically. `MONKEY`/`KEYBOARD`/`TOKENIZER` do NOT match.
+ */
+export function isSecretEnvName(name) {
+  return typeof name === "string" && SECRET_VAR_RE.test(name);
+}
+
 // Ways a secret var is referenced inside a shell segment.
 const SECRET_REF_PATTERNS = [
   /\$env:([A-Za-z_][A-Za-z0-9_]*)/gi, // PowerShell  $env:NAME

package/src/lib/credential-proxy.js

@@ -0,0 +1,182 @@
+/**
+ * Credential proxy — keep the agent's real, long-lived credentials out of the
+ * environment that run_shell / run_code / hook / plugin subprocesses inherit
+ * (P0 §"跨平台沙箱与凭据代理").
+ *
+ * By default a spawned command inherits the WHOLE parent environment — including
+ * the agent's ANTHROPIC_API_KEY, cloud keys and tokens. A compromised or
+ * careless command can then echo, log, or exfiltrate them. This module replaces
+ * credential-named vars with an opaque SENTINEL before the child starts and
+ * keeps the real values in a parent-held vault, to be injected only for an
+ * approved host (via the egress proxy) — never handed to the child wholesale.
+ * The audit log only ever sees redacted values, never a restored secret.
+ *
+ * Pairs with credential-guard.js: that guard stops the AGENT reading secrets
+ * into model context; this stops the SUBPROCESS inheriting them. Both classify
+ * secret var names through the same `isSecretEnvName` so they never drift.
+ *
+ * Opt-in for now (`CC_CREDENTIAL_PROXY=1` or `config.credentialProxy.enabled`)
+ * so existing workflows that legitimately read a token from env keep working;
+ * default-on is the eventual goal once per-host injection is wired everywhere.
+ * Pure + dependency-light so every spawn seam can share it.
+ */
+
+import { isSecretEnvName } from "./credential-guard.js";
+
+/** Opaque replacement a masked credential var carries into the child env. */
+export const CREDENTIAL_SENTINEL_PREFIX = "cc-cred-redacted:";
+
+/**
+ * Well-known credential vars whose NAME does not obviously match the generic
+ * KEY/TOKEN/SECRET/PASSWORD pattern. Most real ones already match; this is a
+ * small safety net, extendable per-project via `deny`.
+ */
+const EXTRA_CREDENTIAL_NAMES = new Set([
+  "AWS_SESSION_TOKEN", // matches TOKEN, kept explicit
+  "GOOGLE_APPLICATION_CREDENTIALS", // path to a key file
+  "CLOUDSDK_AUTH_ACCESS_TOKEN",
+  "DIGITALOCEAN_ACCESS_TOKEN",
+]);
+
+function toSet(value) {
+  if (value instanceof Set) return value;
+  return new Set(Array.isArray(value) ? value : value ? [value] : []);
+}
+
+/**
+ * Classify an env var NAME as credential-bearing. `opts.allow` forces
+ * pass-through (never masked); `opts.deny` forces masking; otherwise the shared
+ * secret-name classifier + the curated extra set decide.
+ */
+export function isCredentialEnvName(name, opts = {}) {
+  if (typeof name !== "string" || !name) return false;
+  if (toSet(opts.allow).has(name)) return false;
+  if (toSet(opts.deny).has(name)) return true;
+  return isSecretEnvName(name) || EXTRA_CREDENTIAL_NAMES.has(name);
+}
+
+/** The sentinel a child sees in place of a credential's real value. */
+export function makeSentinel(name) {
+  return CREDENTIAL_SENTINEL_PREFIX + String(name ?? "");
+}
+
+/** True when a value is a proxy sentinel (carries no secret). */
+export function isSentinel(value) {
+  return (
+    typeof value === "string" && value.startsWith(CREDENTIAL_SENTINEL_PREFIX)
+  );
+}
+
+/**
+ * Mask credential-named vars in `env`. Returns a NEW object (never mutates the
+ * input):
+ *   - `env`    — credential vars replaced with a sentinel (mode "mask", the
+ *                default) or removed entirely (mode "deny"); everything else
+ *                copied through verbatim.
+ *   - `masked` — sorted list of the var names that were masked/removed.
+ *   - `vault`  — Map<name, realValue> the PARENT keeps for approved injection;
+ *                the child never receives it.
+ * Values that are already sentinels, null, or undefined are left as-is (a
+ * sentinel is never double-masked; an absent var is not invented).
+ */
+export function maskCredentialEnv(env = {}, opts = {}) {
+  const mode = opts.mode === "deny" ? "deny" : "mask";
+  const out = {};
+  const masked = [];
+  const vault = new Map();
+  for (const [name, value] of Object.entries(env || {})) {
+    if (
+      value != null &&
+      !isSentinel(value) &&
+      isCredentialEnvName(name, opts)
+    ) {
+      masked.push(name);
+      vault.set(name, String(value));
+      if (mode === "mask") out[name] = makeSentinel(name);
+      // mode "deny": drop the var so the child does not even see a sentinel
+    } else {
+      out[name] = value;
+    }
+  }
+  masked.sort();
+  return { env: out, masked, vault };
+}
+
+/** Replace a secret value with a fixed marker — never the real value. */
+export function redactSecretValue(value) {
+  if (value == null) return value;
+  return String(value) ? "***" : "";
+}
+
+/**
+ * A log-safe projection of an env for the audit trail: credential values →
+ * "***", sentinels kept verbatim (they hold no secret), everything else
+ * untouched. NEVER emits a restored/real credential value.
+ */
+export function redactEnvForAudit(env = {}, opts = {}) {
+  const out = {};
+  for (const [name, value] of Object.entries(env || {})) {
+    if (isSentinel(value)) out[name] = value;
+    else if (isCredentialEnvName(name, opts))
+      out[name] = redactSecretValue(value);
+    else out[name] = value;
+  }
+  return out;
+}
+
+/**
+ * Resolve the real value for a masked credential — but ONLY when the target
+ * host is on the approved list. The whole point of the proxy is that the child
+ * never gets the raw secret; the parent injects it just-in-time for an approved
+ * destination (e.g. the egress proxy adding Authorization for an allowed API
+ * host). Returns null (fail closed) for an unknown var, an empty host, or a
+ * non-approved host.
+ */
+export function resolveApprovedInjection(vault, name, opts = {}) {
+  if (!(vault instanceof Map) || !vault.has(name)) return null;
+  const host = String(opts.host || "").toLowerCase();
+  if (!host) return null;
+  const approved = (opts.approvedHosts || []).map((h) =>
+    String(h || "").toLowerCase(),
+  );
+  return approved.includes(host) ? vault.get(name) : null;
+}
+
+/**
+ * Resolve whether the credential proxy is enabled. Env var wins so a spawn
+ * seam without config access can still honor it; otherwise the config flag.
+ */
+export function credentialProxyEnabled(config = {}, env = process.env) {
+  const raw = env && env.CC_CREDENTIAL_PROXY;
+  if (raw != null) {
+    const v = String(raw).toLowerCase();
+    return v === "1" || v === "true" || v === "on" || v === "yes";
+  }
+  return config?.credentialProxy?.enabled === true;
+}
+
+/**
+ * Apply the credential proxy to a child env when enabled; otherwise return the
+ * env UNCHANGED (same reference — the default path stays byte-identical). The
+ * returned `vault` lets the caller inject approved creds later.
+ *
+ * @returns {{env:object, masked:string[], vault:Map, enabled:boolean}}
+ */
+export function applyCredentialProxy(env, options = {}) {
+  const procEnv = options.env || process.env;
+  const config = options.config || {};
+  if (!credentialProxyEnabled(config, procEnv)) {
+    return { env, masked: [], vault: new Map(), enabled: false };
+  }
+  const allow = new Set([
+    ...toSet(options.allow),
+    ...(config?.credentialProxy?.allow || []),
+  ]);
+  const deny = new Set([
+    ...toSet(options.deny),
+    ...(config?.credentialProxy?.deny || []),
+  ]);
+  const mode = options.mode || config?.credentialProxy?.mode || "mask";
+  const result = maskCredentialEnv(env, { allow, deny, mode });
+  return { ...result, enabled: true };
+}

package/src/lib/event-seq-replay.js

@@ -0,0 +1,167 @@
+/**
+ * Event-stream gap-detection + replay primitives — the server→client (event)
+ * counterpart to the client→server RemoteCommandLedger (harness/
+ * remote-command-ledger.js). Both give a reconnecting peer an at-most-once,
+ * totally-ordered view over a lossy transport; the ledger orders *commands*,
+ * this orders *events*.
+ *
+ * A producer keeps a bounded buffer of recently emitted, seq-stamped frames
+ * (EventReplayBuffer); a reconnecting consumer reports its last-seen seq and
+ * gets the tail re-sent, or is told to full-resync when the missed range has
+ * already been evicted. A consumer detects holes with SeqGapTracker.
+ *
+ * Pure + deterministic: no I/O, no timers, no globals. The `seq` it stamps is
+ * the same additive protocol-v1 notion used on the stream-json surface
+ * (agent-sdk docs/PROTOCOL.md §1.2.1) — 1-based, monotonic, per producer
+ * instance; consumers MUST tolerate its absence and MUST NOT require gap-free
+ * numbering across a producer restart (a fresh instance rewinds to 1).
+ */
+
+const DEFAULT_MAX_EVENTS = 512;
+const DEFAULT_MAX_BYTES = 1 << 20; // 1 MiB — bound memory on a chatty session
+
+/** Best-effort byte size of a frame (overridable for deterministic tests). */
+function approxBytes(frame) {
+  try {
+    return Buffer.byteLength(JSON.stringify(frame));
+  } catch {
+    return 0; // circular / unserializable — don't let sizing throw
+  }
+}
+
+/**
+ * Producer-side bounded replay buffer. `record(frame)` stamps the next `seq`
+ * onto a shallow copy, retains it (evicting the oldest beyond count/byte
+ * bounds), and returns the stamped frame ready to send. `replaySince(cursor)`
+ * returns the frames a consumer with last-seen seq `cursor` still needs.
+ */
+export class EventReplayBuffer {
+  constructor({
+    maxEvents = DEFAULT_MAX_EVENTS,
+    maxBytes = DEFAULT_MAX_BYTES,
+    sizeOf,
+  } = {}) {
+    this._max = Math.max(1, Math.floor(maxEvents) || DEFAULT_MAX_EVENTS);
+    this._maxBytes = Math.max(0, Math.floor(maxBytes) || 0);
+    this._sizeOf = typeof sizeOf === "function" ? sizeOf : approxBytes;
+    this._buf = []; // [{ seq, frame, bytes }] oldest → newest
+    this._seq = 0;
+    this._bytes = 0;
+  }
+
+  /** Highest seq stamped so far (0 before anything is recorded). */
+  get latestSeq() {
+    return this._seq;
+  }
+
+  /** Oldest seq still retained (== latestSeq when the buffer is empty). */
+  get oldestSeq() {
+    return this._buf.length ? this._buf[0].seq : this._seq;
+  }
+
+  /** Number of frames currently retained. */
+  get size() {
+    return this._buf.length;
+  }
+
+  /**
+   * Stamp the next seq onto `frame` (shallow copy), retain it, evict overflow.
+   * @returns the stamped frame (`{ ...frame, seq }`) to hand straight to send.
+   */
+  record(frame) {
+    const seq = ++this._seq;
+    const stamped = { ...frame, seq };
+    const bytes = this._sizeOf(stamped) || 0;
+    this._buf.push({ seq, frame: stamped, bytes });
+    this._bytes += bytes;
+    this._evict();
+    return stamped;
+  }
+
+  _evict() {
+    // Always keep at least the newest frame even if it alone exceeds maxBytes.
+    while (
+      this._buf.length > this._max ||
+      (this._maxBytes > 0 &&
+        this._bytes > this._maxBytes &&
+        this._buf.length > 1)
+    ) {
+      const dropped = this._buf.shift();
+      this._bytes -= dropped.bytes;
+    }
+  }
+
+  /**
+   * Frames a consumer whose last-seen seq is `cursor` still needs.
+   *  - `cursor >= latestSeq` → nothing missed → `{ frames: [], truncated: false }`.
+   *  - `cursor` still within the retained window → the exact tail after it.
+   *  - `cursor` older than what's retained → the gap was evicted →
+   *    `truncated: true` (consumer MUST full-resync; the returned frames are
+   *    only the retained suffix, not the whole hole).
+   * @param {number} cursor last seq the consumer acknowledged (default 0 = all)
+   */
+  replaySince(cursor = 0) {
+    const c = Number.isFinite(cursor) ? cursor : 0;
+    if (c >= this._seq) {
+      return { frames: [], truncated: false, from: c, to: this._seq };
+    }
+    // The lowest cursor we can honor without a hole is (oldest retained − 1).
+    const floor = this._buf.length ? this._buf[0].seq - 1 : this._seq;
+    const truncated = c < floor;
+    const frames = this._buf.filter((e) => e.seq > c).map((e) => e.frame);
+    return { frames, truncated, from: c, to: this._seq };
+  }
+}
+
+const OK = Object.freeze({ status: "ok" });
+
+/**
+ * Consumer-side sequence tracker. Feed it each received frame's `seq`; it
+ * reports contiguity so the consumer can request a replay on a hole and drop
+ * duplicates a reconnect re-sent. One tracker per producer epoch — reset it
+ * when the transport hands you a fresh producer instance (e.g. a non-reattach
+ * bg-attach reply), since a fresh producer rewinds seq to 1.
+ */
+export class SeqGapTracker {
+  constructor() {
+    this._last = 0;
+    this._started = false;
+  }
+
+  /** Last contiguous seq accepted (0 before the first frame). */
+  get lastSeq() {
+    return this._last;
+  }
+
+  /**
+   * @param {number} seq the received frame's seq (absent/NaN on older
+   *   producers that don't stamp — treated as always-ok, never a gap).
+   * @returns {{status:"ok"}|{status:"duplicate"}|{status:"gap",from:number,to:number}}
+   *   - `ok`: contiguous (or the first frame, or an unstamped frame).
+   *   - `duplicate`: `seq <= lastSeq` — already seen; drop it.
+   *   - `gap`: `seq > lastSeq + 1` — frames `(from, to)` were missed; ask the
+   *     producer for `replaySince(from)`. The tracker adopts `to` as current.
+   */
+  observe(seq) {
+    if (!Number.isFinite(seq)) return OK; // unstamped producer — tolerate
+    if (!this._started) {
+      this._started = true;
+      this._last = seq;
+      return OK;
+    }
+    if (seq === this._last + 1) {
+      this._last = seq;
+      return OK;
+    }
+    if (seq <= this._last) return { status: "duplicate" };
+    const from = this._last;
+    this._last = seq; // adopt new position; caller replays the (from, to) hole
+    return { status: "gap", from, to: seq };
+  }
+
+  /** Forget all history (call when attaching to a fresh producer instance). */
+  reset() {
+    this._last = 0;
+    this._started = false;
+  }
+}