@wrongstack/core 0.284.1 → 0.286.0

package/dist/hq/index.js

@@ -1,56 +1,71 @@
-import { randomUUID, randomBytes, createHash } from 'crypto';
-import * as syncFs from 'fs';
-import * as os from 'os';
-import { hostname } from 'os';
-import * as path2 from 'path';
-import { basename } from 'path';
-import * as fsp from 'fs/promises';
-
 // src/hq/protocol.ts
 var HQ_PROTOCOL_VERSION = 1;
 var DEFAULT_HQ_REDACTION_POLICY = {
-  rawContent: false,
-  toolArgs: "summary",
-  paths: "project-relative"
+  rawContent: true,
+  toolArgs: "full",
+  paths: "full"
 };
+var HQ_TRANSCRIPT_TEXT_CAP = 16e3;
 var KNOWN_HQ_CLIENT_FRAME_TYPES = /* @__PURE__ */ new Set([
   "client.hello",
   "client.event",
   "client.command_poll",
   "client.command_ack"
 ]);
+var HQ_CLIENT_KINDS = /* @__PURE__ */ new Set(["tui", "repl", "webui", "cli", "unknown"]);
+var HQ_WORKSPACE_KINDS = /* @__PURE__ */ new Set(["git", "directory", "unknown"]);
+var HQ_CLIENT_CAPABILITIES = /* @__PURE__ */ new Set([
+  "telemetry.publish",
+  "session.summary",
+  "fleet.summary",
+  "mailbox.summary",
+  "control.receive"
+]);
+var HQ_COMMAND_ACK_STATUSES = /* @__PURE__ */ new Set([
+  "accepted",
+  "completed",
+  "failed",
+  "rejected"
+]);
 function hasStringType(x) {
   return typeof x === "object" && x !== null && typeof x.type === "string";
 }
 function isHqClientIdentity(x) {
   if (typeof x !== "object" || x === null) return false;
   const v = x;
-  return typeof v.clientId === "string" && typeof v.kind === "string" && typeof v.machineId === "string" && typeof v.startedAt === "string";
+  return typeof v.clientId === "string" && typeof v.kind === "string" && HQ_CLIENT_KINDS.has(v.kind) && typeof v.machineId === "string" && typeof v.startedAt === "string";
 }
 function isHqProjectIdentity(x) {
   if (typeof x !== "object" || x === null) return false;
   const v = x;
-  return typeof v.projectId === "string" && typeof v.projectRoot === "string" && typeof v.projectName === "string" && typeof v.machineId === "string" && typeof v.workspaceKind === "string";
+  return typeof v.projectId === "string" && typeof v.projectRoot === "string" && typeof v.projectName === "string" && typeof v.machineId === "string" && typeof v.workspaceKind === "string" && HQ_WORKSPACE_KINDS.has(v.workspaceKind);
+}
+function isHqRedactionPolicy(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.rawContent === "boolean" && (v.toolArgs === "none" || v.toolArgs === "summary" || v.toolArgs === "redacted" || v.toolArgs === "full") && (v.paths === "none" || v.paths === "project-relative" || v.paths === "redacted" || v.paths === "full");
 }
 function isHqClientHelloPayload(x) {
   if (typeof x !== "object" || x === null) return false;
   const v = x;
-  return typeof v.protocolVersion === "number" && isHqClientIdentity(v.client) && isHqProjectIdentity(v.project) && Array.isArray(v.capabilities);
+  return typeof v.protocolVersion === "number" && isHqClientIdentity(v.client) && isHqProjectIdentity(v.project) && Array.isArray(v.capabilities) && v.capabilities.every(
+    (capability) => typeof capability === "string" && HQ_CLIENT_CAPABILITIES.has(capability)
+  ) && (v.redactionPolicy === void 0 || isHqRedactionPolicy(v.redactionPolicy));
 }
 function isHqEventEnvelope(x) {
   if (typeof x !== "object" || x === null) return false;
   const v = x;
-  return typeof v.id === "string" && typeof v.type === "string" && typeof v.schemaVersion === "number" && typeof v.timestamp === "string" && typeof v.clientId === "string" && typeof v.projectId === "string" && typeof v.seq === "number";
+  return typeof v.id === "string" && typeof v.type === "string" && v.schemaVersion === HQ_PROTOCOL_VERSION && typeof v.timestamp === "string" && typeof v.clientId === "string" && typeof v.projectId === "string" && Number.isSafeInteger(v.seq) && v.seq >= 0 && Object.hasOwn(v, "payload");
 }
 function isHqClientCommandPollMessage(x) {
   if (typeof x !== "object" || x === null) return false;
   const v = x;
-  return typeof v.clientId === "string" && typeof v.projectId === "string";
+  return typeof v.clientId === "string" && typeof v.projectId === "string" && (v.afterCommandId === void 0 || typeof v.afterCommandId === "string") && (v.limit === void 0 || Number.isSafeInteger(v.limit) && v.limit > 0 && v.limit <= 200);
 }
 function isHqClientCommandAckMessage(x) {
   if (typeof x !== "object" || x === null) return false;
   const v = x;
-  return typeof v.clientId === "string" && typeof v.projectId === "string" && typeof v.commandId === "string" && typeof v.status === "string";
+  return typeof v.clientId === "string" && typeof v.projectId === "string" && typeof v.commandId === "string" && typeof v.status === "string" && HQ_COMMAND_ACK_STATUSES.has(v.status) && (v.message === void 0 || typeof v.message === "string");
 }
 function parseHqFrame(raw) {
   let parsed;
@@ -83,7 +98,13 @@ function parseHqFrame(raw) {
       }
       return {
         ok: true,
-        frame: { type: "client.command_poll", clientId: obj.clientId, projectId: obj.projectId }
+        frame: {
+          type: "client.command_poll",
+          clientId: obj.clientId,
+          projectId: obj.projectId,
+          ...typeof obj.afterCommandId === "string" ? { afterCommandId: obj.afterCommandId } : {},
+          ...typeof obj.limit === "number" ? { limit: obj.limit } : {}
+        }
       };
     case "client.command_ack":
       if (!isHqClientCommandAckMessage(obj)) {
@@ -118,8 +139,58 @@ var KNOWN_HQ_EVENT_PAYLOAD_TYPES = /* @__PURE__ */ new Set([
   "worktree.event",
   "tool.started",
   "tool.completed",
-  "session.usage"
+  "session.usage",
+  "client.heartbeat",
+  "mcp.health.snapshot",
+  "mcp.operation"
+]);
+function isHqMcpLatencySummary(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.count === "number" && (v.lastMs === void 0 || typeof v.lastMs === "number") && (v.minMs === void 0 || typeof v.minMs === "number") && (v.maxMs === void 0 || typeof v.maxMs === "number") && (v.p50Ms === void 0 || typeof v.p50Ms === "number") && (v.p95Ms === void 0 || typeof v.p95Ms === "number");
+}
+function isHqMcpFailureCounts(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.transport === "number" && typeof v.protocol === "number" && typeof v.tool === "number";
+}
+function isHqMcpHealthCheck(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.name === "string" && typeof v.passed === "boolean" && (v.value === void 0 || typeof v.value === "number") && (v.threshold === void 0 || typeof v.threshold === "number");
+}
+var HQ_MCP_HEALTH_STATES = /* @__PURE__ */ new Set([
+  "disabled",
+  "dormant",
+  "connecting",
+  "healthy",
+  "degraded",
+  "failed"
 ]);
+var HQ_MCP_CONNECTION_STATES = /* @__PURE__ */ new Set([
+  "idle",
+  "dormant",
+  "connecting",
+  "connected",
+  "reconnecting",
+  "disconnected",
+  "failed"
+]);
+function isHqMcpServerHealth(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.name === "string" && typeof v.projectId === "string" && typeof v.clientId === "string" && typeof v.connectionState === "string" && HQ_MCP_CONNECTION_STATES.has(v.connectionState) && typeof v.healthState === "string" && HQ_MCP_HEALTH_STATES.has(v.healthState) && (v.lastSuccessAt === void 0 || typeof v.lastSuccessAt === "string") && (v.lastFailureAt === void 0 || typeof v.lastFailureAt === "string") && (v.lastFailureKind === void 0 || v.lastFailureKind === "transport" || v.lastFailureKind === "protocol" || v.lastFailureKind === "tool") && typeof v.consecutiveFailures === "number" && isHqMcpFailureCounts(v.failures) && typeof v.reconnectCount === "number" && typeof v.wakeCount === "number" && typeof v.sleepCount === "number" && typeof v.restartCount === "number" && isHqMcpLatencySummary(v.connectionLatency) && isHqMcpLatencySummary(v.discoveryLatency) && isHqMcpLatencySummary(v.callLatency) && typeof v.inFlightCalls === "number" && typeof v.peakInFlightCalls === "number" && Array.isArray(v.healthChecks) && v.healthChecks.every(isHqMcpHealthCheck);
+}
+function isHqMcpHealthSnapshotPayload(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return Array.isArray(v.servers) && v.servers.every(isHqMcpServerHealth);
+}
+function isHqMcpOperationPayload(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.operation === "object" && v.operation !== null && Array.isArray(v.servers) && v.servers.every(isHqMcpServerHealth);
+}
 function isHqMailboxMessageSummary(x) {
   if (typeof x !== "object" || x === null) return false;
   const v = x;
@@ -293,6 +364,11 @@ function isHqUsagePayload(x) {
   if (typeof x !== "object" || x === null) return false;
   return !Array.isArray(x);
 }
+function isHqClientHeartbeatPayload(x) {
+  if (typeof x !== "object" || x === null || Array.isArray(x)) return false;
+  const v = x;
+  return typeof v.uptimeMs === "number" && (v.activeSessionId === void 0 || typeof v.activeSessionId === "string") && (v.activeRunId === void 0 || typeof v.activeRunId === "string") && typeof v.status === "string" && (v.status === "active" || v.status === "idle" || v.status === "stale" || v.status === "error") && (v.activeSubagents === void 0 || typeof v.activeSubagents === "number") && (v.queuedTasks === void 0 || typeof v.queuedTasks === "number");
+}
 function parseHqEventPayload(eventType, payload) {
   if (!KNOWN_HQ_EVENT_PAYLOAD_TYPES.has(eventType)) {
     return { ok: true, payload };
@@ -322,6 +398,12 @@ function parseHqEventPayload(eventType, payload) {
       return isHqToolCompletedPayload(payload) ? { ok: true, payload } : { ok: false, reason: "malformed-payload" };
     case "session.usage":
       return isHqUsagePayload(payload) ? { ok: true, payload } : { ok: false, reason: "malformed-payload" };
+    case "client.heartbeat":
+      return isHqClientHeartbeatPayload(payload) ? { ok: true, payload } : { ok: false, reason: "malformed-payload" };
+    case "mcp.health.snapshot":
+      return isHqMcpHealthSnapshotPayload(payload) ? { ok: true, payload } : { ok: false, reason: "malformed-payload" };
+    case "mcp.operation":
+      return isHqMcpOperationPayload(payload) ? { ok: true, payload } : { ok: false, reason: "malformed-payload" };
     default: {
       const _exhaustive = eventType;
       return _exhaustive;
@@ -548,6 +630,8 @@ var RAW_CONTENT_KEYS = /* @__PURE__ */ new Set([
   "prompts",
   "completion",
   "response",
+  "text",
+  "partialText",
   "assistantMessage",
   "userMessage",
   "stdout",
@@ -555,6 +639,7 @@ var RAW_CONTENT_KEYS = /* @__PURE__ */ new Set([
   "output",
   "toolInput",
   "toolOutput",
+  "outputSummary",
   "body",
   "mailboxBody",
   "messageBody",
@@ -595,12 +680,34 @@ var PATH_KEYS = /* @__PURE__ */ new Set([
   "workingDirectory"
 ]);
 var defaultScrubber = new DefaultSecretScrubber();
-function resolvePolicy(policy) {
+function resolveHqRedactionPolicy(policy) {
   return {
     ...DEFAULT_HQ_REDACTION_POLICY,
     ...policy
   };
 }
+function tightenHqRedactionPolicy(publisherPolicy, operatorPolicy) {
+  if (operatorPolicy === void 0) return publisherPolicy;
+  const toolRank = {
+    none: 0,
+    summary: 1,
+    redacted: 2,
+    full: 3
+  };
+  const pathRank = {
+    none: 0,
+    redacted: 0,
+    "project-relative": 1,
+    full: 2
+  };
+  const requestedToolArgs = operatorPolicy.toolArgs;
+  const requestedPaths = operatorPolicy.paths;
+  return {
+    rawContent: publisherPolicy.rawContent && (operatorPolicy.rawContent === void 0 || operatorPolicy.rawContent),
+    toolArgs: requestedToolArgs !== void 0 && toolRank[requestedToolArgs] < toolRank[publisherPolicy.toolArgs] ? requestedToolArgs : publisherPolicy.toolArgs,
+    paths: requestedPaths !== void 0 && pathRank[requestedPaths] < pathRank[publisherPolicy.paths] ? requestedPaths : publisherPolicy.paths
+  };
+}
 function isPlainObject(value) {
   return Object.prototype.toString.call(value) === "[object Object]";
 }
@@ -618,7 +725,7 @@ function normalizePathForCompare(value) {
   return value.replace(/\\/g, "/").replace(/\/+$/g, "");
 }
 function redactPath(value, projectRoot, policy) {
-  if (policy.paths === "full") return defaultScrubber.scrub(value);
+  if (policy.paths === "full") return value;
   if (policy.paths === "none" || policy.paths === "redacted") return REDACTED_PATH_REPLACEMENT;
   const normalizedValue = normalizePathForCompare(value);
   if (!projectRoot) return normalizedValue.split("/").at(-1) ?? REDACTED_PATH_REPLACEMENT;
@@ -629,17 +736,17 @@ function redactPath(value, projectRoot, policy) {
   }
   return normalizedValue.split("/").at(-1) ?? REDACTED_PATH_REPLACEMENT;
 }
-function summarizeString(value, maxSummaryLength) {
-  const scrubbed = defaultScrubber.scrub(value);
+function summarizeString(value, maxSummaryLength, scrub) {
+  const scrubbed = scrub ? defaultScrubber.scrub(value) : value;
   if (scrubbed.length <= maxSummaryLength) return scrubbed;
   return `${scrubbed.slice(0, maxSummaryLength)}\u2026[truncated:${scrubbed.length - maxSummaryLength}]`;
 }
 function scrubAndTruncateHqPreview(value, maxLength = 280) {
   if (typeof value !== "string" || value.length === 0) return void 0;
-  return summarizeString(value, maxLength);
+  return summarizeString(value, maxLength, true);
 }
 function visitValue(value, options, key) {
-  if (key !== void 0 && isSensitiveKey(key)) {
+  if (!options.policy.rawContent && key !== void 0 && isSensitiveKey(key)) {
     return { value: SENSITIVE_FIELD_REPLACEMENT, redacted: true };
   }
   if (typeof value === "string") {
@@ -650,7 +757,7 @@ function visitValue(value, options, key) {
     if (!options.policy.rawContent && key !== void 0 && isRawContentKey(key)) {
       return { value: RAW_CONTENT_REPLACEMENT, redacted: true };
     }
-    const scrubbed = summarizeString(value, options.maxSummaryLength);
+    const scrubbed = summarizeString(value, options.maxSummaryLength, !options.policy.rawContent);
     return { value: scrubbed, redacted: scrubbed !== value };
   }
   if (value === null || typeof value !== "object") return { value, redacted: false };
@@ -677,7 +784,7 @@ function visitValue(value, options, key) {
 }
 function redactHqValue(value, options = {}) {
   const result = visitValue(value, {
-    policy: resolvePolicy(options.policy),
+    policy: resolveHqRedactionPolicy(options.policy),
     ...options.projectRoot !== void 0 ? { projectRoot: options.projectRoot } : {},
     maxSummaryLength: options.maxSummaryLength ?? 500,
     seen: /* @__PURE__ */ new WeakSet()
@@ -693,7 +800,8 @@ function redactHqEvent(event, options = {}) {
   return { value: nextEvent, redacted: payload.redacted };
 }
 function summarizeHqToolArgs(value, options = {}) {
-  const policy = resolvePolicy(options.policy);
+  const policy = resolveHqRedactionPolicy(options.policy);
+  if (policy.toolArgs === "full") return value;
   if (policy.toolArgs === "none") return "[REDACTED:hq_tool_args]";
   if (policy.toolArgs === "redacted") return redactHqValue(value, options).value;
   if (value === null || typeof value !== "object") return redactHqValue(value, options).value;
@@ -704,7 +812,7 @@ function summarizeHqToolArgs(value, options = {}) {
     if (isSensitiveKey(key)) {
       summary[key] = SENSITIVE_FIELD_REPLACEMENT;
     } else if (typeof item === "string") {
-      summary[key] = isPathKey(key) ? redactPath(item, options.projectRoot, policy) : summarizeString(item, 120);
+      summary[key] = isPathKey(key) ? redactPath(item, options.projectRoot, policy) : summarizeString(item, 120, true);
     } else if (Array.isArray(item)) {
       summary[key] = `[array:${item.length}]`;
     } else if (item !== null && typeof item === "object") {
@@ -720,9 +828,12 @@ function summarizeHqToolArgs(value, options = {}) {
 // src/hq/mailbox-mapper.ts
 function previewText(value, maxLength, policy) {
   if (value === void 0 || value.length === 0) return void 0;
-  const redacted = redactHqValue(value, { maxSummaryLength: maxLength, policy: { rawContent: true, ...policy } }).value;
-  if (redacted.length <= maxLength) return redacted;
-  return `${redacted.slice(0, maxLength)}\u2026`;
+  if (policy?.rawContent === false) return "[REDACTED:hq_raw_content]";
+  if (policy?.rawContent === true) {
+    if (value.length <= maxLength) return value;
+    return `${value.slice(0, maxLength)}\u2026`;
+  }
+  return scrubAndTruncateHqPreview(value, maxLength);
 }
 function readCount(message) {
   return Object.keys(message.readBy).length;
@@ -823,6 +934,10 @@ function createMailboxEventPayload(input) {
     ...input.summary !== void 0 ? { summary: previewText(input.summary, input.previewLength ?? 160, input.redactionPolicy) ?? "" } : {}
   };
 }
+
+// src/hq/publisher.ts
+import { randomUUID } from "node:crypto";
+var TRANSCRIPT_EVENT_TYPES = /* @__PURE__ */ new Set(["session.transcript", "agent.message"]);
 var OPEN_STATE = 1;
 var CONNECT_WARN_AFTER_FAILURES = 5;
 var DEFAULT_RECONNECT_BASE_MS = 1e3;
@@ -831,6 +946,7 @@ var DEFAULT_DISCOVERY_POLL_MS = 5e3;
 var DEFAULT_MAX_QUEUED_MESSAGES = 2e3;
 var DEFAULT_COMMAND_POLL_INTERVAL_MS = 2e3;
 var DEFAULT_COMMAND_POLL_LIMIT = 25;
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 25e3;
 function defaultSocketFactory(url) {
   const WebSocketCtor = globalThis.WebSocket;
   if (WebSocketCtor === void 0) {
@@ -877,6 +993,8 @@ var HqPublisher = class {
     this.reconnectBaseMs = options.reconnectBaseMs ?? DEFAULT_RECONNECT_BASE_MS;
     this.reconnectMaxMs = options.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
     this.maxQueuedMessages = options.maxQueuedMessages ?? DEFAULT_MAX_QUEUED_MESSAGES;
+    this.resolvedRedactionPolicy = resolveHqRedactionPolicy(options.redactionPolicy);
+    this.logger = options.logger;
   }
   options;
   socketFactory;
@@ -887,6 +1005,8 @@ var HqPublisher = class {
   reconnectBaseMs;
   reconnectMaxMs;
   maxQueuedMessages;
+  resolvedRedactionPolicy;
+  logger;
   socket = null;
   seq = 0;
   queue = [];
@@ -896,6 +1016,7 @@ var HqPublisher = class {
   lastAttempt = null;
   reconnectTimer = null;
   commandPollTimer = null;
+  heartbeatTimer = null;
   lastCommandId;
   connect() {
     if (this.socket !== null || this.stopped) return;
@@ -926,6 +1047,7 @@ var HqPublisher = class {
       this.reconnectAttempt = 0;
       this.sendHelloNow();
       this.flushQueue();
+      this.startHeartbeat();
       if (this.options.onCommand !== void 0) {
         this.startCommandPolling();
         this.pollCommands();
@@ -940,6 +1062,7 @@ var HqPublisher = class {
       removeSocketListener(socket, "close", onCloseOrError);
       removeSocketListener(socket, "error", onCloseOrError);
       this.stopCommandPolling();
+      this.stopHeartbeat();
       if (this.socket === socket) this.socket = null;
       this.scheduleReconnect();
     };
@@ -956,6 +1079,7 @@ var HqPublisher = class {
       this.reconnectTimer = null;
     }
     this.stopCommandPolling();
+    this.stopHeartbeat();
     this.queue = [];
     const socket = this.socket;
     this.socket = null;
@@ -973,13 +1097,19 @@ var HqPublisher = class {
       ...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {},
       ...options.runId !== void 0 ? { runId: options.runId } : {}
     });
-    this.sendFrame({ type: "client.event", event });
-    return event;
+    const maxSummaryLength = options.maxSummaryLength ?? (TRANSCRIPT_EVENT_TYPES.has(options.type) ? HQ_TRANSCRIPT_TEXT_CAP : void 0);
+    const redacted = redactHqEvent(event, {
+      policy: this.resolvedRedactionPolicy,
+      projectRoot: this.options.project.projectRoot,
+      ...maxSummaryLength !== void 0 ? { maxSummaryLength } : {}
+    }).value;
+    this.sendFrame({ type: "client.event", event: redacted });
+    return redacted;
   }
   async publishMailboxSnapshot(mailbox, options) {
     const payload = await createMailboxSnapshotPayloadFromMailbox(mailbox, {
       ...options,
-      ...this.options.redactionPolicy !== void 0 ? { redactionPolicy: this.options.redactionPolicy } : {}
+      redactionPolicy: this.resolvedRedactionPolicy
     });
     return this.publishEvent({
       type: "mailbox.snapshot",
@@ -996,7 +1126,7 @@ var HqPublisher = class {
       ...input.agent !== void 0 ? { agent: input.agent } : {},
       ...input.summary !== void 0 ? { summary: input.summary } : {},
       ...input.previewLength !== void 0 ? { previewLength: input.previewLength } : {},
-      ...this.options.redactionPolicy !== void 0 ? { redactionPolicy: this.options.redactionPolicy } : {}
+      redactionPolicy: this.resolvedRedactionPolicy
     });
     return this.publishEvent({
       type: "mailbox.event",
@@ -1013,6 +1143,10 @@ var HqPublisher = class {
   get project() {
     return this.options.project;
   }
+  /** Effective publisher-side policy applied before any event leaves this process. */
+  get redactionPolicy() {
+    return this.resolvedRedactionPolicy;
+  }
   /** Publish a live session/terminal snapshot (state + agents). */
   publishSessionSnapshot(payload, opts) {
     return this.publishEvent({
@@ -1076,7 +1210,8 @@ var HqPublisher = class {
         protocolVersion: HQ_PROTOCOL_VERSION,
         client: this.options.client,
         project: this.options.project,
-        capabilities: this.capabilities
+        capabilities: this.capabilities,
+        redactionPolicy: this.resolvedRedactionPolicy
       }
     };
   }
@@ -1124,6 +1259,30 @@ var HqPublisher = class {
     clearInterval(this.commandPollTimer);
     this.commandPollTimer = null;
   }
+  startHeartbeat() {
+    if (this.heartbeatTimer !== null) return;
+    this.heartbeatTimer = setInterval(
+      () => this.publishHeartbeat(),
+      this.options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS
+    );
+    this.heartbeatTimer.unref?.();
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer === null) return;
+    clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+  }
+  publishHeartbeat() {
+    const startedAt = Date.parse(this.options.client.startedAt);
+    const now = Date.parse(this.now());
+    this.publishEvent({
+      type: "client.heartbeat",
+      payload: {
+        uptimeMs: Number.isFinite(startedAt) && Number.isFinite(now) ? Math.max(0, now - startedAt) : 0,
+        status: "idle"
+      }
+    });
+  }
   async handleServerMessage(event) {
     const message = this.parseServerMessage(event);
     if (message?.type !== "hq.command_batch") return;
@@ -1186,6 +1345,10 @@ var HqPublisher = class {
   emitConnectWarning() {
     const attempt = this.lastAttempt;
     const message = `WrongStack HQ publisher: ${this.reconnectAttempt} consecutive connection failures${attempt !== null ? ` to ${attempt.url} (client token ${attempt.hadToken ? "present" : "absent"})` : ""}. Either the HQ server is unreachable or it rejected the token (401). If HQ runs in client-token mode, verify WRONGSTACK_HQ_TOKEN / auth.json. Retries continue with backoff.`;
+    if (this.logger) {
+      this.logger.warn(message, { event: "hq.publisher.connect_failed" });
+      return;
+    }
     const warn = this.options.warn ?? ((msg) => console.warn(
       JSON.stringify({
         level: "warn",
@@ -1215,13 +1378,32 @@ var HqPublisher = class {
     this.reconnectTimer.unref?.();
   }
 };
+
+// src/hq/factory.ts
+import { createHash as createHash2, randomUUID as randomUUID4 } from "node:crypto";
+import * as fs3 from "node:fs";
+import { hostname } from "node:os";
+import { basename as basename5 } from "node:path";
+
+// src/coordination/global-mailbox.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import * as fsp from "node:fs/promises";
+import * as path4 from "node:path";
+
+// src/utils/atomic-write.ts
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path3 from "node:path";
+
+// src/utils/session-scoped-path.ts
+import * as path from "node:path";
 function sessionScopedPath(dir, sessionId, suffix) {
   if (!sessionId || sessionId.includes("\\") || sessionId.includes("..")) {
     throw invalid(sessionId);
   }
-  const resolved = path2.resolve(dir, `${sessionId}${suffix}`);
-  const rel = path2.relative(path2.resolve(dir), resolved);
-  if (rel.startsWith("..") || path2.isAbsolute(rel)) {
+  const resolved = path.resolve(dir, `${sessionId}${suffix}`);
+  const rel = path.relative(path.resolve(dir), resolved);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
     throw invalid(sessionId);
   }
   return resolved;
@@ -1234,6 +1416,11 @@ function invalid(sessionId) {
     context: { reason: "path_traversal" }
   });
 }
+
+// src/utils/wstack-paths.ts
+import { createHash } from "node:crypto";
+import * as os from "node:os";
+import * as path2 from "node:path";
 function projectHash(absRoot) {
   return createHash("sha256").update(path2.resolve(absRoot)).digest("hex").slice(0, 12);
 }
@@ -1307,9 +1494,61 @@ function resolveWstackPaths(opts) {
 
 // src/types/errors.ts
 var ERROR_CODES = {
+  // Provider
+  PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED",
+  PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
+  PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED",
+  PROVIDER_INVALID_REQUEST: "PROVIDER_INVALID_REQUEST",
+  PROVIDER_SERVER_ERROR: "PROVIDER_SERVER_ERROR",
+  PROVIDER_NETWORK_ERROR: "PROVIDER_NETWORK_ERROR",
+  PROVIDER_CONTEXT_OVERFLOW: "PROVIDER_CONTEXT_OVERFLOW",
+  // Tool
+  TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
+  TOOL_PERMISSION_DENIED: "TOOL_PERMISSION_DENIED",
+  TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
+  TOOL_TIMEOUT: "TOOL_TIMEOUT",
+  TOOL_INPUT_INVALID: "TOOL_INPUT_INVALID",
+  // Config
+  CONFIG_INVALID: "CONFIG_INVALID",
+  CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+  CONFIG_PARSE_FAILED: "CONFIG_PARSE_FAILED",
+  CONFIG_MIGRATION_NEEDED: "CONFIG_MIGRATION_NEEDED",
+  // Plugin
+  PLUGIN_LOAD_FAILED: "PLUGIN_LOAD_FAILED",
+  PLUGIN_API_MISMATCH: "PLUGIN_API_MISMATCH",
+  PLUGIN_MISSING_DEPENDENCY: "PLUGIN_MISSING_DEPENDENCY",
+  // Agent
+  AGENT_ITERATION_LIMIT: "AGENT_ITERATION_LIMIT",
+  AGENT_CONTEXT_OVERFLOW: "AGENT_CONTEXT_OVERFLOW",
+  AGENT_ABORTED: "AGENT_ABORTED",
+  AGENT_RUN_FAILED: "AGENT_RUN_FAILED",
+  // Session
+  SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
+  SESSION_CORRUPTED: "SESSION_CORRUPTED",
+  SESSION_WRITE_FAILED: "SESSION_WRITE_FAILED",
+  // Container / Registry
+  CONTAINER_TOKEN_ALREADY_BOUND: "CONTAINER_TOKEN_ALREADY_BOUND",
+  CONTAINER_TOKEN_NOT_BOUND: "CONTAINER_TOKEN_NOT_BOUND",
+  CONTAINER_CIRCULAR_DEPENDENCY: "CONTAINER_CIRCULAR_DEPENDENCY",
+  REGISTRY_DUPLICATE: "REGISTRY_DUPLICATE",
+  REGISTRY_NOT_FOUND: "REGISTRY_NOT_FOUND",
+  REGISTRY_INVALID: "REGISTRY_INVALID",
   // File system
   FS_READ_FAILED: "FS_READ_FAILED",
-  FS_DELETE_FAILED: "FS_DELETE_FAILED"};
+  FS_WRITE_FAILED: "FS_WRITE_FAILED",
+  FS_MKDIR_FAILED: "FS_MKDIR_FAILED",
+  FS_DELETE_FAILED: "FS_DELETE_FAILED",
+  FS_ATOMIC_WRITE_FAILED: "FS_ATOMIC_WRITE_FAILED",
+  // SDD (Spec-Driven Development)
+  SDD_VALIDATION_FAILED: "SDD_VALIDATION_FAILED",
+  SDD_PARSE_FAILED: "SDD_PARSE_FAILED",
+  SDD_INVALID_STATE: "SDD_INVALID_STATE",
+  SDD_NOT_READY: "SDD_NOT_READY",
+  // General
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  PARSE_FAILED: "PARSE_FAILED",
+  UNKNOWN: "UNKNOWN"
+};
 var WrongStackError = class extends Error {
   code;
   subsystem;
@@ -1357,17 +1596,17 @@ var FsError = class extends WrongStackError {
 
 // src/utils/atomic-write.ts
 async function atomicWrite(targetPath, content, opts = {}) {
-  const dir = path2.dirname(targetPath);
-  await fsp.mkdir(dir, { recursive: true });
-  const tmp = path2.join(dir, `.${path2.basename(targetPath)}.${randomBytes(6).toString("hex")}.tmp`);
+  const dir = path3.dirname(targetPath);
+  await fs.mkdir(dir, { recursive: true });
+  const tmp = path3.join(dir, `.${path3.basename(targetPath)}.${randomBytes(6).toString("hex")}.tmp`);
   try {
     if (typeof content === "string") {
-      await fsp.writeFile(tmp, content, { flag: "wx", encoding: opts.encoding ?? "utf8" });
+      await fs.writeFile(tmp, content, { flag: "wx", encoding: opts.encoding ?? "utf8" });
     } else {
-      await fsp.writeFile(tmp, content, { flag: "wx" });
+      await fs.writeFile(tmp, content, { flag: "wx" });
     }
     try {
-      const fh = await fsp.open(tmp, "r+");
+      const fh = await fs.open(tmp, "r+");
       try {
         await fh.sync();
       } finally {
@@ -1377,53 +1616,53 @@ async function atomicWrite(targetPath, content, opts = {}) {
     }
     let mode;
     try {
-      const stat4 = await fsp.stat(targetPath);
+      const stat4 = await fs.stat(targetPath);
       mode = stat4.mode & 511;
     } catch {
       mode = opts.mode;
     }
     if (mode !== void 0) {
-      await fsp.chmod(tmp, mode);
+      await fs.chmod(tmp, mode);
     }
     await renameWithRetry(tmp, targetPath);
     if (mode !== void 0 && process.platform === "win32") {
       try {
-        await fsp.chmod(targetPath, mode);
+        await fs.chmod(targetPath, mode);
       } catch {
       }
     }
   } catch (err) {
     try {
-      await fsp.unlink(tmp);
+      await fs.unlink(tmp);
     } catch {
     }
     throw err;
   }
 }
 async function withFileLock(targetPath, fn, opts = {}) {
-  const dir = path2.dirname(targetPath);
-  await fsp.mkdir(dir, { recursive: true });
-  const lockPath = path2.join(dir, `.${path2.basename(targetPath)}.lock`);
+  const dir = path3.dirname(targetPath);
+  await fs.mkdir(dir, { recursive: true });
+  const lockPath = path3.join(dir, `.${path3.basename(targetPath)}.lock`);
   const timeoutMs = opts.timeoutMs ?? 5e3;
   const staleMs = opts.staleMs ?? 3e4;
   const started = Date.now();
   let handle;
   for (; ; ) {
     try {
-      handle = await fsp.open(lockPath, "wx");
+      handle = await fs.open(lockPath, "wx");
       await handle.writeFile(`${process.pid}:${Date.now()}`);
       break;
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") {
-        await fsp.mkdir(dir, { recursive: true });
+        await fs.mkdir(dir, { recursive: true });
         continue;
       }
       if (code !== "EEXIST") throw err;
       try {
-        const stat4 = await fsp.stat(lockPath);
+        const stat4 = await fs.stat(lockPath);
         if (Date.now() - stat4.mtimeMs > staleMs) {
-          await fsp.unlink(lockPath);
+          await fs.unlink(lockPath);
           continue;
         }
       } catch {
@@ -1448,7 +1687,7 @@ async function withFileLock(targetPath, fn, opts = {}) {
     } catch {
     }
     try {
-      await fsp.unlink(lockPath);
+      await fs.unlink(lockPath);
     } catch {
     }
   }
@@ -1456,14 +1695,14 @@ async function withFileLock(targetPath, fn, opts = {}) {
 var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
 async function renameWithRetry(from, to) {
   if (process.platform !== "win32") {
-    await fsp.rename(from, to);
+    await fs.rename(from, to);
     return;
   }
   const delays = [10, 25, 60, 120, 250];
   let lastErr;
   for (let i = 0; i <= delays.length; i++) {
     try {
-      await fsp.rename(from, to);
+      await fs.rename(from, to);
       return;
     } catch (err) {
       lastErr = err;
@@ -1477,6 +1716,148 @@ async function renameWithRetry(from, to) {
   throw lastErr;
 }
 
+// src/coordination/mailbox-constants.ts
+var AGENT_STALE_MS = 6e4;
+var CLIENT_STALE_MS = 6e4;
+var HEARTBEAT_THROTTLE_MS = 5e3;
+var REGISTRY_CACHE_TTL_MS = 2e3;
+var LINE_SEPARATOR = "\n";
+var MESSAGE_CACHE_MAX_ENTRIES = 1e4;
+var AUTO_COMPACT_INTERVAL_MS = 3e5;
+var AUTO_COMPACT_READ_MAX_AGE_MS = 6e5;
+var AUTO_COMPACT_DEFAULT_TTL_MS = 864e5;
+
+// src/coordination/mailbox-message-codec.ts
+var MESSAGE_TYPES = /* @__PURE__ */ new Set([
+  "note",
+  "ask",
+  "assign",
+  "steer",
+  "btw",
+  "broadcast",
+  "status",
+  "result",
+  "review",
+  "control"
+]);
+var PRIORITIES = /* @__PURE__ */ new Set(["low", "normal", "high"]);
+var TASK_STATUSES = /* @__PURE__ */ new Set([
+  "pending",
+  "in_progress",
+  "completed",
+  "failed",
+  "idle",
+  "running",
+  "streaming",
+  "waiting_user",
+  "error",
+  "offline",
+  "busy"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiredString(record, key) {
+  const value = record[key];
+  if (typeof value !== "string") {
+    throw new TypeError(`mailbox message field "${key}" must be a string`);
+  }
+  return value;
+}
+function optionalString(record, key) {
+  const value = record[key];
+  if (value === void 0) return {};
+  if (typeof value !== "string") {
+    throw new TypeError(`mailbox message field "${key}" must be a string when present`);
+  }
+  return { [key]: value };
+}
+function parseMessageType(value) {
+  if (value === "info") return "note";
+  if (value === "task") return "assign";
+  if (typeof value === "string" && MESSAGE_TYPES.has(value)) {
+    return value;
+  }
+  throw new TypeError('mailbox message field "type" is invalid');
+}
+function normalizeMailboxMessageType(value) {
+  return parseMessageType(value);
+}
+function parsePriority(value) {
+  if (typeof value === "string" && PRIORITIES.has(value)) {
+    return value;
+  }
+  if (typeof value === "string") return "normal";
+  throw new TypeError('mailbox message field "priority" must be a string');
+}
+function parseReadReceipts(record, to) {
+  const value = record["readBy"];
+  if (value === void 0) {
+    const legacyReadAt = record["readAt"];
+    return record["read"] === true && typeof legacyReadAt === "string" ? { [to || "unknown"]: legacyReadAt } : {};
+  }
+  if (!isRecord(value)) {
+    throw new TypeError('mailbox message field "readBy" must be an object');
+  }
+  const receipts = {};
+  for (const [agentId, timestamp] of Object.entries(value)) {
+    if (typeof timestamp !== "string") {
+      throw new TypeError("mailbox message read receipt timestamps must be strings");
+    }
+    receipts[agentId] = timestamp;
+  }
+  return receipts;
+}
+function parseTaskContext(value) {
+  if (value === void 0) return void 0;
+  if (!isRecord(value)) {
+    throw new TypeError('mailbox message field "taskContext" must be an object');
+  }
+  const status = value["status"];
+  if (status !== void 0 && (typeof status !== "string" || !TASK_STATUSES.has(status))) {
+    throw new TypeError("mailbox message taskContext status is invalid");
+  }
+  return {
+    ...optionalString(value, "agentRole"),
+    ...optionalString(value, "agentName"),
+    ...optionalString(value, "taskId"),
+    ...status === void 0 ? {} : { status }
+  };
+}
+function parseMailboxMessage(value) {
+  if (!isRecord(value)) throw new TypeError("mailbox message must be an object");
+  const to = value["to"] === void 0 ? "" : requiredString(value, "to");
+  const completed = value["completed"];
+  if (typeof completed !== "boolean") {
+    throw new TypeError('mailbox message field "completed" must be a boolean');
+  }
+  const taskContext = parseTaskContext(value["taskContext"]);
+  return {
+    id: requiredString(value, "id"),
+    from: requiredString(value, "from"),
+    to,
+    type: parseMessageType(value["type"]),
+    subject: requiredString(value, "subject"),
+    body: requiredString(value, "body"),
+    priority: parsePriority(value["priority"]),
+    readBy: parseReadReceipts(value, to),
+    completed,
+    timestamp: requiredString(value, "timestamp"),
+    ...optionalString(value, "completedBy"),
+    ...optionalString(value, "outcome"),
+    ...optionalString(value, "completedAt"),
+    ...optionalString(value, "deletedAt"),
+    ...optionalString(value, "deletedBy"),
+    ...optionalString(value, "replyTo"),
+    ...optionalString(value, "senderSessionId"),
+    ...optionalString(value, "expiresAt"),
+    ...taskContext === void 0 ? {} : { taskContext }
+  };
+}
+function parseMailboxMessageLine(line) {
+  return parseMailboxMessage(JSON.parse(line));
+}
+
 // src/coordination/mailbox-types.ts
 function normalizeRecipient(to) {
   return to.trim().toLowerCase() === "all" ? "*" : to.trim();
@@ -1485,13 +1866,6 @@ function normalizeRecipient(to) {
 // src/coordination/global-mailbox.ts
 var MAILBOX_FILE = "_mailbox.jsonl";
 var CLIENT_REGISTRY_FILE = "_mailbox.clients.json";
-var AGENT_STALE_MS = 6e4;
-var AGENT_PURGE_MS = 864e5;
-var CLIENT_STALE_MS = 6e4;
-var HEARTBEAT_THROTTLE_MS = 5e3;
-var REGISTRY_CACHE_TTL_MS = 2e3;
-var LINE_SEPARATOR = "\n";
-var MESSAGE_CACHE_MAX_ENTRIES = 1e4;
 var GlobalMailbox = class {
   /** Path to the JSONL message file. */
   messagePath;
@@ -1503,6 +1877,12 @@ var GlobalMailbox = class {
   _events;
   /** Optional HQ publisher for cross-project command-center telemetry. */
   _hqPublisher;
+  /**
+   * Optional SSE event emitter for real-time push to HTTP bridge clients.
+   * When present, `send`/`ack`/`softDelete`/`restore` emit events that
+   * connected SSE subscribers receive instantly.
+   */
+  eventEmitter;
   /**
    * Local cache of the agent registry to avoid re-reading on every call.
    * Time-bounded: the registry file is shared ACROSS PROCESSES (that's the
@@ -1548,20 +1928,47 @@ var GlobalMailbox = class {
    * that follows the read. Pattern mirrors `DefaultMemoryStore.runSerialized`.
    */
   _readChain = Promise.resolve([]);
+  /**
+   * Recipient → Set of indices into `_messageCache`. Maintained alongside
+   * the cache so `query({ to })` and `unreadCount(agentId)` can skip the
+   * O(N) full scan and iterate only the messages addressed to the target
+   * recipient (plus broadcasts `*`).
+   *
+   * The index is rebuilt whenever the cache array is replaced
+   * (`_setMessageCache`), extended when new messages are pushed
+   * (`_pushToCache`, `_readNewMessagesOnly`), and cleared on `close()`.
+   * It is `null` when the cache itself is null (> MESSAGE_CACHE_MAX_ENTRIES
+   * or never populated).
+   *
+   * Safety: array indices are valid only as long as the cache array
+   * reference hasn't changed. Since we rebuild the index in the same
+   * synchronous step that replaces the cache, a reader that calls
+   * `_readMessagesCached()` either gets the old array + old index, or
+   * the new array + new index — never a mismatch.
+   */
+  _recipientIndex = null;
+  /**
+   * Sender → Set of indices into `_messageCache`. Same lifecycle and
+   * safety properties as `_recipientIndex`, but keyed on `msg.from`
+   * so `query({ from })` can skip the full scan.
+   */
+  _senderIndex = null;
   /**
    * @param projectDir — `~/.wrongstack/projects/<slug>/`
    * @param events — optional EventBus for real-time TUI/WebUI notifications
    * @param hqPublisher — optional HQ publisher, or getter, for cross-project telemetry
+   * @param eventEmitter — optional SSE event emitter for HTTP bridge push
    */
-  constructor(projectDir, events, hqPublisher) {
-    this.messagePath = path2.join(projectDir, MAILBOX_FILE);
-    this.registryPath = path2.join(projectDir, "_mailbox.registry.json");
-    this.clientRegistryPath = path2.join(projectDir, CLIENT_REGISTRY_FILE);
+  constructor(projectDir, events, hqPublisher, eventEmitter) {
+    this.messagePath = path4.join(projectDir, MAILBOX_FILE);
+    this.registryPath = path4.join(projectDir, "_mailbox.registry.json");
+    this.clientRegistryPath = path4.join(projectDir, CLIENT_REGISTRY_FILE);
     this._events = events;
     this._hqPublisher = hqPublisher;
+    this.eventEmitter = eventEmitter;
   }
   get hqMailboxId() {
-    return `${path2.basename(path2.dirname(this.messagePath))}:mailbox`;
+    return `${path4.basename(path4.dirname(this.messagePath))}:mailbox`;
   }
   get hqPublisher() {
     return typeof this._hqPublisher === "function" ? this._hqPublisher() : this._hqPublisher;
@@ -1582,12 +1989,12 @@ var GlobalMailbox = class {
   async send(input) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const msg = {
-      id: randomUUID(),
+      id: randomUUID2(),
       from: input.from,
       // "all" is an accepted spelling of the broadcast address — canonical
       // form on disk is '*' so every query/checker matches it.
       to: normalizeRecipient(input.to),
-      type: input.type,
+      type: normalizeMailboxMessageType(input.type),
       subject: input.subject,
       body: input.body,
       priority: input.priority ?? "normal",
@@ -1595,10 +2002,11 @@ var GlobalMailbox = class {
       completed: false,
       timestamp: now,
       replyTo: input.replyTo,
-      taskContext: input.taskContext
+      taskContext: input.taskContext,
+      expiresAt: input.ttlMs !== void 0 ? new Date(Date.now() + input.ttlMs).toISOString() : void 0
     };
     const line = JSON.stringify(msg) + LINE_SEPARATOR;
-    await fsp.mkdir(path2.dirname(this.messagePath), { recursive: true });
+    await fsp.mkdir(path4.dirname(this.messagePath), { recursive: true });
     await withFileLock(this.messagePath, async () => {
       await fsp.appendFile(this.messagePath, line, "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
@@ -1610,21 +2018,49 @@ var GlobalMailbox = class {
       message: msg
     });
     this.publishHqMailboxSnapshot();
+    this._events?.emitCustom("mailbox.message_sent", {
+      messageId: msg.id,
+      from: msg.from,
+      to: msg.to,
+      type: msg.type,
+      subject: msg.subject
+    });
+    this.eventEmitter?.emit({
+      type: "message.sent",
+      messageId: msg.id,
+      from: msg.from,
+      to: msg.to,
+      timestamp: now
+    });
     return msg;
   }
   async query(q) {
+    const queryType = q.type === void 0 ? void 0 : normalizeMailboxMessageType(q.type);
     const all = await this._readMessagesCached();
     const limit = q.limit ?? 50;
     const order = q.minPriority !== void 0 ? { low: 0, normal: 1, high: 2 } : null;
     const minPriorityRank = order && q.minPriority !== void 0 ? order[q.minPriority] : 0;
     const out = [];
-    for (let i = 0; i < all.length; i++) {
-      const m = all[i];
+    let candidates;
+    if (q.to !== void 0 && this._recipientIndex !== null && q.from === void 0 && q.type === void 0 && q.minPriority === void 0) {
+      const indices = /* @__PURE__ */ new Set();
+      const direct = this._recipientIndex.get(q.to);
+      if (direct !== void 0) for (const i of direct) indices.add(i);
+      const broadcasts = this._recipientIndex.get("*");
+      if (broadcasts !== void 0) for (const i of broadcasts) indices.add(i);
+      candidates = [...indices].sort((a, b) => a - b).map((i) => all[i]);
+    } else if (q.from !== void 0 && q.to === void 0 && this._senderIndex !== null && q.type === void 0 && q.minPriority === void 0) {
+      const indices = this._senderIndex.get(q.from);
+      candidates = indices !== void 0 ? [...indices].sort((a, b) => a - b).map((i) => all[i]) : [];
+    } else {
+      candidates = all;
+    }
+    for (const m of candidates) {
       if (q.to !== void 0 && m.to !== q.to && m.to !== "*") continue;
       if (q.from !== void 0 && m.from !== q.from) continue;
       if (q.unreadBy !== void 0 && q.unreadBy in m.readBy) continue;
       if (q.incompleteOnly && m.completed) continue;
-      if (q.type !== void 0 && m.type !== q.type) continue;
+      if (queryType !== void 0 && m.type !== queryType) continue;
       if (order !== null && (order[m.priority] ?? 1) < minPriorityRank) {
         continue;
       }
@@ -1682,6 +2118,13 @@ var GlobalMailbox = class {
         action: message.completed ? "message.completed" : "message.read",
         message
       });
+      this.eventEmitter?.emit({
+        type: "message.acked",
+        messageId: message.id,
+        from: message.from,
+        to: message.to,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
     }
     if (updated.length > 0) this.publishHqMailboxSnapshot();
     return updated;
@@ -1689,10 +2132,22 @@ var GlobalMailbox = class {
   async unreadCount(forAgentId) {
     const all = await this._readMessagesCached();
     let count = 0;
-    for (let i = 0; i < all.length; i++) {
-      const m = all[i];
-      if ((m.to === forAgentId || m.to === "*") && !(forAgentId in m.readBy) && !m.completed) {
-        count++;
+    if (this._recipientIndex !== null) {
+      const indices = /* @__PURE__ */ new Set();
+      const direct = this._recipientIndex.get(forAgentId);
+      if (direct !== void 0) for (const i of direct) indices.add(i);
+      const broadcasts = this._recipientIndex.get("*");
+      if (broadcasts !== void 0) for (const i of broadcasts) indices.add(i);
+      for (const i of indices) {
+        const m = all[i];
+        if (!(forAgentId in m.readBy) && !m.completed) count++;
+      }
+    } else {
+      for (let i = 0; i < all.length; i++) {
+        const m = all[i];
+        if ((m.to === forAgentId || m.to === "*") && !(forAgentId in m.readBy) && !m.completed) {
+          count++;
+        }
       }
     }
     return count;
@@ -1702,6 +2157,7 @@ var GlobalMailbox = class {
     await withFileLock(this.messagePath, async () => {
       const all = await this._readMessagesFresh();
       const now = (/* @__PURE__ */ new Date()).toISOString();
+      let changed = false;
       for (const m of all) {
         if (m.id !== mailId) continue;
         if (m.deletedAt !== void 0) {
@@ -1711,19 +2167,30 @@ var GlobalMailbox = class {
         m.deletedAt = now;
         m.deletedBy = by;
         updated = m;
+        changed = true;
+      }
+      if (changed) {
+        const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
+        await fsp.writeFile(this.messagePath, serialized, "utf8");
       }
-      const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
-      await fsp.writeFile(this.messagePath, serialized, "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
       this._setMessageCache(all, mtimeMs, size);
     });
     if (updated !== null) {
+      const msg = updated;
       this.publishHqMailboxEvent({
         mailboxId: this.hqMailboxId,
         action: "message.updated",
-        message: updated
+        message: msg
       });
       this.publishHqMailboxSnapshot();
+      this.eventEmitter?.emit({
+        type: "message.deleted",
+        messageId: msg.id,
+        from: msg.from,
+        to: msg.to,
+        timestamp: msg.deletedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+      });
     }
     return updated;
   }
@@ -1731,24 +2198,40 @@ var GlobalMailbox = class {
     let updated = null;
     await withFileLock(this.messagePath, async () => {
       const all = await this._readMessagesFresh();
+      let changed = false;
       for (const m of all) {
         if (m.id !== mailId) continue;
+        if (m.deletedAt === void 0 && m.deletedBy === void 0) {
+          updated = m;
+          continue;
+        }
         delete m.deletedAt;
         delete m.deletedBy;
         updated = m;
+        changed = true;
+      }
+      if (changed) {
+        const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
+        await fsp.writeFile(this.messagePath, serialized, "utf8");
       }
-      const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
-      await fsp.writeFile(this.messagePath, serialized, "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
       this._setMessageCache(all, mtimeMs, size);
     });
     if (updated !== null) {
+      const msg = updated;
       this.publishHqMailboxEvent({
         mailboxId: this.hqMailboxId,
         action: "message.updated",
-        message: updated
+        message: msg
       });
       this.publishHqMailboxSnapshot();
+      this.eventEmitter?.emit({
+        type: "message.restored",
+        messageId: msg.id,
+        from: msg.from,
+        to: msg.to,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
     }
     return updated;
   }
@@ -1881,8 +2364,19 @@ var GlobalMailbox = class {
   }
   async getAgentStatuses() {
     await this._ensureRegistry();
-    const registry = await this._readRegistry();
+    let registry = await this._readRegistry();
+    const before = registry.size;
     this._pruneStaleInPlace(registry);
+    if (registry.size < before) {
+      await withFileLock(this.registryPath, async () => {
+        const fresh = await this._readRegistry({ fresh: true });
+        this._pruneStaleInPlace(fresh);
+        this._registryCache = fresh;
+        this._registryCacheAt = Date.now();
+        await this._writeRegistry(fresh);
+        registry = fresh;
+      });
+    }
     const now = Date.now();
     return Array.from(registry.values()).map((a) => ({
       agentId: a.agentId,
@@ -1934,6 +2428,20 @@ var GlobalMailbox = class {
     });
     this.publishHqMailboxSnapshot();
   }
+  async deregisterClient(clientId) {
+    await this._ensureClientRegistry();
+    await withFileLock(this.clientRegistryPath, async () => {
+      const registry = await this._readClientRegistry({ fresh: true });
+      this._pruneStaleClientsInPlace(registry);
+      registry.delete(clientId);
+      this._clientRegistryCache = registry;
+      this._clientRegistryCacheAt = Date.now();
+      await this._writeClientRegistry(registry);
+    });
+    this._lastClientHeartbeat.delete(clientId);
+    this._events?.emitCustom("mailbox.client_deregistered", { clientId });
+    this.publishHqMailboxSnapshot();
+  }
   async clientHeartbeat(input) {
     const last = this._lastClientHeartbeat.get(input.clientId) ?? 0;
     const now = Date.now();
@@ -1963,7 +2471,11 @@ var GlobalMailbox = class {
   async getClientStatuses() {
     await this._ensureClientRegistry();
     const registry = await this._readClientRegistry();
+    const before = registry.size;
     this._pruneStaleClientsInPlace(registry);
+    if (registry.size < before) {
+      await this._writeClientRegistry(registry);
+    }
     const now = Date.now();
     return Array.from(registry.values()).map((c) => ({
       clientId: c.clientId,
@@ -1975,6 +2487,32 @@ var GlobalMailbox = class {
       pid: c.pid
     })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
   }
+  /**
+   * Explicitly purge stale clients from the registry and write back to disk.
+   * Removes client entries whose lastSeenAt is older than CLIENT_STALE_MS.
+   * Returns the number of entries purged.
+   *
+   * Idempotent — safe to call regularly. The same pruning runs implicitly
+   * inside registerClient, clientHeartbeat, and getClientStatuses, but if
+   * no client registers or heartbeats for a long time, this public method
+   * ensures the file gets cleaned up on demand.
+   */
+  async purgeClients() {
+    await this._ensureClientRegistry();
+    let purged = 0;
+    await withFileLock(this.clientRegistryPath, async () => {
+      const registry = await this._readClientRegistry({ fresh: true });
+      const before = registry.size;
+      this._pruneStaleClientsInPlace(registry);
+      purged = before - registry.size;
+      if (purged > 0) {
+        this._clientRegistryCache = registry;
+        this._clientRegistryCacheAt = Date.now();
+        await this._writeClientRegistry(registry);
+      }
+    });
+    return purged;
+  }
   // ── Lifecycle ───────────────────────────────────────────────────────────
   async close() {
     this._registryCache = null;
@@ -1982,6 +2520,8 @@ var GlobalMailbox = class {
     this._messageCache = null;
     this._messageCacheMtime = -1;
     this._messageCacheSize = -1;
+    this._recipientIndex = null;
+    this._senderIndex = null;
   }
   async clearAll() {
     await withFileLock(this.messagePath, async () => {
@@ -2030,6 +2570,100 @@ var GlobalMailbox = class {
       remaining
     };
   }
+  // ── Auto-compaction ─────────────────────────────────────────────────────
+  _autoCompactTimer = null;
+  async autoCompact(opts) {
+    const readMaxAgeMs = opts?.readMaxAgeMs ?? AUTO_COMPACT_READ_MAX_AGE_MS;
+    const defaultTtlMs = opts?.defaultTtlMs ?? AUTO_COMPACT_DEFAULT_TTL_MS;
+    const completedMaxAgeMs = opts?.completedMaxAgeMs ?? 864e5;
+    const incompleteMaxAgeMs = opts?.incompleteMaxAgeMs ?? 6048e5;
+    let expiredPurged = 0;
+    let readByAllPurged = 0;
+    let completedPurged = 0;
+    let incompletePurged = 0;
+    let remaining = 0;
+    let onlineAgentIds = null;
+    try {
+      const statuses = await this.getAgentStatuses();
+      const online = statuses.filter((s) => s.online);
+      onlineAgentIds = online.length > 0 ? new Set(online.map((s) => s.agentId)) : null;
+    } catch {
+      onlineAgentIds = null;
+    }
+    await withFileLock(this.messagePath, async () => {
+      const all = await this._readMessagesFresh();
+      const now = Date.now();
+      const cutoffReadAge = now - readMaxAgeMs;
+      const cutoffCompleted = now - completedMaxAgeMs;
+      const cutoffIncomplete = now - incompleteMaxAgeMs;
+      const cutoffDefaultTtl = now - defaultTtlMs;
+      const kept = [];
+      for (const msg of all) {
+        const msgTime = new Date(msg.timestamp).getTime();
+        if (msg.expiresAt !== void 0) {
+          if (new Date(msg.expiresAt).getTime() < now) {
+            expiredPurged++;
+            continue;
+          }
+        } else if (msgTime < cutoffDefaultTtl) {
+          expiredPurged++;
+          continue;
+        }
+        if (onlineAgentIds !== null && !msg.completed) {
+          const readByAll = onlineAgentIds.size > 0 && [...onlineAgentIds].every((id) => id in msg.readBy);
+          if (readByAll) {
+            const readTimes = Object.values(msg.readBy).map((t) => new Date(t).getTime());
+            const latestRead = Math.max(...readTimes);
+            if (latestRead < cutoffReadAge) {
+              readByAllPurged++;
+              continue;
+            }
+          }
+        }
+        const completedTime = msg.completedAt ? new Date(msg.completedAt).getTime() : 0;
+        if (msg.completed && completedTime < cutoffCompleted) {
+          completedPurged++;
+          continue;
+        }
+        if (!msg.completed && msgTime < cutoffIncomplete) {
+          incompletePurged++;
+          continue;
+        }
+        kept.push(msg);
+      }
+      remaining = kept.length;
+      if (kept.length < all.length) {
+        const content = kept.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
+        await fsp.writeFile(this.messagePath, content, "utf8");
+      }
+      const { mtimeMs, size } = await this._statMessageFile();
+      this._setMessageCache(kept, mtimeMs, size);
+    });
+    const totalRemoved = expiredPurged + readByAllPurged + completedPurged + incompletePurged;
+    return {
+      expiredRemoved: expiredPurged,
+      readByAllRemoved: readByAllPurged,
+      stalePurged: completedPurged + incompletePurged,
+      totalRemoved,
+      remaining
+    };
+  }
+  startAutoCompactTimer(opts) {
+    if (this._autoCompactTimer !== null) {
+      clearInterval(this._autoCompactTimer);
+    }
+    const intervalMs = opts?.intervalMs ?? AUTO_COMPACT_INTERVAL_MS;
+    const timer = setInterval(() => {
+      this.autoCompact(opts).catch(() => {
+      });
+    }, intervalMs);
+    timer.unref?.();
+    this._autoCompactTimer = timer;
+    return () => {
+      clearInterval(timer);
+      this._autoCompactTimer = null;
+    };
+  }
   // ── Internal ────────────────────────────────────────────────────────────
   /**
    * Read all messages from the JSONL file. Always reads + parses the file.
@@ -2062,44 +2696,59 @@ var GlobalMailbox = class {
     const buf = Buffer.alloc(tailLen);
     await fd.read(buf, 0, tailLen, oldSize);
     const tail = buf.toString("utf8");
-    for (const line of tail.split(LINE_SEPARATOR)) {
+    if (!tail.endsWith(LINE_SEPARATOR)) {
+      const lastSeparatorIdx = tail.lastIndexOf(LINE_SEPARATOR);
+      if (lastSeparatorIdx === -1) {
+        return this._messageCache;
+      }
+      const completeTail = tail.slice(0, lastSeparatorIdx + 1);
+      this._appendIncrementalLines(completeTail);
+      this._messageCacheSize = oldSize + lastSeparatorIdx + 1;
+      return this._messageCache;
+    }
+    this._appendIncrementalLines(tail);
+    this._messageCacheSize = newSize;
+    return this._messageCache;
+  }
+  _appendIncrementalLines(raw) {
+    for (const line of raw.split(LINE_SEPARATOR)) {
       if (!line.trim()) continue;
-      try {
-        const parsed = JSON.parse(line);
-        if (!parsed["readBy"]) {
-          const readBy = {};
-          if (parsed["read"] && parsed["readAt"]) {
-            readBy[parsed["to"]] = parsed["readAt"];
-          }
-          parsed["readBy"] = readBy;
-          delete parsed["read"];
-          delete parsed["readAt"];
+      const message = this._parseLine(line);
+      if (message === null) continue;
+      this._messageCache.push(message);
+      const idx = this._messageCache.length - 1;
+      if (this._recipientIndex !== null) {
+        let set = this._recipientIndex.get(message.to);
+        if (set === void 0) {
+          set = /* @__PURE__ */ new Set();
+          this._recipientIndex.set(message.to, set);
         }
-        this._messageCache.push(parsed);
-      } catch {
+        set.add(idx);
+      }
+      if (this._senderIndex !== null) {
+        let set = this._senderIndex.get(message.from);
+        if (set === void 0) {
+          set = /* @__PURE__ */ new Set();
+          this._senderIndex.set(message.from, set);
+        }
+        set.add(idx);
       }
     }
-    return this._messageCache;
+  }
+  _parseLine(line) {
+    try {
+      return parseMailboxMessageLine(line);
+    } catch {
+      return null;
+    }
   }
   /** Parse a JSONL string into MailboxMessage[], including migration. */
   _parseLines(raw) {
     const lines = raw.split(LINE_SEPARATOR).filter((l) => l.trim().length > 0);
     const messages = [];
     for (const line of lines) {
-      try {
-        const parsed = JSON.parse(line);
-        if (!parsed["readBy"]) {
-          const readBy = {};
-          if (parsed["read"] && parsed["readAt"]) {
-            readBy[parsed["to"]] = parsed["readAt"];
-          }
-          parsed["readBy"] = readBy;
-          delete parsed["read"];
-          delete parsed["readAt"];
-        }
-        messages.push(parsed);
-      } catch {
-      }
+      const message = this._parseLine(line);
+      if (message !== null) messages.push(message);
     }
     return messages;
   }
@@ -2187,7 +2836,6 @@ var GlobalMailbox = class {
         try {
           const updated = await this._readNewMessagesOnly(fd, this._messageCacheSize, st.size);
           this._messageCacheMtime = st.mtimeMs;
-          this._messageCacheSize = st.size;
           return updated;
         } finally {
           await fd.close();
@@ -2224,11 +2872,46 @@ var GlobalMailbox = class {
       this._messageCache = null;
       this._messageCacheMtime = -1;
       this._messageCacheSize = -1;
+      this._recipientIndex = null;
+      this._senderIndex = null;
       return;
     }
     this._messageCache = messages;
     this._messageCacheMtime = mtime;
     this._messageCacheSize = size;
+    this._rebuildRecipientIndex();
+  }
+  /**
+   * Build the recipient AND sender indexes from the current `_messageCache`.
+   * Called only from `_setMessageCache` so both indexes are always in sync
+   * with a freshly-replaced cache array.
+   */
+  _rebuildRecipientIndex() {
+    const cache = this._messageCache;
+    if (cache === null) {
+      this._recipientIndex = null;
+      this._senderIndex = null;
+      return;
+    }
+    const recIdx = /* @__PURE__ */ new Map();
+    const sndIdx = /* @__PURE__ */ new Map();
+    for (let i = 0; i < cache.length; i++) {
+      const msg = cache[i];
+      let rSet = recIdx.get(msg.to);
+      if (rSet === void 0) {
+        rSet = /* @__PURE__ */ new Set();
+        recIdx.set(msg.to, rSet);
+      }
+      rSet.add(i);
+      let sSet = sndIdx.get(msg.from);
+      if (sSet === void 0) {
+        sSet = /* @__PURE__ */ new Set();
+        sndIdx.set(msg.from, sSet);
+      }
+      sSet.add(i);
+    }
+    this._recipientIndex = recIdx;
+    this._senderIndex = sndIdx;
   }
   /**
    * Append a single just-sent message to the in-memory cache without
@@ -2255,11 +2938,28 @@ var GlobalMailbox = class {
       return;
     }
     this._messageCache.push(msg);
+    const newIdx = this._messageCache.length - 1;
+    if (this._recipientIndex !== null) {
+      let set = this._recipientIndex.get(msg.to);
+      if (set === void 0) {
+        set = /* @__PURE__ */ new Set();
+        this._recipientIndex.set(msg.to, set);
+      }
+      set.add(newIdx);
+    }
+    if (this._senderIndex !== null) {
+      let set = this._senderIndex.get(msg.from);
+      if (set === void 0) {
+        set = /* @__PURE__ */ new Set();
+        this._senderIndex.set(msg.from, set);
+      }
+      set.add(newIdx);
+    }
     this._messageCacheMtime = mtime;
     this._messageCacheSize = size;
   }
   async _ensureRegistry() {
-    await fsp.mkdir(path2.dirname(this.registryPath), { recursive: true });
+    await fsp.mkdir(path4.dirname(this.registryPath), { recursive: true });
   }
   async _readRegistry(opts) {
     if (!opts?.fresh && this._registryCache && Date.now() - this._registryCacheAt < REGISTRY_CACHE_TTL_MS) {
@@ -2286,35 +2986,26 @@ var GlobalMailbox = class {
     }
   }
   _pruneStaleInPlace(registry) {
-    const staleCutoff = Date.now() - AGENT_STALE_MS;
-    const purgeCutoff = Date.now() - AGENT_PURGE_MS;
-    const toDelete = [];
+    const cutoff = Date.now() - AGENT_STALE_MS;
     for (const [id, agent] of registry) {
-      const lastSeen = new Date(agent.lastSeenAt).getTime();
-      if (lastSeen < purgeCutoff) {
-        toDelete.push(id);
-        continue;
-      }
-      if (lastSeen < staleCutoff) {
-        agent.status = "idle";
+      const lastSeen = Date.parse(agent.lastSeenAt);
+      if (!Number.isFinite(lastSeen) || lastSeen < cutoff) {
+        registry.delete(id);
       }
     }
-    for (const id of toDelete) {
-      registry.delete(id);
-    }
   }
   async _writeRegistry(registry) {
     const obj = {};
     for (const [id, agent] of registry) {
       obj[id] = agent;
     }
-    const tmp = `${this.registryPath}.${randomUUID().slice(0, 8)}.tmp`;
+    const tmp = `${this.registryPath}.${randomUUID2().slice(0, 8)}.tmp`;
     await fsp.writeFile(tmp, JSON.stringify(obj), "utf8");
     await fsp.rename(tmp, this.registryPath);
   }
   // ── Client registry internals ───────────────────────────────────────────
   async _ensureClientRegistry() {
-    await fsp.mkdir(path2.dirname(this.clientRegistryPath), { recursive: true });
+    await fsp.mkdir(path4.dirname(this.clientRegistryPath), { recursive: true });
   }
   async _readClientRegistry(opts) {
     if (!opts?.fresh && this._clientRegistryCache && Date.now() - this._clientRegistryCacheAt < REGISTRY_CACHE_TTL_MS) {
@@ -2342,9 +3033,10 @@ var GlobalMailbox = class {
   }
   _pruneStaleClientsInPlace(registry) {
     const cutoff = Date.now() - CLIENT_STALE_MS;
-    for (const client of registry.values()) {
-      if (new Date(client.lastSeenAt).getTime() < cutoff) {
-        client.lastSeenAt = new Date(cutoff).toISOString();
+    for (const [id, client] of registry) {
+      const lastSeen = Date.parse(client.lastSeenAt);
+      if (!Number.isFinite(lastSeen) || lastSeen < cutoff) {
+        registry.delete(id);
       }
     }
   }
@@ -2353,19 +3045,25 @@ var GlobalMailbox = class {
     for (const [id, client] of registry) {
       obj[id] = client;
     }
-    const tmp = `${this.clientRegistryPath}.${randomUUID().slice(0, 8)}.tmp`;
+    const tmp = `${this.clientRegistryPath}.${randomUUID2().slice(0, 8)}.tmp`;
     await fsp.writeFile(tmp, JSON.stringify(obj), "utf8");
     await fsp.rename(tmp, this.clientRegistryPath);
   }
 };
+
+// src/hq/auth-store.ts
+import { randomBytes as randomBytes2, randomUUID as randomUUID3, scrypt, timingSafeEqual } from "node:crypto";
+import * as fs2 from "node:fs/promises";
+import * as syncFs from "node:fs";
+import * as path5 from "node:path";
 var HQ_AUTH_FILE_VERSION = 1;
 function defaultHqDataDir() {
-  return path2.join(wstackGlobalRoot(), "hq");
+  return path5.join(wstackGlobalRoot(), "hq");
 }
 function resolveHqDataDir(override, env = process.env) {
   const raw = override ?? env["WRONGSTACK_HQ_DATA_DIR"]?.trim();
   if (!raw) return defaultHqDataDir();
-  return path2.isAbsolute(raw) ? path2.resolve(raw) : path2.resolve(process.cwd(), raw);
+  return path5.isAbsolute(raw) ? path5.resolve(raw) : path5.resolve(process.cwd(), raw);
 }
 function tokenHasCapability(token, capability) {
   if (token === void 0) return false;
@@ -2379,10 +3077,10 @@ function emptyHqAuthFile() {
   };
 }
 function hqAuthFilePath(dataDir) {
-  return path2.join(dataDir, "auth.json");
+  return path5.join(dataDir, "auth.json");
 }
 function hqRuntimeFilePath(dataDir) {
-  return path2.join(dataDir, "runtime.json");
+  return path5.join(dataDir, "runtime.json");
 }
 async function writeHqRuntimeFile(dataDir, file) {
   const payload = {
@@ -2419,7 +3117,7 @@ async function readHqAuthFile(dataDir, opts = {}) {
   const file = hqAuthFilePath(dataDir);
   let raw;
   try {
-    raw = await fsp.readFile(file, "utf8");
+    raw = await fs2.readFile(file, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") return emptyHqAuthFile();
     opts.warn?.(`HQ auth file read failed at ${file}: ${err.message}`);
@@ -2452,7 +3150,7 @@ async function writeHqAuthFile(dataDir, file) {
 async function ensureHqFirstRunAuthFile(dataDir, opts = {}) {
   const file = hqAuthFilePath(dataDir);
   try {
-    await fsp.access(file);
+    await fs2.access(file);
     return { authFile: await readHqAuthFile(dataDir, opts), created: false };
   } catch (err) {
     if (err.code !== "ENOENT") {
@@ -2460,14 +3158,18 @@ async function ensureHqFirstRunAuthFile(dataDir, opts = {}) {
       return { authFile: await readHqAuthFile(dataDir, opts), created: false };
     }
   }
-  const browserToken = mintHqToken("first-run browser");
-  const clientToken = mintHqToken("first-run client");
+  const browserToken = { ...mintHqToken("first-run browser"), capabilities: ["control.enqueue"] };
+  const clientToken = { ...mintHqToken("first-run client"), capabilities: ["telemetry.publish"] };
   const authFile = {
     version: HQ_AUTH_FILE_VERSION,
     updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     browserTokens: [browserToken],
     clientTokens: [clientToken]
   };
+  if (opts.password) {
+    authFile.passwordHash = await hashHqPassword(opts.password);
+    authFile.cookieSecret = mintHqCookieSecret();
+  }
   await writeHqAuthFile(dataDir, authFile);
   return { authFile: await readHqAuthFile(dataDir, opts), created: true, browserToken, clientToken };
 }
@@ -2477,11 +3179,47 @@ async function mutateHqAuthFile(dataDir, mutator, opts = {}) {
   await writeHqAuthFile(dataDir, next);
   return next;
 }
+var HQ_PASSWORD_SALT_BYTES = 16;
+var HQ_PASSWORD_HASH_BYTES = 32;
+var HQ_PASSWORD_SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
+function hashHqPassword(password) {
+  return new Promise((resolve4, reject) => {
+    const salt = randomBytes2(HQ_PASSWORD_SALT_BYTES);
+    scrypt(password, salt, HQ_PASSWORD_HASH_BYTES, HQ_PASSWORD_SCRYPT_PARAMS, (err, derivedKey) => {
+      if (err) return reject(err);
+      const payload = `scrypt$${salt.toString("base64url")}$${derivedKey.toString("base64url")}`;
+      resolve4(payload);
+    });
+  });
+}
+async function verifyHqPassword(password, hash) {
+  const parts = hash.split("$");
+  if (parts.length !== 3 || parts[0] !== "scrypt" || !parts[1] || !parts[2]) return false;
+  let salt;
+  let expected;
+  try {
+    salt = Buffer.from(parts[1], "base64url");
+    expected = Buffer.from(parts[2], "base64url");
+  } catch {
+    return false;
+  }
+  if (salt.length === 0 || expected.length === 0) return false;
+  const derived = await new Promise((resolve4, reject) => {
+    scrypt(password, salt, expected.length, HQ_PASSWORD_SCRYPT_PARAMS, (err, key) => {
+      if (err) reject(err);
+      else resolve4(key);
+    });
+  });
+  return timingSafeEqual(derived, expected);
+}
+function mintHqCookieSecret() {
+  return randomBytes2(32).toString("base64url");
+}
 function mintHqToken(label) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   return {
-    id: randomUUID(),
-    token: randomUUID().replace(/-/g, "") + randomUUID().replace(/-/g, ""),
+    id: randomUUID3(),
+    token: randomUUID3().replace(/-/g, "") + randomUUID3().replace(/-/g, ""),
     ...label ? { label } : {},
     createdAt: now
   };
@@ -2494,7 +3232,7 @@ function watchHqAuthFile(dataDir, onChange, opts = {}) {
   let closed = false;
   let watcher;
   try {
-    watcher = syncFs.watch(path2.dirname(file), { recursive: false });
+    watcher = syncFs.watch(path5.dirname(file), { recursive: false });
   } catch (err) {
     opts.warn?.(`HQ auth watcher could not start: ${err.message}`);
     return { close: () => {
@@ -2518,7 +3256,7 @@ function watchHqAuthFile(dataDir, onChange, opts = {}) {
   watcher.on("change", (eventType, filename) => {
     const name = typeof filename === "string" ? filename : "";
     if (eventType === "rename" || eventType === "change") {
-      if (!name || name === "auth.json" || name === path2.basename(file)) {
+      if (!name || name === "auth.json" || name === path5.basename(file)) {
         trigger();
       }
     }
@@ -2545,7 +3283,7 @@ function discoverLocalHqEndpoint(options = {}) {
 }
 function readFirstClientTokenFromAuthFile(dataDir) {
   try {
-    const raw = syncFs.readFileSync(hqAuthFilePath(dataDir), "utf8");
+    const raw = fs3.readFileSync(hqAuthFilePath(dataDir), "utf8");
     const parsed = JSON.parse(raw);
     return parsed.clientTokens?.find((t) => t.token.trim().length > 0)?.token;
   } catch {
@@ -2578,6 +3316,10 @@ function resolveHqConfig(options = {}) {
   const url = envUrl || configUrl;
   const localFallbackToken = !url || isLoopbackHqUrl(url) ? readFirstClientTokenFromAuthFile(dataDir) : void 0;
   const token = explicitToken || localFallbackToken;
+  const rawContentEnv = env["WRONGSTACK_HQ_RAW_CONTENT"]?.trim();
+  const explicitRawContent = rawContentEnv ? rawContentEnv === "1" : fileConfig?.rawContent;
+  const projectAliasEnv = env["WRONGSTACK_HQ_PROJECT_ALIAS"]?.trim();
+  const projectAlias = projectAliasEnv || fileConfig?.projectAlias;
   if (!url) {
     if (enabled === false) return void 0;
     return {
@@ -2585,33 +3327,34 @@ function resolveHqConfig(options = {}) {
       enabled: true,
       discover: true,
       dataDir,
-      ...token ? { token } : {}
+      rawContent: explicitRawContent ?? true,
+      ...token ? { token } : {},
+      ...projectAlias ? { projectAlias } : {}
     };
   }
-  const rawContentEnv = env["WRONGSTACK_HQ_RAW_CONTENT"]?.trim();
-  const projectAliasEnv = env["WRONGSTACK_HQ_PROJECT_ALIAS"]?.trim();
+  const rawContent = explicitRawContent ?? true;
   return {
     url,
     ...token ? { token } : {},
     ...enabled !== void 0 ? { enabled } : {},
-    ...rawContentEnv ? { rawContent: rawContentEnv === "1" } : fileConfig?.rawContent !== void 0 ? { rawContent: fileConfig.rawContent } : {},
-    ...projectAliasEnv ? { projectAlias: projectAliasEnv } : fileConfig?.projectAlias ? { projectAlias: fileConfig.projectAlias } : {}
+    ...rawContent !== void 0 ? { rawContent } : {},
+    ...projectAlias ? { projectAlias } : {}
   };
 }
 function stableMachineId() {
-  return createHash("sha256").update(hostname()).digest("hex").slice(0, 12);
+  return createHash2("sha256").update(hostname()).digest("hex").slice(0, 12);
 }
 function deriveProjectId(projectRoot) {
-  return createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+  return createHash2("sha256").update(projectRoot).digest("hex").slice(0, 12);
 }
 function createHqPublisherFromEnv(options) {
   const config = options.config ?? resolveHqConfig({ config: options.appConfig?.hq });
   if (!config || config.enabled === false) return void 0;
   const machineId = options.machineId ?? stableMachineId();
   const host = options.hostnameOverride ?? hostname();
-  const projectName = options.projectName ?? config.projectAlias ?? (basename(options.projectRoot) || "unknown");
+  const projectName = options.projectName ?? config.projectAlias ?? (basename5(options.projectRoot) || "unknown");
   const client = {
-    clientId: `${machineId}:${options.clientKind}:${process.pid}`,
+    clientId: `${machineId}:${options.clientKind}:${process.pid}:${randomUUID4().slice(0, 8)}`,
     kind: options.clientKind,
     machineId,
     ...host ? { hostname: host } : {},
@@ -2642,7 +3385,8 @@ function createHqPublisherFromEnv(options) {
     // Auto-discovery: re-read the local HQ runtime marker + client token on
     // every connect attempt so late-started/restarted HQs are picked up.
     ...config.discover ? { resolveEndpoint: () => discoverLocalHqEndpoint({ dataDir: discoveryDataDir }) } : {},
-    ...options.discoveryPollMs !== void 0 ? { discoveryPollMs: options.discoveryPollMs } : {}
+    ...options.discoveryPollMs !== void 0 ? { discoveryPollMs: options.discoveryPollMs } : {},
+    ...options.logger !== void 0 ? { logger: options.logger } : {}
   });
 }
 function createGlobalMailbox(options) {
@@ -2704,6 +3448,10 @@ function startAgentMonitorEventBridge(opts) {
   };
 }
 
+// src/hq/session-bridge.ts
+import * as fs4 from "node:fs";
+import * as fsp2 from "node:fs/promises";
+
 // src/hq/transcript-mapper.ts
 function blocksToText(content) {
   if (typeof content === "string") return content;
@@ -2852,6 +3600,8 @@ var VALID_AGENT_STATUS = /* @__PURE__ */ new Set([
   "waiting_user",
   "error"
 ]);
+var MAX_TRANSCRIPT_BATCH_ENTRIES = 32;
+var MAX_TRANSCRIPT_BATCH_BYTES = 512 * 1024;
 function toAgentSummary(a) {
   const status = VALID_AGENT_STATUS.has(a.status) ? a.status : "idle";
   return {
@@ -2923,6 +3673,37 @@ function startSessionTelemetryBridge(opts) {
     } catch {
     }
   }
+  function publishTranscriptEntries(entries) {
+    let batch = [];
+    let batchFromSeq = seqEmitted;
+    const publishBatch = () => {
+      if (batch.length === 0) return;
+      try {
+        publisher.publishTranscriptAppend({
+          sessionId: opts.sessionId,
+          fromSeq: batchFromSeq,
+          entries: batch
+        });
+      } catch {
+      }
+      seqEmitted += batch.length;
+      batch = [];
+      batchFromSeq = seqEmitted;
+    };
+    for (const entry of entries) {
+      const candidate = [...batch, entry];
+      const candidatePayload = {
+        sessionId: opts.sessionId,
+        fromSeq: batchFromSeq,
+        entries: candidate
+      };
+      const tooManyEntries = candidate.length > MAX_TRANSCRIPT_BATCH_ENTRIES;
+      const tooLarge = batch.length > 0 && Buffer.byteLength(JSON.stringify(candidatePayload), "utf8") > MAX_TRANSCRIPT_BATCH_BYTES;
+      if (tooManyEntries || tooLarge) publishBatch();
+      batch.push(entry);
+    }
+    publishBatch();
+  }
   const offAgents = opts.events?.on("session.agents_updated", (payload) => {
     agents = payload.agents.map(toAgentSummary);
     lastActivityAt = now();
@@ -2938,7 +3719,7 @@ function startSessionTelemetryBridge(opts) {
   function setupWatcher() {
     if (disposed || watcher) return;
     try {
-      const nextWatcher = syncFs.watch(sessionFile, () => {
+      const nextWatcher = fs4.watch(sessionFile, () => {
         if (watchPending || disposed) return;
         watchPending = true;
         setTimeout(() => {
@@ -2962,12 +3743,12 @@ function startSessionTelemetryBridge(opts) {
     if (disposed || tailing) return;
     tailing = true;
     try {
-      const stat4 = await fsp.stat(sessionFile).catch(() => null);
+      const stat4 = await fsp2.stat(sessionFile).catch(() => null);
       if (disposed) return;
       if (!stat4) return;
       setupWatcher();
       if (stat4.size <= offset) return;
-      const fd = await fsp.open(sessionFile, "r");
+      const fd = await fsp2.open(sessionFile, "r");
       try {
         if (disposed) return;
         const len = stat4.size - offset;
@@ -2990,15 +3771,7 @@ function startSessionTelemetryBridge(opts) {
           for (const entry of mapSessionEventToEntries(obj)) entries.push(entry);
         }
         if (entries.length > 0) {
-          try {
-            publisher.publishTranscriptAppend({
-              sessionId: opts.sessionId,
-              fromSeq: seqEmitted,
-              entries
-            });
-          } catch {
-          }
-          seqEmitted += entries.length;
+          publishTranscriptEntries(entries);
           lastActivityAt = now();
         }
       } finally {
@@ -3306,6 +4079,7 @@ function startToolTelemetryBridge(opts) {
         toolName: p.name,
         ...p.input !== void 0 ? {
           inputSummary: summarizeHqToolArgs(p.input, {
+            policy: publisher.redactionPolicy,
             ...opts.projectRoot !== void 0 ? { projectRoot: opts.projectRoot } : {}
           })
         } : {}
@@ -3327,7 +4101,7 @@ function startToolTelemetryBridge(opts) {
         toolName: p.name,
         status: p.ok ? "success" : "error",
         durationMs: p.durationMs,
-        ...p.output !== void 0 && p.output.length > 0 ? { outputSummary: truncateForSummary(p.output) } : {}
+        ...p.output !== void 0 && p.output.length > 0 ? { outputSummary: truncateForSummary(p.output, publisher.redactionPolicy) } : {}
       };
       publisher.publishEvent({
         type: "tool.completed",
@@ -3344,9 +4118,13 @@ function startToolTelemetryBridge(opts) {
     inFlight.clear();
   };
 }
-function truncateForSummary(output, max = 280) {
-  if (output.length <= max) return output;
-  return `${output.slice(0, max)}\u2026[truncated:${output.length - max}]`;
+function truncateForSummary(output, policy, max = 280) {
+  const resolved = resolveHqRedactionPolicy(policy);
+  if (resolved.rawContent) {
+    if (output.length <= max) return output;
+    return `${output.slice(0, max)}\u2026[truncated:${output.length - max}]`;
+  }
+  return scrubAndTruncateHqPreview(output, max) ?? "";
 }
 
 // src/hq/cost-bridge.ts
@@ -3375,6 +4153,10 @@ function startCostTelemetryBridge(opts) {
     off();
   };
 }
+
+// src/hq/persistence.ts
+import * as fs5 from "node:fs/promises";
+import * as path6 from "node:path";
 var DEFAULT_EVENT_LOG_MAX_LINES = 5e4;
 var DEFAULT_EVENT_LOG_ROTATE_KEEP = 2e4;
 var HqEventLog = class {
@@ -3385,7 +4167,7 @@ var HqEventLog = class {
   lineCount = 0;
   counted = false;
   constructor(opts) {
-    this.filePath = path2.join(opts.dataDir, "events.jsonl");
+    this.filePath = path6.join(opts.dataDir, "events.jsonl");
     this.maxLines = opts.maxLines ?? DEFAULT_EVENT_LOG_MAX_LINES;
     this.rotateKeep = opts.rotateKeep ?? DEFAULT_EVENT_LOG_ROTATE_KEEP;
   }
@@ -3405,7 +4187,7 @@ var HqEventLog = class {
       this.counted = true;
     }
     const line = JSON.stringify(event) + "\n";
-    await fsp.appendFile(this.filePath, line, { encoding: "utf8" });
+    await fs5.appendFile(this.filePath, line, { encoding: "utf8" });
     this.lineCount += 1;
     if (this.lineCount >= this.maxLines) {
       await this.rotate();
@@ -3414,7 +4196,7 @@ var HqEventLog = class {
   async rotate() {
     await withFileLock(this.filePath, async () => {
       try {
-        const content = await fsp.readFile(this.filePath, "utf8");
+        const content = await fs5.readFile(this.filePath, "utf8");
         const lines = content.split("\n").filter((l) => l.length > 0);
         if (lines.length <= this.rotateKeep) {
           this.lineCount = lines.length;
@@ -3429,7 +4211,7 @@ var HqEventLog = class {
   }
   async countLines() {
     try {
-      const content = await fsp.readFile(this.filePath, "utf8");
+      const content = await fs5.readFile(this.filePath, "utf8");
       return content.split("\n").filter((l) => l.length > 0).length;
     } catch {
       return 0;
@@ -3442,7 +4224,7 @@ var HqEventLog = class {
   async recent(limit, typeFilter) {
     let content;
     try {
-      content = await fsp.readFile(this.filePath, "utf8");
+      content = await fs5.readFile(this.filePath, "utf8");
     } catch {
       return [];
     }
@@ -3469,7 +4251,7 @@ var HqSnapshotStore = class {
   filePath;
   writeChain = Promise.resolve();
   constructor(opts) {
-    this.filePath = path2.join(opts.dataDir, "snapshot.json");
+    this.filePath = path6.join(opts.dataDir, "snapshot.json");
   }
   /** Persist a snapshot. Best-effort, never rejects. */
   save(snapshot) {
@@ -3484,7 +4266,7 @@ var HqSnapshotStore = class {
   /** Read the last persisted snapshot, or `null` if none. */
   async load() {
     try {
-      const content = await fsp.readFile(this.filePath, "utf8");
+      const content = await fs5.readFile(this.filePath, "utf8");
       return JSON.parse(content);
     } catch {
       return null;
@@ -3498,7 +4280,7 @@ var HqTimeseriesStore = class {
   buckets = /* @__PURE__ */ new Map();
   flushChain = Promise.resolve();
   constructor(opts) {
-    this.filePath = path2.join(opts.dataDir, "timeseries.jsonl");
+    this.filePath = path6.join(opts.dataDir, "timeseries.jsonl");
     this.bucketMs = opts.bucketMs ?? 5 * 60 * 1e3;
     this.maxBuckets = opts.maxBuckets ?? 2016;
   }
@@ -3542,7 +4324,7 @@ var HqTimeseriesStore = class {
   async flushInternal(toWrite) {
     const lines = toWrite.map((b) => JSON.stringify(b)).join("\n") + "\n";
     await withFileLock(this.filePath, async () => {
-      await fsp.appendFile(this.filePath, lines, { encoding: "utf8" });
+      await fs5.appendFile(this.filePath, lines, { encoding: "utf8" });
     });
     const sorted = Array.from(this.buckets.keys()).sort((a, b) => a - b);
     while (this.buckets.size > this.maxBuckets) {
@@ -3561,7 +4343,7 @@ var HqTimeseriesStore = class {
   async load() {
     let content;
     try {
-      content = await fsp.readFile(this.filePath, "utf8");
+      content = await fs5.readFile(this.filePath, "utf8");
     } catch {
       return;
     }
@@ -3680,6 +4462,15 @@ var HqCommandAuditLog = class {
     const entry = this.entries.find((e) => e.commandId === commandId);
     if (entry) Object.assign(entry, patch);
   }
+  /** Update only when the command belongs to the authenticated client. */
+  updateForClient(commandId, clientId, patch) {
+    const entry = this.entries.find(
+      (candidate) => candidate.commandId === commandId && candidate.clientId === clientId
+    );
+    if (!entry) return false;
+    Object.assign(entry, patch);
+    return true;
+  }
   recent(limit = 200) {
     return this.entries.slice(-limit);
   }
@@ -3837,7 +4628,67 @@ function toAlertMessage(alert) {
     timestamp: new Date(alert.lastFiredAt).toISOString()
   };
 }
-
-export { DEFAULT_HQ_REDACTION_POLICY, HQ_AUTH_FILE_VERSION, HQ_COMMAND_TYPES, HQ_PROTOCOL_VERSION, HqAlertEngine, HqCommandAuditLog, HqEventLog, HqPublisher, HqSnapshotStore, HqTimeseriesStore, buildTranscriptFromEvents, createGlobalMailbox, createHqEventEnvelope, createHqPersistence, createHqPublisherFromEnv, createMailboxEventPayload, createMailboxSnapshotPayload, createMailboxSnapshotPayloadFromMailbox, defaultHqDataDir, discoverLocalHqEndpoint, emptyHqAuthFile, ensureHqFirstRunAuthFile, hqAuthFilePath, hqRuntimeFilePath, mapMailboxAgentToHqSummary, mapMailboxMessageToHqSummary, mapSessionEventToEntries, mergeToolResults, mintHqBrowserToken, mintHqToken, mutateHqAuthFile, parseHqEventPayload, parseHqFrame, readHqAuthFile, readHqRuntimeFileSync, redactHqEvent, redactHqValue, resolveHqConfig, resolveHqConfigFromEnv, resolveHqDataDir, scrubAndTruncateHqPreview, startAgentMonitorEventBridge, startBrainTelemetryBridge, startCostTelemetryBridge, startFleetTelemetryBridge, startSessionTelemetryBridge, startToolTelemetryBridge, startWorktreeTelemetryBridge, summarizeHqToolArgs, toAlertMessage, tokenHasCapability, validateHqCommand, watchHqAuthFile, writeHqAuthFile, writeHqRuntimeFile };
+export {
+  DEFAULT_HQ_REDACTION_POLICY,
+  HQ_AUTH_FILE_VERSION,
+  HQ_COMMAND_TYPES,
+  HQ_PROTOCOL_VERSION,
+  HQ_TRANSCRIPT_TEXT_CAP,
+  HqAlertEngine,
+  HqCommandAuditLog,
+  HqEventLog,
+  HqPublisher,
+  HqSnapshotStore,
+  HqTimeseriesStore,
+  buildTranscriptFromEvents,
+  createGlobalMailbox,
+  createHqEventEnvelope,
+  createHqPersistence,
+  createHqPublisherFromEnv,
+  createMailboxEventPayload,
+  createMailboxSnapshotPayload,
+  createMailboxSnapshotPayloadFromMailbox,
+  defaultHqDataDir,
+  discoverLocalHqEndpoint,
+  emptyHqAuthFile,
+  ensureHqFirstRunAuthFile,
+  hashHqPassword,
+  hqAuthFilePath,
+  hqRuntimeFilePath,
+  mapMailboxAgentToHqSummary,
+  mapMailboxMessageToHqSummary,
+  mapSessionEventToEntries,
+  mergeToolResults,
+  mintHqBrowserToken,
+  mintHqCookieSecret,
+  mintHqToken,
+  mutateHqAuthFile,
+  parseHqEventPayload,
+  parseHqFrame,
+  readHqAuthFile,
+  readHqRuntimeFileSync,
+  redactHqEvent,
+  redactHqValue,
+  resolveHqConfig,
+  resolveHqConfigFromEnv,
+  resolveHqDataDir,
+  resolveHqRedactionPolicy,
+  scrubAndTruncateHqPreview,
+  startAgentMonitorEventBridge,
+  startBrainTelemetryBridge,
+  startCostTelemetryBridge,
+  startFleetTelemetryBridge,
+  startSessionTelemetryBridge,
+  startToolTelemetryBridge,
+  startWorktreeTelemetryBridge,
+  summarizeHqToolArgs,
+  tightenHqRedactionPolicy,
+  toAlertMessage,
+  tokenHasCapability,
+  validateHqCommand,
+  verifyHqPassword,
+  watchHqAuthFile,
+  writeHqAuthFile,
+  writeHqRuntimeFile
+};
 //# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map