@wrongstack/cli 0.299.0 → 0.301.0

package/dist/fleet/host-status.d.ts

@@ -1,4 +1,27 @@
 import type { TaskResult } from '@wrongstack/core/types';
+/** Read-only fleet concurrency + lifetime spawn budget snapshot for operators. */
+export interface FleetBudgetView {
+    maxConcurrent: number;
+    activeAgents: number;
+    maxSpawns: number;
+    usedSpawns: number;
+    remainingSpawns: number;
+    maxTokens?: number | undefined;
+    usedTokens?: number | undefined;
+    remainingTokens?: number | undefined;
+    maxCostUsd?: number | undefined;
+    usedCostUsd?: number | undefined;
+    remainingCostUsd?: number | undefined;
+    /** Historical ceiling from checkpoint metadata when it differed from live. */
+    checkpointMaxSpawns?: number | undefined;
+    ceilingMismatch?: boolean | undefined;
+    /** Winning source for maxConcurrent: cli-flag | env | profile | default. */
+    maxConcurrentSource?: string | undefined;
+    /** Winning source for maxSpawns: cli-flag | env | profile | default. */
+    maxSpawnsSource?: string | undefined;
+    /** Compact effective-source label for status lines. */
+    effectiveSource?: string | undefined;
+}
 export interface FleetHostStatus {
     pending: {
         taskId: string;
@@ -12,6 +35,7 @@ export interface FleetHostStatus {
         task?: string | undefined;
     }[];
     summary: string;
+    budget?: FleetBudgetView | undefined;
 }
 export interface FleetHostUsage {
     rows: Array<{
@@ -42,7 +66,14 @@ export interface FleetHostStatusInputs {
     } | null | undefined;
     completedResults?: readonly TaskResult[] | null | undefined;
     shadowTaskIds: ReadonlySet<string>;
+    budget?: FleetBudgetView | undefined;
 }
 export declare function buildFleetHostStatus(input: FleetHostStatusInputs): FleetHostStatus;
+/** Format a compact multi-line budget block for `/fleet status` and resume logs. */
+export declare function formatFleetBudgetLines(budget: FleetBudgetView, colorize?: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    amber: (s: string) => string;
+}): string[];
 export declare function aggregateFleetUsage(completed: readonly TaskResult[]): FleetHostUsage;
 //# sourceMappingURL=host-status.d.ts.map

package/dist/fleet/host-types.d.ts

@@ -58,6 +58,14 @@ export interface MultiAgentHostOptions {
     };
     /** Lifetime spawn cap for this Director. CLI default: 64. */
     maxSpawns?: number | undefined;
+    /**
+     * Winning configuration sources for concurrency / lifetime spawn ceilings
+     * (issue #323). Surfaced in `/fleet status` and WebUI budget views.
+     */
+    budgetSources?: {
+        maxConcurrent?: import('./budget-source.js').FleetBudgetSource | undefined;
+        maxSpawns?: import('./budget-source.js').FleetBudgetSource | undefined;
+    } | undefined;
     /** Maximum auto-extensions per subagent per budget kind. */
     maxBudgetExtensions?: number | undefined;
     /** Optional global Brain arbiter for director-level policy decisions. */

package/dist/fleet/host.d.ts

@@ -203,6 +203,11 @@ export declare class MultiAgentHost {
     private recordLearningRole;
     private captureCompletedTaskLearning;
     status(): FleetHostStatus;
+    /**
+     * Read-only concurrency + lifetime spawn budget for `/fleet status` and
+     * resume diagnostics. Safe when no director/fleet is active yet.
+     */
+    budgetView(): import('./host-status.js').FleetBudgetView;
     usage(): FleetHostUsage;
     manifest(): Promise<string | null>;
     promoteToDirector(): Promise<Director | null>;

package/dist/fleet/status-broadcast.d.ts

@@ -22,8 +22,8 @@
  *
  * @module fleet/status-broadcast
  */
-import type { EventBus } from '@wrongstack/core/kernel';
 import type { Mailbox } from '@wrongstack/core/coordination';
+import type { EventBus } from '@wrongstack/core/kernel';
 import type { FleetConfig } from '@wrongstack/core/types';
 export interface FleetStatusBroadcasterOptions {
     /** Host EventBus carrying the re-emitted `subagent.*` lifecycle events. */

package/dist/{hq-BDO56CX6.js → hq-LN5CJHCM.js}

@@ -36,7 +36,7 @@ var hqCmd = async (args, deps) => {
   return 1;
 };
 async function startServer(deps) {
-  const { startHqServer } = await import("./hq-server-RJLJJZU7.js");
+  const { startHqServer } = await import("./hq-server-S7HZG3PA.js");
   const dataDir = resolveDataDir(deps);
   const flags = deps.flags ?? {};
   const host = typeof flags["host"] === "string" ? flags["host"] : HQ_CLI_DEFAULT_HOST;
@@ -56,6 +56,18 @@ async function startServer(deps) {
     }
     tokenTtlMs = parsed.value;
   }
+  const rawHops = typeof flags["hq-trusted-proxy-hops"] === "string" ? flags["hq-trusted-proxy-hops"] : void 0;
+  let trustedProxyHops;
+  if (rawHops !== void 0 && rawHops.length > 0) {
+    const parsed = Number.parseInt(rawHops, 10);
+    if (!Number.isFinite(parsed) || parsed < 0 || String(parsed) !== rawHops.trim()) {
+      deps.renderer.writeError(
+        "--hq-trusted-proxy-hops must be a non-negative integer (0 = ignore X-Forwarded-For).\n"
+      );
+      return 1;
+    }
+    trustedProxyHops = parsed;
+  }
   if (password !== void 0 && password.length < 8) {
     deps.renderer.writeError("HQ password must be at least 8 characters.\n");
     return 1;
@@ -69,7 +81,8 @@ async function startServer(deps) {
       dataDir,
       allowInsecureOpen,
       ...password !== void 0 ? { password } : {},
-      ...tokenTtlMs !== void 0 ? { tokenTtlMs } : {}
+      ...tokenTtlMs !== void 0 ? { tokenTtlMs } : {},
+      ...trustedProxyHops !== void 0 ? { trustedProxyHops } : {}
     });
   } catch (err) {
     if (err instanceof HqInsecureExposureError) {
@@ -528,6 +541,12 @@ function printHelp(deps) {
 `);
   deps.renderer.write(`  --hq-token-ttl <dur>  Stamp an expiresAt on first-run tokens (e.g. 1h, 7d, 3600s).
 `);
+  deps.renderer.write(
+    `  --hq-trusted-proxy-hops <n>  Trust the rightmost n X-Forwarded-For entries when rate-limiting logins.
+                        Default 0 (ignore the header). Set to the real hop count behind a tunnel,
+                        otherwise every user shares one backoff bucket. Never guess high.
+`
+  );
   deps.renderer.write(`  --open              Open the dashboard in the default browser.
 `);
   deps.renderer.write(`  --client, -c        Operate on client tokens instead of browser tokens.
@@ -544,4 +563,4 @@ export {
   hqCmd,
   resolveAuditActor
 };
-//# sourceMappingURL=hq-BDO56CX6.js.map
+//# sourceMappingURL=hq-LN5CJHCM.js.map

package/dist/hq-server/auth-state.d.ts

@@ -5,6 +5,34 @@ export interface HqAuthState {
     apply(next: HqAuthFile): void;
     tokenStats(): NonNullable<HqSnapshot['totals']['tokenStats']>;
 }
+export interface HqAuthStateOptions {
+    /**
+     * Invoked after every {@link HqAuthState.apply}, with the freshly projected
+     * `mutableAuth`. The server wires this to the WS-010 exposure re-assessment
+     * so `requireAuthFloor` is re-latched by EVERY path that changes the live
+     * credential set — not just the `fs.watch` reload.
+     *
+     * WS-101: the in-process mutation routes (`DELETE /api/auth/password`, the
+     * TOTP endpoints, recovery-code consumption) used to run their own copy of
+     * this projection and never touched the floor, so removing the last
+     * credential on a non-loopback bind dropped HQ into open mode until the
+     * watcher happened to fire. Routing every mutation through `apply` is what
+     * makes the latch unconditional.
+     */
+    onApplied?: ((mutableAuth: HqRouterMutableAuth) => void) | undefined;
+}
+/**
+ * Project an `auth.json` document onto the live `mutableAuth` used by every
+ * HQ gate. THE single projection — `HqAuthState.apply` is its only caller and
+ * every mutation path goes through that, so there is exactly one place where
+ * "which tokens are live" is decided.
+ *
+ * Expired tokens are dropped from BOTH scopes here. The browser scope is also
+ * re-checked at the request boundary (`authenticateBrowserRequest`), but the
+ * `/ws/client` upgrade gate is a bare set-membership test, so for client
+ * tokens this filter is the only expiry enforcement there is.
+ */
+export declare function projectAuthFile(mutableAuth: HqRouterMutableAuth, next: HqAuthFile): void;
 /** Owns the live auth projection, expiry statistics, and reload audit diff. */
-export declare function createHqAuthState(authFile: HqAuthFile, dataDir: string): HqAuthState;
+export declare function createHqAuthState(authFile: HqAuthFile, dataDir: string, opts?: HqAuthStateOptions): HqAuthState;
 //# sourceMappingURL=auth-state.d.ts.map

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

@@ -42,6 +42,22 @@ export declare function hasTrustedBrowserOrigin(req: http.IncomingMessage, bound
 export declare function serializeHqSessionCookie(sessionId: string, secret: string): string;
 export declare function parseHqSessionCookie(value: string, secret: string): string | undefined;
 export declare function parseCookieHeader(cookieHeader: string | undefined): Record<string, string>;
+/**
+ * Read the HQ session cookie, preferring the `__Host-`-prefixed name.
+ *
+ * WS-103: every reader open-coded `cookies[HQ_SESSION_COOKIE] ??
+ * cookies['__Host-hq.session']`, which prefers the UNPREFIXED name. The whole
+ * point of the `__Host-` prefix is that a browser refuses to accept such a
+ * cookie unless it is Secure, Path=/, and Domain-less — guarantees a plain
+ * `hq.session` set by a sibling subdomain does not carry. Reading the weak name
+ * first hands that injected value precedence over the hardened one on exactly
+ * the deployments (`secure`) where the prefix was doing work.
+ *
+ * Signature verification still stands behind this, so a forged cookie needs
+ * `cookieSecret` — but preference order is the layer whose only job is to stop
+ * the attacker-controlled name from winning, so it should not be inverted.
+ */
+export declare function readHqSessionCookie(cookieHeader: string | undefined): string | undefined;
 export declare function setHqSessionCookie(res: http.ServerResponse, value: string, secure?: boolean): void;
 export declare function clearHqSessionCookie(res: http.ServerResponse, secure?: boolean): void;
 export declare function isTokenAuth(auth: HqBrowserAuthResult): auth is HqBrowserAuthContext;

package/dist/hq-server/client-address.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Client-address resolution for rate limiting behind a reverse proxy.
+ *
+ * WS-106: HQ's login backoff keys on `req.socket.remoteAddress`. On a direct
+ * bind that is exactly right. Behind the documented public-relay / tunnel
+ * deployment (`--hq-public-url`, `requireBrowserAuth`) it is exactly wrong:
+ * every request arrives from the tunnel's own address, so all users share one
+ * bucket and a single attacker's backoff locks out everyone — while a
+ * distributed attacker gets no per-source limiting at all.
+ *
+ * The fix is NOT to read `X-Forwarded-For` whenever it is present. That header
+ * is client-supplied; trusting it unconditionally would let an attacker mint a
+ * fresh rate-limit identity per request and remove the limiter entirely, which
+ * is strictly worse than the shared bucket. It is only meaningful when the
+ * operator states how many proxies actually sit in front of HQ.
+ *
+ * So resolution is opt-in and counted, following the well-understood
+ * `trust proxy: <n>` model:
+ *
+ *   chain = [socket.remoteAddress, ...reverse(X-Forwarded-For)]
+ *   client = chain[hops]
+ *
+ * `hops` is how many trusted proxies stand between the client and this server.
+ * The default, 0, ignores the header completely and returns the socket peer —
+ * byte-for-byte the previous behaviour.
+ *
+ * Only the rightmost `hops` entries are ever consulted, because those are the
+ * ones trusted infrastructure appended. Everything further left is whatever
+ * the client claimed and is never read. If the chain is shorter than `hops`
+ * (a client that stripped or under-filled the header), resolution falls back
+ * to the socket address rather than reaching into attacker-controlled entries:
+ * such requests then share the proxy's bucket, which throttles them rather
+ * than freeing them.
+ *
+ * @module hq-server/client-address
+ */
+import type * as http from 'node:http';
+/**
+ * Parse one `X-Forwarded-For` element into a bare address, or `undefined` when
+ * it is not one. Handles `1.2.3.4`, `1.2.3.4:5678`, `[::1]`, and `[::1]:5678`.
+ * Anything that does not parse as an IP is dropped — a forwarded chain with a
+ * junk entry must not silently become a rate-limit identity of its own.
+ */
+export declare function parseForwardedEntry(entry: string): string | undefined;
+/**
+ * Resolve the address a rate limiter should key on.
+ *
+ * @param req - the incoming request.
+ * @param trustedProxyHops - how many trusted reverse proxies sit in front of
+ *   this server. `0` (the default) ignores `X-Forwarded-For` entirely.
+ * @returns a bare IP address, or `'unknown'` when the socket has none (a
+ *   destroyed socket). `'unknown'` is a single shared bucket by design — it
+ *   should throttle, not exempt.
+ */
+export declare function resolveClientAddress(req: http.IncomingMessage, trustedProxyHops?: number): string;
+//# sourceMappingURL=client-address.d.ts.map

package/dist/hq-server/login-attempt-store.d.ts

@@ -38,27 +38,47 @@ export declare class LoginAttemptStore {
     set(key: string, entry: LoginAttemptEntry): void;
     delete(key: string): void;
     /**
-     * Compound rate-limit key for public-relay mode: IP + SHA-256(password).
-     * Limits how often the SAME password can be tried from different IPs,
-     * so a rotating-IP attacker can't bypass per-IP backoff.
+     * Rate-limit key for a *candidate password*, independent of source IP.
+     *
+     * WS-104: this used to be `cred:${ip}:${hash}`. Embedding the IP made the
+     * documented purpose — "limit how often the SAME password can be tried from
+     * different IPs" — structurally impossible, because a rotating-IP attacker
+     * got a fresh counter with every hop, exactly the case the key exists for.
+     * The IP-scoped counter is already kept separately under the bare `ip` key.
+     *
+     * Backoff caps at 16s (see {@link recordFailure}), so a global per-password
+     * counter throttles guessing without becoming a lockout an attacker could
+     * aim at the operator.
      */
-    static credentialKey(ip: string, password: string): string;
+    static credentialKey(password: string): string;
     /**
-     * Check both IP and credential keys; return the stricter (later blockedUntil).
+     * Check the IP key and — when a candidate password is supplied — the
+     * credential key too, returning the stricter (later `blockedUntil`).
+     *
+     * WS-104: `handleApiLogin` called this with `''` before parsing the request
+     * body ("we don't have the password yet") and never called it again, so the
+     * credential entries {@link recordFailure} wrote were only ever *written*.
+     * Callers now re-check once the password is known; passing no password (or
+     * an empty one) means "IP scope only".
      */
-    checkBlocked(ip: string, password: string): {
+    checkBlocked(ip: string, password?: string): {
         blocked: boolean;
         retryAfter: number;
     };
     /**
-     * Record a failed attempt on both IP and credential keys.
+     * Record a failed attempt on the IP key, and on the credential key when a
+     * candidate password is supplied. Omit the password for flows that have no
+     * one (2FA verification, TOTP disable) so they do not accumulate a
+     * meaningless `cred:sha256("")` counter shared by every such flow.
+     *
      * Returns the updated IP entry (for the response Retry-After header).
      */
-    recordFailure(ip: string, password: string, maxBackoffMs?: number): LoginAttemptEntry;
+    recordFailure(ip: string, password?: string, maxBackoffMs?: number): LoginAttemptEntry;
     /**
-     * Clear both IP and credential entries on successful login.
+     * Clear the IP entry — and the credential entry when a password is given —
+     * on successful login.
      */
-    clearOnSuccess(ip: string, password: string): void;
+    clearOnSuccess(ip: string, password?: string): void;
     /** Number of tracked entries (for diagnostics). */
     get size(): number;
     /**

package/dist/hq-server/routes/auth-handlers.d.ts

@@ -1,27 +1,59 @@
 import type * as http from 'node:http';
-import { type HqAlertRuleConfig, type HqRedactionPolicy, type HqToken } from '@wrongstack/core/hq';
+import { type HqAuthFile } from '@wrongstack/core/hq';
+import { type HqBrowserAuthResult } from '../auth.js';
 import type { LoginAttemptStore } from '../login-attempt-store.js';
 import type { HqRouterMutableAuth, HqSessionEntry } from '../types.js';
+/**
+ * Capability required to operate the account-security surface: enrolling or
+ * removing 2FA, changing the password without knowing it, listing and revoking
+ * browser sessions, and reading the auth audit log.
+ *
+ * WS-102: these routes used to gate on `if (!auth)` alone, so ANY authenticated
+ * principal could reach them — including the least-privileged token HQ mints on
+ * first run (`capabilities: ['control.enqueue']`). That token could
+ * `POST /api/auth/totp/setup` → `/enable`, receive the recovery codes, and take
+ * the `sessions.clear()` that enrollment performs. The operator was then held
+ * at `totpRequired: true` on every password login with no authenticator and no
+ * recovery codes, and `/totp/disable` demands auth they could no longer obtain:
+ * a one-request, unrecoverable lockout from a token scoped to enqueueing
+ * commands. Editing `auth.json` by hand was the only way back.
+ */
+export declare const HQ_AUTH_ADMIN_CAPABILITY = "auth.admin";
+/**
+ * True when `auth` may operate the account-security surface.
+ *
+ * - Password-origin cookie sessions (`kind: 'cookie'` with no `tokenId`) are
+ *   the operator themselves — always allowed.
+ * - A token with no `capabilities` field is unrestricted by the documented
+ *   contract in `HqToken.capabilities`, so it is allowed.
+ * - A capability-scoped token must list {@link HQ_AUTH_ADMIN_CAPABILITY}.
+ *
+ * Token-origin cookie sessions resolve their capabilities from the LIVE token
+ * record on every request (see `authenticateBrowserRequest`), so upgrading a
+ * token to a cookie never widens what it can do here.
+ */
+export declare function callerCanAdministerAuth(auth: HqBrowserAuthResult): boolean;
 export declare function handleApiAuthStatus(req: http.IncomingMessage, res: http.ServerResponse, url: URL, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, requireBrowserAuth: boolean | undefined, trustedPublicOrigins: Set<string>, secureCookies: boolean | undefined): Promise<void>;
-export declare function handleApiLogin(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, loginAttempts: LoginAttemptStore, secureCookies: boolean | undefined): Promise<void>;
+export declare function handleApiLogin(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, loginAttempts: LoginAttemptStore, secureCookies: boolean | undefined, trustedProxyHops: number): Promise<void>;
 export declare function handleApiLogout(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, secureCookies: boolean | undefined): Promise<void>;
-export declare function handleApiPassword(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, secureCookies: boolean | undefined, requireBrowserAuth: boolean | undefined): Promise<void>;
-export declare function applyAuthFile(mutableAuth: HqRouterMutableAuth, next: {
-    browserTokens?: Array<{
-        token: string;
-        id: string;
-        capabilities?: string[];
-        expiresAt?: string;
-    }>;
-    clientTokens?: Array<HqToken>;
-    redactionPolicy?: Partial<HqRedactionPolicy>;
-    passwordHash?: string;
-    cookieSecret?: string;
-    alertRules?: HqAlertRuleConfig;
-    totpSecret?: string;
-    totpPendingSecret?: string;
-    totpRecoveryCodes?: string[];
-}): void;
+export declare function handleApiPassword(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, secureCookies: boolean | undefined, requireBrowserAuth: boolean | undefined, applyAuthFile: ApplyHqAuthFile): Promise<void>;
+/**
+ * Applies a freshly-persisted `auth.json` to the live server state.
+ *
+ * WS-101: this used to be a second, hand-rolled copy of the projection in
+ * `hq-server/auth-state.ts`. The two drifted in exactly the ways duplicated
+ * security code drifts: this copy skipped the expired-token filter on the
+ * CLIENT scope (re-admitting expired `/ws/client` tokens, where the upgrade
+ * gate does no expiry check of its own), never refreshed the raw token lists
+ * behind `tokenStats()`, and — worst — never re-ran the WS-010 exposure
+ * assessment, so `DELETE /api/auth/password` on a non-loopback bind dropped
+ * every gate into open mode until the `fs.watch` debounce happened to fire.
+ *
+ * It is now a function type supplied by the server, bound to
+ * `HqAuthState.apply`, so the mutation routes and the reload watcher share one
+ * projection and one floor evaluation.
+ */
+export type ApplyHqAuthFile = (next: HqAuthFile) => void;
 export declare function handleApiBootstrap(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, secureCookies: boolean | undefined, bootstrapStore: import('@wrongstack/core/hq').HqBootstrapCodeStore): Promise<void>;
 /**
  * WS-065 — exchange a live browser token for an HttpOnly session cookie.
@@ -50,7 +82,7 @@ export declare function handleApiTokenUpgrade(req: http.IncomingMessage, res: ht
  * session is upgraded to a full session (pending2fa cleared). Recovery codes
  * are single-use: the matched hash is removed from `auth.json` on success.
  */
-export declare function handleApiLoginVerify(req: http.IncomingMessage, res: http.ServerResponse, _url: URL, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, loginAttempts: LoginAttemptStore, dataDir: string, secureCookies: boolean | undefined): Promise<void>;
+export declare function handleApiLoginVerify(req: http.IncomingMessage, res: http.ServerResponse, _url: URL, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, loginAttempts: LoginAttemptStore, dataDir: string, secureCookies: boolean | undefined, applyAuthFile: ApplyHqAuthFile, trustedProxyHops: number): Promise<void>;
 /**
  * POST `/api/auth/totp/setup` — generate a new TOTP secret (not yet active).
  * Returns the base32 secret + otpauth URI for QR display. The secret is
@@ -60,24 +92,32 @@ export declare function handleApiLoginVerify(req: http.IncomingMessage, res: htt
  *
  * Requires existing auth (cookie or token) — only the operator can set up 2FA.
  */
-export declare function handleApiTotpSetup(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string): Promise<void>;
+export declare function handleApiTotpSetup(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, applyAuthFile: ApplyHqAuthFile): Promise<void>;
 /**
  * POST `/api/auth/totp/enable` — confirm 2FA enrollment by providing a valid
  * TOTP code. Promotes `totpPendingSecret` → `totpSecret` (active), generates
  * and returns recovery codes (shown once). After this, 2FA is required for
  * password login.
  */
-export declare function handleApiTotpEnable(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string): Promise<void>;
+export declare function handleApiTotpEnable(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, applyAuthFile: ApplyHqAuthFile): Promise<void>;
 /**
  * POST `/api/auth/totp/disable` — remove TOTP 2FA entirely. Requires the
  * current password (or a valid TOTP code) as confirmation.
  */
-export declare function handleApiTotpDisable(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, loginAttempts: LoginAttemptStore, dataDir: string): Promise<void>;
+export declare function handleApiTotpDisable(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, loginAttempts: LoginAttemptStore, dataDir: string, applyAuthFile: ApplyHqAuthFile, trustedProxyHops: number): Promise<void>;
 /**
  * GET `/api/auth/sessions` — list all active browser sessions for the
- * session-management UI. Returns each session's kind, creation time,
- * last-seen time, and a truncated ID (never the full session ID — that
- * would allow cookie forgery since the session ID IS the cookie value).
+ * session-management UI.
+ *
+ * The full session ID is returned because the revoke endpoint below is keyed
+ * on it. That is safe on its own — the cookie value is `<id>.<HMAC>` and the
+ * HMAC needs `cookieSecret` — but it does hand every reader a working revoke
+ * handle for every other session, so the route is gated on `auth.admin`
+ * (WS-102) rather than on "is authenticated" as it was.
+ *
+ * The previous docstring claimed the full ID was never returned while the code
+ * returned it; the code was right about what the UI needs, the docstring was
+ * right about it deserving a gate.
  */
 export declare function handleApiAuthSessions(_req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>): void;
 /**

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

@@ -16,6 +16,7 @@ import type { createMailboxHttpRouter } from '@wrongstack/core/coordination';
 import { type Mailbox, type MailboxHttpAccessDecision, type MailboxHttpRateLimiter } from '@wrongstack/core/coordination';
 import * as HqServerAuth from './auth.js';
 import * as HqServerUtils from './utils.js';
+import { type ApplyHqAuthFile } from './routes/auth-handlers.js';
 export declare const setHqSecurityHeaders: typeof HqServerAuth.setHqSecurityHeaders;
 export declare const hasTrustedBrowserOrigin: typeof HqServerAuth.hasTrustedBrowserOrigin;
 export declare const authenticateBrowserRequest: typeof HqServerAuth.authenticateBrowserRequest;
@@ -50,7 +51,16 @@ export interface HqRouterMailboxGateway {
 export interface HqRouterDeps {
     trustBoundary: TrustBoundary;
     host: string;
-    listeningPort: number;
+    /**
+     * Getter, not a value. The router is constructed BEFORE `listen()`
+     * resolves, so a copied number froze the REQUESTED port. When the default
+     * is busy and `strictPort` is off, the scan binds `port+1` and the banner
+     * prints it — but the origin guard kept comparing against the old number and
+     * answered `403 forbidden: untrusted request origin` to the dashboard and
+     * every `/api/*` call. (The WS upgrade handler read the live local, so the
+     * failure looked like "the socket connects but the page won't load".)
+     */
+    listeningPort: () => number;
     trustedPublicOrigins: Set<string>;
     /** Trust `Origin: file://`. Off by default — see StartHqServerOptions (WS-081). */
     allowFileOrigin?: boolean | undefined;
@@ -77,6 +87,18 @@ export interface HqRouterDeps {
     getTokenStats?: (() => HqSnapshot['totals']['tokenStats'] | undefined) | undefined;
     /** One-time bootstrap code store for token-to-cookie exchange. */
     bootstrapStore?: import('@wrongstack/core/hq').HqBootstrapCodeStore | undefined;
+    /**
+     * Applies a freshly-persisted `auth.json` to live server state. Bound to
+     * `HqAuthState.apply` so the in-process mutation routes share one projection
+     * — and one WS-010 exposure re-assessment — with the reload watcher.
+     */
+    applyAuthFile: ApplyHqAuthFile;
+    /**
+     * How many trusted reverse proxies sit in front of this server. Only used to
+     * resolve the address the login backoff keys on — see `client-address.ts`.
+     * Defaults to 0, which ignores `X-Forwarded-For` entirely.
+     */
+    trustedProxyHops?: number | undefined;
 }
 /**
  * Create the HTTP request listener that handles all `/api/*` routes as well

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

@@ -83,6 +83,16 @@ export interface HqRouterMutableAuth {
     totpPendingSecret?: string | undefined;
     /** SHA-256 hashes of single-use recovery codes (live-reloaded from auth.json). */
     totpRecoveryCodes?: string[] | undefined;
+    /**
+     * Highest TOTP time-step counter already spent on a successful login
+     * (RFC 6238 §5.2 single-use). The ±1-step validation window keeps a code
+     * arithmetically valid for ~90s, so without this a code captured in transit
+     * — shoulder-surfed, read off a notification, replayed from a proxy log —
+     * authenticates a second time. Deliberately process-local and NOT persisted
+     * to auth.json: a code cannot outlive its own window, so a restart losing
+     * the marker costs at most the tail of one step.
+     */
+    totpLastUsedCounter?: number | undefined;
     alertRules: HqAlertRuleConfig | undefined;
     /**
      * WS-010: set when the live bind would become unauthenticated and

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

@@ -32,11 +32,22 @@ export declare function detectLeaderLoss(lostClient: ConnectedClient, clients: M
 /**
  * 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`, and
- *  - every browser in `browsers` (browsers are not project-scoped at the
- *    WS level; the browser-side projection filters by project when it
- *    applies the snapshot).
+ * 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
@@ -44,7 +55,7 @@ export declare function detectLeaderLoss(lostClient: ConnectedClient, clients: M
  *
  * 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): {
+export declare function fanoutKanbanDelta(message: string, clients: Map<WebSocket, ConnectedClient>, _browsers: Set<WebSocket>, projectId: string): {
     clientsNotified: number;
     browsersNotified: number;
 };

package/dist/{hq-server-RJLJJZU7.js → hq-server-S7HZG3PA.js}

@@ -15,7 +15,8 @@ import {
   readLocalSubagentTranscript,
   sanitizeApiError,
   startHqServer
-} from "./chunk-2SLSUDYS.js";
+} from "./chunk-2KDOFTTM.js";
+import "./chunk-KE7E7DPX.js";
 import "./chunk-Q5GTM25S.js";
 import "./chunk-7OCVIDC7.js";
 export {
@@ -36,4 +37,4 @@ export {
   sanitizeApiError,
   startHqServer
 };
-//# sourceMappingURL=hq-server-RJLJJZU7.js.map
+//# sourceMappingURL=hq-server-S7HZG3PA.js.map

package/dist/hq-server.d.ts

@@ -60,6 +60,25 @@ export interface HqServerOptions {
      * `--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 {
     dataDir: string;