@wrongstack/cli 0.306.4 → 0.307.0

package/dist/fleet/host-learning-scheduler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Learning optimization scheduler and dispatch classifier for MultiAgentHost.
+ *
+ * @module fleet/host-learning-scheduler
+ */
+import { LearningOptimizationScheduler, type LearningOptimizerLlm } from '@wrongstack/core/agent-catalog';
+import type { MultiAgentDeps } from './host-types.js';
+export declare class HostLearningScheduler {
+    private readonly deps;
+    private learningOptimizer;
+    private learningSwept;
+    constructor(deps: MultiAgentDeps);
+    getOptimizer(): LearningOptimizationScheduler | null;
+    notifyCaptured(role: string): void;
+    sweep(): void;
+    classifyDispatch(task: string, candidates: {
+        role: string;
+        name: string;
+        summary: string;
+    }[]): Promise<{
+        role: string;
+        reason?: string | undefined;
+    } | null>;
+    resolveOptimizerLlm(): Promise<LearningOptimizerLlm | undefined>;
+    dispose(): void;
+}
+//# sourceMappingURL=host-learning-scheduler.d.ts.map

package/dist/fleet/host-shadow-manager.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Host-level Shadow Agent lifecycle and observation management.
+ *
+ * @module fleet/host-shadow-manager
+ */
+import type { SubagentConfig } from '@wrongstack/core/types';
+import type { Director } from '@wrongstack/core/coordination';
+import type { MultiAgentDeps, MultiAgentHostOptions } from './host-types.js';
+export interface HostShadowManagerContext {
+    deps: MultiAgentDeps;
+    opts: MultiAgentHostOptions;
+    getDirector: () => Director | undefined;
+    spawnAndAssign: (subagentConfig: SubagentConfig, description: string, opts?: {
+        internalTask?: boolean;
+        stopShadowAfterTask?: boolean;
+        shadowIntervalMs?: number | undefined;
+        taskContext?: {
+            kanban?: {
+                boardId?: string;
+                taskId?: string;
+                projectRoot?: string;
+            };
+        } | undefined;
+    }) => Promise<{
+        subagentId: string;
+        taskId: string;
+    }>;
+}
+export declare class HostShadowManager {
+    private readonly ctx;
+    private shadowAgentId;
+    private shadowTaskId;
+    private readonly shadowTaskIds;
+    private readonly shadowOutstandingTaskIds;
+    private readonly shadowStopAfterTaskIds;
+    private shadowHeartbeatIntervalMs;
+    private shadowAutoStartSuppressions;
+    private shadowObservedWorkDepth;
+    private shadowPassInFlight;
+    private shadowQueuedProblem;
+    private readonly shadowActivityOffHandles;
+    constructor(ctx: HostShadowManagerContext);
+    getTaskIds(): ReadonlySet<string>;
+    isShadowTask(taskId: string): boolean;
+    getAgentId(): string | null;
+    getTaskId(): string | null;
+    enterShadowSpawn(): void;
+    exitShadowSpawn(): void;
+    onShadowTaskCompleted(taskId: string, subagentId: string): void;
+    armIfNeeded(): void;
+    recordShadowAgent(subagentId: string, taskId: string, intervalMs?: number): void;
+    clearShadowAgent(subagentId?: string): void;
+    markShadowTask(taskId: string): void;
+    addStopAfterTaskId(taskId: string): void;
+    removeShadowTask(taskId: string): void;
+    isActiveSubagent(subagentId: string): boolean;
+    private noteShadowWorkStarted;
+    private noteShadowWorkCompleted;
+    requestShadowPass(reason: string): void;
+    runShadowPass(reason: string): Promise<void>;
+    private stopShadowAfterTask;
+    dispose(): void;
+}
+//# sourceMappingURL=host-shadow-manager.d.ts.map

package/dist/fleet/host.d.ts

@@ -39,30 +39,12 @@ export declare class MultiAgentHost {
      *  Bounded to 20 entries with LRU eviction to prevent unbounded memory growth. */
     private readonly acpRunnerCache;
     private readonly learningRoles;
-    /** Background distillation of captured learning into per-skill addenda. */
-    private learningOptimizer;
-    private learningSwept;
+    private readonly learningScheduler;
     /** Adaptive concurrency controller — created in buildDirector() when config has
      *  adaptiveConcurrency.enabled = true. Monitors FleetBus for 429 errors and
      *  automatically adjusts maxConcurrent to prevent rate limiting. */
     private adaptiveConcurrencyController?;
-    /** Active Shadow Agent spawned by the host or /shadow start. */
-    private shadowAgentId;
-    /** Assigned monitoring task for the active Shadow Agent. */
-    private shadowTaskId;
-    /** All internal Shadow Agent startup/heartbeat task ids, excluded from fleet summaries. */
-    private readonly shadowTaskIds;
-    /** Shadow task ids assigned but not yet completed. Prevents heartbeat backlog. */
-    private readonly shadowOutstandingTaskIds;
-    /** Shadow task ids whose subagent should stop immediately after the one-shot pass. */
-    private readonly shadowStopAfterTaskIds;
-    private shadowHeartbeatIntervalMs;
-    /** Suppresses buildDirector() auto-start while /shadow start is explicitly spawning one. */
-    private shadowAutoStartSuppressions;
-    private shadowObservedWorkDepth;
-    private shadowPassInFlight;
-    private shadowQueuedProblem;
-    private readonly shadowActivityOffHandles;
+    private readonly shadowManager;
     /** Peer-awareness status broadcaster (mailbox `status` mails on subagent
      *  transitions + rich registry heartbeats). Started in buildDirector(),
      *  stopped in dispose(). */
@@ -92,23 +74,10 @@ export declare class MultiAgentHost {
     private getCoordinator;
     /** Public accessor for the Director — used by buildRoutingRunner. */
     getDirector(): Director | undefined;
+    /** Run one shadow review pass immediately. */
+    runShadowPass(reason: string): Promise<void>;
     private ensureCoordinator;
     private buildDirector;
-    /**
-     * Arm host-owned Shadow observation. Healthy work windows stay fully
-     * deterministic; a one-shot LLM Shadow pass runs only after problematic work
-     * finishes, or when the user explicitly invokes /shadow start.
-     */
-    private armShadowAgentIfNeeded;
-    private recordShadowAgent;
-    private clearShadowAgent;
-    private markShadowTask;
-    private isActiveSubagent;
-    private noteShadowWorkStarted;
-    private noteShadowWorkCompleted;
-    private requestShadowPass;
-    private runShadowPass;
-    private stopShadowAfterTask;
     /**
      * Returns the FleetEmitTool for director-mode subagents, if the director
      * has been built. Used by makeSubagentFactory to inject the tool into
@@ -118,127 +87,30 @@ export declare class MultiAgentHost {
     /**
      * Build a per-role subagent factory: given a SubagentConfig, construct a
      * fresh, isolated Agent with the role's filtered tools and (when the config
-     * carries one) the role's persona as an appended system-prompt block. Public
-     * so the autonomy-parallel engine can reuse the exact same agent-construction
-     * path the director/spawn flow uses — each parallel slot then runs as a real,
-     * specialized, concurrency-safe agent instead of sharing the leader's Context.
+     * carries one) the role's persona as an appended system-prompt block.
      */
     makeSubagentFactory(config: Config): AgentFactory;
     /**
      * Build the per-subagent runner.
-     *
-     * ACP agents (provider: 'acp') get their own runner via
-     * makeACPSubagentRunner — they run external processes and don't go
-     * through the Agent factory. Regular agents use the standard
-     * makeAgentSubagentRunner path.
      */
     buildSubagentRunner(config: Config): Promise<SubagentRunner>;
     buildACPRunner(subagentId: string): Promise<SubagentRunner>;
     spawnACP(subagentId: string, task: string, config: Config): Promise<string>;
-    /** Returns a tool slice for the subagent — full set unless restricted. */
     private filterTools;
-    /** Resolved shared-mailbox project dir — same as the leader's checker. */
     private mailboxProjectDir;
-    /**
-     * Construct + start the brain-gated FleetSupervisor over this director's
-     * fleet. Requires a BrainArbiter (production always wires one); without
-     * it there is no safe decision path, so supervision stays off. All
-     * actions flow through Director APIs — the supervisor never touches
-     * coordinator internals or budget negotiation.
-     */
     private buildFleetSupervisor;
-    /**
-     * Fire-and-forget report-back (wired as the Director's
-     * `taskResultNotifier`): posts a non-awaited task's outcome to THIS
-     * session's leader via the project mailbox. The leader's mailbox checker
-     * injects it inline before the next step, so `assign_task`-without-await
-     * results reach the conversation without polling. The body carries a
-     * short excerpt only — the full result stays in the director's completed
-     * cache, retrievable via `await_tasks`/`roll_up`.
-     */
     private reportTaskResultToLeader;
     private subagentToolRegistry;
-    /**
-     * Spawn a fresh subagent and assign a single task. Returns task id.
-     *
-     * Optional `opts` lets the caller (a `/spawn` slash command or the
-     * future director surface) override the subagent's provider, model,
-     * and tool slice on a per-spawn basis. Without options, the legacy
-     * behavior holds: the subagent uses the leader's provider/model and
-     * the full tool registry.
-     */
     spawn(description: string, opts?: HostSpawnOptions): Promise<{
         subagentId: string;
         taskId: string;
     }>;
-    /**
-     * Spawn a fresh subagent, assign a task, and **await** its completion.
-     *
-     * Unlike `spawn()`, which returns immediately with spawn metadata, this
-     * method blocks until the subagent finishes (success, failure, or timeout)
-     * and returns the full `TaskResult`. Use this when the caller needs the
-     * subagent's actual output — e.g. `/techstack` displaying the generated report
-     * in chat, or `/spawn` showing the result inline.
-     *
-     * Optional `opts` lets the caller override the subagent's provider, model,
-     * and tool slice per spawn.
-     */
     spawnAndWait(description: string, opts?: HostSpawnAndWaitOptions): Promise<TaskResult>;
-    /**
-     * Common spawn + assign logic shared by both director mode and raw
-     * coordinator mode. Extracts the identical body from the two branches
-     * in `spawn()` so future changes (e.g. adding a new field to both
-     * paths) are made in one place.
-     *
-     * Returns `{ subagentId, taskId }`. Caller holds `pending` tracking
-     * and event emission — the helper only talks to the coordinator.
-     */
     private _spawnAndAssign;
-    /**
-     * Relay a `task.completed` notification (from either the Director or
-     * the raw coordinator) to the EventBus so non-director TUIs and any
-     * other observer can react. We forward the full result shape rather
-     * than mutating the existing `task.completed` schema — coordination
-     * code already binds to that event, and adding subscribers there
-     * would change ordering semantics for those listeners.
-     */
     private emitLifecycleCompleted;
     private recordLearningRole;
     private captureCompletedTaskLearning;
-    /**
-     * Lazily built so a session that never spawns a subagent pays nothing, and
-     * so the policy is read from the live config rather than frozen at boot.
-     * Returns null when auto-optimization is switched off.
-     */
-    private getLearningOptimizer;
-    /**
-     * Break a dispatch tie with a model when the keyword heuristic is ambiguous.
-     *
-     * Routes through the `dispatcher` model-matrix slot when one is configured —
-     * picking a role is a short classification, so it belongs on a cheap fast
-     * model rather than the leader's — and the session default otherwise.
-     * Returning `null` on any failure leaves the dispatcher on its heuristic
-     * result, so routing degrades rather than breaking a spawn.
-     */
-    private classifyDispatch;
-    /**
-     * Resolve a model for the distillation pass. Uses the `memory-curator` slot
-     * of the model matrix when one is configured — curating learned knowledge is
-     * exactly that role's job — and the session default otherwise. A failure
-     * here is not fatal: the pass still writes the deterministic skill addenda.
-     */
-    private resolveOptimizerLlm;
-    /**
-     * Evaluate every role with learning data once per session. Without it, a
-     * role that became eligible before this session would wait for its next
-     * capture — which for a rarely-used role can be never.
-     */
-    private sweepLearningOptimization;
     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>;
@@ -248,13 +120,6 @@ export declare class MultiAgentHost {
     stopAll(): Promise<void>;
     getMaxConcurrent(): number;
     setMaxConcurrent(n: number): void;
-    /**
-     * Clean up all listeners and resources held by the host.
-     * Unregisters all EventBus/FleetBus listeners registered in `buildDirector`
-     * and stops the Director and its coordinator.
-     *
-     * Safe to call multiple times — subsequent calls are no-ops.
-     */
     dispose(): Promise<void>;
 }
 //# sourceMappingURL=host.d.ts.map

package/dist/{hq-ZK6PGN3W.js → hq-PA6RH2UW.js}

@@ -51,7 +51,7 @@ var hqCmd = async (args, deps) => {
   return 1;
 };
 async function startServer(deps) {
-  const { startHqServer } = await import("./hq-server-IVZLVCFV.js");
+  const { startHqServer } = await import("./hq-server-PBRU275L.js");
   const dataDir = resolveDataDir(deps);
   const flags = deps.flags ?? {};
   const host = typeof flags["host"] === "string" ? flags["host"] : HQ_CLI_DEFAULT_HOST;
@@ -701,4 +701,4 @@ export {
   hqCmd,
   resolveAuditActor
 };
-//# sourceMappingURL=hq-ZK6PGN3W.js.map
+//# sourceMappingURL=hq-PA6RH2UW.js.map

package/dist/hq-server/mailbox-gateway-manager.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Mailbox gateway management and idle eviction for HQ server.
+ *
+ * @module hq-server/mailbox-gateway-manager
+ */
+import type { IncomingMessage } from 'node:http';
+import { type MailboxHttpAccessDecision, MailboxHttpRateLimiter } from '@wrongstack/core/coordination';
+import type { HqAuthState } from './auth-state.js';
+import { type HqRouterMailboxGateway } from './routes.js';
+import type { HqSessionEntry } from './types.js';
+export interface MailboxGatewayManagerDeps {
+    host: string;
+    port: number;
+    mutableAuth: HqAuthState['mutableAuth'];
+    sessions: Map<string, HqSessionEntry>;
+}
+export declare class MailboxGatewayManager {
+    private readonly deps;
+    readonly mailboxGateways: Map<string, HqRouterMailboxGateway>;
+    readonly mailboxGatewayLastUsed: Map<string, number>;
+    readonly mailboxGatewayRateLimiter: MailboxHttpRateLimiter;
+    private readonly rateLimitCleanupTimer;
+    private readonly sweepTimer;
+    private readonly MAILBOX_GATEWAY_IDLE_TTL_MS;
+    private readonly MAILBOX_GATEWAY_SWEEP_INTERVAL_MS;
+    constructor(deps: MailboxGatewayManagerDeps);
+    authorizeMailboxGateway(req: IncomingMessage, projectDir: string): MailboxHttpAccessDecision;
+    getMailboxGateway(projectDir: string): HqRouterMailboxGateway;
+    private evictIdleGateways;
+    close(): void;
+}
+//# sourceMappingURL=mailbox-gateway-manager.d.ts.map

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

@@ -0,0 +1,5 @@
+import type * as http from 'node:http';
+import type { HqRouterMutableAuth, HqSessionEntry } from '../../types.js';
+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>;
+export declare function handleApiTokenUpgrade(req: http.IncomingMessage, res: http.ServerResponse, url: URL, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, secureCookies: boolean | undefined): Promise<void>;
+//# sourceMappingURL=bootstrap-routes.d.ts.map

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

@@ -0,0 +1,11 @@
+import type * as http from 'node:http';
+import { type HqAuthFile } from '@wrongstack/core/hq';
+import { type HqBrowserAuthResult } from '../../auth.js';
+import type { HqRouterMutableAuth, HqSessionEntry } from '../../types.js';
+export declare function isLoopbackRequest(req: http.IncomingMessage): boolean;
+export declare const HQ_AUTH_ADMIN_CAPABILITY = "auth.admin";
+export declare function callerCanAdministerAuth(auth: HqBrowserAuthResult): boolean;
+export declare function writeAuthAdminRequired(res: http.ServerResponse): void;
+export declare function authorizeAuthAdmin(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>): HqBrowserAuthResult;
+export type ApplyHqAuthFile = (next: HqAuthFile) => void;
+//# sourceMappingURL=common.d.ts.map

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

@@ -0,0 +1,9 @@
+import type * as http from 'node:http';
+import type { LoginAttemptStore } from '../../login-attempt-store.js';
+import type { HqRouterMutableAuth, HqSessionEntry } from '../../types.js';
+import { type ApplyHqAuthFile } from './common.js';
+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, 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, applyAuthFile: ApplyHqAuthFile): Promise<void>;
+//# sourceMappingURL=password-routes.d.ts.map

package/dist/hq-server/routes/auth/session-audit-routes.d.ts

@@ -0,0 +1,6 @@
+import type * as http from 'node:http';
+import type { HqRouterMutableAuth, HqSessionEntry } from '../../types.js';
+export declare function handleApiAuthSessions(_req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>): void;
+export declare function handleApiAuthSessionsRevoke(_req: http.IncomingMessage, res: http.ServerResponse, url: URL, sessions: Map<string, HqSessionEntry>): Promise<void>;
+export declare function handleApiAuthAudit(_req: http.IncomingMessage, res: http.ServerResponse, dataDir: string): void;
+//# sourceMappingURL=session-audit-routes.d.ts.map

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

@@ -0,0 +1,9 @@
+import type * as http from 'node:http';
+import type { LoginAttemptStore } from '../../login-attempt-store.js';
+import type { HqRouterMutableAuth, HqSessionEntry } from '../../types.js';
+import { type ApplyHqAuthFile } from './common.js';
+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>;
+export declare function handleApiTotpSetup(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, applyAuthFile: ApplyHqAuthFile): Promise<void>;
+export declare function handleApiTotpEnable(req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, applyAuthFile: ApplyHqAuthFile): 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>;
+//# sourceMappingURL=totp-routes.d.ts.map

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

@@ -1,133 +1,6 @@
-import type * as http from 'node:http';
-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, 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, 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.
- *
- * The bootstrap flow above already gives fresh startup URLs a cookie and never
- * persists a client-side credential. What it does not cover is the *legacy*
- * paths: an older `?token=` startup URL, and manual token entry in the token
- * gate. Both leave the raw token in `sessionStorage`, where any script on the
- * origin can read it. This endpoint lets the SPA complete that migration on
- * its own — authenticate once with the token it already holds, receive a
- * cookie, and delete the stored copy.
- *
- * The minted session is exactly the one `handleApiBootstrap` mints: `kind:
- * 'token'` carrying the source token's id. That matters because
- * `authenticateBrowserRequest` re-resolves a token-origin session's
- * capabilities from the LIVE token record on every request, so upgrading
- * grants nothing the token did not already grant and dies the moment the token
- * is revoked. No privilege boundary is crossed: the caller proved possession
- * of the token, and the cookie is strictly weaker (HttpOnly, same-origin,
- * server-expiring).
- */
-export declare function handleApiTokenUpgrade(req: http.IncomingMessage, res: http.ServerResponse, url: URL, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, secureCookies: boolean | undefined): Promise<void>;
-/**
- * POST `/api/login/verify` — complete 2FA for a pending-2FA session.
- * Accepts either a TOTP `code` or a `recoveryCode`. On success, the pending
- * 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, 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
- * persisted as `totpPendingSecret` — login does NOT check this field, so
- * an unconfirmed setup cannot lock the operator out. 2FA becomes active
- * only after `/api/auth/totp/enable` verifies a code.
- *
- * 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, 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, 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, applyAuthFile: ApplyHqAuthFile, trustedProxyHops: number): Promise<void>;
-/**
- * GET `/api/auth/sessions` — list all active browser sessions for the
- * 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;
-/**
- * DELETE `/api/auth/sessions/:id` — revoke a single session by ID.
- * DELETE `/api/auth/sessions` — revoke ALL sessions (force logout everyone).
- */
-export declare function handleApiAuthSessionsRevoke(_req: http.IncomingMessage, res: http.ServerResponse, url: URL, sessions: Map<string, HqSessionEntry>): Promise<void>;
-/**
- * GET `/api/auth/audit` — recent auth events for the audit panel.
- * Returns the last 50 entries from auth-audit.jsonl, newest first.
- */
-export declare function handleApiAuthAudit(_req: http.IncomingMessage, res: http.ServerResponse, dataDir: string): void;
+export { authorizeAuthAdmin, callerCanAdministerAuth, HQ_AUTH_ADMIN_CAPABILITY, isLoopbackRequest, writeAuthAdminRequired, type ApplyHqAuthFile, } from './auth/common.js';
+export { handleApiAuthStatus, handleApiLogin, handleApiLogout, handleApiPassword, } from './auth/password-routes.js';
+export { handleApiLoginVerify, handleApiTotpDisable, handleApiTotpEnable, handleApiTotpSetup, } from './auth/totp-routes.js';
+export { handleApiBootstrap, handleApiTokenUpgrade, } from './auth/bootstrap-routes.js';
+export { handleApiAuthAudit, handleApiAuthSessions, handleApiAuthSessionsRevoke, } from './auth/session-audit-routes.js';
 //# sourceMappingURL=auth-handlers.d.ts.map

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

@@ -0,0 +1,7 @@
+import type * as http from 'node:http';
+import type { HqCommandAuditLog } from '@wrongstack/core/hq';
+import type { TrustBoundary } from '@wrongstack/core/security';
+import type { WebSocket } from 'ws';
+import type { ConnectedClient, HqRouterMutableAuth, HqSessionEntry } from '../types.js';
+export declare function handleApiCommand(req: http.IncomingMessage, res: http.ServerResponse, url: URL, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, clients: Map<WebSocket, ConnectedClient>, browsers: Set<WebSocket>, auditLog: HqCommandAuditLog, trustBoundary: TrustBoundary): Promise<void>;
+//# sourceMappingURL=command-handlers.d.ts.map

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

@@ -0,0 +1,8 @@
+import type * as http from 'node:http';
+import type { createHqPersistence } from '@wrongstack/core/hq';
+import type { WebSocket } from 'ws';
+import type { ConnectedClient } from '../types.js';
+export declare function handleApiProjectDetail(_req: http.IncomingMessage, res: http.ServerResponse, url: URL, clients: Map<WebSocket, ConnectedClient>): Promise<void>;
+export declare function handleApiEvents(req: http.IncomingMessage, res: http.ServerResponse, persistence: ReturnType<typeof createHqPersistence>): Promise<void>;
+export declare function handleApiTrendsCost(req: http.IncomingMessage, res: http.ServerResponse, persistence: ReturnType<typeof createHqPersistence>): Promise<void>;
+//# sourceMappingURL=data-handlers.d.ts.map

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

@@ -0,0 +1,22 @@
+import type * as http from 'node:http';
+import { type MailboxHttpAccessDecision } from '@wrongstack/core/coordination';
+import { authenticateBrowserRequest } from '../auth.js';
+import type { HqRouterMailboxGateway, HqRouterMutableAuth, HqSessionEntry } from '../types.js';
+/**
+ * Does this authenticated caller hold `control.enqueue`?
+ *
+ * WS-012: this predicate was inlined at two call sites with a subtly different
+ * unauthenticated fallback (`!inBrowserTokenMode` vs
+ * `mutableAuth.browserTokens.size === 0` — equivalent, but drifting), and a
+ * third route, `POST /api/mailbox/messages/:id/action`, skipped it entirely:
+ * its auth parameters were `_`-prefixed to mark them deliberately unused. That
+ * left mailbox mutation (mark-read, acknowledge, reopen, soft-delete, restore)
+ * reachable by any authenticated caller regardless of capability.
+ *
+ * One helper so the three cannot diverge again.
+ */
+export declare function callerCanEnqueue(auth: ReturnType<typeof authenticateBrowserRequest>, mutableAuth: HqRouterMutableAuth): boolean;
+export declare function handleMailboxGateway(_req: http.IncomingMessage, res: http.ServerResponse, match: RegExpMatchArray, authorizeMailboxGateway: (req: http.IncomingMessage, projectDir: string) => MailboxHttpAccessDecision, getMailboxGateway: (projectDir: string) => HqRouterMailboxGateway, dataDir: string): Promise<void>;
+export declare function handleApiMailboxSend(_req: http.IncomingMessage, res: http.ServerResponse, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, getMailboxGateway: (projectDir: string) => HqRouterMailboxGateway, hqSessionTag: string): Promise<void>;
+export declare function handleMailboxAction(_req: http.IncomingMessage, res: http.ServerResponse, match: RegExpMatchArray, mutableAuth: HqRouterMutableAuth, sessions: Map<string, HqSessionEntry>, dataDir: string, getMailboxGateway: (projectDir: string) => HqRouterMailboxGateway): Promise<void>;
+//# sourceMappingURL=mailbox-handlers.d.ts.map

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

@@ -9,9 +9,9 @@
  */
 import type * as http from 'node:http';
 import type { createMailboxHttpRouter } from '@wrongstack/core/coordination';
-import { type Mailbox, type MailboxHttpAccessDecision, type MailboxHttpRateLimiter } from '@wrongstack/core/coordination';
+import type { Mailbox, MailboxHttpAccessDecision, MailboxHttpRateLimiter } from '@wrongstack/core/coordination';
 import type { HqAlertEngine, HqCommandAuditLog, HqEventEnvelope, HqSnapshot, HqTranscriptEntry } from '@wrongstack/core/hq';
-import { type createHqPersistence } from '@wrongstack/core/hq';
+import type { createHqPersistence } from '@wrongstack/core/hq';
 import type { TrustBoundary } from '@wrongstack/core/security';
 import type { WebSocket } from 'ws';
 import * as HqServerAuth from './auth.js';
@@ -89,7 +89,7 @@ export interface HqRouterDeps {
     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
+    * `HqAuthState.apply` so the in-process mutation routes share one projection
      * — and one WS-010 exposure re-assessment — with the reload watcher.
      */
     applyAuthFile: ApplyHqAuthFile;

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

@@ -0,0 +1,37 @@
+/**
+ * HQ server lifecycle and shutdown management.
+ *
+ * @module hq-server/server-lifecycle
+ */
+import type { Server as HttpServer } from 'node:http';
+import type { WebSocket, WebSocketServer } from 'ws';
+import type { HqPersistence } from '@wrongstack/core/hq';
+import type { LoginAttemptStore } from './login-attempt-store.js';
+import type { MailboxGatewayManager } from './mailbox-gateway-manager.js';
+export interface HqServerShutdownParams {
+    cleanupTimer: NodeJS.Timeout;
+    browserHeartbeatTimer: NodeJS.Timeout;
+    timeseriesFlushTimer: NodeJS.Timeout;
+    sessionCleanupTimer: NodeJS.Timeout;
+    loginAttempts: LoginAttemptStore;
+    stopAlertEngine: () => void;
+    authWatcher: {
+        close(): void;
+    };
+    snapshotBroadcaster: {
+        close(): void;
+    };
+    bootstrapStore: {
+        clear(): void;
+    };
+    persistence: HqPersistence;
+    browsers: Set<WebSocket>;
+    clients: Map<WebSocket, unknown>;
+    wss: WebSocketServer;
+    mailboxManager: MailboxGatewayManager;
+    httpServer: HttpServer;
+    dataDir: string;
+    hqUrl: string;
+}
+export declare function createHqServerShutdown(params: HqServerShutdownParams): () => Promise<void>;
+//# sourceMappingURL=server-lifecycle.d.ts.map