@promptctl/cc-candybar 1.149.4 → 1.150.0

package/dist/cc-extra/src/seams.js

@@ -0,0 +1,163 @@
+// seams.js — the fragments of the app's own source the injector anchors on, and what it splices in.
+//
+// This file is the ONLY place in the tree that knows anything about Claude Code's internals, and a
+// seam deliberately knows as little as possible: one fragment of source, and one statement to insert
+// before it. Everything else — which module carries it, at what offset — is resolved from the
+// installed binary at launch by seam-plan.js. There is no chunk name here and no version literal,
+// because both change every release and a map that changes weekly is a map that is already lying.
+//
+// WHY THESE ANCHORS SURVIVE MINIFICATION. Bun renames every module-scope binding — the gate function
+// below was renamed between two releases a week apart — but it cannot rename a PROPERTY, and it
+// cannot rewrite a STRING LITERAL the app sends to a server. Property names and literals come
+// through verbatim. Anchoring on one of those rather than on an offset, a variable, or a line number
+// is what makes this hold across releases without a table someone maintains by hand. No minified
+// name is spelled here: the one place any of them appears is the dated measurement below.
+
+'use strict';
+
+// The global a spliced statement calls. The host installs it before a single module is evaluated,
+// which is why inserted code can call it unguarded — an absent registrar is unrepresentable rather
+// than survivable. [LAW:no-defensive-null-guards]
+const REGISTRAR = '__CC_EXTRA_SEAM__';
+
+// THE PROPOSE-GOAL SEAM — give the model the goal tool the shipped build already carries.
+//
+// `/goal` has two shipped forms. The one a person types is a slash command; the one the MODEL can
+// reach is a real tool, `ProposeGoal`, which enqueues `/goal <condition>` on the session's own
+// message queue — the shipped way a tool runs a slash command. That tool is already built, already
+// in `getAllBaseTools()`'s array, and already excluded from the offered set by its own `isEnabled()`.
+//
+// MEASURED on the shipped 2.1.280 (a dated observation, not an input — nothing below reads it, and
+// every name in it is minified and already different from 2.1.278's). `isEnabled()` is five
+// conjuncts, and on an ordinary interactive local session exactly one of them is false:
+//
+//     isEnabled(){ if(Te()||Zn())return!1; if(At())return!1; if(!Pjt())return!1;
+//                  let e=pze(); if(e==="disabled")return!1; return E(e),!0 }
+//
+//   Te()   — the session is NOT interactive.     false here: it is.
+//   Zn()   — the workspace is remote.            false here: it is local.
+//   At()   — `s9()==="bg"`, a background job.    false here: it is a terminal session.
+//   pze()  — the `modelProposedGoals` setting, `"auto"` when absent, and only `"disabled"` refuses.
+//   Pjt()  — `x("tengu_propose_goal",!1)`, a SERVER-SIDE feature gate, default false. This one.
+//
+// WHY THE GATE AND NOT THE TOOL. That gate is the app's single authority on whether the goal feature
+// exists at all: the tool's `isEnabled` reads it, and so does the `/config` panel, which shows the
+// `modelProposedGoals` row only when the gate is on. Splicing the gate turns the feature on once, at
+// its source, and both consumers agree by construction. Splicing `isEnabled` instead would leave a
+// session whose goal tool works and whose settings panel denies the tool exists — two maps of one
+// fact, drifting the moment either is read. [LAW:one-source-of-truth] [LAW:single-enforcer]
+//
+// WHY NOT CONFIGURATION. Feature values resolve environment override -> config override -> remote
+// payload -> disk cache -> default, and on a shipped build the first two are compiled to
+// `return null` / `return`. When the remote payload is non-empty but lacks the key the resolver
+// returns the default and SKIPS the disk cache entirely, so seeding the cache does nothing — and
+// writing it would make this a second writer to a file the gate client owns and rewrites on its own
+// schedule. The gate is a runtime value; the only honest place to change it is at runtime.
+//
+// WHY THE ANCHOR IS SHAPED THE WAY IT IS. `"tengu_propose_goal"` is a key the app sends to a feature
+// service, so it survives minification untouched and occurs exactly ONCE across all 1,991 js modules.
+// The rest of the anchor is not there to find the site — the literal already did that — it is there
+// to PROVE the site is a statement whose value is the gate's answer, because the only insertion that
+// could go wrong here is one absorbed into a larger expression that inverts it:
+//
+//   the        `function <name>(){` pins the brace to a FUNCTION BODY, so the spliced `return true;`
+//   lookbehind is provably the first statement that function runs, and the leading `[;}\n]` pins that
+//              declaration to a STATEMENT POSITION — a function declaration, never an expression
+//              whose value an enclosing operator consumes. Neither half is ornamental. A lookbehind
+//              of just `\{` admits `if(W()){return P(...)}else{...}`: it resolves to one site,
+//              splices cleanly, and leaves a gate that still answers the server on the other branch
+//              — resolved to the wrong place and still running, which is the one failure this whole
+//              anchor exists to prevent. Without `[;}\n]`, `return!function R(){return P(...)}()`
+//              admits the same way, and there an operator inverts what the splice returns. The
+//              `function ` keyword carries its own weight: `\w+ ` in its place admits the valid class
+//              members `get G(){`, `async G(){` and `static G(){`.
+//              IT DOES NOT PROVE NESTING DEPTH — no regex counts braces. A declaration inside another
+//              function body still matches whenever `;`, `}` or a newline precedes it, and
+//              `seams.test.js` pins that as the known limit rather than implying it away. Proving top
+//              level would take a parser, and it would refuse the one nesting that actually occurs: a
+//              Bun `__esm`/`__commonJS` chunk wrapper, where the nested declaration IS the gate and
+//              splicing into it is correct. The residual is a hand-written
+//              `function outer(){…function R(){gate}return!R()}`, which minification does not produce
+//              from this source. The lookbehind is variable-length, which V8 supports and most
+//              engines do not; node is the only host here, so that is a fact rather than a bet.
+//   `\s+`      a `return` whose operand is a call has to be separated from it, so requiring the
+//              space is what tells `return P(...)` apart from a call to a function NAMED
+//              `returnP(...)`. `\s*` would match the second and splice a return into a function
+//              that never asked the gate anything. (A negated call, `return!P(...)`, is refused by
+//              the identifier class that follows, not by this.)
+//   the quote  the closing `"` pins the exact key, so a future `"tengu_propose_goal_v2"` refuses
+//              instead of resolving onto a gate that means something else.
+//
+// Every one of those is a REFUSAL when the shape moves, and a refusal costs the user the hosted
+// session and never a working one: the host reports `no-module-carries-the-seam` and the caller falls
+// back to stock claude. A seam that resolved to the wrong place is the failure worth engineering
+// against, because that one still runs. [LAW:no-silent-failure]
+//
+// A patch enters this list as a VALUE — an anchor and the statement to insert — and every other part
+// of the mechanism is already unconditional: the plan is resolved, the transform is applied and the
+// registrar is installed on every boot, whether this list holds one seam or ten. Adding a patch is
+// adding data, never a new path. [LAW:dataflow-not-control-flow]
+// THE STATUSLINE-PUSH SEAM — draw the status line from frames cc-candybar's daemon pushes
+// (statusline-push.js says why and how).
+//
+// MEASURED on the shipped 2.1.299 (dated, not an input). The status line controller is one class;
+// it draws through a PRIVATE emitter, and runs the command from an arrow inside its own method:
+//
+//     #R(e,n,r,s){ … await _Yo({signal:e, executeCommand:()=>{ let M=this.#t, z=kYo({…});
+//                    if(!e.aborted)this.#b(wYo(z)); return this.#e.execute(z,e,r) },
+//                  getCommandLength:()=>…, pendingResultLogRef:this.#g, onResult:(M)=>this.#S(M), … }) }
+//     #S(e){ if(this.#n.text===e)return; this.#n={text:e}; …; this.#o.emit() }
+//
+// `z` is the statusline JSON, `this.#e.execute(z,e,r)` runs the command, and `#S` is what its output
+// is drawn through. A private name can only be written inside the class body, which is exactly where
+// this splice lands: `this` is the controller and `this.#S` is reachable. The anchor CAPTURES the
+// pieces the insert needs — the deps field, the payload, the run's other two arguments, the emitter —
+// so no minified name is written here; each is read off the release being spliced.
+//
+// THE SHAPE OF THE INSERT. A splice only adds text before its anchor, and the anchor is the command
+// call itself, so the original call stays after the insert as the right operand of `||`:
+//
+//     return <registrar>.statusLine(this, z, (t)=>this.#S(t), ()=>this.#e.execute(z,e,r)) || this.#e.execute(z,e,r)
+//
+// `statusLine` is async, so it always returns a promise and the right operand never runs; the run
+// goes through the thunk the registrar is handed, once.
+//
+// WHY THE ANCHOR IS SHAPED THE WAY IT IS. `.execute(` alone occurs all over the graph; what makes
+// this one the status line's is what follows it — the `getCommandLength:` key of the same object
+// literal, then that literal's `onResult:` arrow into a private method — keys the minifier cannot
+// rename. `(?<=return )` pins the anchor to the operand of the arrow's `return`, so the `||` lands in
+// a return expression and nowhere an operator could absorb it. The `[^]{0,400}?` between
+// `getCommandLength:` and `onResult:` spans the two keys between them in this literal (about 120
+// characters in 2.1.299); bounded, so it cannot reach into another object literal's `onResult:`.
+// Resolved to exactly one site in every installed release, 2.1.267 through 2.1.299.
+const STATUSLINE_PUSH = {
+  name: 'statusline-push',
+  anchor:
+    /(?<=return )this\.(?<deps>#[\w$]+)\.execute\((?<payload>[\w$]+),(?<rest>[\w$]+,[\w$]+)\)(?=\},getCommandLength:[^]{0,400}?onResult:\([\w$]+\)=>this\.(?<emit>#[\w$]+)\()/,
+  insert: `globalThis.${REGISTRAR}.statusLine(this,$<payload>,(t)=>this.$<emit>(t),()=>this.$<deps>.execute($<payload>,$<rest>))||`,
+  // THE BREAKPOINT FORM, for a stock Bun session reached over its inspector (bun-attach.js), where
+  // nothing can be spliced. A breakpoint on the `return` the anchor stands after — the lookbehind is
+  // why the offset is minus its length — evaluates `action` in the controller's own frame on every
+  // command run, without pausing. That frame is inside the class body, so `this.#S` evaluates there
+  // (MEASURED on 2.1.299: JSC accepts the private name in-frame), and the action hands the registrar
+  // the controller, its deps object and its emitter. The registrar wraps `deps.execute` once, so the
+  // run answers with the newest pushed frame exactly as the splice's `||` does. Wrapping deps is
+  // per-controller because the app builds a fresh deps object literal for each controller it
+  // constructs (2.1.299). A breakpoint cannot replace a return value, which is why the wrap and not
+  // the action is what changes the answer.
+  attach: {
+    offset: -'return '.length,
+    action: `globalThis.${REGISTRAR}.attachStatusLine(this,this.$<deps>,(t)=>this.$<emit>(t))`,
+  },
+};
+
+const SEAMS = [
+  {
+    name: 'propose-goal',
+    anchor: /(?<=[;}\n]function [A-Za-z_$][\w$]*\(\)\{)return\s+[A-Za-z_$][\w$]*\("tengu_propose_goal"/,
+    insert: 'return true;',
+  },
+  STATUSLINE_PUSH,
+];
+
+module.exports = { REGISTRAR, SEAMS };

package/dist/cc-extra/src/statusline-push.js

@@ -0,0 +1,179 @@
+// statusline-push.js — draw the status line from the frames cc-candybar's daemon pushes, instead of
+// only the output of the command Claude Code reruns.
+//
+// WHY. Claude Code reruns the status line command once a second at best (`refreshInterval` is
+// clamped to a whole second, and every tick passes a 300 ms debounce that restarts itself), so an
+// animated bar moves at one frame a second. cc-candybar's daemon can push a session's frames as it
+// draws them — up to thirty a second while the bar moves, and the moment a click changes it — over a
+// `subscribe` request on its socket (cc-candybar candybar-animation-wbxz.jmm.usl). This module holds
+// one such subscription per status line controller and hands each frame to the controller's own
+// emitter, the one the command's output goes through, so the bar is drawn by the code that always
+// drew it.
+//
+// THE COMMAND KEEPS RUNNING. The daemon draws a session's frames from the latest statusline JSON it
+// was sent, and the command is what sends it: Claude Code builds that JSON and runs the command on
+// its own schedule, as it always has, so the data stays exactly as fresh as a stock session's. What
+// changes is what the command's own answer is used for. While frames arrive, the answer handed back
+// to the controller is the newest pushed frame, not the command's output — that output is the bar
+// as it stood when the command ran, an instant older than the frame already on screen, and showing
+// it would step the animation backwards once a tick. While no frames arrive (no daemon listening,
+// one too old to know `subscribe`, a session it has no data for yet), the command's output is the
+// answer, exactly as in a stock session: both come from the same daemon's one renderer, so this is
+// not a fallback to a different source. [LAW:one-source-of-truth]
+//
+// [LAW:effects-at-boundaries] the socket is passed in (`connect`), so the suite drives this with no
+// daemon. The one thing this module knows of cc-candybar's internals is its wire contract, below.
+
+'use strict';
+
+// cc-candybar's wire contract (its src/daemon/protocol.ts): every frame a 4-byte big-endian length
+// and a UTF-8 JSON body; a request names the protocol version it speaks; the daemon listens on the
+// socket `CC_CANDYBAR_SOCKET` names, else the one derived from the user's uid. A daemon on another
+// version answers VERSION_MISMATCH, which this module reports and stops on — never guesses past.
+const PROTOCOL_VERSION = 3;
+const HEADER_BYTES = 4;
+const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+const daemonSocketPath = (env, uid) => env.CC_CANDYBAR_SOCKET || `/tmp/cc-candybar-${uid}/socket`;
+
+const encodeFrame = (value) => {
+  const body = Buffer.from(JSON.stringify(value), 'utf8');
+  const header = Buffer.alloc(HEADER_BYTES);
+  header.writeUInt32BE(body.length, 0);
+  return Buffer.concat([header, body]);
+};
+
+// Calls `onFrame` with each complete frame's parsed body; `onError` once, on a frame that cannot be
+// one (too large, not JSON), after which it reads nothing more.
+function frameReader(onFrame, onError) {
+  let buf = Buffer.alloc(0);
+  let broken = false;
+  return (chunk) => {
+    if (broken) return;
+    buf = Buffer.concat([buf, chunk]);
+    while (buf.length >= HEADER_BYTES) {
+      const len = buf.readUInt32BE(0);
+      if (len > MAX_FRAME_BYTES) { broken = true; onError(new Error(`frame too large: ${len}`)); return; }
+      if (buf.length < HEADER_BYTES + len) return;
+      const body = buf.subarray(HEADER_BYTES, HEADER_BYTES + len).toString('utf8');
+      buf = buf.subarray(HEADER_BYTES + len);
+      let frame;
+      try { frame = JSON.parse(body); } catch (e) { broken = true; onError(e); return; }
+      onFrame(frame);
+    }
+  };
+}
+
+// What Claude Code does to a status line command's stdout before it draws it (MEASURED in 2.1.299's
+// command runner: trim, trim each line, drop the empty ones; nothing left is no status line). A
+// pushed frame goes through the same, so it draws exactly as the command's output would.
+const asStatusText = (output) =>
+  output.trim().split('\n').flatMap((line) => line.trim() || []).join('\n') || undefined;
+
+// The animation lane this subscription is (cc-candybar candybar-animation-wbxz.81o.azo): the daemon
+// streams it only while the session's settings switch it on (`🧪 statusline (B)` in the settings
+// menu, `globals.experimentalStatusline`), and refuses it SWITCHED_OFF otherwise.
+const LANE = 'statusline';
+
+// How long a subscription the daemon refused SWITCHED_OFF waits before it asks again: a toggle turned
+// on is picked up within this, and a lane left off costs the daemon one refusal per wait, not one per
+// run of the command.
+const SWITCHED_OFF_RETRY_MS = 5000;
+
+// [LAW:types-are-the-program] One controller's subscription, as state: none open; one open and not
+// yet carrying frames; one carrying frames, with the newest; switched off in the session's settings
+// as of `at` (ms), asked again once SWITCHED_OFF_RETRY_MS has passed; or refused for good by the
+// daemon (a version it does not speak, a request it does not know), which is not retried for that
+// session.
+//   { kind: 'closed' } | { kind: 'open', socket } | { kind: 'live', socket, text } |
+//   { kind: 'off', at } | { kind: 'refused', reason }
+
+function createStatusLinePush({ connect, socketPath, report, now = Date.now }) {
+  // WEAK, so a controller the app drops takes its subscription's bookkeeping with it. The socket
+  // itself is closed by the stream ending or by the session moving; a controller that stops running
+  // its command and is collected leaves its socket to close when the daemon or the process does.
+  const feeds = new WeakMap();
+
+  const open = (feed, sessionId) => {
+    const socket = connect(socketPath);
+    feed.sessionId = sessionId;
+    feed.state = { kind: 'open', socket };
+    const mine = () => feed.state.socket === socket;
+    const end = (why) => {
+      if (!mine()) return;
+      feed.state = { kind: 'closed' };
+      socket.destroy();
+      report(`statusline-push sid=${JSON.stringify(sessionId)} ended: ${why}`);
+    };
+    socket.on('connect', () => {
+      socket.write(encodeFrame({ v: PROTOCOL_VERSION, kind: 'subscribe', sessionId, lane: LANE }));
+      if (!feed.off) report(`statusline-push sid=${JSON.stringify(sessionId)} subscribed`);
+    });
+    socket.on('data', frameReader(
+      (resp) => {
+        if (!mine()) return;
+        if (resp && resp.ok === true && typeof resp.output === 'string') {
+          const text = asStatusText(resp.output);
+          feed.state = { kind: 'live', socket, text };
+          feed.off = false;
+          feed.emit(text);
+          return;
+        }
+        const code = resp && resp.code;
+        // A daemon that does not know the request, or speaks another version, will refuse it the
+        // same way next tick: stop asking for this session, and say why once.
+        if (code === 'BAD_REQUEST' || code === 'VERSION_MISMATCH') {
+          feed.state = { kind: 'refused', reason: `${code}: ${resp.error}` };
+          socket.destroy();
+          report(`statusline-push sid=${JSON.stringify(sessionId)} refused: ${code}: ${resp.error}`);
+          return;
+        }
+        // The lane is switched off in the session's settings: the command's own answer shows, and
+        // the subscription is asked again after a wait. Said once, until a frame streams again.
+        if (code === 'SWITCHED_OFF') {
+          feed.state = { kind: 'off', at: now() };
+          socket.destroy();
+          if (!feed.off) report(`statusline-push sid=${JSON.stringify(sessionId)} switched off: ${resp.error}`);
+          feed.off = true;
+          return;
+        }
+        // A frame the daemon could not draw: the command's own answer shows how it failed, as in a
+        // stock session, until a frame draws again.
+        feed.state = { kind: 'open', socket };
+        report(`statusline-push sid=${JSON.stringify(sessionId)} frame failed: ${code}: ${resp && resp.error}`);
+      },
+      (e) => end(`unreadable frame: ${e.message}`),
+    ));
+    socket.on('error', (e) => end(e.message));
+    socket.on('close', () => end('closed by the daemon'));
+  };
+
+  // What the spliced statement calls each time the controller runs its command: the controller, the
+  // statusline JSON it built, its own emitter, and the run itself. Always a promise, so the splice's
+  // `||` never reaches the original call it leaves in place.
+  async function statusLine(controller, payload, emit, run) {
+    // `off`: the last refusal said the lane is switched off, so the retries it causes are not news.
+    const feed = feeds.get(controller) || { sessionId: null, state: { kind: 'closed' }, emit, off: false };
+    feeds.set(controller, feed);
+    feed.emit = emit;
+    // [LAW:dataflow-not-control-flow] the session the subscription is for is read off every payload,
+    // so a new session id (after /clear) moves it, and a closed one reopens on the next run.
+    const sessionId = payload.session_id;
+    const moved = feed.sessionId !== sessionId;
+    if (moved && feed.state.socket) {
+      const old = feed.state.socket;
+      feed.state = { kind: 'closed' };
+      old.destroy();
+    }
+    if (moved) feed.off = false;
+    const due = feed.state.kind === 'closed' ||
+      (feed.state.kind === 'off' && now() - feed.state.at >= SWITCHED_OFF_RETRY_MS);
+    if (moved || due) open(feed, sessionId);
+    const ran = await run();
+    return feed.state.kind === 'live' ? feed.state.text : ran;
+  }
+
+  return { statusLine };
+}
+
+module.exports = { LANE, PROTOCOL_VERSION, SWITCHED_OFF_RETRY_MS, asStatusText, createStatusLinePush, daemonSocketPath, encodeFrame, frameReader };

package/dist/cc-extra/src/ws-unix.js

@@ -0,0 +1,125 @@
+// ws-unix.js — a WebSocket client over a unix socket, for the one peer this repo talks to that way:
+// the inspector a Bun binary opens when `BUN_INSPECT=ws+unix://<path>` is set.
+//
+// WHY NOT node's WebSocket. Node's global WebSocket dials TCP only, and the inspector is deliberately
+// NOT on TCP: anything that can reach it can run code in the user's session, and a unix socket in a
+// 0700 directory is reachable by this user alone. So the client is the handshake (node's http client
+// already speaks Upgrade over a socketPath) and RFC 6455 framing, which is all this file is.
+//
+// The framing is pure and exported, so the suite checks it against the RFC's own vectors without a
+// server. [LAW:effects-at-boundaries]
+
+'use strict';
+
+const crypto = require('crypto');
+const http = require('http');
+
+const OPCODES = { continuation: 0x0, text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xa };
+
+// One client-to-server frame: FIN set, MASKED (RFC 6455 5.3 requires a client to mask every frame).
+// `mask` is a parameter so the suite can pin it to the RFC's example key.
+function encodeFrame(opcode, payload, mask = crypto.randomBytes(4)) {
+  const len = payload.length;
+  const lengthBytes = len < 126 ? 0 : len < 0x10000 ? 2 : 8;
+  const head = Buffer.alloc(2 + lengthBytes + 4);
+  head[0] = 0x80 | opcode;
+  head[1] = 0x80 | (lengthBytes === 0 ? len : lengthBytes === 2 ? 126 : 127);
+  if (lengthBytes === 2) head.writeUInt16BE(len, 2);
+  if (lengthBytes === 8) head.writeBigUInt64BE(BigInt(len), 2);
+  mask.copy(head, 2 + lengthBytes);
+  const body = Buffer.alloc(len);
+  for (let i = 0; i < len; i++) body[i] = payload[i] ^ mask[i % 4];
+  return Buffer.concat([head, body]);
+}
+
+// Reads server-to-client frames from a byte stream: returns a function to feed chunks, and calls
+// `onFrame({ fin, opcode, payload })` for each complete frame. A server must not mask (RFC 6455 5.1);
+// a masked one is a protocol error, reported through `onError` once, after which nothing more is read.
+function frameReader(onFrame, onError) {
+  let buf = Buffer.alloc(0);
+  let broken = false;
+  return (chunk) => {
+    if (broken) return;
+    buf = Buffer.concat([buf, chunk]);
+    while (buf.length >= 2) {
+      const fin = (buf[0] & 0x80) !== 0;
+      const opcode = buf[0] & 0x0f;
+      if (buf[1] & 0x80) { broken = true; onError(new Error('server sent a masked frame')); return; }
+      const short = buf[1] & 0x7f;
+      const lengthBytes = short === 126 ? 2 : short === 127 ? 8 : 0;
+      if (buf.length < 2 + lengthBytes) return;
+      const len = lengthBytes === 2 ? buf.readUInt16BE(2) : lengthBytes === 8 ? Number(buf.readBigUInt64BE(2)) : short;
+      const start = 2 + lengthBytes;
+      if (buf.length < start + len) return;
+      onFrame({ fin, opcode, payload: buf.subarray(start, start + len) });
+      buf = buf.subarray(start + len);
+    }
+  };
+}
+
+// Joins fragmented text messages and answers the control frames, handing each whole message to
+// `onMessage(text)`. `write` sends raw bytes; `onClose` is told once, with why.
+function messageReader({ onMessage, write, onClose }) {
+  let parts = [];
+  return (frame) => {
+    if (frame.opcode === OPCODES.ping) { write(encodeFrame(OPCODES.pong, frame.payload)); return; }
+    if (frame.opcode === OPCODES.pong) return;
+    if (frame.opcode === OPCODES.close) { onClose('closed by the peer'); return; }
+    parts.push(frame.payload);
+    if (!frame.fin) return;
+    const text = Buffer.concat(parts).toString('utf8');
+    parts = [];
+    onMessage(text);
+  };
+}
+
+// Open a WebSocket to `path` on the server listening at `socketPath`. Resolves once the handshake is
+// accepted with { send(text), close(why?), listen({ onMessage, onClose }) }, or rejects naming why it was
+// not.
+function connect(socketPath, path = '/') {
+  return new Promise((resolve, reject) => {
+    const key = crypto.randomBytes(16).toString('base64');
+    const req = http.request({
+      socketPath, path,
+      headers: { Connection: 'Upgrade', Upgrade: 'websocket', 'Sec-WebSocket-Key': key, 'Sec-WebSocket-Version': '13' },
+    });
+    req.on('error', reject);
+    req.on('response', (res) => reject(new Error(`inspector refused the upgrade: HTTP ${res.statusCode}`)));
+    req.on('upgrade', (res, socket, head) => {
+      // The accept header proves the peer read OUR key, not a stale or proxied answer (RFC 6455 4.1).
+      const expected = crypto.createHash('sha1').update(key + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11').digest('base64');
+      if (res.headers['sec-websocket-accept'] !== expected) { socket.destroy(); reject(new Error('inspector answered the upgrade with the wrong accept key')); return; }
+      let listener = null;
+      let endedBecause = null;
+      const close = (why) => {
+        if (endedBecause !== null) return;
+        endedBecause = why;
+        socket.destroy();
+        if (listener) listener.onClose(why);
+      };
+      const feed = frameReader(
+        // An ended connection delivers nothing, a frame read after its close frame in the same chunk included.
+        messageReader({ onMessage: (text) => endedBecause === null && listener.onMessage(text), write: (bytes) => socket.write(bytes), onClose: close }),
+        (e) => close(e.message),
+      );
+      socket.on('error', (e) => close(e.message));
+      socket.on('close', () => close('socket closed'));
+      resolve({
+        send: (text) => socket.write(encodeFrame(OPCODES.text, Buffer.from(text, 'utf8'))),
+        close: (why = 'closed by this client') => close(why),
+        // Both handlers at once, and only then is anything read — the bytes that came with the upgrade
+        // first — so no message or close lands before there is someone to tell it to.
+        // [LAW:no-ambient-temporal-coupling] delivery starts at the one moment a listener exists.
+        listen: (handlers) => {
+          listener = handlers;
+          if (endedBecause !== null) { handlers.onClose(endedBecause); return; }
+          if (head.length) feed(head);
+          socket.on('data', feed);
+        },
+      });
+    });
+    req.end();
+  });
+}
+
+module.exports = { OPCODES, encodeFrame, frameReader, messageReader, connect };