@wrongstack/core 0.277.1 → 0.280.0

package/dist/hq/index.d.ts

@@ -1,9 +1,10 @@
-import { Z as HqRedactionPolicy, r as HqEventEnvelope, U as HqPublisher, n as HqClientIdentity, aa as HqSocketFactory, G as GlobalMailbox, ah as HqTranscriptEntry } from '../global-mailbox-Dr4cTKqL.js';
-export { D as DEFAULT_HQ_REDACTION_POLICY, H as HQ_PROTOCOL_VERSION, a as HqAgentMessagePayload, b as HqAgentStatusPayload, c as HqAlertMessage, d as HqBrowserEventMessage, e as HqBrowserMessage, f as HqBrowserSnapshotMessage, g as HqClientCapability, h as HqClientCommandAckMessage, i as HqClientCommandPollMessage, j as HqClientEventMessage, k as HqClientHeartbeatPayload, l as HqClientHelloMessage, m as HqClientHelloPayload, o as HqClientKind, p as HqClientMessage, q as HqClientRecord, s as HqEventPayloadResult, t as HqEventType, u as HqFleetEventPayload, v as HqFleetSnapshotPayload, w as HqFleetSummary, x as HqGitSnapshotPayload, y as HqMachineRecord, z as HqMailboxAgentStatus, A as HqMailboxAgentSummary, B as HqMailboxEventAction, C as HqMailboxEventPayload, E as HqMailboxMappingOptions, F as HqMailboxMessageSummary, I as HqMailboxMessageType, J as HqMailboxPriority, K as HqMailboxSnapshotOptions, L as HqMailboxSnapshotPayload, M as HqMailboxSummary, N as HqParseResult, O as HqPathPolicy, P as HqProjectIdentity, Q as HqProjectRecord, R as HqProjectStatus, S as HqProtocolVersion, T as HqPublishEventOptions, V as HqPublisherCommandHandler, W as HqPublisherCommandResult, X as HqPublisherOptions, Y as HqQueuedCommand, _ as HqServerCommandBatchMessage, $ as HqServerMessage, a0 as HqSessionAgentLiveStatus, a1 as HqSessionAgentSummary, a2 as HqSessionEndedPayload, a3 as HqSessionLiveStatus, a4 as HqSessionSnapshotPayload, a5 as HqSessionStartedPayload, a6 as HqSessionStatus, a7 as HqSessionStatusPayload, a8 as HqSessionSummary, a9 as HqSnapshot, ab as HqSocketLike, ac as HqSubagentSummary, ad as HqToolArgsPolicy, ae as HqToolCompletedPayload, af as HqToolStartedPayload, ag as HqTranscriptAppendPayload, ai as HqTranscriptRole, aj as HqUsagePayload, ak as HqWelcomePayload, al as HqWorklistCounts, am as HqWorklistSnapshotPayload, an as HqWorkspaceKind, ao as createHqEventEnvelope, ap as createMailboxEventPayload, aq as createMailboxSnapshotPayload, ar as createMailboxSnapshotPayloadFromMailbox, as as mapMailboxAgentToHqSummary, at as mapMailboxMessageToHqSummary, au as parseHqEventPayload, av as parseHqFrame } from '../global-mailbox-Dr4cTKqL.js';
-import { E as EventBus, T as TrackedAgentSnapshot } from '../brain-CCfuEOdp.js';
-import { z as HqClientConfig } from '../config-DAOjriz9.js';
-import '../mailbox-types-DTl7bRH3.js';
-import '../context-DPlA6kid.js';
+import { $ as HqRedactionPolicy, t as HqEventEnvelope, W as HqPublisher, p as HqClientIdentity, ac as HqSocketFactory, i as HqClientCapability, X as HqPublisherCommandHandler, G as GlobalMailbox, ab as HqSnapshot, _ as HqQueuedCommand, c as HqAlertMessage, aj as HqTranscriptEntry } from '../global-mailbox-Ct7IorLJ.js';
+export { D as DEFAULT_HQ_REDACTION_POLICY, H as HQ_PROTOCOL_VERSION, a as HqAgentMessagePayload, b as HqAgentStatusPayload, d as HqBrainEventKind, e as HqBrainEventPayload, f as HqBrowserEventMessage, g as HqBrowserMessage, h as HqBrowserSnapshotMessage, j as HqClientCommandAckMessage, k as HqClientCommandPollMessage, l as HqClientEventMessage, m as HqClientHeartbeatPayload, n as HqClientHelloMessage, o as HqClientHelloPayload, q as HqClientKind, r as HqClientMessage, s as HqClientRecord, u as HqEventPayloadResult, v as HqEventType, w as HqFleetEventPayload, x as HqFleetSnapshotPayload, y as HqFleetSummary, z as HqGitSnapshotPayload, A as HqMachineRecord, B as HqMailboxAgentStatus, C as HqMailboxAgentSummary, E as HqMailboxEventAction, F as HqMailboxEventPayload, I as HqMailboxMappingOptions, J as HqMailboxMessageSummary, K as HqMailboxMessageType, L as HqMailboxPriority, M as HqMailboxSnapshotOptions, N as HqMailboxSnapshotPayload, O as HqMailboxSummary, P as HqParseResult, Q as HqPathPolicy, R as HqProjectIdentity, S as HqProjectRecord, T as HqProjectStatus, U as HqProtocolVersion, V as HqPublishEventOptions, Y as HqPublisherCommandResult, Z as HqPublisherOptions, a0 as HqServerCommandBatchMessage, a1 as HqServerMessage, a2 as HqSessionAgentLiveStatus, a3 as HqSessionAgentSummary, a4 as HqSessionEndedPayload, a5 as HqSessionLiveStatus, a6 as HqSessionSnapshotPayload, a7 as HqSessionStartedPayload, a8 as HqSessionStatus, a9 as HqSessionStatusPayload, aa as HqSessionSummary, ad as HqSocketLike, ae as HqSubagentSummary, af as HqToolArgsPolicy, ag as HqToolCompletedPayload, ah as HqToolStartedPayload, ai as HqTranscriptAppendPayload, ak as HqTranscriptRole, al as HqUsagePayload, am as HqWelcomePayload, an as HqWorklistCounts, ao as HqWorklistSnapshotPayload, ap as HqWorkspaceKind, aq as HqWorktreeEventKind, ar as HqWorktreeEventPayload, as as createHqEventEnvelope, at as createMailboxEventPayload, au as createMailboxSnapshotPayload, av as createMailboxSnapshotPayloadFromMailbox, aw as mapMailboxAgentToHqSummary, ax as mapMailboxMessageToHqSummary, ay as parseHqEventPayload, az as parseHqFrame } from '../global-mailbox-Ct7IorLJ.js';
+import { E as EventBus, T as TrackedAgentSnapshot } from '../events-Bs2fmldo.js';
+import { G as HqClientConfig } from '../config-Cr3312zc.js';
+import '../mailbox-types-BGZWrYTJ.js';
+import '../tool-BkOgs_KL.js';
+import '../permission-Dx6dIqS2.js';
 
 interface HqRedactOptions {
     policy?: Partial<HqRedactionPolicy>;
@@ -33,7 +34,29 @@ interface HqPublisherEnvConfig {
     enabled?: boolean;
     rawContent?: boolean;
     projectAlias?: string;
+    /**
+     * Same-machine auto-discovery mode: no explicit URL was configured, so the
+     * publisher should re-resolve the endpoint from `<dataDir>/runtime.json`
+     * (+ the first client token in `auth.json`) before every connect attempt.
+     * This lets every client on the machine attach to a `wstack --hq` that is
+     * already running, starts later, or restarts on a different port.
+     */
+    discover?: boolean;
+    /** Resolved HQ data dir the discovery reads from. */
+    dataDir?: string;
 }
+/**
+ * Discover a locally running `wstack --hq` endpoint: reads the runtime
+ * marker (pid-liveness-checked) and the first client token. Returns
+ * `undefined` when no live HQ is advertised on this machine.
+ */
+declare function discoverLocalHqEndpoint(options?: {
+    dataDir?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+}): {
+    url: string;
+    token?: string | undefined;
+} | undefined;
 declare function resolveHqConfigFromEnv(env?: NodeJS.ProcessEnv): HqPublisherEnvConfig | undefined;
 declare function resolveHqConfig(options?: {
     env?: NodeJS.ProcessEnv | undefined;
@@ -51,6 +74,12 @@ interface CreateHqPublisherOptions {
         hq?: HqClientConfig | undefined;
     } | undefined;
     redactionPolicy?: Partial<HqRedactionPolicy>;
+    /** Forwarded to the HqPublisher constructor (Phase 4 control plane). */
+    capabilities?: readonly HqClientCapability[];
+    /** Forwarded to the HqPublisher constructor (Phase 4 control plane). */
+    onCommand?: HqPublisherCommandHandler;
+    /** Dormant discovery re-check interval override (tests / tight loops). */
+    discoveryPollMs?: number;
 }
 declare function createHqPublisherFromEnv(options: CreateHqPublisherOptions): HqPublisher | undefined;
 interface CreateGlobalMailboxOptions {
@@ -82,6 +111,13 @@ declare function resolveHqDataDir(override?: string, env?: NodeJS.ProcessEnv): s
  * `/ws/browser`) and client tokens (validated on `/ws/client`). The two
  * are stored in separate lists so a browser-only token cannot be replayed
  * against the client channel and vice versa.
+ *
+ * `capabilities` scopes what a token may do. When absent the token is
+ * unrestricted (backward-compat with tokens minted before Phase 3). Known
+ * capability strings:
+ *   - `control.enqueue` — browser token may enqueue commands to clients
+ *   - `control.execute` — client token may execute `run-command` commands
+ *   - `telemetry.publish` — client token may publish telemetry
  */
 interface HqToken {
     id: string;
@@ -89,7 +125,19 @@ interface HqToken {
     label?: string;
     createdAt: string;
     lastUsedAt?: string;
+    /**
+     * Optional capability scope. When absent, the token is unrestricted
+     * (backward-compat). When present, only the listed capabilities are
+     * granted.
+     */
+    capabilities?: string[];
 }
+/**
+ * Check whether a token grants a capability. A token with no `capabilities`
+ * field is unrestricted (backward-compat). Otherwise the capability must be
+ * explicitly listed.
+ */
+declare function tokenHasCapability(token: HqToken | undefined, capability: string): boolean;
 /**
  * Alias kept for backward-compat with Phase 3 callers/tests. New code
  * should prefer `HqToken`.
@@ -254,6 +302,455 @@ interface SessionTelemetryBridgeOptions {
  */
 declare function startSessionTelemetryBridge(opts: SessionTelemetryBridgeOptions): () => void;
 
+/**
+ * FleetTelemetryBridge — forwards local multi-agent coordinator stats to the
+ * HQ publisher as `fleet.snapshot` envelopes, so the command center can render
+ * a global fleet roll-up (queued/completed/failed tasks, per-subagent status,
+ * fleet cost) across every connected machine.
+ *
+ * Source: the `coordinator.stats` EventBus event (originating on the FleetBus
+ * and re-emitted onto the host EventBus by `fleet/host.ts`). All payload
+ * fields are plain serializable data — no closures, no decoupled relay needed.
+ *
+ * The snapshot is republished on every `coordinator.stats` change (hash-dedup,
+ * mirroring {@link startSessionTelemetryBridge}) so the HQ browser sees live
+ * fleet counters without polling.
+ *
+ * @module hq/fleet-bridge
+ */
+
+interface FleetTelemetryBridgeOptions {
+    /** Local EventBus emitting `coordinator.stats` (host EventBus after the FleetBus hop). */
+    events: EventBus;
+    /** HQ publisher to forward envelopes to. */
+    publisher: HqPublisher;
+    /** Coordinator run id — identifies this fleet instance. Falls back to a stable per-session id. */
+    runId: string;
+    /** Optional sessionId to tag envelopes with. */
+    sessionId?: string;
+    /** Override `now()` for deterministic tests. */
+    now?: () => string;
+}
+/**
+ * Start forwarding coordinator stats to HQ. Returns a disposer that
+ * unsubscribes the listener — call on shutdown.
+ */
+declare function startFleetTelemetryBridge(opts: FleetTelemetryBridgeOptions): () => void;
+
+/**
+ * BrainTelemetryBridge — forwards local Brain (decision layer) events to the
+ * HQ publisher as `brain.event` envelopes, so the command center can observe
+ * decision requests, answers, denials, ask-human escalations, and
+ * self-activated interventions across every connected machine.
+ *
+ * Source: the `brain.*` EventBus events emitted by `ObservableBrainArbiter`
+ * (`coordination/brain.ts`) and `BrainMonitor` (`coordination/brain-monitor.ts`).
+ * All payloads are plain serializable data (request id, question, source, risk,
+ * decision kind, rationale) — no closures, no decoupled relay needed.
+ *
+ * The webui `setup-events.ts` already forwards these verbatim to its browser;
+ * this bridge does the same for the cross-machine HQ plane.
+ *
+ * @module hq/brain-bridge
+ */
+
+interface BrainTelemetryBridgeOptions {
+    /** Local EventBus emitting `brain.*` events. */
+    events: EventBus;
+    /** HQ publisher to forward envelopes to. */
+    publisher: HqPublisher;
+    /** Optional sessionId to tag envelopes with. */
+    sessionId?: string;
+    /** Override `now()` for deterministic tests. */
+    now?: () => string;
+}
+/**
+ * Start forwarding brain events to HQ. Returns a disposer that unsubscribes
+ * all listeners — call on shutdown.
+ */
+declare function startBrainTelemetryBridge(opts: BrainTelemetryBridgeOptions): () => void;
+
+/**
+ * WorktreeTelemetryBridge — forwards local git-worktree lifecycle events to
+ * the HQ publisher as `worktree.event` envelopes, so the command center can
+ * render live build phase swim-lanes / DAG across every connected machine.
+ *
+ * Source: the `worktree.*` EventBus events emitted by `WorktreeManager`
+ * (`worktree/worktree-manager.ts`): allocated, committed, merged, conflict,
+ * released, failed. All payload fields are plain serializable data
+ * (handleId, ownerId, branch, diff stats, conflict files) — no closures, no
+ * decoupled relay needed.
+ *
+ * @module hq/worktree-bridge
+ */
+
+interface WorktreeTelemetryBridgeOptions {
+    /** Local EventBus emitting `worktree.*` events. */
+    events: EventBus;
+    /** HQ publisher to forward envelopes to. */
+    publisher: HqPublisher;
+    /** Optional sessionId to tag envelopes with. */
+    sessionId?: string;
+    /** Override `now()` for deterministic tests. */
+    now?: () => string;
+}
+/**
+ * Start forwarding worktree lifecycle events to HQ. Returns a disposer that
+ * unsubscribes all listeners — call on shutdown.
+ */
+declare function startWorktreeTelemetryBridge(opts: WorktreeTelemetryBridgeOptions): () => void;
+
+/**
+ * ToolTelemetryBridge — forwards local tool execution events to the HQ
+ * publisher as `tool.started` and `tool.completed` envelopes, so the command
+ * center can surface live tool activity (what's running, durations, success
+ * rates) across every connected machine.
+ *
+ * Sources:
+ *  - `tool.started` (EventBus) → `tool.started` envelope. Raw tool input is
+ *    summarized via {@link summarizeHqToolArgs} so no secrets or oversized
+ *    payloads leak to the HQ browser.
+ *  - `tool.executed` (EventBus) → `tool.completed` envelope (carries the
+ *    richer post-execution signal: duration, ok/error, output bytes).
+ *
+ * All payload fields are plain serializable data — no closures. The
+ * `tool.started.input` raw args are the only sensitive surface and are
+ * reduced to a summary before publishing.
+ *
+ * @module hq/tool-bridge
+ */
+
+interface ToolTelemetryBridgeOptions {
+    /** Local EventBus emitting `tool.started` and `tool.executed` events. */
+    events: EventBus;
+    /** HQ publisher to forward envelopes to. */
+    publisher: HqPublisher;
+    /** Project root for path redaction in tool input summaries. */
+    projectRoot?: string;
+    /** Optional sessionId to tag envelopes with. */
+    sessionId?: string;
+    /** Override `now()` for deterministic tests. */
+    now?: () => string;
+}
+/**
+ * Start forwarding tool execution events to HQ. Returns a disposer that
+ * unsubscribes all listeners — call on shutdown.
+ */
+declare function startToolTelemetryBridge(opts: ToolTelemetryBridgeOptions): () => void;
+
+/**
+ * CostTelemetryBridge — forwards local token/cost accounting events to the HQ
+ * publisher as `session.usage` envelopes, giving the command center the
+ * granular per-call cost signal it needs to render live cost trends and
+ * roll-ups across every connected machine.
+ *
+ * Source: the `token.accounted` EventBus event, emitted by the TokenCounter
+ * (`infrastructure/token-counter.ts`) after every provider call. The payload
+ * is plain serializable data (usage counts + a cost breakdown) — no closures.
+ *
+ * This is the high-frequency cost feed; HQ's persistence layer (Phase 2)
+ * time-buckets these into trend series.
+ *
+ * @module hq/cost-bridge
+ */
+
+interface CostTelemetryBridgeOptions {
+    /** Local EventBus emitting `token.accounted`. */
+    events: EventBus;
+    /** HQ publisher to forward envelopes to. */
+    publisher: HqPublisher;
+    /** Optional sessionId to tag envelopes with (overrides the event's, when set). */
+    sessionId?: string;
+    /** Override `now()` for deterministic tests. */
+    now?: () => string;
+}
+/**
+ * Start forwarding token/cost events to HQ. Returns a disposer that
+ * unsubscribes the listener — call on shutdown.
+ */
+declare function startCostTelemetryBridge(opts: CostTelemetryBridgeOptions): () => void;
+
+interface HqEventLogOptions {
+    dataDir: string;
+    maxLines?: number;
+    rotateKeep?: number;
+}
+/**
+ * Append-only JSONL event log. Every received event envelope is appended to
+ * `events.jsonl`; when the file exceeds `maxLines` it is rotated under a file
+ * lock to keep only the most recent `rotateKeep` lines.
+ *
+ * Writes are serialized through a FIFO chain so concurrent appends never
+ * interleave. All operations are best-effort: a rejected append resolves
+ * (never rejects) and the caller's `await` never breaks the server loop.
+ */
+declare class HqEventLog {
+    private readonly filePath;
+    private readonly maxLines;
+    private readonly rotateKeep;
+    private writeChain;
+    private lineCount;
+    private counted;
+    constructor(opts: HqEventLogOptions);
+    /** Append an event envelope as one JSON line. Best-effort, never rejects. */
+    append(event: HqEventEnvelope): void;
+    /** Resolves once all queued appends have settled. For tests. */
+    drain(): Promise<void>;
+    private appendInternal;
+    private rotate;
+    private countLines;
+    /**
+     * Read the most recent `limit` events, optionally filtered by envelope
+     * `type`. Newest first. Returns `[]` if the file doesn't exist yet.
+     */
+    recent(limit: number, typeFilter?: string): Promise<HqEventEnvelope[]>;
+    /** Initialize the line count cache from disk (call once at boot). */
+    hydrate(): Promise<void>;
+}
+interface HqSnapshotStoreOptions {
+    dataDir: string;
+}
+/**
+ * Atomic checkpoint of the latest snapshot, written to `snapshot.json`.
+ * The HQ server writes on every debounced broadcast and reads on boot to
+ * re-seed its in-memory state. Best-effort, never rejects.
+ */
+declare class HqSnapshotStore {
+    private readonly filePath;
+    private writeChain;
+    constructor(opts: HqSnapshotStoreOptions);
+    /** Persist a snapshot. Best-effort, never rejects. */
+    save(snapshot: HqSnapshot): void;
+    /** Resolves once all queued saves have settled. For tests. */
+    drain(): Promise<void>;
+    /** Read the last persisted snapshot, or `null` if none. */
+    load(): Promise<HqSnapshot | null>;
+}
+interface HqTimeseriesSample {
+    /** Bucket start (epoch ms, floored to the bucket width). */
+    ts: number;
+    /** Total cost (USD) accumulated in this bucket. */
+    costUsd: number;
+    /** Total input tokens in this bucket. */
+    inputTokens: number;
+    /** Total output tokens in this bucket. */
+    outputTokens: number;
+    /** Number of tool executions in this bucket. */
+    toolCalls: number;
+    /** Snapshot of active agents at bucket close (last-write per bucket). */
+    activeAgents?: number;
+}
+interface HqTimeseriesStoreOptions {
+    dataDir: string;
+    /** Bucket width in ms. Default 5 minutes. */
+    bucketMs?: number;
+    /** How many buckets to retain. Default 2016 (1 week of 5-min buckets). */
+    maxBuckets?: number;
+}
+/**
+ * Time-bucketed cost + activity samples for trend charts. Each {@link record}
+ * call folds a cost/tool signal into the current bucket; {@link flush} writes
+ * the accumulated buckets to `timeseries.jsonl` (append under lock) and prunes
+ * to `maxBuckets`.
+ *
+ * The store keeps an in-memory ring of buckets for cheap reads; {@link load}
+ * rehydrates them on boot.
+ */
+declare class HqTimeseriesStore {
+    private readonly filePath;
+    private readonly bucketMs;
+    private readonly maxBuckets;
+    private readonly buckets;
+    private flushChain;
+    constructor(opts: HqTimeseriesStoreOptions);
+    private bucketStart;
+    /** Fold a cost/tool signal into the current bucket. Best-effort. */
+    record(signal: {
+        ts?: number;
+        costUsd?: number;
+        inputTokens?: number;
+        outputTokens?: number;
+        toolCalls?: number;
+        activeAgents?: number;
+    }): void;
+    /** Persist accumulated buckets to disk (append under lock), prune to maxBuckets. */
+    flush(): void;
+    /** Resolves once all queued flushes have settled. For tests. */
+    drain(): Promise<void>;
+    private flushInternal;
+    /** Read buckets within `[since, now]`, oldest-first. */
+    read(sinceMs?: number): Promise<HqTimeseriesSample[]>;
+    /** Rehydrate buckets from disk (deduped, latest-per-bucket wins). */
+    load(): Promise<void>;
+}
+interface HqPersistence {
+    eventLog: HqEventLog;
+    snapshotStore: HqSnapshotStore;
+    timeseries: HqTimeseriesStore;
+}
+declare function createHqPersistence(dataDir: string): HqPersistence;
+
+/**
+ * HQ control-plane command definitions — typed payloads for the commands the
+ * HQ dashboard can enqueue to connected machines (Phase 3+ of the HQ command
+ * center). These are carried over the existing `HqQueuedCommand` wire shape
+ * (`{commandId, type, payload, …}`) whose `type`/`payload` were previously
+ * type-erased. This module gives them a discriminated union for type-safe
+ * dispatch on the client side (Phase 4).
+ *
+ * Security model: `run-command` (raw shell) is gated by a per-token
+ * `control.execute` capability AND an operator opt-in; the other four commands
+ * route through the agent's own decision loop / mailbox and inherit their
+ * existing guardrails. See `docs/plans/hq-command-center-2026-07.md`.
+ *
+ * @module hq/commands
+ */
+
+/** HQ_COMMAND_TYPES — the full set of recognized command `type` strings. */
+declare const HQ_COMMAND_TYPES: readonly ["steer", "abort", "spawn", "broadcast", "run-command"];
+type HqCommandType = (typeof HQ_COMMAND_TYPES)[number];
+/** Inject a steer text into a target agent's conversation. */
+interface HqSteerCommand {
+    type: 'steer';
+    /** Target agent address: a unique id (`leader@<tag>`), an alias (`leader`), or `*` for all. */
+    to: string;
+    subject: string;
+    body: string;
+    priority?: 'low' | 'normal' | 'high';
+}
+/** Abort a running agent run or fleet. */
+interface HqAbortCommand {
+    type: 'abort';
+    /** `'leader'` aborts the session leader; a subagentId aborts one agent; `'fleet'` stops all. */
+    target: 'leader' | 'fleet' | string;
+}
+/** Spawn a subagent of the given role. */
+interface HqSpawnCommand {
+    type: 'spawn';
+    role: string;
+    /** Optional task description for dispatch routing. */
+    task?: string;
+    maxIterations?: number;
+}
+/** Broadcast a mailbox message to all agents on the target's project. */
+interface HqBroadcastCommand {
+    type: 'broadcast';
+    subject: string;
+    body: string;
+    priority?: 'low' | 'normal' | 'high';
+}
+/** Run a shell command on the target machine. GATED by `control.execute`. */
+interface HqRunCommandCommand {
+    type: 'run-command';
+    command: string;
+    /** Optional working directory (defaults to the agent's project root). */
+    cwd?: string;
+}
+type HqCommand = HqSteerCommand | HqAbortCommand | HqSpawnCommand | HqBroadcastCommand | HqRunCommandCommand;
+/**
+ * Validate that an inbound `HqQueuedCommand` has a recognized `type` and a
+ * minimally well-formed payload. Returns the narrowed command on success, or
+ * `null` when the command should be rejected.
+ *
+ * This is a shape check, not a security gate — capability enforcement happens
+ * at enqueue time (browser token must have `control.enqueue`) and at execute
+ * time (`run-command` requires `control.execute`).
+ */
+declare function validateHqCommand(queued: HqQueuedCommand): HqCommand | null;
+interface HqCommandAuditEntry {
+    commandId: string;
+    type: HqCommandType;
+    clientId: string;
+    /** Who enqueued the command (browser token id, or 'anonymous' in open mode). */
+    enqueuedBy: string;
+    enqueuedAt: string;
+    status: 'queued' | 'delivered' | 'acked';
+    /** Ack status when the client has responded. */
+    ackStatus?: 'accepted' | 'completed' | 'failed' | 'rejected';
+    ackMessage?: string;
+    ackedAt?: string;
+}
+/**
+ * In-memory command audit ring. Capped; the Phase 2 persistence layer can
+ * sink entries to disk when wired (future). For now this gives the server a
+ * queryable history for `/api/commands` and snapshot enrichment.
+ */
+declare class HqCommandAuditLog {
+    private readonly entries;
+    private readonly max;
+    constructor(max?: number);
+    record(entry: HqCommandAuditEntry): void;
+    update(commandId: string, patch: Partial<HqCommandAuditEntry>): void;
+    recent(limit?: number): HqCommandAuditEntry[];
+}
+
+/**
+ * HQ alerting engine — evaluates the current snapshot against a set of
+ * operator-configurable rules and emits `hq.alert` messages when a threshold
+ * is crossed. Mirrors the BrainMonitor's self-activation logic (tool-failure
+ * streaks, error storms) but at the fleet-wide command-center scope.
+ *
+ * Rules are evaluated on a periodic tick (default 15s, unref'd) against the
+ * latest in-memory snapshot. Deduplication prevents alert storms: a rule that
+ * is still firing is not re-emitted until it clears (state machine per rule).
+ *
+ * @module hq/alerts
+ */
+
+/** Severity levels for alerts, mirroring {@link HqAlertMessage}. */
+type HqAlertSeverity = HqAlertMessage['severity'];
+interface HqAlert {
+    id: string;
+    ruleId: string;
+    severity: HqAlertSeverity;
+    message: string;
+    /** Epoch ms when the alert first fired in its current episode. */
+    firstFiredAt: number;
+    /** Epoch ms of the most recent evaluation that confirmed the alert. */
+    lastFiredAt: number;
+}
+interface HqAlertRuleConfig {
+    /** Maximum cost (USD) across the whole fleet before alerting. Default 50. */
+    costThresholdUsd?: number;
+    /** Seconds of silence from ALL machines before a stale alert fires. Default 120. */
+    staleMachineSeconds?: number;
+    /** Minimum number of active agents before concurrency alert fires. Default: disabled (0). */
+    maxAgents?: number;
+}
+/**
+ * In-memory alert state. Tracks which rules are currently firing so the same
+ * alert is not re-emitted every tick — only state transitions (cleared →
+ * firing) emit. Optionally persists to disk via a callback.
+ */
+declare class HqAlertEngine {
+    private readonly active;
+    private readonly history;
+    private readonly maxHistory;
+    private timer;
+    private readonly onAlert;
+    constructor(opts: {
+        onAlert: (alert: HqAlert) => void;
+        maxHistory?: number;
+    });
+    /**
+     * Evaluate all rules against the snapshot. Emits (via the `onAlert`
+     * callback) only for rules that newly transition to firing. Clears rules
+     * that are no longer firing. Returns the list of newly-fired alerts.
+     */
+    evaluate(snapshot: HqSnapshot | null, config?: HqAlertRuleConfig, now?: number): HqAlert[];
+    /** Currently-active (firing) alerts. */
+    activeAlerts(): HqAlert[];
+    /** Historical alerts (newest-last), capped at maxHistory. */
+    recentAlerts(limit?: number): HqAlert[];
+    /**
+     * Start periodic evaluation against a snapshot getter. The timer is
+     * unref'd so it never keeps the process alive. Returns a disposer.
+     */
+    startPeriodic(getSnapshot: () => HqSnapshot | null, config?: HqAlertRuleConfig | (() => HqAlertRuleConfig | undefined), intervalMs?: number): () => void;
+}
+/** Map an internal {@link HqAlert} to the wire {@link HqAlertMessage}. */
+declare function toAlertMessage(alert: HqAlert): HqAlertMessage;
+
 /**
  * Transcript mapper — converts raw session JSONL events into the canonical
  * {@link HqTranscriptEntry} shape used by HQ for full chat-history rendering.
@@ -290,4 +787,4 @@ declare function mergeToolResults(flat: readonly HqTranscriptEntry[]): HqTranscr
  */
 declare function buildTranscriptFromEvents(events: Iterable<Record<string, unknown>>): HqTranscriptEntry[];
 
-export { type AgentMonitorEventBridgeOptions, type CreateGlobalMailboxOptions, type CreateHqPublisherOptions, type EnsureHqFirstRunAuthResult, HQ_AUTH_FILE_VERSION, type HqAgentEventPublisher, type HqAuthFile, type HqBrowserToken, HqClientIdentity, HqEventEnvelope, HqPublisher, type HqPublisherEnvConfig, type HqRedactOptions, HqRedactionPolicy, type HqRedactionResult, type HqRuntimeFile, HqSocketFactory, type HqToken, HqTranscriptEntry, type SessionTelemetryBridgeOptions, buildTranscriptFromEvents, createGlobalMailbox, createHqPublisherFromEnv, defaultHqDataDir, emptyHqAuthFile, ensureHqFirstRunAuthFile, hqAuthFilePath, hqRuntimeFilePath, mapSessionEventToEntries, mergeToolResults, mintHqBrowserToken, mintHqToken, mutateHqAuthFile, readHqAuthFile, readHqRuntimeFileSync, redactHqEvent, redactHqValue, resolveHqConfig, resolveHqConfigFromEnv, resolveHqDataDir, scrubAndTruncateHqPreview, startAgentMonitorEventBridge, startSessionTelemetryBridge, summarizeHqToolArgs, watchHqAuthFile, writeHqAuthFile, writeHqRuntimeFile };
+export { type AgentMonitorEventBridgeOptions, type BrainTelemetryBridgeOptions, type CostTelemetryBridgeOptions, type CreateGlobalMailboxOptions, type CreateHqPublisherOptions, type EnsureHqFirstRunAuthResult, type FleetTelemetryBridgeOptions, HQ_AUTH_FILE_VERSION, HQ_COMMAND_TYPES, type HqAbortCommand, type HqAgentEventPublisher, type HqAlert, HqAlertEngine, HqAlertMessage, type HqAlertRuleConfig, type HqAlertSeverity, type HqAuthFile, type HqBroadcastCommand, type HqBrowserToken, HqClientCapability, HqClientIdentity, type HqCommand, type HqCommandAuditEntry, HqCommandAuditLog, type HqCommandType, HqEventEnvelope, HqEventLog, type HqEventLogOptions, type HqPersistence, HqPublisher, HqPublisherCommandHandler, type HqPublisherEnvConfig, HqQueuedCommand, type HqRedactOptions, HqRedactionPolicy, type HqRedactionResult, type HqRunCommandCommand, type HqRuntimeFile, HqSnapshot, HqSnapshotStore, type HqSnapshotStoreOptions, HqSocketFactory, type HqSpawnCommand, type HqSteerCommand, type HqTimeseriesSample, HqTimeseriesStore, type HqTimeseriesStoreOptions, type HqToken, HqTranscriptEntry, type SessionTelemetryBridgeOptions, type ToolTelemetryBridgeOptions, type WorktreeTelemetryBridgeOptions, buildTranscriptFromEvents, createGlobalMailbox, createHqPersistence, createHqPublisherFromEnv, defaultHqDataDir, discoverLocalHqEndpoint, emptyHqAuthFile, ensureHqFirstRunAuthFile, hqAuthFilePath, hqRuntimeFilePath, mapSessionEventToEntries, mergeToolResults, mintHqBrowserToken, mintHqToken, mutateHqAuthFile, readHqAuthFile, readHqRuntimeFileSync, redactHqEvent, redactHqValue, resolveHqConfig, resolveHqConfigFromEnv, resolveHqDataDir, scrubAndTruncateHqPreview, startAgentMonitorEventBridge, startBrainTelemetryBridge, startCostTelemetryBridge, startFleetTelemetryBridge, startSessionTelemetryBridge, startToolTelemetryBridge, startWorktreeTelemetryBridge, summarizeHqToolArgs, toAlertMessage, tokenHasCapability, validateHqCommand, watchHqAuthFile, writeHqAuthFile, writeHqRuntimeFile };