@wrongstack/cli 0.306.3 → 0.307.0

package/dist/hq-server/snapshot.d.ts

@@ -44,11 +44,12 @@ export declare function sendGuarded(ws: WebSocket, data: string): boolean;
  * That is both retained memory and, worse, permanent weight in every
  * `buildSnapshot()` broadcast to every browser.
  *
- * A live session republishes unconditionally every 2.5s (`session-bridge.ts`
- * forces the snapshot on a timer, bypassing its own dedupe hash), so
- * `receivedAt` is a true liveness signal rather than a change signal. Five
- * minutes is 120 consecutive missed publishes — far past any GC pause,
- * scheduler stall, or transient hiccup, so this never evicts a live session.
+ * A live session refreshes `receivedAt` with every changed snapshot, and
+ * `session-bridge.ts` additionally forces a keep-alive republish every
+ * 4 minutes when nothing changed (well inside this window), so `receivedAt`
+ * is a true liveness signal rather than a change signal. Five minutes is
+ * far past any GC pause, scheduler stall, or transient hiccup — and beyond
+ * the keep-alive cadence — so this never evicts a live session.
  */
 export declare const HQ_STALE_SNAPSHOT_MS: number;
 /**

package/dist/hq-server/types.d.ts

@@ -148,4 +148,8 @@ export interface ProjectDetail {
     clients: readonly HqClientRecord[];
     mailboxes: readonly HqMailboxSnapshotPayload[];
 }
+export interface HqRouterMailboxGateway {
+    mailbox: import('@wrongstack/core/coordination').Mailbox;
+    router: ReturnType<typeof import('@wrongstack/core/coordination').createMailboxHttpRouter>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/hq-server/upgrade-handler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * WebSocket upgrade and connection dispatch for HQ server.
+ *
+ * @module hq-server/upgrade-handler
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { type HqToken } from '@wrongstack/core/hq';
+import type { WebSocket, WebSocketServer } from 'ws';
+import type { HqAuthState } from './auth-state.js';
+import type { ConnectedClient, HqSessionEntry, TranscriptRing } from './types.js';
+export interface HqUpgradeHandlerDeps {
+    host: string;
+    port: number;
+    listeningPort: () => number;
+    trustedPublicOrigins: Set<string>;
+    allowFileOrigin?: boolean | undefined;
+    requireBrowserAuth?: boolean | undefined;
+    mutableAuth: HqAuthState['mutableAuth'];
+    sessions: Map<string, HqSessionEntry>;
+    clients: Map<WebSocket, ConnectedClient>;
+    clientSocketTokens: Map<WebSocket, HqToken | undefined>;
+    browsers: Set<WebSocket>;
+    eventLog: import('@wrongstack/core/hq').HqEventEnvelope[];
+    transcripts: Map<string, TranscriptRing>;
+    agentMessages: Map<string, import('@wrongstack/core/hq').HqTranscriptEntry[]>;
+    persistence: import('@wrongstack/core/hq').HqPersistence;
+    auditLog: import('@wrongstack/core/hq').HqCommandAuditLog;
+    snapshotBroadcaster: ReturnType<typeof import('./snapshot.js').createSnapshotBroadcaster>;
+    wss: WebSocketServer;
+}
+export declare function handleHqUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer, deps: HqUpgradeHandlerDeps): void;
+export declare function handleHqConnection(ws: WebSocket, req: IncomingMessage, pathname: string, deps: HqUpgradeHandlerDeps): void;
+//# sourceMappingURL=upgrade-handler.d.ts.map

package/dist/hq-server/ws-client-events.d.ts

@@ -0,0 +1,25 @@
+/**
+ * HQ server — Inbound client event handling and Kanban fanout.
+ *
+ * @module hq-server/ws-client-events
+ */
+import type { HqEventEnvelope, HqPersistence, HqRedactionPolicy, HqToken, HqTranscriptEntry } from '@wrongstack/core/hq';
+import type { WebSocket } from 'ws';
+import type { ConnectedClient, HqSnapshotBroadcaster, TranscriptRing } from './types.js';
+/**
+ * Server-side fanout of a `hq.kanban_snapshot` envelope after a merge.
+ *
+ * C2 — broadcasts the post-merge `delta` payload to every client whose
+ * `projectId` matches `projectId`.
+ *
+ * Exported for direct unit testing in `tests/hq-kanban-fanout.test.ts`.
+ */
+export declare function fanoutKanbanDelta(message: string, clients: Map<WebSocket, ConnectedClient>, _browsers: Set<WebSocket>, projectId: string): {
+    clientsNotified: number;
+    browsersNotified: number;
+};
+export declare function handleIncomingClientEvent(ws: WebSocket, incomingEvent: HqEventEnvelope, clients: Map<WebSocket, ConnectedClient>, browsers: Set<WebSocket>, auth: {
+    token?: HqToken | undefined;
+    getOperatorPolicy: () => Partial<HqRedactionPolicy> | undefined;
+}, snapshotBroadcaster: HqSnapshotBroadcaster, transcripts: Map<string, TranscriptRing>, agentMessages: Map<string, HqTranscriptEntry[]>, persistence: HqPersistence | undefined, persistEvent: (event: HqEventEnvelope) => void): void;
+//# sourceMappingURL=ws-client-events.d.ts.map

package/dist/hq-server/ws-leader.d.ts

@@ -0,0 +1,47 @@
+/**
+ * HQ server — Leader tracking, promotion, and leader loss detection.
+ *
+ * @module hq-server/ws-leader
+ */
+import type { HqEventEnvelope, HqPeerRehydrateReason, HqPersistence } from '@wrongstack/core/hq';
+import type { WebSocket } from 'ws';
+import type { ConnectedClient } from './types.js';
+/**
+ * Leader tracking: the project leader is the unique client with
+ * `control.receive` capability. The first client to register with that
+ * capability wins (`isLeader = true`); subsequent clients with the same
+ * capability are followers (`isLeader = false`). When the leader's
+ * connection is lost, the next-most-recent client with `control.receive`
+ * is promoted via `promoteNewLeader` (see `detectLeaderLoss`).
+ */
+export declare function computeIsLeader(clients: Map<WebSocket, ConnectedClient>, projectId: string, acceptedCapabilities: readonly string[]): boolean;
+/**
+ * After a leader is removed, promote the most recent surviving client with
+ * `control.receive` to leader. Returns the promoted client id, or null if
+ * no surviving client has `control.receive`.
+ */
+export declare function promoteNewLeader(clients: Map<WebSocket, ConnectedClient>, projectId: string, excludeWs: WebSocket, excludeClient: ConnectedClient): string | null;
+/**
+ * Detect leader loss and emit the appropriate envelope. Currently wired
+ * on `client.closed` (graceful close) and the two heartbeat-timeout sites
+ * in `hq-server.ts`. An `auth-revoked` call site is a planned follow-up;
+ * the `reason` parameter already accepts it.
+ *
+ * Returns `true` when a leader-loss event was actually emitted. Note:
+ * the dedup gate (`PEER_DEDUP_WINDOW_MS`) suppresses re-emit for the same
+ * `(projectId, previousLeaderHandle)` and is intentionally NOT considered
+ * a "not the leader" outcome — the lost client is still the leader; the
+ * function returns `false` purely because there is nothing new to broadcast.
+ * Callers that need to log the loss should consult `lostClient.isLeader`
+ * separately.
+ *
+ * Dedup: a `peer.rehydrate` for the same `(projectId, previousLeaderHandle)`
+ * is suppressed if one was emitted within `PEER_DEDUP_WINDOW_MS` (1 h).
+ * `peer.lost` is not deduped — a project losing its last surviving client
+ * is significant enough to emit every time the topology changes.
+ */
+export declare function detectLeaderLoss(lostClient: ConnectedClient, clients: Map<WebSocket, ConnectedClient>, browsers: Set<WebSocket>, reason: HqPeerRehydrateReason, eventSink?: {
+    eventLog: HqEventEnvelope[];
+    persistence?: HqPersistence | undefined;
+}): boolean;
+//# sourceMappingURL=ws-leader.d.ts.map

package/dist/hq-server/ws-resume.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HQ server — Client resume protocol handler.
+ *
+ * @module hq-server/ws-resume
+ */
+import type { HqClientResumeMessage, HqEventEnvelope } from '@wrongstack/core/hq';
+import type { WebSocket } from 'ws';
+import type { ConnectedClient, HqSnapshotBroadcaster } from './types.js';
+export declare function browserResumeClient(ws: WebSocket, clientId: string): Map<WebSocket, ConnectedClient>;
+/**
+ * Server-side handler for `client.resume` frames.
+ *
+ * Wired from `handleClient` when the client frame type is `client.resume`.
+ * The handler:
+ *  - Validates identity (clientId/projectId match against the WS).
+ *  - Updates `client.lastSeenAt`.
+ *  - Computes the cursor (what the client has received).
+ *  - Filters `eventLog` for envelopes with `clientId === client.clientId && env.seq > cursor`.
+ *  - Checks the log cannot serve the gap (log_unavailable).
+ *  - Checks the gap is fresh (last_seen_too_old).
+ *  - Checks the gap is not too large (gap_too_large).
+ *  - Sends `hq.resume_gap` on success.
+ *
+ * Exported for direct unit testing in `tests/hq-resume-handler.test.ts`.
+ */
+export declare function handleClientResume(ws: WebSocket, clients: Map<WebSocket, ConnectedClient>, eventLog: HqEventEnvelope[], frame: HqClientResumeMessage, snapshotBroadcaster?: HqSnapshotBroadcaster): void;
+//# sourceMappingURL=ws-resume.d.ts.map

package/dist/hq-server/ws.d.ts

@@ -3,79 +3,12 @@
  *
  * @module hq-server/ws
  */
-import type { HqClientResumeMessage, HqCommandAuditLog, HqEventEnvelope, HqPeerRehydrateReason, HqPersistence, HqRedactionPolicy, HqToken, HqTranscriptEntry } from '@wrongstack/core/hq';
+import type { HqCommandAuditLog, HqEventEnvelope, HqPersistence, HqRedactionPolicy, HqToken, HqTranscriptEntry } from '@wrongstack/core/hq';
 import { WebSocket } from 'ws';
 import type { ConnectedClient, HqSnapshotBroadcaster, TranscriptRing } from './types.js';
-/**
- * Detect leader loss and emit the appropriate envelope. Currently wired
- * on `client.closed` (graceful close) and the two heartbeat-timeout sites
- * in `hq-server.ts`. An `auth-revoked` call site is a planned follow-up;
- * the `reason` parameter already accepts it.
- *
- * Returns `true` when a leader-loss event was actually emitted. Note:
- * the dedup gate (`PEER_DEDUP_WINDOW_MS`) suppresses re-emit for the same
- * `(projectId, previousLeaderHandle)` and is intentionally NOT considered
- * a "not the leader" outcome — the lost client is still the leader; the
- * function returns `false` purely because there is nothing new to broadcast.
- * Callers that need to log the loss should consult `lostClient.isLeader`
- * separately.
- *
- * Dedup: a `peer.rehydrate` for the same `(projectId, previousLeaderHandle)`
- * is suppressed if one was emitted within `PEER_DEDUP_WINDOW_MS` (1 h).
- * `peer.lost` is not deduped — a project losing its last surviving client
- * is significant enough to emit every time the topology changes.
- */
-export declare function detectLeaderLoss(lostClient: ConnectedClient, clients: Map<WebSocket, ConnectedClient>, browsers: Set<WebSocket>, reason: HqPeerRehydrateReason, eventSink?: {
-    eventLog: HqEventEnvelope[];
-    persistence?: HqPersistence | undefined;
-}): boolean;
-/**
- * Server-side fanout of a `hq.kanban_snapshot` envelope after a merge.
- *
- * C2 — broadcasts the post-merge `delta` payload to every client whose
- * `projectId` matches `projectId`.
- *
- * BROWSERS ARE DELIBERATELY NOT NOTIFIED. They used to be — unscoped, so
- * every browser received every project's deltas — on the strength of a
- * comment claiming "the browser-side projection filters by project when it
- * applies the snapshot". No such projection exists: `hq.kanban_snapshot` is
- * absent from `HqBrowserMessage` and from the SPA's dispatch chain, so
- * `HqWsClient` parsed each frame and dropped it. The board view learns about
- * changes from the `kanban.snapshot` HQ *event* and refetches over HTTP
- * (`views/kanban.tsx`), which is why the drift was invisible.
- *
- * `browsers` stays in the signature: the fan-out is the natural place to wire
- * a real browser consumer, and the parity test in
- * `tests/hq-browser-protocol-parity.test.ts` now fails the moment a
- * browser-bound frame has no handler.
- *
- * The `delta` payload is the same touched-only payload the merge handler
- * builds (full-set broadcasts drive V8 heap exhaustion on long-lived
- * boards — see the merge handler's comment).
- *
- * Exported for direct unit testing in `tests/hq-kanban-fanout.test.ts`.
- */
-export declare function fanoutKanbanDelta(message: string, clients: Map<WebSocket, ConnectedClient>, _browsers: Set<WebSocket>, projectId: string): {
-    clientsNotified: number;
-    browsersNotified: number;
-};
-/**
- * Server-side handler for `client.resume` frames.
- *
- * Wired from `handleClient` (line 511) when the client frame type is
- * `client.resume`. The handler:
- *  - Validates identity (clientId/projectId match against the WS).
- *  - Updates `client.lastSeenAt`.
- *  - Computes the cursor (what the client has received).
- *  - Filters `eventLog` for envelopes with `clientId === client.clientId && env.seq > cursor`.
- *  - Checks the log cannot serve the gap (log_unavailable).
- *  - Checks the gap is fresh (last_seen_too_old).
- *  - Checks the gap is not too large (gap_too_large).
- *  - Sends `hq.resume_gap` on success.
- *
- * Exported for direct unit testing in `tests/hq-resume-handler.test.ts`.
- */
-export declare function handleClientResume(ws: WebSocket, clients: Map<WebSocket, ConnectedClient>, eventLog: HqEventEnvelope[], frame: HqClientResumeMessage, snapshotBroadcaster?: HqSnapshotBroadcaster): void;
+export { detectLeaderLoss } from './ws-leader.js';
+export { fanoutKanbanDelta } from './ws-client-events.js';
+export { handleClientResume } from './ws-resume.js';
 export declare function handleBrowser(ws: WebSocket, snapshotBroadcaster: HqSnapshotBroadcaster, browsers: Set<WebSocket>, eventLog: HqEventEnvelope[]): void;
 export declare function handleClient(ws: WebSocket, clients: Map<WebSocket, ConnectedClient>, browsers: Set<WebSocket>, eventLog: HqEventEnvelope[], auth: {
     token?: HqToken | undefined;

package/dist/{hq-server-IVZLVCFV.js → hq-server-PBRU275L.js}

@@ -15,7 +15,7 @@ import {
   readLocalSubagentTranscript,
   sanitizeApiError,
   startHqServer
-} from "./chunk-RHLQT3EV.js";
+} from "./chunk-CB35UVXO.js";
 import "./chunk-KE7E7DPX.js";
 import "./chunk-Q5GTM25S.js";
 import "./chunk-7OCVIDC7.js";
@@ -37,4 +37,4 @@ export {
   sanitizeApiError,
   startHqServer
 };
-//# sourceMappingURL=hq-server-IVZLVCFV.js.map
+//# sourceMappingURL=hq-server-PBRU275L.js.map

package/dist/hq-server.d.ts

@@ -24,7 +24,6 @@ export declare const BROWSER_HEARTBEAT_INTERVAL_MS = 15000;
 export declare const SESSION_SNAPSHOT_TTL_MS = 30000;
 export { agentMessageToEntry, agentRingKey, decodePathSegment, readLocalSubagentTranscript, sanitizeApiError, };
 export interface HqServerOptions {
-    /** Policy authority for control-plane command enqueue decisions. */
     trustBoundary?: TrustBoundary | undefined;
     host?: string;
     port?: number;
@@ -39,45 +38,8 @@ export interface HqServerOptions {
     allowInsecureOpen?: boolean;
     secureCookies?: boolean;
     requireBrowserAuth?: boolean;
-    /**
-     * Trust `Origin: file://` on the HTTP and WebSocket surfaces, for serving the
-     * HQ dashboard from a local file in air-gapped use. Default false.
-     *
-     * Off by default because the Host check does not contain a `file:` page — it
-     * can aim at the real HQ authority — so trusting it unconditionally let any
-     * locally-opened HTML file clear HQ's only cross-origin control (WS-081).
-     * Enable only when you actually serve the dashboard that way.
-     */
     allowFileOrigin?: boolean;
-    /**
-     * Optional time-to-live (milliseconds) stamped on the first-run browser
-     * and client tokens minted on a brand-new HQ data directory. Existing
-     * auth.json files are not modified. When set, tokens carry an `expiresAt`
-     * and the server refuses them past that timestamp; default is no expiry.
-     *
-     * Useful for short-lived deployments (CI, ephemeral relays) where a leaked
-     * first-run token should not outlive the deployment window. Set via the
-     * `--hq-token-ttl-ms` CLI flag.
-     */
     tokenTtlMs?: number;
-    /**
-     * How many trusted reverse proxies sit between a browser and this server.
-     * Controls which address the login backoff keys on (WS-106).
-     *
-     * Default `0`: `X-Forwarded-For` is ignored entirely and the socket peer is
-     * used — correct for a direct bind, and the only safe default, because the
-     * header is client-supplied and honouring it unasked would let an attacker
-     * mint a fresh rate-limit identity per request.
-     *
-     * Set it to the real hop count when HQ runs behind a tunnel or relay
-     * (`--hq-public-url`, `--hq-require-browser-auth`). Without it every request
-     * arrives from the tunnel's own address, so all users share one backoff
-     * bucket: one attacker locks out everyone, and a distributed attacker is not
-     * limited per-source at all. `1` covers the common single-tunnel case.
-     *
-     * Only the rightmost `n` forwarded entries are ever read — see
-     * `hq-server/client-address.ts`. Set via `--hq-trusted-proxy-hops`.
-     */
     trustedProxyHops?: number;
 }
 export interface HqStartupConnectionInfo {