@wrongstack/core 0.285.0 → 0.287.0

package/dist/hq/index.js

@@ -1,11 +1,13 @@
-// src/hq/protocol.ts
-var HQ_PROTOCOL_VERSION = 1;
+// src/hq/protocol/tool.ts
 var DEFAULT_HQ_REDACTION_POLICY = {
   rawContent: true,
   toolArgs: "full",
   paths: "full"
 };
 var HQ_TRANSCRIPT_TEXT_CAP = 16e3;
+
+// src/hq/protocol/core.ts
+var HQ_PROTOCOL_VERSION = 1;
 var KNOWN_HQ_CLIENT_FRAME_TYPES = /* @__PURE__ */ new Set([
   "client.hello",
   "client.event",
@@ -140,8 +142,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 +402,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;
@@ -490,7 +545,12 @@ function hasCredentialAnchors(text) {
   text.includes("_TOKEN=") || // ACCESS_TOKEN=, AUTH_TOKEN=, ...
   text.includes("_SECRET=") || // API_SECRET=, CLIENT_SECRET=, ...
   text.includes("_PASSWORD=") || // DB_PASSWORD=, ROOT_PASSWORD=, ...
-  text.includes("mongodb://") || text.includes("mongodb+srv://") || text.includes("postgres://") || text.includes("postgresql://") || text.includes("mysql://") || text.includes("redis://");
+  text.includes("mongodb://") || text.includes("mongodb+srv://") || text.includes("postgres://") || text.includes("postgresql://") || text.includes("mysql://") || text.includes("redis://") || // JSON-style credential keys: tool outputs often serialise objects as
+  // raw JSON strings rather than parsed objects. The value may not start
+  // with a recognisable prefix (sk-, ghp_, etc.), so we anchor on common
+  // key names. The `"` prefix avoids matching prose that happens to mention
+  // these words — JSON serialisation always quotes string keys.
+  text.includes('"apiKey"') || text.includes('"api_key"') || text.includes('"token"') || text.includes('"secret"') || text.includes('"password"') || text.includes('"authorization"') || text.includes('"bearer"') || text.includes('"private_key"') || text.includes('"access_token"') || text.includes('"refresh_token"') || text.includes('"client_secret"');
 }
 var DefaultSecretScrubber = class {
   scrub(text) {
@@ -941,6 +1001,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 +1013,7 @@ var HqPublisher = class {
   reconnectMaxMs;
   maxQueuedMessages;
   resolvedRedactionPolicy;
+  logger;
   socket = null;
   seq = 0;
   queue = [];
@@ -1290,6 +1352,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",
@@ -1322,7 +1388,7 @@ var HqPublisher = class {
 
 // src/hq/factory.ts
 import { createHash as createHash2, randomUUID as randomUUID4 } from "node:crypto";
-import * as fs3 from "node:fs";
+import * as fs4 from "node:fs";
 import { hostname } from "node:os";
 import { basename as basename5 } from "node:path";
 
@@ -1333,7 +1399,8 @@ 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 fs2 from "node:fs/promises";
+import { watch as watchDir } from "node:fs";
 import * as path3 from "node:path";
 
 // src/utils/session-scoped-path.ts
@@ -1360,14 +1427,34 @@ function invalid(sessionId) {
 
 // src/utils/wstack-paths.ts
 import { createHash } from "node:crypto";
+import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path2 from "node:path";
+function canonicalProjectRoot(absRoot) {
+  const checkoutRoot = path2.resolve(absRoot);
+  const dotGit = path2.join(checkoutRoot, ".git");
+  try {
+    if (!fs.statSync(dotGit).isFile()) return checkoutRoot;
+    const gitDirLine = fs.readFileSync(dotGit, "utf8").trim();
+    const match = /^gitdir:\s*(.+)$/i.exec(gitDirLine);
+    if (!match?.[1]) return checkoutRoot;
+    const gitDir = path2.resolve(checkoutRoot, match[1].trim());
+    const commonDirFile = path2.join(gitDir, "commondir");
+    if (!fs.statSync(commonDirFile).isFile()) return checkoutRoot;
+    const commonDir = path2.resolve(gitDir, fs.readFileSync(commonDirFile, "utf8").trim());
+    if (path2.basename(commonDir).toLowerCase() !== ".git") return checkoutRoot;
+    return path2.dirname(commonDir);
+  } catch {
+    return checkoutRoot;
+  }
+}
 function projectHash(absRoot) {
-  return createHash("sha256").update(path2.resolve(absRoot)).digest("hex").slice(0, 12);
+  return createHash("sha256").update(canonicalProjectRoot(absRoot)).digest("hex").slice(0, 12);
 }
 function projectSlug(absRoot) {
-  const base = slugify(path2.basename(absRoot));
-  const hash = createHash("sha256").update(path2.resolve(absRoot)).digest("hex").slice(0, 6);
+  const identityRoot = canonicalProjectRoot(absRoot);
+  const base = slugify(path2.basename(identityRoot));
+  const hash = createHash("sha256").update(identityRoot).digest("hex").slice(0, 6);
   return `${base}-${hash}`;
 }
 function slugify(name) {
@@ -1538,16 +1625,16 @@ var FsError = class extends WrongStackError {
 // src/utils/atomic-write.ts
 async function atomicWrite(targetPath, content, opts = {}) {
   const dir = path3.dirname(targetPath);
-  await fs.mkdir(dir, { recursive: true });
+  await fs2.mkdir(dir, { recursive: true });
   const tmp = path3.join(dir, `.${path3.basename(targetPath)}.${randomBytes(6).toString("hex")}.tmp`);
   try {
     if (typeof content === "string") {
-      await fs.writeFile(tmp, content, { flag: "wx", encoding: opts.encoding ?? "utf8" });
+      await fs2.writeFile(tmp, content, { flag: "wx", encoding: opts.encoding ?? "utf8" });
     } else {
-      await fs.writeFile(tmp, content, { flag: "wx" });
+      await fs2.writeFile(tmp, content, { flag: "wx" });
     }
     try {
-      const fh = await fs.open(tmp, "r+");
+      const fh = await fs2.open(tmp, "r+");
       try {
         await fh.sync();
       } finally {
@@ -1557,24 +1644,24 @@ async function atomicWrite(targetPath, content, opts = {}) {
     }
     let mode;
     try {
-      const stat4 = await fs.stat(targetPath);
+      const stat4 = await fs2.stat(targetPath);
       mode = stat4.mode & 511;
     } catch {
       mode = opts.mode;
     }
     if (mode !== void 0) {
-      await fs.chmod(tmp, mode);
+      await fs2.chmod(tmp, mode);
     }
     await renameWithRetry(tmp, targetPath);
     if (mode !== void 0 && process.platform === "win32") {
       try {
-        await fs.chmod(targetPath, mode);
+        await fs2.chmod(targetPath, mode);
       } catch {
       }
     }
   } catch (err) {
     try {
-      await fs.unlink(tmp);
+      await fs2.unlink(tmp);
     } catch {
     }
     throw err;
@@ -1582,7 +1669,7 @@ async function atomicWrite(targetPath, content, opts = {}) {
 }
 async function withFileLock(targetPath, fn, opts = {}) {
   const dir = path3.dirname(targetPath);
-  await fs.mkdir(dir, { recursive: true });
+  await fs2.mkdir(dir, { recursive: true });
   const lockPath = path3.join(dir, `.${path3.basename(targetPath)}.lock`);
   const timeoutMs = opts.timeoutMs ?? 5e3;
   const staleMs = opts.staleMs ?? 3e4;
@@ -1590,26 +1677,27 @@ async function withFileLock(targetPath, fn, opts = {}) {
   let handle;
   for (; ; ) {
     try {
-      handle = await fs.open(lockPath, "wx");
+      handle = await fs2.open(lockPath, "wx");
       await handle.writeFile(`${process.pid}:${Date.now()}`);
       break;
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") {
-        await fs.mkdir(dir, { recursive: true });
+        await fs2.mkdir(dir, { recursive: true });
         continue;
       }
-      if (code !== "EEXIST") throw err;
+      if (code !== "EEXIST" && code !== "EPERM") throw err;
       try {
-        const stat4 = await fs.stat(lockPath);
+        const stat4 = await fs2.stat(lockPath);
         if (Date.now() - stat4.mtimeMs > staleMs) {
-          await fs.unlink(lockPath);
+          await fs2.unlink(lockPath);
           continue;
         }
       } catch {
         continue;
       }
-      if (Date.now() - started >= timeoutMs) {
+      const elapsed = Date.now() - started;
+      if (elapsed >= timeoutMs) {
         throw new FsError({
           message: `Timed out waiting for file lock: ${targetPath}`,
           code: "FS_ATOMIC_WRITE_FAILED",
@@ -1617,7 +1705,7 @@ async function withFileLock(targetPath, fn, opts = {}) {
           context: { timeoutMs }
         });
       }
-      await new Promise((resolve4) => setTimeout(resolve4, 25));
+      await waitForLockRelease(lockPath, timeoutMs - elapsed);
     }
   }
   try {
@@ -1628,22 +1716,66 @@ async function withFileLock(targetPath, fn, opts = {}) {
     } catch {
     }
     try {
-      await fs.unlink(lockPath);
+      await fs2.unlink(lockPath);
     } catch {
     }
   }
 }
+async function waitForLockRelease(lockPath, remainingMs) {
+  const parentDir = path3.dirname(lockPath);
+  const lockName = path3.basename(lockPath);
+  const intervalMs = Math.min(remainingMs, 100);
+  return new Promise((resolve4) => {
+    let settled = false;
+    let watcher = null;
+    const timer = setTimeout(() => {
+      settled = true;
+      watcher?.close();
+      resolve4();
+    }, intervalMs);
+    try {
+      watcher = watchDir(parentDir, (eventType, filename) => {
+        if (settled) return;
+        if (filename === lockName && (eventType === "rename" || eventType === "change")) {
+          settled = true;
+          clearTimeout(timer);
+          watcher?.close();
+          resolve4();
+        }
+      });
+    } catch {
+      clearTimeout(timer);
+      if (!settled) {
+        settled = true;
+        setTimeout(resolve4, Math.min(remainingMs, 25));
+      }
+      return;
+    }
+    fs2.access(lockPath).then(
+      () => {
+      },
+      () => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          watcher?.close();
+          resolve4();
+        }
+      }
+    );
+  });
+}
 var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
 async function renameWithRetry(from, to) {
   if (process.platform !== "win32") {
-    await fs.rename(from, to);
+    await fs2.rename(from, to);
     return;
   }
   const delays = [10, 25, 60, 120, 250];
   let lastErr;
   for (let i = 0; i <= delays.length; i++) {
     try {
-      await fs.rename(from, to);
+      await fs2.rename(from, to);
       return;
     } catch (err) {
       lastErr = err;
@@ -1657,6 +1789,181 @@ 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 isAckRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && value["__ack"] === true;
+}
+function parseMailboxLine(line) {
+  try {
+    const parsed = JSON.parse(line);
+    if (isAckRecord(parsed)) return parsed;
+    return parseMailboxMessage(parsed);
+  } catch {
+    return null;
+  }
+}
+function applyAckToMessage(msg, ack) {
+  if (ack.read && !(ack.readerId in msg.readBy)) {
+    msg.readBy[ack.readerId] = ack.timestamp;
+  }
+  if (ack.completed && !msg.completed) {
+    msg.completed = true;
+    msg.completedBy = ack.completedBy ?? ack.readerId;
+    msg.completedAt = ack.timestamp;
+  }
+  if (ack.outcome !== void 0 && msg.outcome !== ack.outcome) {
+    msg.outcome = ack.outcome;
+  }
+  if (ack.deleted === true) {
+    msg.deletedAt = ack.timestamp;
+    msg.deletedBy = ack.deletedBy ?? ack.readerId;
+  }
+  if (ack.deleted === false) {
+    delete msg.deletedAt;
+    delete msg.deletedBy;
+  }
+}
+function serializeAckRecord(ack) {
+  return JSON.stringify(ack) + "\n";
+}
+
 // src/coordination/mailbox-types.ts
 function normalizeRecipient(to) {
   return to.trim().toLowerCase() === "all" ? "*" : to.trim();
@@ -1665,13 +1972,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 +1983,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
@@ -1725,20 +2031,47 @@ var GlobalMailbox = class {
    * appended message). The chain runs each read to completion before
    * the next starts, in issue order — readers are read-only and never
    * conflict with each other on content, only on the cache mutation
-   * that follows the read. Pattern mirrors `DefaultMemoryStore.runSerialized`.
+   * that follows the read. Pattern mirrors a serialized mutation chain.
    */
   _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`), 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 +2100,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 +2108,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 +2124,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;
       }
@@ -1819,42 +2181,100 @@ var GlobalMailbox = class {
     const updated = await this.ackMany({ acks: [input] });
     return updated.length > 0 ? updated[0] : null;
   }
+  /** Diagnostic counters exposed for test/tool introspection. */
+  diag = {
+    ackManyCacheDesync: 0,
+    ackManyPreLockMtime: 0,
+    ackManyPostLockMtime: 0,
+    ackManyPreLockSize: 0,
+    ackManyPostLockSize: 0,
+    ackManyMessageCount: 0,
+    ackManyAckCount: 0,
+    cacheHitCount: 0,
+    cacheMissCount: 0,
+    cacheDesyncNoOp: 0,
+    applyAckTargetMissing: 0,
+    setMessageCacheCount: 0,
+    pushToCacheCount: 0
+  };
   async ackMany(input) {
     if (input.acks.length === 0) return [];
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const ackRecords = [];
     const updated = [];
+    const targetIds = /* @__PURE__ */ new Set();
     const byId = /* @__PURE__ */ new Map();
     for (const a of input.acks) {
       byId.set(a.messageId, a);
+      targetIds.add(a.messageId);
     }
-    await withFileLock(this.messagePath, async () => {
-      const all = await this._readMessagesFresh();
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      let changed = false;
-      for (const msg of all) {
-        const a = byId.get(msg.id);
-        if (!a) continue;
-        updated.push(msg);
-        if (a.read !== false && !(a.readerId in msg.readBy)) {
-          msg.readBy[a.readerId] = now;
-          changed = true;
-        }
-        if (a.completed && !msg.completed) {
-          msg.completed = true;
-          msg.completedBy = a.readerId;
-          msg.completedAt = now;
-          changed = true;
-        }
-        if (a.outcome !== void 0 && msg.outcome !== a.outcome) {
-          msg.outcome = a.outcome;
-          changed = true;
-        }
+    const preLockMtime = this._messageCacheMtime;
+    const preLockSize = this._messageCacheSize;
+    this.diag.ackManyPreLockMtime = preLockMtime;
+    this.diag.ackManyPreLockSize = preLockSize;
+    const all = await this._readMessagesCached();
+    for (const msg of all) {
+      const a = byId.get(msg.id);
+      if (!a) continue;
+      const needsRead = a.read !== false && !(a.readerId in msg.readBy);
+      const needsComplete = a.completed && !msg.completed;
+      const needsOutcome = a.outcome !== void 0 && msg.outcome !== a.outcome;
+      if (!needsRead && !needsComplete && !needsOutcome) {
+        updated.push({ ...msg, readBy: { ...msg.readBy } });
+        continue;
       }
-      if (changed) {
-        const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
-        await fsp.writeFile(this.messagePath, serialized, "utf8");
+      const copy = { ...msg, readBy: { ...msg.readBy } };
+      if (needsRead) copy.readBy[a.readerId] = now;
+      if (needsComplete) {
+        copy.completed = true;
+        copy.completedBy = a.readerId;
+        copy.completedAt = now;
       }
+      if (needsOutcome) copy.outcome = a.outcome;
+      updated.push(copy);
+      ackRecords.push({
+        __ack: true,
+        messageId: msg.id,
+        readerId: a.readerId,
+        timestamp: now,
+        read: a.read !== false,
+        completed: a.completed,
+        completedBy: a.completed ? a.readerId : void 0,
+        outcome: a.outcome
+      });
+    }
+    if (ackRecords.length === 0) {
+      if (updated.length > 0) {
+        for (const message of updated) {
+          this.publishHqMailboxEvent({
+            mailboxId: this.hqMailboxId,
+            action: message.completed ? "message.completed" : "message.read",
+            message
+          });
+        }
+      }
+      return updated;
+    }
+    const serialized = ackRecords.map((a) => serializeAckRecord(a)).join("");
+    await withFileLock(this.messagePath, async () => {
+      await fsp.appendFile(this.messagePath, serialized, "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
-      this._setMessageCache(all, mtimeMs, size);
+      for (const ack of ackRecords) {
+        this._applyAckToCache(ack);
+      }
+      this._messageCacheMtime = mtimeMs;
+      this._messageCacheSize = size;
+      this.diag.ackManyPostLockMtime = mtimeMs;
+      this.diag.ackManyPostLockSize = size;
+      this.diag.ackManyMessageCount = this._messageCache?.length ?? -1;
+      this.diag.ackManyAckCount = ackRecords.length;
+      const expectedMinSize = preLockSize + serialized.length;
+      if (preLockSize > 0 && size > expectedMinSize) {
+        const extraBytes = size - expectedMinSize;
+        console.error(
+          `[MAILBOX-DIAG] ackMany: post-lock size ${size} exceeds expected ${expectedMinSize} by ${extraBytes}B (mtime ${preLockMtime}->${mtimeMs}). Cache may be missing cross-process messages. diag.ackManyCacheDesync=${++this.diag.ackManyCacheDesync}`
+        );
+      }
     });
     for (const message of updated) {
       this.publishHqMailboxEvent({
@@ -1862,6 +2282,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,68 +2296,108 @@ 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;
   }
   async softDelete(mailId, by) {
-    let updated = null;
+    const all = await this._readMessagesCached();
+    const target = all.find((m) => m.id === mailId);
+    if (target === void 0) return null;
+    if (target.deletedAt !== void 0) {
+      return { ...target, readBy: { ...target.readBy } };
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const ack = {
+      __ack: true,
+      messageId: mailId,
+      readerId: by,
+      timestamp: now,
+      read: true,
+      deleted: true,
+      deletedBy: by
+    };
     await withFileLock(this.messagePath, async () => {
-      const all = await this._readMessagesFresh();
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      for (const m of all) {
-        if (m.id !== mailId) continue;
-        if (m.deletedAt !== void 0) {
-          updated = m;
-          continue;
-        }
-        m.deletedAt = now;
-        m.deletedBy = by;
-        updated = m;
-      }
-      const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
-      await fsp.writeFile(this.messagePath, serialized, "utf8");
+      await fsp.appendFile(this.messagePath, serializeAckRecord(ack), "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
-      this._setMessageCache(all, mtimeMs, size);
+      this._applyAckToCache(ack);
+      this._messageCacheMtime = mtimeMs;
+      this._messageCacheSize = size;
     });
-    if (updated !== null) {
-      this.publishHqMailboxEvent({
-        mailboxId: this.hqMailboxId,
-        action: "message.updated",
-        message: updated
-      });
-      this.publishHqMailboxSnapshot();
-    }
-    return updated;
+    const msg = { ...target, readBy: { ...target.readBy } };
+    msg.deletedAt = now;
+    msg.deletedBy = by;
+    this.publishHqMailboxEvent({
+      mailboxId: this.hqMailboxId,
+      action: "message.updated",
+      message: msg
+    });
+    this.publishHqMailboxSnapshot();
+    this.eventEmitter?.emit({
+      type: "message.deleted",
+      messageId: msg.id,
+      from: msg.from,
+      to: msg.to,
+      timestamp: msg.deletedAt ?? now
+    });
+    return msg;
   }
   async restore(mailId) {
-    let updated = null;
+    const all = await this._readMessagesCached();
+    const target = all.find((m) => m.id === mailId);
+    if (target === void 0) return null;
+    if (target.deletedAt === void 0 && target.deletedBy === void 0) {
+      return { ...target, readBy: { ...target.readBy } };
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const ack = {
+      __ack: true,
+      messageId: mailId,
+      readerId: "",
+      timestamp: now,
+      read: true,
+      deleted: false
+    };
     await withFileLock(this.messagePath, async () => {
-      const all = await this._readMessagesFresh();
-      for (const m of all) {
-        if (m.id !== mailId) continue;
-        delete m.deletedAt;
-        delete m.deletedBy;
-        updated = m;
-      }
-      const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
-      await fsp.writeFile(this.messagePath, serialized, "utf8");
+      await fsp.appendFile(this.messagePath, serializeAckRecord(ack), "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
-      this._setMessageCache(all, mtimeMs, size);
+      this._applyAckToCache(ack);
+      this._messageCacheMtime = mtimeMs;
+      this._messageCacheSize = size;
     });
-    if (updated !== null) {
-      this.publishHqMailboxEvent({
-        mailboxId: this.hqMailboxId,
-        action: "message.updated",
-        message: updated
-      });
-      this.publishHqMailboxSnapshot();
-    }
-    return updated;
+    const msg = { ...target, readBy: { ...target.readBy } };
+    delete msg.deletedAt;
+    delete msg.deletedBy;
+    this.publishHqMailboxEvent({
+      mailboxId: this.hqMailboxId,
+      action: "message.updated",
+      message: msg
+    });
+    this.publishHqMailboxSnapshot();
+    this.eventEmitter?.emit({
+      type: "message.restored",
+      messageId: msg.id,
+      from: msg.from,
+      to: msg.to,
+      timestamp: now
+    });
+    return msg;
   }
   // ── Agent registry ──────────────────────────────────────────────────────
   async registerAgent(input) {
@@ -2061,8 +2528,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 +2592,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();
@@ -2142,8 +2634,19 @@ var GlobalMailbox = class {
   }
   async getClientStatuses() {
     await this._ensureClientRegistry();
-    const registry = await this._readClientRegistry();
+    let registry = await this._readClientRegistry();
+    const before = registry.size;
     this._pruneStaleClientsInPlace(registry);
+    if (registry.size < before) {
+      await withFileLock(this.clientRegistryPath, async () => {
+        registry = await this._readClientRegistry({ fresh: true });
+        const postLockBefore = registry.size;
+        this._pruneStaleClientsInPlace(registry);
+        if (registry.size < postLockBefore) {
+          await this._writeClientRegistry(registry);
+        }
+      });
+    }
     const now = Date.now();
     return Array.from(registry.values()).map((c) => ({
       clientId: c.clientId,
@@ -2155,6 +2658,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 +2691,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 +2741,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.
@@ -2226,61 +2851,23 @@ var GlobalMailbox = class {
       throw err;
     }
   }
-  /**
-   * Read only newly-appended bytes from the file and append them to the
-   * in-memory cache. This avoids re-reading and re-parsing the entire file
-   * when another process appended messages since our last read.
-   *
-   * Only safe when the file grew in size (messages are append-only). When
-   * the file was rewritten (ack/purge changed existing content), callers
-   * must fall back to {@link _readMessages}.
-   *
-   * @returns The (now up-to-date) message cache.
-   */
-  async _readNewMessagesOnly(fd, oldSize, newSize) {
-    const tailLen = newSize - oldSize;
-    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 (!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"];
-        }
-        this._messageCache.push(parsed);
-      } catch {
-      }
-    }
-    return this._messageCache;
-  }
-  /** Parse a JSONL string into MailboxMessage[], including migration. */
+  /** Parse a JSONL string into MailboxMessage[], applying ack records. */
   _parseLines(raw) {
     const lines = raw.split(LINE_SEPARATOR).filter((l) => l.trim().length > 0);
     const messages = [];
+    const acks = [];
     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"];
-        }
+      const parsed = parseMailboxLine(line);
+      if (isAckRecord(parsed)) {
+        acks.push(parsed);
+      } else if (parsed !== null) {
         messages.push(parsed);
-      } catch {
       }
     }
+    for (const ack of acks) {
+      const target = messages.find((m) => m.id === ack.messageId);
+      if (target) applyAckToMessage(target, ack);
+    }
     return messages;
   }
   /**
@@ -2362,17 +2949,6 @@ var GlobalMailbox = class {
       if (this._messageCache !== null && this._messageCacheMtime === st.mtimeMs && this._messageCacheSize === st.size) {
         return this._messageCache;
       }
-      if (this._messageCache !== null && this._messageCacheSize >= 0 && st.size > this._messageCacheSize) {
-        const fd = await fsp.open(this.messagePath, "r");
-        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();
-        }
-      }
       const all = await this._readMessages();
       this._setMessageCache(all, st.mtimeMs, st.size);
       return all;
@@ -2404,11 +2980,61 @@ 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();
+  }
+  /**
+   * Fold a single ack record into the in-memory cache, mutating the target
+   * message in place. Called from `ackMany` after appending the record to
+   * disk so the cache reflects the ack without a full re-read + re-parse.
+   *
+   * An ack only touches `readBy`/`completed*`/`outcome` — none of which
+   * affect the recipient/sender indexes — so no index rebuild is needed.
+   * No-op when the cache is empty or the target message isn't cached.
+   */
+  _applyAckToCache(ack) {
+    const cache = this._messageCache;
+    if (cache === null) return;
+    const target = cache.find((m) => m.id === ack.messageId);
+    if (target !== void 0) applyAckToMessage(target, ack);
+  }
+  /**
+   * 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 +3061,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 +3109,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 +3156,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,8 +3175,8 @@ var GlobalMailbox = class {
 };
 
 // src/hq/auth-store.ts
-import { randomUUID as randomUUID3 } from "node:crypto";
-import * as fs2 from "node:fs/promises";
+import { randomBytes as randomBytes2, randomUUID as randomUUID3, scrypt, timingSafeEqual } from "node:crypto";
+import * as fs3 from "node:fs/promises";
 import * as syncFs from "node:fs";
 import * as path5 from "node:path";
 var HQ_AUTH_FILE_VERSION = 1;
@@ -2601,29 +3236,31 @@ function readHqRuntimeFileSync(dataDir) {
     return void 0;
   }
 }
-async function readHqAuthFile(dataDir, opts = {}) {
+async function readHqAuthFile(dataDir, _opts = {}) {
   const file = hqAuthFilePath(dataDir);
   let raw;
   try {
-    raw = await fs2.readFile(file, "utf8");
+    raw = await fs3.readFile(file, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") return emptyHqAuthFile();
-    opts.warn?.(`HQ auth file read failed at ${file}: ${err.message}`);
-    return emptyHqAuthFile();
+    throw new Error(
+      `HQ auth file at ${file} cannot be read: ${err.message}. Fix the file permissions or delete it to start with an empty auth state.`
+    );
   }
+  let parsed;
   try {
-    const parsed = JSON.parse(raw);
-    if (parsed.version !== HQ_AUTH_FILE_VERSION) {
-      opts.warn?.(
-        `HQ auth file at ${file} has unsupported version ${String(parsed.version)} (expected ${String(HQ_AUTH_FILE_VERSION)}); ignoring stored policy/tokens.`
-      );
-      return emptyHqAuthFile();
-    }
-    return parsed;
+    parsed = JSON.parse(raw);
   } catch (err) {
-    opts.warn?.(`HQ auth file at ${file} is not valid JSON; ignoring stored policy/tokens: ${err.message}`);
-    return emptyHqAuthFile();
+    throw new Error(
+      `HQ auth file at ${file} is not valid JSON: ${err.message}. Fix the file or delete it to start with an empty auth state.`
+    );
   }
+  if (parsed.version !== HQ_AUTH_FILE_VERSION) {
+    throw new Error(
+      `HQ auth file at ${file} has unsupported version ${String(parsed.version)} (expected ${String(HQ_AUTH_FILE_VERSION)}). Remove or update the file to match the current schema version.`
+    );
+  }
+  return parsed;
 }
 async function writeHqAuthFile(dataDir, file) {
   const target = hqAuthFilePath(dataDir);
@@ -2638,7 +3275,7 @@ async function writeHqAuthFile(dataDir, file) {
 async function ensureHqFirstRunAuthFile(dataDir, opts = {}) {
   const file = hqAuthFilePath(dataDir);
   try {
-    await fs2.access(file);
+    await fs3.access(file);
     return { authFile: await readHqAuthFile(dataDir, opts), created: false };
   } catch (err) {
     if (err.code !== "ENOENT") {
@@ -2654,6 +3291,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 +3304,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 {
@@ -2731,7 +3408,7 @@ function discoverLocalHqEndpoint(options = {}) {
 }
 function readFirstClientTokenFromAuthFile(dataDir) {
   try {
-    const raw = fs3.readFileSync(hqAuthFilePath(dataDir), "utf8");
+    const raw = fs4.readFileSync(hqAuthFilePath(dataDir), "utf8");
     const parsed = JSON.parse(raw);
     return parsed.clientTokens?.find((t) => t.token.trim().length > 0)?.token;
   } catch {
@@ -2833,70 +3510,16 @@ 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) {
   return new GlobalMailbox(options.projectDir, options.events, options.hqPublisher);
 }
 
-// src/hq/agent-bridge.ts
-function startAgentMonitorEventBridge(opts) {
-  const { events, clientId, projectId, publish } = opts;
-  const seq = { current: 0 };
-  function nextSeq() {
-    seq.current += 1;
-    return seq.current;
-  }
-  function buildEnvelope(type, payload, sessionId) {
-    return createHqEventEnvelope({
-      id: `${Date.now().toString(36)}-${nextSeq()}`,
-      type,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      clientId,
-      projectId,
-      seq: nextSeq(),
-      payload,
-      // Carry the parent session id so HQ can scope per-agent transcripts by
-      // (sessionId, subagentId) — without it, two sessions whose leaders both
-      // use the default id 'leader' would collide into one shared ring.
-      ...sessionId !== void 0 ? { sessionId } : {}
-    });
-  }
-  const offMessage = events.on("agent.timeline.message", (payload) => {
-    if (!publish) return;
-    const msgPayload = {
-      subagentId: payload.subagentId,
-      agentName: payload.agentName,
-      content: payload.content,
-      kind: payload.kind,
-      iteration: payload.iteration,
-      ts: payload.ts
-    };
-    if (payload.toolName !== void 0) msgPayload.toolName = payload.toolName;
-    if (payload.costUsd !== void 0) msgPayload.costUsd = payload.costUsd;
-    publish(buildEnvelope("agent.message", msgPayload, payload.sessionId));
-  });
-  const offStatus = events.on("agent.status_changed", (payload) => {
-    if (!publish) return;
-    const statusPayload = {
-      subagentId: payload.subagentId,
-      agentName: payload.agentName,
-      status: payload.status,
-      ts: payload.ts
-    };
-    if (payload.summary !== void 0) statusPayload.summary = payload.summary;
-    if (payload.task !== void 0) statusPayload.task = payload.task;
-    publish(buildEnvelope("agent.status", statusPayload));
-  });
-  return () => {
-    offMessage();
-    offStatus();
-  };
-}
-
 // src/hq/session-bridge.ts
-import * as fs4 from "node:fs";
+import * as fs5 from "node:fs";
 import * as fsp2 from "node:fs/promises";
 
 // src/hq/transcript-mapper.ts
@@ -3166,7 +3789,7 @@ function startSessionTelemetryBridge(opts) {
   function setupWatcher() {
     if (disposed || watcher) return;
     try {
-      const nextWatcher = fs4.watch(sessionFile, () => {
+      const nextWatcher = fs5.watch(sessionFile, () => {
         if (watchPending || disposed) return;
         watchPending = true;
         setTimeout(() => {
@@ -3263,7 +3886,11 @@ function startFleetTelemetryBridge(opts) {
     const subagents = stats.subagentStatuses.map((s) => ({
       subagentId: s.subagentId,
       ...s.taskId ? { task: s.taskId } : {},
-      status: normalizeSubagentStatus(s.status)
+      status: normalizeSubagentStatus(s.status),
+      ...s.model !== void 0 ? { model: s.model } : {},
+      ...s.costUsd !== void 0 ? { costUsd: s.costUsd } : {},
+      ...s.runtimeMs !== void 0 ? { runtimeMs: s.runtimeMs } : {},
+      ...s.lastActivityAt !== void 0 ? { lastActivityAt: s.lastActivityAt } : {}
     }));
     return {
       runId,
@@ -3271,6 +3898,7 @@ function startFleetTelemetryBridge(opts) {
       queuedTasks: stats.pending,
       completedTasks: stats.completed,
       failedTasks: stats.stopped,
+      ...stats.totalCostUsd !== void 0 ? { totalCostUsd: stats.totalCostUsd } : {},
       subagents
     };
   }
@@ -3586,6 +4214,10 @@ function startCostTelemetryBridge(opts) {
         totalTokens: p.usage.input + p.usage.output,
         costUsd: p.cost.total
       };
+      if (p.provider !== void 0) payload.provider = p.provider;
+      if (p.model !== void 0) payload.model = p.model;
+      if (p.usage.cacheRead !== void 0) payload.cacheRead = p.usage.cacheRead;
+      if (p.usage.cacheWrite !== void 0) payload.cacheWrite = p.usage.cacheWrite;
       const sessionId = opts.sessionId ?? p.sessionId;
       publisher.publishEvent({
         type: "session.usage",
@@ -3602,7 +4234,7 @@ function startCostTelemetryBridge(opts) {
 }
 
 // src/hq/persistence.ts
-import * as fs5 from "node:fs/promises";
+import * as fs6 from "node:fs/promises";
 import * as path6 from "node:path";
 var DEFAULT_EVENT_LOG_MAX_LINES = 5e4;
 var DEFAULT_EVENT_LOG_ROTATE_KEEP = 2e4;
@@ -3634,7 +4266,7 @@ var HqEventLog = class {
       this.counted = true;
     }
     const line = JSON.stringify(event) + "\n";
-    await fs5.appendFile(this.filePath, line, { encoding: "utf8" });
+    await fs6.appendFile(this.filePath, line, { encoding: "utf8" });
     this.lineCount += 1;
     if (this.lineCount >= this.maxLines) {
       await this.rotate();
@@ -3643,7 +4275,7 @@ var HqEventLog = class {
   async rotate() {
     await withFileLock(this.filePath, async () => {
       try {
-        const content = await fs5.readFile(this.filePath, "utf8");
+        const content = await fs6.readFile(this.filePath, "utf8");
         const lines = content.split("\n").filter((l) => l.length > 0);
         if (lines.length <= this.rotateKeep) {
           this.lineCount = lines.length;
@@ -3658,7 +4290,7 @@ var HqEventLog = class {
   }
   async countLines() {
     try {
-      const content = await fs5.readFile(this.filePath, "utf8");
+      const content = await fs6.readFile(this.filePath, "utf8");
       return content.split("\n").filter((l) => l.length > 0).length;
     } catch {
       return 0;
@@ -3671,7 +4303,7 @@ var HqEventLog = class {
   async recent(limit, typeFilter) {
     let content;
     try {
-      content = await fs5.readFile(this.filePath, "utf8");
+      content = await fs6.readFile(this.filePath, "utf8");
     } catch {
       return [];
     }
@@ -3713,7 +4345,7 @@ var HqSnapshotStore = class {
   /** Read the last persisted snapshot, or `null` if none. */
   async load() {
     try {
-      const content = await fs5.readFile(this.filePath, "utf8");
+      const content = await fs6.readFile(this.filePath, "utf8");
       return JSON.parse(content);
     } catch {
       return null;
@@ -3747,6 +4379,21 @@ var HqTimeseriesStore = class {
     if (signal.outputTokens !== void 0) bucket.outputTokens += signal.outputTokens;
     if (signal.toolCalls !== void 0) bucket.toolCalls += signal.toolCalls;
     if (signal.activeAgents !== void 0) bucket.activeAgents = signal.activeAgents;
+    if (signal.model !== void 0 || signal.provider !== void 0) {
+      const entry = {
+        costUsd: signal.costUsd ?? 0,
+        inputTokens: signal.inputTokens ?? 0,
+        outputTokens: signal.outputTokens ?? 0,
+        ...signal.cacheRead !== void 0 ? { cacheRead: signal.cacheRead } : {},
+        ...signal.cacheWrite !== void 0 ? { cacheWrite: signal.cacheWrite } : {}
+      };
+      if (signal.model !== void 0) {
+        bucket.byModel = foldBreakdown(bucket.byModel, signal.model, entry);
+      }
+      if (signal.provider !== void 0) {
+        bucket.byProvider = foldBreakdown(bucket.byProvider, signal.provider, entry);
+      }
+    }
     if (this.buckets.size > this.maxBuckets) {
       const sorted = Array.from(this.buckets.keys()).sort((a, b) => a - b);
       while (this.buckets.size > this.maxBuckets && sorted.length > 0) {
@@ -3771,7 +4418,7 @@ var HqTimeseriesStore = class {
   async flushInternal(toWrite) {
     const lines = toWrite.map((b) => JSON.stringify(b)).join("\n") + "\n";
     await withFileLock(this.filePath, async () => {
-      await fs5.appendFile(this.filePath, lines, { encoding: "utf8" });
+      await fs6.appendFile(this.filePath, lines, { encoding: "utf8" });
     });
     const sorted = Array.from(this.buckets.keys()).sort((a, b) => a - b);
     while (this.buckets.size > this.maxBuckets) {
@@ -3790,7 +4437,7 @@ var HqTimeseriesStore = class {
   async load() {
     let content;
     try {
-      content = await fs5.readFile(this.filePath, "utf8");
+      content = await fs6.readFile(this.filePath, "utf8");
     } catch {
       return;
     }
@@ -3811,11 +4458,66 @@ var HqTimeseriesStore = class {
     }
   }
 };
+function foldBreakdown(map, key, entry) {
+  const next = { ...map };
+  const existing = next[key];
+  if (existing === void 0) {
+    next[key] = { ...entry };
+  } else {
+    next[key] = {
+      costUsd: existing.costUsd + entry.costUsd,
+      inputTokens: existing.inputTokens + entry.inputTokens,
+      outputTokens: existing.outputTokens + entry.outputTokens,
+      cacheRead: existing.cacheRead !== void 0 || entry.cacheRead !== void 0 ? (existing.cacheRead ?? 0) + (entry.cacheRead ?? 0) : void 0,
+      cacheWrite: existing.cacheWrite !== void 0 || entry.cacheWrite !== void 0 ? (existing.cacheWrite ?? 0) + (entry.cacheWrite ?? 0) : void 0
+    };
+  }
+  return next;
+}
+var HqSimpleLog = class {
+  filePath;
+  writeChain = Promise.resolve();
+  constructor(dataDir, filename) {
+    this.filePath = path6.join(dataDir, filename);
+  }
+  /** Append one record as a JSON line. Best-effort, never rejects. */
+  append(record) {
+    this.writeChain = this.writeChain.then(() => fs6.appendFile(this.filePath, `${JSON.stringify(record)}
+`, { encoding: "utf8" })).catch(() => {
+    });
+  }
+  /** Resolves once all queued appends have settled. For tests. */
+  async drain() {
+    await this.writeChain.catch(() => {
+    });
+  }
+  /** Read all records oldest-first. Returns `[]` if the file doesn't exist. */
+  async readAll() {
+    let content;
+    try {
+      content = await fs6.readFile(this.filePath, "utf8");
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        out.push(JSON.parse(trimmed));
+      } catch {
+      }
+    }
+    return out;
+  }
+};
 function createHqPersistence(dataDir) {
   return {
     eventLog: new HqEventLog({ dataDir }),
     snapshotStore: new HqSnapshotStore({ dataDir }),
-    timeseries: new HqTimeseriesStore({ dataDir })
+    timeseries: new HqTimeseriesStore({ dataDir }),
+    commandLog: new HqSimpleLog(dataDir, "commands.jsonl"),
+    alertLog: new HqSimpleLog(dataDir, "alerts.jsonl")
   };
 }
 
@@ -3896,18 +4598,24 @@ function validateHqCommand(queued) {
 var HqCommandAuditLog = class {
   entries = [];
   max;
-  constructor(max = 1e3) {
+  onPersist;
+  constructor(max = 1e3, onPersist) {
     this.max = max;
+    this.onPersist = onPersist;
   }
   record(entry) {
     this.entries.push(entry);
     if (this.entries.length > this.max) {
       this.entries.splice(0, this.entries.length - this.max);
     }
+    this.onPersist?.(entry);
   }
   update(commandId, patch) {
     const entry = this.entries.find((e) => e.commandId === commandId);
-    if (entry) Object.assign(entry, patch);
+    if (entry) {
+      Object.assign(entry, patch);
+      this.onPersist?.(entry);
+    }
   }
   /** Update only when the command belongs to the authenticated client. */
   updateForClient(commandId, clientId, patch) {
@@ -3916,8 +4624,18 @@ var HqCommandAuditLog = class {
     );
     if (!entry) return false;
     Object.assign(entry, patch);
+    this.onPersist?.(entry);
     return true;
   }
+  /** Seed the ring from a durable store on boot (no persist callback fired). */
+  seed(entries) {
+    for (const entry of entries) {
+      this.entries.push(entry);
+    }
+    if (this.entries.length > this.max) {
+      this.entries.splice(0, this.entries.length - this.max);
+    }
+  }
   recent(limit = 200) {
     return this.entries.slice(-limit);
   }
@@ -3992,9 +4710,11 @@ var HqAlertEngine = class {
   maxHistory;
   timer = null;
   onAlert;
+  onPersist;
   constructor(opts) {
     this.onAlert = opts.onAlert;
     this.maxHistory = opts.maxHistory ?? 500;
+    this.onPersist = opts.onPersist;
   }
   /**
    * Evaluate all rules against the snapshot. Emits (via the `onAlert`
@@ -4024,6 +4744,7 @@ var HqAlertEngine = class {
           if (this.history.length > this.maxHistory) this.history.splice(0, this.history.length - this.maxHistory);
           fired.push(alert);
           this.onAlert(alert);
+          this.onPersist?.(alert);
         } else {
           existing.lastFiredAt = now;
         }
@@ -4044,6 +4765,15 @@ var HqAlertEngine = class {
   recentAlerts(limit = 100) {
     return this.history.slice(-limit);
   }
+  /** Seed the history from a durable store on boot (no alert callbacks fired). */
+  seed(alerts) {
+    for (const alert of alerts) {
+      this.history.push(alert);
+    }
+    if (this.history.length > this.maxHistory) {
+      this.history.splice(0, this.history.length - this.maxHistory);
+    }
+  }
   /**
    * Start periodic evaluation against a snapshot getter. The timer is
    * unref'd so it never keeps the process alive. Returns a disposer.
@@ -4085,6 +4815,7 @@ export {
   HqCommandAuditLog,
   HqEventLog,
   HqPublisher,
+  HqSimpleLog,
   HqSnapshotStore,
   HqTimeseriesStore,
   buildTranscriptFromEvents,
@@ -4099,6 +4830,7 @@ export {
   discoverLocalHqEndpoint,
   emptyHqAuthFile,
   ensureHqFirstRunAuthFile,
+  hashHqPassword,
   hqAuthFilePath,
   hqRuntimeFilePath,
   mapMailboxAgentToHqSummary,
@@ -4106,6 +4838,7 @@ export {
   mapSessionEventToEntries,
   mergeToolResults,
   mintHqBrowserToken,
+  mintHqCookieSecret,
   mintHqToken,
   mutateHqAuthFile,
   parseHqEventPayload,
@@ -4119,7 +4852,6 @@ export {
   resolveHqDataDir,
   resolveHqRedactionPolicy,
   scrubAndTruncateHqPreview,
-  startAgentMonitorEventBridge,
   startBrainTelemetryBridge,
   startCostTelemetryBridge,
   startFleetTelemetryBridge,
@@ -4131,6 +4863,7 @@ export {
   toAlertMessage,
   tokenHasCapability,
   validateHqCommand,
+  verifyHqPassword,
   watchHqAuthFile,
   writeHqAuthFile,
   writeHqRuntimeFile