@wrongstack/core 0.285.0 → 0.286.0

package/dist/hq/index.js

@@ -140,8 +140,57 @@ var KNOWN_HQ_EVENT_PAYLOAD_TYPES = /* @__PURE__ */ new Set([
   "tool.started",
   "tool.completed",
   "session.usage",
-  "client.heartbeat"
+  "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;
@@ -351,6 +400,10 @@ function parseHqEventPayload(eventType, payload) {
       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;
@@ -941,6 +994,7 @@ var HqPublisher = class {
     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;
@@ -952,6 +1006,7 @@ var HqPublisher = class {
   reconnectMaxMs;
   maxQueuedMessages;
   resolvedRedactionPolicy;
+  logger;
   socket = null;
   seq = 0;
   queue = [];
@@ -1290,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",
@@ -1657,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();
@@ -1665,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;
@@ -1683,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
@@ -1728,17 +1928,44 @@ 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) {
+  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 `${path4.basename(path4.dirname(this.messagePath))}:mailbox`;
@@ -1767,7 +1994,7 @@ var GlobalMailbox = class {
       // "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",
@@ -1775,7 +2002,8 @@ 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(path4.dirname(this.messagePath), { recursive: true });
@@ -1790,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;
       }
@@ -1862,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;
@@ -1869,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;
@@ -1882,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) {
@@ -1891,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;
   }
@@ -1911,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;
   }
@@ -2061,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,
@@ -2114,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();
@@ -2143,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,
@@ -2155,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;
@@ -2162,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 () => {
@@ -2210,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.
@@ -2242,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;
   }
@@ -2367,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();
@@ -2404,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
@@ -2435,6 +2938,23 @@ 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;
   }
@@ -2466,22 +2986,13 @@ 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 = {};
@@ -2522,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);
       }
     }
   }
@@ -2540,7 +3052,7 @@ var GlobalMailbox = class {
 };
 
 // src/hq/auth-store.ts
-import { randomUUID as randomUUID3 } from "node:crypto";
+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";
@@ -2654,6 +3166,10 @@ async function ensureHqFirstRunAuthFile(dataDir, opts = {}) {
     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 };
 }
@@ -2663,6 +3179,42 @@ 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 {
@@ -2833,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) {
@@ -4099,6 +4652,7 @@ export {
   discoverLocalHqEndpoint,
   emptyHqAuthFile,
   ensureHqFirstRunAuthFile,
+  hashHqPassword,
   hqAuthFilePath,
   hqRuntimeFilePath,
   mapMailboxAgentToHqSummary,
@@ -4106,6 +4660,7 @@ export {
   mapSessionEventToEntries,
   mergeToolResults,
   mintHqBrowserToken,
+  mintHqCookieSecret,
   mintHqToken,
   mutateHqAuthFile,
   parseHqEventPayload,
@@ -4131,6 +4686,7 @@ export {
   toAlertMessage,
   tokenHasCapability,
   validateHqCommand,
+  verifyHqPassword,
   watchHqAuthFile,
   writeHqAuthFile,
   writeHqRuntimeFile