@byok-sdk/client 0.4.0 → 0.4.1

package/dist/adapters/pi/resolve-bin.d.ts

@@ -25,7 +25,7 @@ export interface ResolvedBin {
  * only ever constructs `new PiAdapter()` with no options (see `createDaemon`),
  * so an out-of-process substitution (e.g. examples/basic's e2e run swapping
  * in the fake-pi fixture, or a single-file product injecting its required
- * Node 22.19+ pi sidecar) has no other seam to use.
+ * Node 22.22+ pi sidecar) has no other seam to use.
  *
  * Deliberately does NOT use `createRequire(...).resolve()`: this package is
  * pure ESM with no `require` export condition (`exports["."]` only offers

package/dist/adapters/pi/rpc-client.d.ts

@@ -66,7 +66,13 @@ export declare class PiRpcClient {
      * a post-mortem on a failed/hung task has it without separate log scraping.
      */
     recordUnmappedFrame(type: string): void;
-    /** Immediate process-tree termination request. `dispose()` is the settlement receipt. */
+    /**
+     * Immediate process-tree termination request. `dispose()` is the settlement
+     * receipt, so this stays fire-and-forget: an interrupt must not block on a
+     * terminator. A request that could not be spawned is left unrecorded, so
+     * `dispose()` re-issues it and raises the typed `stage:'signal'` failure —
+     * swallowing it here loses nothing.
+     */
     kill(): void;
     waitClosed(): Promise<void>;
     dispose(): Promise<void>;

package/dist/adapters/process-tree.d.ts

@@ -1,4 +1,5 @@
-import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import { spawn, type ChildProcess, type SpawnOptions } from 'node:child_process';
+type KillFn = (pid: number, signal: NodeJS.Signals | number) => void;
 export interface OwnedProcessTreeOptions {
     child: ChildProcess;
     waitClosed: () => Promise<void>;
@@ -6,6 +7,12 @@ export interface OwnedProcessTreeOptions {
     label: string;
     termGraceMs?: number;
     killGraceMs?: number;
+    /** DI seam — defaults to `process.platform`. Lets the win32 branch be exercised from POSIX CI, mirroring `util/secure-dir.ts`'s identical convention. */
+    platform?: NodeJS.Platform;
+    /** DI seam for the win32 `taskkill` sweep — defaults to `node:child_process`'s `spawn`. */
+    spawnFn?: typeof spawn;
+    /** DI seam for liveness probing — defaults to `process.kill`. */
+    killFn?: KillFn;
 }
 /**
  * Every bundled runtime root is an owned process-group leader on POSIX. Pipes
@@ -13,7 +20,41 @@ export interface OwnedProcessTreeOptions {
  * the runtime outlive the daemon. Windows uses taskkill's `/T` tree authority.
  */
 export declare function withOwnedProcessTree<T extends SpawnOptions>(options: T): T;
-/** Immediate termination request used by interrupt paths; close remains the receipt. */
-export declare function requestOwnedProcessTreeTermination(options: OwnedProcessTreeOptions): void;
-/** Resolve only after the adapter-owned root and descendants are quiescent. */
+/**
+ * Immediate termination request used by interrupt paths; close remains the
+ * receipt. On win32 the request also RECORDS the pid set taskkill walked,
+ * which is what {@link disposeOwnedProcessTree} later measures — so an
+ * interrupt that is fired and forgotten still leaves disposal a measurable
+ * tree. A request that could not be spawned records nothing, which makes
+ * disposal re-issue it and surface `stage:'signal'` itself.
+ */
+export declare function requestOwnedProcessTreeTermination(options: OwnedProcessTreeOptions): Promise<void>;
+/**
+ * Resolve only after the adapter-owned root and descendants are quiescent.
+ *
+ * POSIX measures the owned process GROUP; win32 measures the pid set taskkill
+ * reported walking (`stage:'quiescence'` names how many of those were still
+ * alive at the deadline). Neither platform reads a terminator's exit status:
+ * on win32 `stage:'signal'` now means only that taskkill could not be spawned.
+ * `close` stays the final receipt on both — it is the stdio-flush guarantee,
+ * not the liveness proof.
+ *
+ * Grace budget: each phase carries its own full grace on both platforms. On
+ * win32 the quiescence poll gets `killGraceMs` and the close wait that follows
+ * gets a fresh `killGraceMs`; POSIX likewise gives the SIGTERM wait
+ * `termGraceMs`, the SIGKILL wait `killGraceMs`, and the close wait another
+ * `killGraceMs`. Worst-case disposal is therefore bounded by the sum, never by
+ * one shared deadline that could starve the close wait after a slow drain.
+ *
+ * Residual boundary, stated honestly. Three cases this mechanism cannot cover:
+ * a descendant whose intermediate parent died before any sweep observed it is
+ * unreachable, because Windows does not re-parent orphans — nothing in the
+ * surviving tree links back to it and `taskkill /T` cannot find it. The same
+ * window means a recycled pid could read as alive. And if taskkill's output is
+ * empty or unparseable, the walked set collapses to `{root}`: disposal then
+ * measures the root alone and reports quiescence on that basis, which is a
+ * narrower claim than the tree, not a false one. Preventing orphans left behind
+ * by a DAEMON crash is a separate job-object concern, explicitly out of scope.
+ */
 export declare function disposeOwnedProcessTree(options: OwnedProcessTreeOptions): Promise<void>;
+export {};

package/dist/adapters/taskkill-pid-set.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Windows-only: recovers the process-tree PID set that `taskkill /T /F`
+ * reports it walked, so `process-tree.ts` can MEASURE quiescence instead of
+ * trusting taskkill's exit status.
+ *
+ * Two constraints shape this parser:
+ *
+ * - taskkill's messages are LOCALIZED (the same run prints
+ *   `SUCCESS: The process with PID ...` on en-US and a translated sentence on
+ *   de-DE/zh-CN/ja-JP), so no word, prefix, or field label may be matched.
+ *   Only the integers and their CO-OCCURRENCE on one line are stable: every
+ *   line taskkill emits for a walked process names that process and its
+ *   parent together. Seeding with the root pid and closing over co-occurrence
+ *   therefore reaches exactly the walked tree, in any locale.
+ * - the text arrives in the console OEM codepage, not UTF-8. It is decoded as
+ *   latin1 (byte-preserving) rather than guessed: every OEM codepage taskkill
+ *   can use encodes ASCII digits as single bytes 0x30-0x39, and no DBCS trail
+ *   byte (CP932/CP936/CP949/CP950 all start their trail range at 0x40) can
+ *   land in that range. Undecodable non-ASCII bytes become mojibake, which is
+ *   irrelevant: they can never manufacture a digit.
+ *
+ * Line ORDER is deliberately not relied on (taskkill emits children before
+ * parents today); the walk iterates to a fixpoint instead.
+ */
+/**
+ * Returns the PID set reachable from `rootPid` by co-occurrence over `text`.
+ *
+ * `excludedPids` removes integers that must never enter the set even when
+ * they share a line with an accepted pid — taskkill names the ROOT's own
+ * parent (this daemon process) on the root's line, and accepting it would
+ * make quiescence unreachable by construction. `rootPid` is always seeded and
+ * is never subject to exclusion.
+ */
+export declare function walkTaskkillPidSet(text: string, rootPid: number, excludedPids?: Iterable<number>): Set<number>;

package/dist/bin/byok-agent.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { execFile, spawn, spawnSync } from 'child_process';
+import { execFile, spawn } from 'child_process';
 import { randomUUID, createHash, randomBytes, timingSafeEqual, createHmac, createPrivateKey, generateKeyPairSync, sign } from 'crypto';
 import { readFileSync, promises, linkSync, fstatSync, lstatSync, unlinkSync, constants, readSync, openSync, writeFileSync, fchmodSync, fsyncSync, closeSync, opendirSync, existsSync, realpathSync, mkdirSync, renameSync, chmodSync, statSync, readdirSync } from 'fs';
 import path20, { isAbsolute, join } from 'path';
@@ -887,12 +887,12 @@ function resolvePiBin() {
     }
   } catch (cause) {
     throw new Error(
-      `Required ${PI_PACKAGE_NAME} could not be resolved; install @byok-sdk/client dependencies or set BYOK_PI_BIN to a Node 22.19+ pi sidecar`,
+      `Required ${PI_PACKAGE_NAME} could not be resolved; install @byok-sdk/client dependencies or set BYOK_PI_BIN to a Node 22.22+ pi sidecar`,
       { cause }
     );
   }
   throw new Error(
-    `Required ${PI_PACKAGE_NAME} does not expose the pi CLI; reinstall the pinned dependency or set BYOK_PI_BIN to a Node 22.19+ pi sidecar`
+    `Required ${PI_PACKAGE_NAME} does not expose the pi CLI; reinstall the pinned dependency or set BYOK_PI_BIN to a Node 22.22+ pi sidecar`
   );
 }
 
@@ -1097,11 +1097,54 @@ var AsyncQueue = class {
     };
   }
 };
+
+// src/adapters/taskkill-pid-set.ts
+var INTEGER_PATTERN = /\d+/g;
+function isCandidatePid(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+function walkTaskkillPidSet(text, rootPid, excludedPids = []) {
+  const excluded = new Set(excludedPids);
+  const accepted = /* @__PURE__ */ new Set();
+  if (isCandidatePid(rootPid)) accepted.add(rootPid);
+  const lines = text.split(/\r?\n/).map((line) => {
+    const pids = [];
+    for (const match of line.matchAll(INTEGER_PATTERN)) {
+      const pid = Number(match[0]);
+      if (isCandidatePid(pid) && !excluded.has(pid)) pids.push(pid);
+    }
+    return pids;
+  });
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const pids of lines) {
+      if (!pids.some((pid) => accepted.has(pid))) continue;
+      for (const pid of pids) {
+        if (accepted.has(pid)) continue;
+        accepted.add(pid);
+        changed = true;
+      }
+    }
+  }
+  return accepted;
+}
+
+// src/adapters/process-tree.ts
 var DEFAULT_TERM_GRACE_MS = 750;
 var DEFAULT_KILL_GRACE_MS = 2e3;
 var POLL_MS = 20;
-var terminationRequested = /* @__PURE__ */ new WeakSet();
-var terminationRequestFailed = /* @__PURE__ */ new WeakSet();
+var terminationState = /* @__PURE__ */ new WeakMap();
+function stateFor(child) {
+  const existing = terminationState.get(child);
+  if (existing) return existing;
+  const created = { requested: false, acceptedPids: /* @__PURE__ */ new Set() };
+  terminationState.set(child, created);
+  return created;
+}
+function defaultKill(pid, signal) {
+  process.kill(pid, signal);
+}
 function withOwnedProcessTree(options) {
   return {
     ...options,
@@ -1119,9 +1162,9 @@ function positivePid(child, label) {
   }
   return pid;
 }
-function groupExists(pid, label) {
+function groupExists(pid, label, kill) {
   try {
-    process.kill(-pid, 0);
+    kill(-pid, 0);
     return true;
   } catch (cause) {
     const code = cause.code;
@@ -1133,9 +1176,23 @@ function groupExists(pid, label) {
     }, { cause });
   }
 }
-function signalGroup(pid, signal, label) {
+function processExists(pid, label, kill) {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (cause) {
+    const code = cause.code;
+    if (code === "ESRCH") return false;
+    if (code === "EPERM") return true;
+    throw new RuntimeDisposalFailure({
+      stage: "quiescence",
+      reason: `${label} runtime process ${pid} state could not be verified`
+    }, { cause });
+  }
+}
+function signalGroup(pid, signal, label, kill) {
   try {
-    process.kill(-pid, signal);
+    kill(-pid, signal);
   } catch (cause) {
     const code = cause.code;
     if (code === "ESRCH" || code === "EPERM") return;
@@ -1145,6 +1202,39 @@ function signalGroup(pid, signal, label) {
     }, { cause });
   }
 }
+async function runTaskkill(pid, options) {
+  const spawnFn = options.spawnFn ?? spawn;
+  return new Promise((resolve, reject) => {
+    const signalFailure = (cause) => {
+      reject(new RuntimeDisposalFailure({
+        stage: "signal",
+        reason: `${options.label} runtime process tree termination could not be requested`
+      }, { cause }));
+    };
+    let taskkill;
+    try {
+      taskkill = spawnFn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch (cause) {
+      signalFailure(cause);
+      return;
+    }
+    const chunks = [];
+    taskkill.stdout?.on("data", (chunk) => chunks.push(chunk));
+    taskkill.stderr?.on("data", (chunk) => chunks.push(chunk));
+    taskkill.once("error", signalFailure);
+    taskkill.once("close", () => resolve(Buffer.concat(chunks).toString("latin1")));
+  });
+}
+function liveAcceptedPids(accepted, label, kill) {
+  const live = [];
+  for (const pid of accepted) {
+    if (processExists(pid, label, kill)) live.push(pid);
+  }
+  return live;
+}
 async function waitUntil(predicate, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (predicate()) {
@@ -1182,29 +1272,27 @@ async function waitWithDeadline(promise, timeoutMs) {
     );
   });
 }
-function requestOwnedProcessTreeTermination(options) {
-  if (options.isClosed()) return;
+async function requestOwnedProcessTreeTermination(options) {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "win32" && options.isClosed()) return;
   const pid = positivePid(options.child, options.label);
   if (pid === void 0) return;
-  if (process.platform === "win32") {
-    const result = spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true });
-    if (result.error) {
-      throw new RuntimeDisposalFailure({
-        stage: "signal",
-        reason: `${options.label} runtime process tree could not be terminated`
-      }, { cause: result.error });
-    }
-    terminationRequested.add(options.child);
-    if (result.status !== 0) terminationRequestFailed.add(options.child);
+  if (platform === "win32") {
+    const output = await runTaskkill(pid, options);
+    const state = stateFor(options.child);
+    for (const walked of walkTaskkillPidSet(output, pid, [process.pid])) state.acceptedPids.add(walked);
+    state.requested = true;
     return;
   }
-  signalGroup(pid, "SIGTERM", options.label);
-  terminationRequested.add(options.child);
+  signalGroup(pid, "SIGTERM", options.label, options.killFn ?? defaultKill);
+  stateFor(options.child).requested = true;
 }
 async function disposeOwnedProcessTree(options) {
   const pid = positivePid(options.child, options.label);
   const termGraceMs = options.termGraceMs ?? DEFAULT_TERM_GRACE_MS;
   const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+  const platform = options.platform ?? process.platform;
+  const kill = options.killFn ?? defaultKill;
   if (pid === void 0) {
     if (await waitWithDeadline(options.waitClosed(), killGraceMs)) return;
     throw new RuntimeDisposalFailure({
@@ -1212,27 +1300,50 @@ async function disposeOwnedProcessTree(options) {
       reason: `${options.label} runtime process did not settle after spawn failure`
     });
   }
-  if (process.platform === "win32") {
-    if (!options.isClosed() && !terminationRequested.has(options.child)) requestOwnedProcessTreeTermination(options);
-    if (await waitWithDeadline(options.waitClosed(), killGraceMs)) return;
-    if (terminationRequestFailed.has(options.child)) {
+  if (platform === "win32") {
+    if (!terminationState.get(options.child)?.requested) {
+      await requestOwnedProcessTreeTermination(options);
+    }
+    const accepted = terminationState.get(options.child)?.acceptedPids ?? /* @__PURE__ */ new Set();
+    const deadline = Date.now() + killGraceMs;
+    const resweepAt = Date.now() + Math.floor(killGraceMs / 2);
+    let reswept = false;
+    let live = liveAcceptedPids(accepted, options.label, kill);
+    while (live.length > 0) {
+      if (Date.now() >= deadline) {
+        throw new RuntimeDisposalFailure({
+          stage: "quiescence",
+          reason: `${options.label} runtime process tree did not quiesce: ${live.length} of ${accepted.size} walked process ids were still alive at the disposal deadline`
+        });
+      }
+      if (!reswept && Date.now() >= resweepAt) {
+        reswept = true;
+        for (const livePid of live) {
+          for (const walked of walkTaskkillPidSet(await runTaskkill(livePid, options), livePid, [process.pid])) {
+            accepted.add(walked);
+          }
+        }
+      }
+      await new Promise((resolve) => {
+        setTimeout(resolve, POLL_MS);
+      });
+      live = liveAcceptedPids(accepted, options.label, kill);
+    }
+    if (!await waitWithDeadline(options.waitClosed(), killGraceMs)) {
       throw new RuntimeDisposalFailure({
-        stage: "signal",
-        reason: `${options.label} runtime process tree could not be terminated`
+        stage: "quiescence",
+        reason: `${options.label} runtime root did not emit close after its process tree quiesced`
       });
     }
-    throw new RuntimeDisposalFailure({
-      stage: "quiescence",
-      reason: `${options.label} runtime process tree did not close before the disposal deadline`
-    });
+    return;
   }
-  if (groupExists(pid, options.label) && !terminationRequested.has(options.child)) {
-    signalGroup(pid, "SIGTERM", options.label);
-    terminationRequested.add(options.child);
+  if (groupExists(pid, options.label, kill) && !terminationState.get(options.child)?.requested) {
+    signalGroup(pid, "SIGTERM", options.label, kill);
+    stateFor(options.child).requested = true;
   }
-  if (!await waitUntil(() => groupExists(pid, options.label), termGraceMs)) {
-    signalGroup(pid, "SIGKILL", options.label);
-    if (!await waitUntil(() => groupExists(pid, options.label), killGraceMs)) {
+  if (!await waitUntil(() => groupExists(pid, options.label, kill), termGraceMs)) {
+    signalGroup(pid, "SIGKILL", options.label, kill);
+    if (!await waitUntil(() => groupExists(pid, options.label, kill), killGraceMs)) {
       throw new RuntimeDisposalFailure({
         stage: "quiescence",
         reason: `${options.label} runtime process group remained live after SIGKILL`
@@ -1330,9 +1441,16 @@ var PiRpcClient = class {
       );
     }
   }
-  /** Immediate process-tree termination request. `dispose()` is the settlement receipt. */
+  /**
+   * Immediate process-tree termination request. `dispose()` is the settlement
+   * receipt, so this stays fire-and-forget: an interrupt must not block on a
+   * terminator. A request that could not be spawned is left unrecorded, so
+   * `dispose()` re-issues it and raises the typed `stage:'signal'` failure —
+   * swallowing it here loses nothing.
+   */
   kill() {
-    requestOwnedProcessTreeTermination(this.processTreeOptions());
+    void requestOwnedProcessTreeTermination(this.processTreeOptions()).catch(() => {
+    });
   }
   waitClosed() {
     return this.closedPromise;
@@ -2135,9 +2253,16 @@ var ClaudeProcessClient = class {
       );
     }
   }
-  /** Immediate process-tree termination request. `dispose()` is the settlement receipt. */
+  /**
+   * Immediate process-tree termination request. `dispose()` is the settlement
+   * receipt, so this stays fire-and-forget: an interrupt must not block on a
+   * terminator. A request that could not be spawned is left unrecorded, so
+   * `dispose()` re-issues it and raises the typed `stage:'signal'` failure —
+   * swallowing it here loses nothing.
+   */
   kill() {
-    requestOwnedProcessTreeTermination(this.processTreeOptions());
+    void requestOwnedProcessTreeTermination(this.processTreeOptions()).catch(() => {
+    });
   }
   waitClosed() {
     return this.closedPromise;
@@ -2902,9 +3027,15 @@ var CodexProcessRunner = class {
    * cleanly resumable afterward via `codex exec resume` (no corruption from
    * killing mid-turn). `taskkill /T /F` on Windows, mirroring
    * `../pi/rpc-client.ts`'s own cross-platform convention.
+   *
+   * Fire-and-forget by design: an interrupt must not block on a terminator,
+   * and `dispose()` is the settlement receipt. A request that could not be
+   * spawned is left unrecorded, so `dispose()` re-issues it and raises the
+   * typed `stage:'signal'` failure — swallowing it here loses nothing.
    */
   kill() {
-    requestOwnedProcessTreeTermination(this.processTreeOptions());
+    void requestOwnedProcessTreeTermination(this.processTreeOptions()).catch(() => {
+    });
   }
   dispose() {
     if (!this.disposalAttempt) {
@@ -4684,14 +4815,17 @@ function parseLooseEventsPollResponse(raw) {
   if (typeof raw !== "object" || raw === null) {
     throw new Error("events poll response is not an object");
   }
-  const { events, cursor } = raw;
+  const { events, cursor, capabilities } = raw;
   if (!Array.isArray(events)) {
     throw new Error("events poll response.events is not an array");
   }
   if (typeof cursor !== "number" || !Number.isInteger(cursor)) {
     throw new Error("events poll response.cursor is not an integer");
   }
-  return { events, cursor };
+  if (capabilities !== void 0 && (!Array.isArray(capabilities) || capabilities.some((flag) => typeof flag !== "string"))) {
+    throw new Error("events poll response.capabilities is not an array of strings");
+  }
+  return { events, cursor, capabilities: capabilities ?? [] };
 }
 function extractSkippableSeq(raw) {
   if (typeof raw !== "object" || raw === null) return void 0;
@@ -4771,12 +4905,14 @@ var LongPollClient = class {
         if (cursor !== void 0) url.searchParams.set("cursor", String(cursor));
         const res = await authedFetch(url, { method: "GET" }, this.opts.auth);
         if (!res.ok) {
+          this.opts.onServerCapabilities?.([]);
           this.opts.onOperationalOutcome?.("failure");
           const baseMs = this.opts.retryDelayMs ?? 2e3;
           await sleep(this.opts.retryDelayForAttempt?.(retryAttempt++, baseMs) ?? baseMs);
           continue;
         }
         const parsed = parseLooseEventsPollResponse(await res.json());
+        this.opts.onServerCapabilities?.(parsed.capabilities);
         let hadValidationFailureThisBatch = false;
         for (const raw of parsed.events) {
           let envelope;
@@ -4820,6 +4956,7 @@ var LongPollClient = class {
           this.opts.onOperationalOutcome?.("success");
         }
       } catch (err) {
+        this.opts.onServerCapabilities?.([]);
         if (err instanceof DeviceRevokedError) {
           this.running = false;
           this.opts.onRevoked?.();
@@ -5055,6 +5192,9 @@ var ConnectionManager = class {
       // re-attempted.
       getCursor: () => this.dedupWatermark(),
       onEnvelope: (envelope) => this.deliver(envelope),
+      onServerCapabilities: (capabilities) => {
+        if (this.mode === "long-poll") this.serverCapabilities = capabilities;
+      },
       onRevoked: () => this.enterRevoked(),
       // M4 Phase 4 (version-negotiation drill fix): a batch entry
       // LongPollClient couldn't parse into a known Envelope at all (an
@@ -5186,25 +5326,24 @@ var ConnectionManager = class {
    */
   cancelPendingDrainRetry;
   /**
-   * The capabilities the CURRENTLY connected server advertised in its
-   * `conn.ack` — untyped `string[]` (forward-compat: a server may advertise
-   * a flag this build doesn't recognize yet), populated by {@link onAcked}
-   * and read by {@link getServerCapabilities}. Empty until the very first
-   * successful handshake.
+   * The capabilities the CURRENT transport's server advertised — untyped
+   * `string[]` for forward compatibility. WS populates it from `conn.ack`;
+   * long-poll populates it from each successful events response. Empty until
+   * the active transport supplies an advertisement.
    *
    * Finding R2 (cross-model re-review — was P1): strictly PER-CONNECTION,
    * not per-daemon-lifetime. Cleared to `[]` the instant the acked WS
    * connection ends for ANY reason — an ordinary disconnect (`onWsOutcome`'s
    * `acked` branch), `stop()`, or a transport switch to long-poll
-   * (`enterLongPoll`) — and only ever repopulated by a FRESH `conn.ack`.
+   * (`enterLongPoll`) — and only repopulated by a fresh advertisement from
+   * the transport that is still current.
    * The previous version of this doc comment claimed long-poll mode simply
    * "stays at whatever the last real WS `conn.ack` said" — that was the bug:
    * a daemon that once learned e.g. `approval_resolved` from an earlier WS
    * session kept believing it applied to whatever it's connected to NOW,
    * even after a disconnect/degrade where nothing has actually confirmed
    * that's still true (a reconnect could land on a DIFFERENT server behind a
-   * load balancer; long-poll fallback itself never performs an equivalent
-   * handshake at all). Concretely, `TaskRunner.sendApprovalResolved` gates
+   * load balancer). Concretely, `TaskRunner.sendApprovalResolved` gates
    * `task.approval_resolved` on this list — sending it to a server that
    * doesn't actually understand it over the long-poll path would get a
    * batch-level 400 from `MessagesSendRequestSchema` (protocol §8.2), which
@@ -5324,13 +5463,10 @@ var ConnectionManager = class {
     return this.mode === "long-poll";
   }
   /**
-   * The capabilities the CURRENTLY connected server advertised in its
-   * `conn.ack` — e.g. lets a caller gate a daemon->server message on whether
-   * THIS server understands it before sending (see `task-runner.ts`'s
-   * `sendApprovalResolved`, gated on `approval_resolved`). Empty before the
-   * first handshake completes, AND (finding R2) once again empty after any
-   * disconnect/degrade — see `serverCapabilities`'s own doc comment for why
-   * this is strictly per-connection rather than "sticky" across one.
+   * The capabilities the CURRENT transport's server advertised: from
+   * `conn.ack` on WS, or the latest successful `GET /byok/events` response
+   * on long-poll. Empty before either transport has supplied its current
+   * advertisement, and cleared across disconnect/switch boundaries.
    */
   getServerCapabilities() {
     return this.serverCapabilities;
@@ -9734,9 +9870,9 @@ var TaskRunner = class {
   /**
    * Whether the CURRENTLY connected server advertised `result-document` —
    * read fresh on every call, never captured, because the answer changes
-   * across a reconnect (`ConnectionManager.getServerCapabilities` returns
-   * `[]` from the moment an acked connection closes until a fresh
-   * `conn.ack` repopulates it). An absent `getServerCapabilities` seam is
+   * across a reconnect or transport switch (`ConnectionManager` clears the
+   * old advertisement at the boundary, then repopulates it from a fresh WS
+   * ack or successful poll response). An absent `getServerCapabilities` seam is
    * "no capabilities", the fail-closed reading.
    */
   hasResultDocumentCapability() {