tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/src/terminal/MonotonicPtyInput.ts

@@ -0,0 +1,153 @@
+import {
+  PtyInputRejectedError,
+  type PtyBoundedInput,
+  type PtyInputLimits,
+  type PtyInputRejectionReason,
+  type PtyInputSnapshot,
+  type PtyInputState,
+  type PtyInputWriteReceipt,
+} from "./PtyAdapter.ts";
+
+/**
+ * Conservative defaults for one real tmux-client PTY generation.
+ *
+ * 256 KiB bounds opaque payload retention while 8,192 frames bounds private
+ * queue/task metadata when a renderer sends one key per frame. A 16 KiB frame
+ * admits ordinary bracketed paste but makes larger paste an explicit transport
+ * operation that must be chunked before it reaches this boundary.
+ */
+export const DEFAULT_PTY_INPUT_LIMITS: PtyInputLimits = Object.freeze({
+  maxFrameBytes: 16 * 1024,
+  maxAcceptedBytes: 256 * 1024,
+  maxAcceptedFrames: 8_192,
+});
+
+/** Hard implementation ceilings; callers cannot trade a byte cap for task explosion. */
+export const MAX_PTY_INPUT_FRAME_BYTES = 64 * 1024;
+export const MAX_PTY_INPUT_ACCEPTED_BYTES = 4 * 1024 * 1024;
+export const MAX_PTY_INPUT_ACCEPTED_FRAMES = 16_384;
+
+export function validatePtyInputLimits(limits: PtyInputLimits): PtyInputLimits {
+  validateLimit("maxFrameBytes", limits.maxFrameBytes, MAX_PTY_INPUT_FRAME_BYTES);
+  validateLimit("maxAcceptedBytes", limits.maxAcceptedBytes, MAX_PTY_INPUT_ACCEPTED_BYTES);
+  validateLimit("maxAcceptedFrames", limits.maxAcceptedFrames, MAX_PTY_INPUT_ACCEPTED_FRAMES);
+  if (limits.maxFrameBytes > limits.maxAcceptedBytes) {
+    throw new RangeError("maxFrameBytes cannot exceed maxAcceptedBytes");
+  }
+  return Object.freeze({ ...limits });
+}
+
+function validateLimit(name: string, value: number, maximum: number): void {
+  if (!Number.isSafeInteger(value) || value <= 0 || value > maximum) {
+    throw new RangeError(`${name} must be a positive safe integer no greater than ${maximum}`);
+  }
+}
+
+/**
+ * Bounds an opaque PTY writer by assuming the worst case: every byte and task
+ * ever accepted remains queued for this process's entire lifetime.
+ *
+ * This deliberately does not inspect node-pty private fields and does not
+ * infer progress from time or terminal echo. Capacity is reserved before the
+ * sink call and is never reclaimed, including when that call throws.
+ */
+export class MonotonicPtyInput implements PtyBoundedInput {
+  readonly #limits: PtyInputLimits;
+  readonly #sink: (frame: Buffer) => void;
+  #acceptedBytes = 0;
+  #acceptedFrames = 0;
+  #state: PtyInputState = "open";
+  #terminalReason: PtyInputRejectionReason | null = null;
+
+  constructor(limits: PtyInputLimits, sink: (frame: Buffer) => void) {
+    this.#limits = validatePtyInputLimits(limits);
+    this.#sink = sink;
+  }
+
+  write(data: Uint8Array): PtyInputWriteReceipt {
+    if (!(data instanceof Uint8Array)) {
+      throw new TypeError("bounded PTY input must be a Uint8Array");
+    }
+    if (data.byteLength === 0) {
+      return { status: "ignored", reason: "empty", snapshot: this.snapshot() };
+    }
+    if (this.#state === "exhausted") {
+      const reason =
+        this.#terminalReason ??
+        (this.#acceptedFrames >= this.#limits.maxAcceptedFrames
+          ? "lifetime_frames_exhausted"
+          : "lifetime_bytes_exhausted");
+      this.#reject(reason, "exhausted");
+    }
+    if (this.#state !== "open") {
+      this.#reject("process_closed", this.#state);
+    }
+    if (data.byteLength > this.#limits.maxFrameBytes) {
+      this.#reject("frame_too_large", "exhausted");
+    }
+    if (this.#acceptedFrames >= this.#limits.maxAcceptedFrames) {
+      this.#reject("lifetime_frames_exhausted", "exhausted");
+    }
+    if (data.byteLength > this.#limits.maxAcceptedBytes - this.#acceptedBytes) {
+      this.#reject("lifetime_bytes_exhausted", "exhausted");
+    }
+
+    // Copy before accounting and before crossing the opaque boundary. This
+    // prevents a renderer-owned ArrayBuffer (including a shared view) from
+    // changing after the exact byteLength has been reserved.
+    const frame = Buffer.from(data);
+    this.#acceptedBytes += frame.byteLength;
+    this.#acceptedFrames += 1;
+    if (
+      this.#acceptedBytes === this.#limits.maxAcceptedBytes ||
+      this.#acceptedFrames === this.#limits.maxAcceptedFrames
+    ) {
+      this.#state = "exhausted";
+      this.#terminalReason =
+        this.#acceptedFrames === this.#limits.maxAcceptedFrames
+          ? "lifetime_frames_exhausted"
+          : "lifetime_bytes_exhausted";
+    }
+
+    try {
+      this.#sink(frame);
+    } catch {
+      this.#state = "failed";
+      this.#terminalReason = "backend_write_failed";
+      throw new PtyInputRejectedError({
+        reason: "backend_write_failed",
+        snapshot: this.snapshot(),
+      });
+    }
+
+    return {
+      status: "accepted",
+      byteLength: frame.byteLength,
+      snapshot: this.snapshot(),
+    };
+  }
+
+  snapshot(): PtyInputSnapshot {
+    return Object.freeze({
+      ...this.#limits,
+      state: this.#state,
+      acceptedBytes: this.#acceptedBytes,
+      acceptedFrames: this.#acceptedFrames,
+      remainingBytes: this.#limits.maxAcceptedBytes - this.#acceptedBytes,
+      remainingFrames: this.#limits.maxAcceptedFrames - this.#acceptedFrames,
+    });
+  }
+
+  close(): void {
+    if (this.#state !== "closed") {
+      this.#state = "closed";
+      this.#terminalReason = "process_closed";
+    }
+  }
+
+  #reject(reason: PtyInputRejectionReason, state: PtyInputState): never {
+    this.#state = state;
+    this.#terminalReason = reason;
+    throw new PtyInputRejectedError({ reason, snapshot: this.snapshot() });
+  }
+}

package/packages/daemon/src/terminal/NodePtyAdapter.ts

@@ -19,9 +19,16 @@ import {
   PtySpawnError,
   type PtyAdapter,
   type PtyExitEvent,
+  type PtyInputLimits,
   type PtyProcess,
   type PtySpawnInput,
+  type PtySpawnListeners,
 } from "./PtyAdapter.ts";
+import {
+  DEFAULT_PTY_INPUT_LIMITS,
+  MonotonicPtyInput,
+  validatePtyInputLimits,
+} from "./MonotonicPtyInput.ts";
 
 const ADAPTER_ID = "node-pty";
 let helperEnsured = false;
@@ -101,9 +108,17 @@ class NodePtyProcess implements PtyProcess {
   private readonly child: pty.IPty;
   private readonly dataListeners = new Set<(data: Buffer) => void>();
   private readonly exitListeners = new Set<(event: PtyExitEvent) => void>();
+  readonly boundedInput: MonotonicPtyInput;
 
-  constructor(child: pty.IPty) {
+  constructor(
+    child: pty.IPty,
+    listeners: PtySpawnListeners = {},
+    inputLimits: PtyInputLimits = DEFAULT_PTY_INPUT_LIMITS,
+  ) {
     this.child = child;
+    this.boundedInput = new MonotonicPtyInput(inputLimits, (frame) => this.child.write(frame));
+    if (listeners.onData) this.dataListeners.add(listeners.onData);
+    if (listeners.onExit) this.exitListeners.add(listeners.onExit);
     // node-pty hands us strings by default; we want raw buffers for
     // byte-accurate WS bridging. The encoding:null on spawn opts gives us
     // buffers in the typings of node-pty@1.2.0-beta.12.
@@ -113,11 +128,15 @@ class NodePtyProcess implements PtyProcess {
     });
     this.child.onExit((evt) => {
       this.exited = true;
+      this.boundedInput.close();
       const event: PtyExitEvent = {
         exitCode: evt.exitCode ?? 0,
         signal: typeof evt.signal === "number" ? evt.signal : null,
       };
-      for (const listener of this.exitListeners) listener(event);
+      const listeners = [...this.exitListeners];
+      this.dataListeners.clear();
+      this.exitListeners.clear();
+      for (const listener of listeners) listener(event);
     });
   }
 
@@ -126,9 +145,11 @@ class NodePtyProcess implements PtyProcess {
   }
 
   write(data: string | Uint8Array): void {
+    // Legacy bridge only. Native attachments receive `boundedInput`, not this
+    // process method, because node-pty exposes no completion/capacity signal.
     if (this.exited) return;
     if (typeof data === "string") this.child.write(data);
-    else this.child.write(Buffer.from(data).toString("binary"));
+    else this.child.write(Buffer.from(data));
   }
 
   resize(cols: number, rows: number): void {
@@ -145,14 +166,26 @@ class NodePtyProcess implements PtyProcess {
     }
   }
 
+  pause(): void {
+    if (!this.exited) this.child.pause();
+  }
+
+  resume(): void {
+    if (!this.exited) this.child.resume();
+  }
+
   kill(signal?: NodeJS.Signals | number): void {
     if (this.exited) return;
+    this.boundedInput.close();
     try {
       this.child.kill(typeof signal === "number" ? String(signal) : signal);
     } catch {
       // Already gone. Synthesize an exit so listeners detach cleanly.
       this.exited = true;
-      for (const listener of this.exitListeners) listener({ exitCode: 0, signal: null });
+      const listeners = [...this.exitListeners];
+      this.dataListeners.clear();
+      this.exitListeners.clear();
+      for (const listener of listeners) listener({ exitCode: 0, signal: null });
     }
   }
 
@@ -183,6 +216,11 @@ export interface NodePtyAdapterOptions {
   statCwd?: (cwd: string) => Stats;
   /** Skip the spawn-helper chmod (test isolation). */
   skipHelperEnsure?: boolean;
+  /**
+   * Daemon-owned monotonic native-input limits. They are copied into each
+   * fresh process and cannot be reset for that process generation.
+   */
+  boundedInputLimits?: PtyInputLimits;
 }
 
 export class NodePtyAdapter implements PtyAdapter {
@@ -190,24 +228,28 @@ export class NodePtyAdapter implements PtyAdapter {
   private readonly spawnPty: typeof pty.spawn;
   private readonly statCwd: (cwd: string) => Stats;
   private readonly skipHelperEnsure: boolean;
+  private readonly boundedInputLimits: PtyInputLimits;
 
   constructor(options: NodePtyAdapterOptions = {}) {
     this.spawnPty = options.spawnPty ?? pty.spawn;
     this.statCwd = options.statCwd ?? statSync;
     this.skipHelperEnsure = options.skipHelperEnsure ?? false;
+    this.boundedInputLimits = validatePtyInputLimits(
+      options.boundedInputLimits ?? DEFAULT_PTY_INPUT_LIMITS,
+    );
   }
 
-  async spawn(input: PtySpawnInput): Promise<PtyProcess> {
+  async spawn(input: PtySpawnInput, listeners?: PtySpawnListeners): Promise<PtyProcess> {
     if (!this.skipHelperEnsure) ensureNodePtySpawnHelperExecutable();
-    return this.spawnSyncInternal(input);
+    return this.spawnSyncInternal(input, listeners);
   }
 
-  spawnSync(input: PtySpawnInput): PtyProcess {
+  spawnSync(input: PtySpawnInput, listeners?: PtySpawnListeners): PtyProcess {
     if (!this.skipHelperEnsure) ensureNodePtySpawnHelperExecutable();
-    return this.spawnSyncInternal(input);
+    return this.spawnSyncInternal(input, listeners);
   }
 
-  private spawnSyncInternal(input: PtySpawnInput): PtyProcess {
+  private spawnSyncInternal(input: PtySpawnInput, listeners?: PtySpawnListeners): PtyProcess {
     assertValidCwd(input.cwd, this.statCwd);
     if (!Number.isInteger(input.cols) || input.cols <= 0) {
       throw new PtySpawnError({
@@ -236,7 +278,7 @@ export class NodePtyAdapter implements PtyAdapter {
         rows: input.rows,
         cwd: input.cwd,
         env,
-        encoding: input.encoding === "utf8" ? "utf8" : (null as unknown as undefined),
+        encoding: input.encoding === "utf8" ? "utf8" : null,
       });
     } catch (err) {
       const errno = (err as NodeJS.ErrnoException | undefined)?.code;
@@ -263,7 +305,7 @@ export class NodePtyAdapter implements PtyAdapter {
         cause: err,
       });
     }
-    return new NodePtyProcess(child);
+    return new NodePtyProcess(child, listeners, this.boundedInputLimits);
   }
 }
 

package/packages/daemon/src/terminal/PtyAdapter.ts

@@ -59,6 +59,100 @@ export interface PtyExitEvent {
   signal: number | null;
 }
 
+/**
+ * Fixed, daemon-owned limits for the fail-closed PTY input capability.
+ *
+ * These are lifetime limits, not watermarks. Accepted capacity is never
+ * returned because the public node-pty API cannot prove that its private
+ * writer queue released any particular byte. A fresh budget therefore
+ * requires a fresh {@link PtyProcess}; callers cannot reset one in place.
+ */
+export interface PtyInputLimits {
+  /** Largest single binary frame that can cross the adapter boundary. */
+  readonly maxFrameBytes: number;
+  /** Total bytes that can ever be handed to the opaque backend process. */
+  readonly maxAcceptedBytes: number;
+  /** Total non-empty frames that can ever be handed to the opaque backend. */
+  readonly maxAcceptedFrames: number;
+}
+
+export type PtyInputState = "open" | "exhausted" | "failed" | "closed";
+
+/** Immutable accounting snapshot; it never contains terminal input bytes. */
+export interface PtyInputSnapshot extends PtyInputLimits {
+  readonly state: PtyInputState;
+  readonly acceptedBytes: number;
+  readonly acceptedFrames: number;
+  readonly remainingBytes: number;
+  readonly remainingFrames: number;
+}
+
+export type PtyInputRejectionReason =
+  | "frame_too_large"
+  | "lifetime_bytes_exhausted"
+  | "lifetime_frames_exhausted"
+  | "process_closed"
+  | "backend_write_failed";
+
+/**
+ * Typed fail-closed rejection from {@link PtyBoundedInput.write}.
+ *
+ * The rejected payload is deliberately absent. Capacity/backend failures
+ * retire the capability permanently so a caller cannot ignore one rejected
+ * frame and continue with a divergent terminal input stream.
+ */
+export class PtyInputRejectedError extends Error {
+  readonly code = "pty_input_rejected" as const;
+  readonly reason: PtyInputRejectionReason;
+  readonly snapshot: PtyInputSnapshot;
+
+  constructor(args: { reason: PtyInputRejectionReason; snapshot: PtyInputSnapshot }) {
+    super(`bounded PTY input rejected: ${args.reason}`);
+    this.name = "PtyInputRejectedError";
+    this.reason = args.reason;
+    this.snapshot = args.snapshot;
+  }
+}
+
+export type PtyInputWriteReceipt =
+  | {
+      readonly status: "accepted";
+      readonly byteLength: number;
+      readonly snapshot: PtyInputSnapshot;
+    }
+  | {
+      readonly status: "ignored";
+      readonly reason: "empty";
+      readonly snapshot: PtyInputSnapshot;
+    };
+
+/**
+ * A bounded binary-only input capability for native attachment transports.
+ *
+ * `write` snapshots accepted input and reserves its byte+frame quota before
+ * invoking the opaque backend. It either returns an accepted/empty receipt or
+ * throws {@link PtyInputRejectedError}; it never silently drops a non-empty
+ * frame. There is intentionally no reset method.
+ */
+export interface PtyBoundedInput {
+  write(data: Uint8Array): PtyInputWriteReceipt;
+  snapshot(): PtyInputSnapshot;
+  /** Permanently reject future writes without releasing accepted capacity. */
+  close(): void;
+}
+
+/**
+ * Optional listeners installed on the adapter's process wrapper before that
+ * wrapper subscribes to the native child. This closes the post-spawn handle
+ * handoff gap and captures even a child implementation which emits
+ * synchronously while `onData`/`onExit` is registered. It does not claim that
+ * a native backend can accept callbacks before its own `spawn(...)` returns.
+ */
+export interface PtySpawnListeners {
+  readonly onData?: (data: Buffer) => void;
+  readonly onExit?: (event: PtyExitEvent) => void;
+}
+
 /**
  * Handle to a live PTY child returned by `PtyAdapter.spawn`. Modelled on
  * t3's `PtyProcess` and `node-pty`'s `IPty` so wrapping is trivial.
@@ -70,10 +164,24 @@ export interface PtyExitEvent {
 export interface PtyProcess {
   /** Underlying OS PID (or a synthetic positive integer for mocks). */
   readonly pid: number;
-  /** Write raw bytes (string is interpreted as UTF-8) into the child stdin. */
+  /**
+   * Fail-closed input for native attachment transports. This is the only PTY
+   * input surface whose opaque-backend memory can be bounded without a public
+   * node-pty drain callback.
+   */
+  readonly boundedInput: PtyBoundedInput;
+  /**
+   * Legacy, non-authoritative input with no completion or capacity proof.
+   * Native attachment transports MUST receive only `boundedInput`, never this
+   * process or method. Retained solely for the historical shell bridge.
+   */
   write(data: string | Uint8Array): void;
   /** Resize the controlling terminal. */
   resize(cols: number, rows: number): void;
+  /** Pause delivery from the native PTY without terminating its child. */
+  pause(): void;
+  /** Resume delivery after a matching pause. */
+  resume(): void;
   /**
    * Send a signal to the child. Defaults to `SIGTERM` so adapters that
    * can't deliver arbitrary signals (mocks, sandboxed remotes) still
@@ -131,10 +239,10 @@ export interface PtyAdapter {
   /** Human-readable adapter id, surfaced in `PtySpawnError.adapter`. */
   readonly id: string;
   /** Canonical async spawn. Resolves once the child PID is known. */
-  spawn(input: PtySpawnInput): Promise<PtyProcess>;
+  spawn(input: PtySpawnInput, listeners?: PtySpawnListeners): Promise<PtyProcess>;
   /**
    * Synchronous spawn. Adapters that can't satisfy this (because they
    * need async setup) MUST throw `PtySpawnError({ code: "sync_unsupported" })`.
    */
-  spawnSync(input: PtySpawnInput): PtyProcess;
+  spawnSync(input: PtySpawnInput, listeners?: PtySpawnListeners): PtyProcess;
 }

package/packages/daemon/src/terminal/README.md

@@ -28,6 +28,14 @@ a remote transport.
 - `NodePtyAdapter.ts` — concrete implementation backed by `node-pty`.
   Ports t3's `ensureNodePtySpawnHelperExecutable` chmod-on-helper trick
   so a fresh install always boots.
+- `attachments/pty-tmux-attachment-launcher.ts` — daemon-owned normal
+  `tmux attach-session` PTY client. It accepts canonical operation metadata,
+  reconstructs the complete guarded argv itself, and rejects unknown fields;
+  no caller-authored tmux argv crosses this boundary. Socket, exact tmux
+  executable, cwd, and sanitized environment remain daemon-owned and are
+  identical for spawn and readiness proof. Output stays bounded until tmux
+  proves the spawned client PID is attached to that exact marked one-window
+  view.
 - `__tests__/MockPtyAdapter.ts` — scripted PTY for the test suite. Lives
   under `__tests__/` so production bundling never picks it up.
 - `__tests__/*.test.ts` — contract tests parameterised over every
@@ -36,17 +44,16 @@ a remote transport.
 ## Why this exists
 
 `node-pty` is a native module compiled against an underlying runtime ABI.
-T085 burned half a day finding out that under Bun, `node-pty`'s `onData`
-callback never fires — the PTY spawns, the child exits, and zero bytes
-flow back. The fix had to live in two places:
+Under Bun, `node-pty`'s `onData` callback never fires — the PTY spawns, the
+child exits, and zero bytes flow back. The fix had to live in two places:
 
-1. **Runtime pinning** (T087 PART 1): every daemon spawn site uses
+1. **Runtime pinning**: every daemon spawn site uses
    `node`/`tsx`, never `bun`. See `daemon-watchdog.ts`,
    `tmux-bridge/src/monitor.ts`, `src/lib/tmux.ts`. The
    `packages/daemon/package.json` `dev`/`start` scripts mirror t3's
    `apps/server/package.json` (`tsx --watch` in dev, `node dist/...` in
    prod).
-2. **Adapter abstraction** (T087 PART 2): a thin interface so the future
+2. **Adapter abstraction**: a thin interface so the future
    doesn't paint us into the same corner. New runtimes get their own
    adapter; tests use `MockPtyAdapter` so we never accidentally spawn a
    real PTY in CI.
@@ -79,14 +86,25 @@ we register there.
   one terminal `onExit` event — subsequent `onExit(...)` subscribers
   receive an inert disposer.
 - No production code outside `NodePtyAdapter.ts` imports `node-pty`.
-  This is enforced by `pty-bridge.ts` now consuming `PtyAdapter` and is
-  the gate G14-T10 will tighten further.
-
-## Roadmap notes
-
-- **G14-T07** introduces Effect runtime. When that lands, this contract
-  grows an `Effect.Effect<PtyProcess, PtySpawnError>` shape; the plain-
-  TS interface here stays so adapters can implement either side.
-- **G14-T10** moves chat reactor → Effect Stream. PTY bytes will flow
-  through the same Stream pipeline; today's `EventEmitter`-based
-  `pty-bridge` becomes the bottom of that Stream.
+  This is enforced by `pty-bridge.ts` consuming `PtyAdapter`.
+- Native PTY input reaches the terminal only through
+  `PtyProcess.boundedInput`, a monotonic fail-closed primitive: it snapshots
+  and accounts a fixed lifetime byte+frame budget before each opaque node-pty
+  call and never reclaims it. That bounds the private queue without reading
+  private fields, but it does not prove delivery. The direct WebSocket stream
+  takes that capability for interactive viewers and rejects input with
+  `input-backpressure-unavailable` when it holds none — a read-only viewer, or
+  a generation whose budget is spent. Legacy `PtyProcess.write()` is explicitly
+  non-authoritative and must never reach that stream. See ADR-0003. Output uses
+  public `IPty.pause()`/`resume()` and byte+frame caps.
+- Read-only attachment clients are also fail-closed in this first launcher
+  slice. They fail before PTY spawn with `read_only_unavailable` until the
+  daemon proves the installed tmux version and continuously holds an
+  interactive geometry owner with defined owner-loss behavior. The tmux
+  `attach-session -r` flag alone is not treated as a geometry-safety proof.
+- Successful attach/recover execution returns a first-class one-use
+  `clientClaim` key through the executor and lease-manager result, so the next
+  stream layer can adopt the exact PTY without intercepting the transport.
+  Proof-ready clients remain paused and must be claimed within the bounded
+  claim deadline (two seconds by default); otherwise the launcher terminates
+  only that client and releases capacity.

package/packages/daemon/src/terminal/attachments/admission-util.ts

@@ -0,0 +1,97 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/**
+ * Pure helpers shared by the daemon's ticket-redeeming WebSocket admission
+ * boundaries (direct terminal attachments and pane streams). Extracted
+ * verbatim from the reviewed direct-websocket admission so both endpoints
+ * keep one Origin canonicalization, one strict-UTF-8 JSON gate, and one
+ * constant-time ticket digest discipline.
+ */
+const WS_OPEN = 1;
+
+export interface CloseableSocket {
+  readonly readyState: number;
+  close(code?: number, reason?: string): void;
+}
+
+/** Canonical renderer Origin, or null for every invalid shape. */
+export function canonicalOriginOrNull(value: string): string | null {
+  if (
+    typeof value !== "string" ||
+    value.length < 4 ||
+    value.length > 2048 ||
+    value === "null" ||
+    value === "*" ||
+    /[\0\r\n\t ]/u.test(value)
+  ) {
+    return null;
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return null;
+  }
+  if (
+    !/^[a-z][a-z0-9+.-]*:$/u.test(parsed.protocol) ||
+    parsed.protocol === "file:" ||
+    parsed.username ||
+    parsed.password ||
+    (parsed.pathname !== "" && parsed.pathname !== "/") ||
+    parsed.search ||
+    parsed.hash ||
+    !parsed.hostname
+  ) {
+    return null;
+  }
+  const canonical = `${parsed.protocol}//${parsed.host}`;
+  return canonical === value ? canonical : null;
+}
+
+export function rawDataToBuffer(data: string | Buffer | ArrayBuffer | readonly Buffer[]): Buffer {
+  if (typeof data === "string") return Buffer.from(data, "utf8");
+  if (Buffer.isBuffer(data)) return data;
+  if (data instanceof ArrayBuffer) return Buffer.from(data);
+  return Buffer.concat(data.map((entry) => Buffer.from(entry)));
+}
+
+/** Byte length with an early exit: anything past `maximum` reports maximum+1. */
+export function rawDataByteLength(
+  data: string | Buffer | ArrayBuffer | readonly Buffer[],
+  maximum: number,
+): number {
+  if (typeof data === "string") return Buffer.byteLength(data, "utf8");
+  if (Buffer.isBuffer(data)) return data.byteLength;
+  if (data instanceof ArrayBuffer) return data.byteLength;
+  let total = 0;
+  for (const entry of data) {
+    if (entry.byteLength > maximum - total) return maximum + 1;
+    total += entry.byteLength;
+  }
+  return total;
+}
+
+/** Strict UTF-8 JSON: replacement characters and mixed encodings are rejected. */
+export function strictJsonParse(bytes: Buffer): unknown {
+  const text = bytes.toString("utf8");
+  if (Buffer.byteLength(text, "utf8") !== bytes.byteLength || text.includes("\uFFFD")) {
+    throw new TypeError("Control frame is not valid UTF-8.");
+  }
+  return JSON.parse(text) as unknown;
+}
+
+export function safeCloseSocket(socket: CloseableSocket, code: number, reason: string): void {
+  try {
+    if (socket.readyState === WS_OPEN) socket.close(code, reason.slice(0, 123));
+  } catch {
+    // Teardown ownership has already moved to the daemon state machine.
+  }
+}
+
+export function digestSecret(secret: string): Buffer {
+  return createHash("sha256").update(secret, "utf8").digest();
+}
+
+export function digestsEqual(left: Buffer, right: Buffer): boolean {
+  return left.byteLength === right.byteLength && timingSafeEqual(left, right);
+}