@wrongstack/core 0.265.1 → 0.268.0

package/dist/hq/index.js

@@ -0,0 +1,1884 @@
+import { randomUUID, randomBytes, createHash } from 'crypto';
+import * as syncFs from 'fs';
+import * as os from 'os';
+import { hostname } from 'os';
+import * as path3 from 'path';
+import { basename } from 'path';
+import * as fsp from 'fs/promises';
+
+// src/hq/protocol.ts
+var HQ_PROTOCOL_VERSION = 1;
+var DEFAULT_HQ_REDACTION_POLICY = {
+  rawContent: false,
+  toolArgs: "summary",
+  paths: "project-relative"
+};
+var KNOWN_HQ_CLIENT_FRAME_TYPES = /* @__PURE__ */ new Set([
+  "client.hello",
+  "client.event",
+  "client.command_poll",
+  "client.command_ack"
+]);
+function hasStringType(x) {
+  return typeof x === "object" && x !== null && typeof x.type === "string";
+}
+function isHqClientIdentity(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.clientId === "string" && typeof v.kind === "string" && typeof v.machineId === "string" && typeof v.startedAt === "string";
+}
+function isHqProjectIdentity(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.projectId === "string" && typeof v.projectRoot === "string" && typeof v.projectName === "string" && typeof v.machineId === "string" && typeof v.workspaceKind === "string";
+}
+function isHqClientHelloPayload(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.protocolVersion === "number" && isHqClientIdentity(v.client) && isHqProjectIdentity(v.project) && Array.isArray(v.capabilities);
+}
+function isHqEventEnvelope(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.id === "string" && typeof v.type === "string" && typeof v.schemaVersion === "number" && typeof v.timestamp === "string" && typeof v.clientId === "string" && typeof v.projectId === "string" && typeof v.seq === "number";
+}
+function isHqClientCommandPollMessage(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.clientId === "string" && typeof v.projectId === "string";
+}
+function isHqClientCommandAckMessage(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.clientId === "string" && typeof v.projectId === "string" && typeof v.commandId === "string" && typeof v.status === "string";
+}
+function parseHqFrame(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
+  } catch {
+    return { ok: false, reason: "invalid-json" };
+  }
+  if (!hasStringType(parsed)) {
+    return { ok: false, reason: "malformed" };
+  }
+  const obj = parsed;
+  if (!KNOWN_HQ_CLIENT_FRAME_TYPES.has(obj.type)) {
+    return { ok: false, reason: "unknown-type" };
+  }
+  switch (obj.type) {
+    case "client.hello":
+      if (!isHqClientHelloPayload(obj.payload)) {
+        return { ok: false, reason: "malformed" };
+      }
+      return { ok: true, frame: { type: "client.hello", payload: obj.payload } };
+    case "client.event":
+      if (!isHqEventEnvelope(obj.event)) {
+        return { ok: false, reason: "malformed" };
+      }
+      return { ok: true, frame: { type: "client.event", event: obj.event } };
+    case "client.command_poll":
+      if (!isHqClientCommandPollMessage(obj)) {
+        return { ok: false, reason: "malformed" };
+      }
+      return {
+        ok: true,
+        frame: { type: "client.command_poll", clientId: obj.clientId, projectId: obj.projectId }
+      };
+    case "client.command_ack":
+      if (!isHqClientCommandAckMessage(obj)) {
+        return { ok: false, reason: "malformed" };
+      }
+      return {
+        ok: true,
+        frame: {
+          type: "client.command_ack",
+          clientId: obj.clientId,
+          projectId: obj.projectId,
+          commandId: obj.commandId,
+          status: obj.status
+        }
+      };
+    default: {
+      const _exhaustive = obj.type;
+      return _exhaustive;
+    }
+  }
+}
+var KNOWN_HQ_EVENT_PAYLOAD_TYPES = /* @__PURE__ */ new Set(["mailbox.snapshot", "mailbox.event"]);
+function isHqMailboxMessageSummary(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.messageId === "string" && typeof v.from === "string" && typeof v.to === "string" && typeof v.subject === "string" && typeof v.priority === "string" && typeof v.timestamp === "string" && typeof v.completed === "boolean" && typeof v.hasBody === "boolean";
+}
+function isHqMailboxAgentSummary(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  return typeof v.agentId === "string" && typeof v.name === "string" && typeof v.sessionId === "string" && typeof v.status === "string" && typeof v.iterations === "number" && typeof v.toolCalls === "number" && typeof v.lastActivityAt === "string" && typeof v.lastSeenAt === "string" && typeof v.online === "boolean";
+}
+function isHqMailboxSnapshotPayload(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  if (typeof v.mailboxId !== "string" || v.scope !== "project" && v.scope !== "global" || !Array.isArray(v.messages) || !Array.isArray(v.agents) || typeof v.totals !== "object" || v.totals === null) {
+    return false;
+  }
+  const totals = v.totals;
+  if (typeof totals.messages !== "number" || typeof totals.unread !== "number" || typeof totals.incomplete !== "number" || typeof totals.highPriority !== "number" || typeof totals.onlineAgents !== "number") {
+    return false;
+  }
+  for (const message of v.messages) {
+    if (!isHqMailboxMessageSummary(message)) return false;
+  }
+  for (const agent of v.agents) {
+    if (!isHqMailboxAgentSummary(agent)) return false;
+  }
+  return true;
+}
+var HQ_MAILBOX_EVENT_ACTIONS = /* @__PURE__ */ new Set([
+  "message.sent",
+  "message.read",
+  "message.completed",
+  "message.updated",
+  "agent.registered",
+  "agent.heartbeat",
+  "agent.offline"
+]);
+function isHqMailboxEventPayload(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const v = x;
+  if (typeof v.mailboxId !== "string") return false;
+  if (typeof v.action !== "string" || !HQ_MAILBOX_EVENT_ACTIONS.has(v.action)) return false;
+  if (v.message !== void 0 && !isHqMailboxMessageSummary(v.message)) return false;
+  if (v.agent !== void 0 && !isHqMailboxAgentSummary(v.agent)) return false;
+  return true;
+}
+function parseHqEventPayload(eventType, payload) {
+  if (!KNOWN_HQ_EVENT_PAYLOAD_TYPES.has(eventType)) {
+    return { ok: true, payload };
+  }
+  switch (eventType) {
+    case "mailbox.snapshot":
+      return isHqMailboxSnapshotPayload(payload) ? { ok: true, payload } : { ok: false, reason: "malformed-payload" };
+    case "mailbox.event":
+      return isHqMailboxEventPayload(payload) ? { ok: true, payload } : { ok: false, reason: "malformed-payload" };
+    default: {
+      const _exhaustive = eventType;
+      return _exhaustive;
+    }
+  }
+}
+function createHqEventEnvelope(input) {
+  return {
+    id: input.id,
+    type: input.type,
+    schemaVersion: HQ_PROTOCOL_VERSION,
+    timestamp: input.timestamp,
+    clientId: input.clientId,
+    projectId: input.projectId,
+    seq: input.seq,
+    payload: input.payload,
+    ...input.sessionId !== void 0 ? { sessionId: input.sessionId } : {},
+    ...input.runId !== void 0 ? { runId: input.runId } : {}
+  };
+}
+
+// src/security/secret-scrubber.ts
+var PATTERNS = [
+  // Anchored at the start where possible so partial matches inside larger
+  // strings don't trigger false positives.
+  {
+    type: "anthropic_key",
+    regex: /(?<![A-Za-z0-9])sk-ant-api\d+-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9])/g
+  },
+  { type: "openai_key", regex: /(?<![A-Za-z0-9])sk-(?:proj-)?[A-Za-z0-9_-]{20,}(?![A-Za-z0-9])/g },
+  { type: "github_pat", regex: /(?<![A-Za-z0-9])ghp_[A-Za-z0-9]{36,}(?![A-Za-z0-9])/g },
+  { type: "github_pat_v2", regex: /(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{50,}(?![A-Za-z0-9])/g },
+  { type: "aws_access_key", regex: /(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}(?![A-Za-z0-9])/g },
+  { type: "gcp_key", regex: /(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}(?![A-Za-z0-9])/g },
+  { type: "slack_token", regex: /(?<![A-Za-z0-9-])xox[abpos]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9-])/g },
+  {
+    type: "stripe_key",
+    regex: /(?<![A-Za-z0-9])sk_(?:live|test)_[A-Za-z0-9]{24,}(?![A-Za-z0-9])/g
+  },
+  {
+    type: "twilio_sid",
+    regex: /(?<![A-Za-z0-9])AC[a-f0-9]{32}(?![A-Za-z0-9])/g
+  },
+  {
+    type: "telegram_bot_token",
+    // Telegram tokens are of the form  bot<digits>:<alphanum>  in URL paths
+    regex: /\/bot\d+:[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])/g
+  },
+  {
+    type: "jwt",
+    // Anchored: look for literal "eyJ" which is unambiguous for JWT header
+    regex: /(?<![A-Za-z0-9/+=])eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}(?![A-Za-z0-9/+=])/g
+  },
+  {
+    type: "private_key",
+    // Anchored: start must be BEGIN, end must be END with no extra dashes after END
+    regex: /(?:^|\n)-----BEGIN (?:RSA|EC|OPENSSH|DSA|PGP)? ?PRIVATE KEY-----[\s\S]*?-----END[^-]*-----(?:\n|$)/g
+  },
+  { type: "mongodb_uri", regex: /mongodb(?:\+srv)?:\/\/[^\s"'`]+/g },
+  { type: "postgres_uri", regex: /postgres(?:ql)?:\/\/[^\s"'`]+/g },
+  { type: "mysql_uri", regex: /mysql:\/\/[^\s"'`]+/g },
+  { type: "redis_uri", regex: /redis:\/\/[^\s"'`]+/g },
+  // AI/ML provider keys — modern LLM services with well-known prefixes
+  {
+    type: "huggingface_token",
+    // HuggingFace tokens: hf_ followed by 34 alphanumeric chars
+    regex: /(?<![A-Za-z0-9])hf_[A-Za-z0-9]{34}(?![A-Za-z0-9])/g
+  },
+  {
+    type: "replicate_token",
+    // Replicate tokens: r8_ followed by 40+ alphanumeric chars
+    regex: /(?<![A-Za-z0-9])r8_[A-Za-z0-9]{40,}(?![A-Za-z0-9])/g
+  },
+  {
+    type: "perplexity_key",
+    // Perplexity API keys: pplx- followed by 40+ alphanumeric chars
+    regex: /(?<![A-Za-z0-9])pplx-[A-Za-z0-9]{40,}(?![A-Za-z0-9])/g
+  },
+  {
+    type: "groq_key",
+    // Groq API keys: gsk_ followed by 40+ alphanumeric chars
+    regex: /(?<![A-Za-z0-9])gsk_[A-Za-z0-9]{40,}(?![A-Za-z0-9])/g
+  },
+  {
+    type: "bearer_token",
+    // Anchored with alternation instead of negative lookahead — avoids V8
+    // backtracking risk on adversarial input. Bounded at 512 chars.
+    // Min 12 chars: some OAuth providers issue shorter-lived tokens (< 20
+    // chars). A 12-char base64 string has ~71 bits of entropy — above the
+    // threshold where random strings are unlikely to produce false matches.
+    regex: /(?:^|[^A-Za-z0-9_.~+/-])Bearer\s+[A-Za-z0-9._~+/-]{12,512}=*(?:$|[^A-Za-z0-9_.~+/-])/g
+  },
+  {
+    type: "high_entropy_env",
+    // Anchored with alternation instead of lookbehind to avoid backtracking.
+    // Value bounded at 512 chars.
+    regex: /(?:^|\s)([A-Z_]{4,}(?:KEY|TOKEN|SECRET|PASSWORD|PWD))\s*[:=]\s*['"]?([A-Za-z0-9_/+=-]{20,512})['"]?(?:\s|$)/g
+  }
+];
+var SIMPLE_PATTERNS = PATTERNS.filter((p) => p.type !== "high_entropy_env");
+var COMBINED_REGEX = new RegExp(SIMPLE_PATTERNS.map((p) => `(${p.regex.source})`).join("|"), "g");
+var HIGH_ENTROPY_REGEX = PATTERNS.find((p) => p.type === "high_entropy_env").regex;
+var COMBINED_REPLACEMENTS = SIMPLE_PATTERNS.map((p) => `[REDACTED:${p.type}]`);
+var SCRUB_CHUNK_BYTES = 64 * 1024;
+function hasCredentialAnchors(text) {
+  return text.includes("-----BEGIN") || // Private keys (most unique → cheap reject)
+  text.includes("sk-") || // Anthropic + OpenAI keys
+  text.includes("sk_") || // Stripe live/test keys
+  text.includes("ghp_") || // GitHub PAT v1
+  text.includes("github_pat_") || // GitHub PAT v2
+  text.includes("eyJ") || // JWT
+  text.includes("AKIA") || // AWS access key
+  text.includes("AIza") || // GCP service key
+  text.includes("xox") || // Slack token (xoxa/xoxb/xoxp/xoxo/xoxs)
+  text.includes("Bearer ") || // Bearer token (space suffix reduces false positives)
+  text.includes("/bot") || // Telegram bot token (URL path pattern)
+  text.includes("hf_") || // HuggingFace token
+  text.includes("r8_") || // Replicate token
+  text.includes("pplx-") || // Perplexity API key
+  text.includes("gsk_") || // Groq API key
+  text.includes("_KEY=") || // High-entropy env vars: API_KEY=, SECRET_KEY=, ...
+  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://");
+}
+var DefaultSecretScrubber = class {
+  scrub(text) {
+    if (!text) return text;
+    if (!hasCredentialAnchors(text)) return text;
+    if (text.length <= SCRUB_CHUNK_BYTES) {
+      return this.scrubOne(text);
+    }
+    const out = [];
+    let i = 0;
+    while (i < text.length) {
+      let end = Math.min(i + SCRUB_CHUNK_BYTES, text.length);
+      if (end < text.length) {
+        const nl = text.lastIndexOf("\n", end);
+        if (nl > i + SCRUB_CHUNK_BYTES / 2) end = nl + 1;
+      }
+      out.push(this.scrubOne(text.slice(i, end)));
+      i = end;
+    }
+    return out.join("");
+  }
+  scrubOne(text) {
+    if (!hasCredentialAnchors(text)) return text;
+    let out = text.replace(
+      COMBINED_REGEX,
+      (match, ...groups) => {
+        const idx = groups.findIndex((g) => g !== void 0);
+        if (idx < 0) return match;
+        const replacement = COMBINED_REPLACEMENTS[idx];
+        return replacement !== void 0 ? replacement : match;
+      }
+    );
+    out = out.replace(HIGH_ENTROPY_REGEX, (_match, group1, _group2) => {
+      return `${group1}=[REDACTED:high_entropy_env]`;
+    });
+    return out;
+  }
+  /**
+   * Recursively scrub every string value in an object/array graph. Secrets can
+   * appear under any key — a URL query param, an `authorization` header, an
+   * arbitrarily-named nested field — so we don't gate recursion on key names.
+   * The per-string `scrub()` fast-path (anchor pre-scan) keeps this cheap: any
+   * value without a credential anchor returns immediately without regex work.
+   */
+  scrubObject(obj) {
+    const seen = /* @__PURE__ */ new WeakSet();
+    const visit = (v) => {
+      if (typeof v === "string") return this.scrub(v);
+      if (v === null || typeof v !== "object") return v;
+      if (seen.has(v)) return v;
+      seen.add(v);
+      if (Array.isArray(v)) return v.map(visit);
+      const out = {};
+      for (const [k, val] of Object.entries(v)) {
+        out[k] = visit(val);
+      }
+      return out;
+    };
+    return visit(obj);
+  }
+};
+
+// src/hq/redaction.ts
+var RAW_CONTENT_REPLACEMENT = "[REDACTED:hq_raw_content]";
+var SENSITIVE_FIELD_REPLACEMENT = "[REDACTED:hq_sensitive_field]";
+var REDACTED_PATH_REPLACEMENT = "[REDACTED:hq_path]";
+var RAW_CONTENT_KEYS = /* @__PURE__ */ new Set([
+  "content",
+  "contents",
+  "raw",
+  "rawContent",
+  "body",
+  "message",
+  "messages",
+  "prompt",
+  "prompts",
+  "completion",
+  "response",
+  "assistantMessage",
+  "userMessage",
+  "stdout",
+  "stderr",
+  "output",
+  "toolInput",
+  "toolOutput",
+  "body",
+  "mailboxBody",
+  "messageBody",
+  "outcome",
+  "fileContent",
+  "diff",
+  "patch",
+  "transcript",
+  "logs"
+]);
+var SENSITIVE_KEYS = /* @__PURE__ */ new Set([
+  "authorization",
+  "cookie",
+  "password",
+  "passwd",
+  "pwd",
+  "secret",
+  "token",
+  "accessToken",
+  "refreshToken",
+  "apiKey",
+  "apikey",
+  "clientSecret",
+  "privateKey"
+]);
+var PATH_KEYS = /* @__PURE__ */ new Set([
+  "path",
+  "paths",
+  "file",
+  "files",
+  "filepath",
+  "filePath",
+  "filename",
+  "projectRoot",
+  "projectRootDisplay",
+  "cwd",
+  "workingDir",
+  "workingDirectory"
+]);
+var defaultScrubber = new DefaultSecretScrubber();
+function resolvePolicy(policy) {
+  return {
+    ...DEFAULT_HQ_REDACTION_POLICY,
+    ...policy
+  };
+}
+function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+function isSensitiveKey(key) {
+  const lower = key.toLowerCase();
+  return SENSITIVE_KEYS.has(key) || lower.includes("authorization") || lower.includes("password") || lower.includes("secret") || lower.endsWith("token") || lower.endsWith("apikey") || lower.endsWith("api_key");
+}
+function isRawContentKey(key) {
+  return RAW_CONTENT_KEYS.has(key) || RAW_CONTENT_KEYS.has(key.toLowerCase());
+}
+function isPathKey(key) {
+  return PATH_KEYS.has(key) || PATH_KEYS.has(key.toLowerCase());
+}
+function normalizePathForCompare(value) {
+  return value.replace(/\\/g, "/").replace(/\/+$/g, "");
+}
+function redactPath(value, projectRoot, policy) {
+  if (policy.paths === "full") return defaultScrubber.scrub(value);
+  if (policy.paths === "none" || policy.paths === "redacted") return REDACTED_PATH_REPLACEMENT;
+  const normalizedValue = normalizePathForCompare(value);
+  if (!projectRoot) return normalizedValue.split("/").at(-1) ?? REDACTED_PATH_REPLACEMENT;
+  const normalizedRoot = normalizePathForCompare(projectRoot);
+  if (normalizedValue === normalizedRoot) return ".";
+  if (normalizedValue.startsWith(`${normalizedRoot}/`)) {
+    return normalizedValue.slice(normalizedRoot.length + 1) || ".";
+  }
+  return normalizedValue.split("/").at(-1) ?? REDACTED_PATH_REPLACEMENT;
+}
+function summarizeString(value, maxSummaryLength) {
+  const scrubbed = defaultScrubber.scrub(value);
+  if (scrubbed.length <= maxSummaryLength) return scrubbed;
+  return `${scrubbed.slice(0, maxSummaryLength)}\u2026[truncated:${scrubbed.length - maxSummaryLength}]`;
+}
+function scrubAndTruncateHqPreview(value, maxLength = 280) {
+  if (typeof value !== "string" || value.length === 0) return void 0;
+  return summarizeString(value, maxLength);
+}
+function visitValue(value, options, key) {
+  if (key !== void 0 && isSensitiveKey(key)) {
+    return { value: SENSITIVE_FIELD_REPLACEMENT, redacted: true };
+  }
+  if (typeof value === "string") {
+    if (key !== void 0 && isPathKey(key)) {
+      const redactedPath = redactPath(value, options.projectRoot, options.policy);
+      return { value: redactedPath, redacted: redactedPath !== value };
+    }
+    if (!options.policy.rawContent && key !== void 0 && isRawContentKey(key)) {
+      return { value: RAW_CONTENT_REPLACEMENT, redacted: true };
+    }
+    const scrubbed = summarizeString(value, options.maxSummaryLength);
+    return { value: scrubbed, redacted: scrubbed !== value };
+  }
+  if (value === null || typeof value !== "object") return { value, redacted: false };
+  if (options.seen.has(value)) return { value: "[REDACTED:hq_circular]", redacted: true };
+  options.seen.add(value);
+  if (Array.isArray(value)) {
+    let redacted2 = false;
+    const out2 = value.map((item) => {
+      const next = visitValue(item, options, key);
+      redacted2 ||= next.redacted;
+      return next.value;
+    });
+    return { value: out2, redacted: redacted2 };
+  }
+  if (!isPlainObject(value)) return { value: String(value), redacted: true };
+  let redacted = false;
+  const out = {};
+  for (const [childKey, childValue] of Object.entries(value)) {
+    const next = visitValue(childValue, options, childKey);
+    redacted ||= next.redacted;
+    out[childKey] = next.value;
+  }
+  return { value: out, redacted };
+}
+function redactHqValue(value, options = {}) {
+  const result = visitValue(value, {
+    policy: resolvePolicy(options.policy),
+    ...options.projectRoot !== void 0 ? { projectRoot: options.projectRoot } : {},
+    maxSummaryLength: options.maxSummaryLength ?? 500,
+    seen: /* @__PURE__ */ new WeakSet()
+  });
+  return { value: result.value, redacted: result.redacted };
+}
+function redactHqEvent(event, options = {}) {
+  const payload = redactHqValue(event.payload, options);
+  const nextEvent = {
+    ...event,
+    payload: payload.value
+  };
+  return { value: nextEvent, redacted: payload.redacted };
+}
+function summarizeHqToolArgs(value, options = {}) {
+  const policy = resolvePolicy(options.policy);
+  if (policy.toolArgs === "none") return "[REDACTED:hq_tool_args]";
+  if (policy.toolArgs === "redacted") return redactHqValue(value, options).value;
+  if (value === null || typeof value !== "object") return redactHqValue(value, options).value;
+  if (Array.isArray(value)) return `[array:${value.length}]`;
+  const entries = Object.entries(value);
+  const summary = {};
+  for (const [key, item] of entries.slice(0, 20)) {
+    if (isSensitiveKey(key)) {
+      summary[key] = SENSITIVE_FIELD_REPLACEMENT;
+    } else if (typeof item === "string") {
+      summary[key] = isPathKey(key) ? redactPath(item, options.projectRoot, policy) : summarizeString(item, 120);
+    } else if (Array.isArray(item)) {
+      summary[key] = `[array:${item.length}]`;
+    } else if (item !== null && typeof item === "object") {
+      summary[key] = "[object]";
+    } else {
+      summary[key] = item;
+    }
+  }
+  if (entries.length > 20) summary.__truncatedKeys = entries.length - 20;
+  return summary;
+}
+
+// src/hq/mailbox-mapper.ts
+function previewText(value, maxLength, policy) {
+  if (value === void 0 || value.length === 0) return void 0;
+  const redacted = redactHqValue(value, { maxSummaryLength: maxLength, policy: { rawContent: true, ...policy } }).value;
+  if (redacted.length <= maxLength) return redacted;
+  return `${redacted.slice(0, maxLength)}\u2026`;
+}
+function readCount(message) {
+  return Object.keys(message.readBy).length;
+}
+function taskSummary(message) {
+  if (message.taskContext === void 0) return void 0;
+  const task = {
+    ...message.taskContext.taskId !== void 0 ? { taskId: message.taskContext.taskId } : {},
+    ...message.taskContext.agentRole !== void 0 ? { agentRole: message.taskContext.agentRole } : {},
+    ...message.taskContext.agentName !== void 0 ? { agentName: message.taskContext.agentName } : {},
+    ...message.taskContext.status !== void 0 ? { status: message.taskContext.status } : {}
+  };
+  return Object.keys(task).length > 0 ? task : void 0;
+}
+function mapMailboxMessageToHqSummary(message, options = {}) {
+  const previewLength = options.previewLength ?? 160;
+  const bodyPreview = previewText(message.body, previewLength, options.redactionPolicy);
+  const outcomePreview = previewText(message.outcome, previewLength, options.redactionPolicy);
+  const task = taskSummary(message);
+  return {
+    messageId: message.id,
+    from: message.from,
+    to: message.to,
+    type: message.type,
+    subject: previewText(message.subject, previewLength, options.redactionPolicy) ?? "",
+    priority: message.priority,
+    timestamp: message.timestamp,
+    ...message.replyTo !== void 0 ? { replyTo: message.replyTo } : {},
+    ...message.senderSessionId !== void 0 ? { senderSessionId: message.senderSessionId } : {},
+    completed: message.completed,
+    ...message.completedBy !== void 0 ? { completedBy: message.completedBy } : {},
+    ...message.completedAt !== void 0 ? { completedAt: message.completedAt } : {},
+    readCount: readCount(message),
+    hasBody: message.body.length > 0,
+    ...bodyPreview !== void 0 ? { bodyPreview } : {},
+    ...outcomePreview !== void 0 ? { outcomePreview } : {},
+    ...task !== void 0 ? { task } : {}
+  };
+}
+function mapMailboxAgentToHqSummary(agent) {
+  return {
+    agentId: agent.agentId,
+    name: agent.name,
+    ...agent.role !== void 0 ? { role: agent.role } : {},
+    sessionId: agent.sessionId,
+    status: agent.status,
+    ...agent.currentTool !== void 0 ? { currentTool: agent.currentTool } : {},
+    ...agent.currentTask !== void 0 ? { currentTask: agent.currentTask } : {},
+    iterations: agent.iterations,
+    toolCalls: agent.toolCalls,
+    lastActivityAt: agent.lastActivityAt,
+    lastSeenAt: agent.lastSeenAt,
+    online: agent.online,
+    ...agent.source !== void 0 ? { source: agent.source } : {}
+  };
+}
+function createMailboxSnapshotPayload(messages, agents, options) {
+  const includeCompleted = options.includeCompleted ?? true;
+  const filteredMessages = includeCompleted ? messages : messages.filter((message) => !message.completed);
+  const limit = options.limit ?? 50;
+  const sortedMessages = [...filteredMessages].sort((a, b) => b.timestamp.localeCompare(a.timestamp)).slice(0, limit);
+  const summaries = sortedMessages.map((message) => mapMailboxMessageToHqSummary(message, options));
+  const agentSummaries = agents.map(mapMailboxAgentToHqSummary);
+  return {
+    mailboxId: options.mailboxId,
+    scope: options.scope ?? "project",
+    messages: summaries,
+    agents: agentSummaries,
+    totals: {
+      messages: messages.length,
+      unread: messages.filter((message) => !message.completed && readCount(message) === 0).length,
+      incomplete: messages.filter((message) => !message.completed).length,
+      highPriority: messages.filter((message) => message.priority === "high").length,
+      onlineAgents: agents.filter((agent) => agent.online).length
+    }
+  };
+}
+async function createMailboxSnapshotPayloadFromMailbox(mailbox, options) {
+  const limit = options.limit ?? 50;
+  const [messages, agents] = await Promise.all([
+    mailbox.query({ limit }),
+    mailbox.getAgentStatuses()
+  ]);
+  return createMailboxSnapshotPayload(messages, agents, options);
+}
+function createMailboxEventPayload(input) {
+  const summaryOptions = {
+    ...input.previewLength !== void 0 ? { previewLength: input.previewLength } : {},
+    ...input.redactionPolicy !== void 0 ? { redactionPolicy: input.redactionPolicy } : {}
+  };
+  return {
+    mailboxId: input.mailboxId,
+    action: input.action,
+    ...input.message !== void 0 ? { message: mapMailboxMessageToHqSummary(input.message, summaryOptions) } : {},
+    ...input.agent !== void 0 ? { agent: mapMailboxAgentToHqSummary(input.agent) } : {},
+    ...input.summary !== void 0 ? { summary: previewText(input.summary, input.previewLength ?? 160, input.redactionPolicy) ?? "" } : {}
+  };
+}
+var OPEN_STATE = 1;
+var DEFAULT_RECONNECT_BASE_MS = 1e3;
+var DEFAULT_RECONNECT_MAX_MS = 3e4;
+var DEFAULT_MAX_QUEUED_MESSAGES = 250;
+var DEFAULT_COMMAND_POLL_INTERVAL_MS = 1e4;
+var DEFAULT_COMMAND_POLL_LIMIT = 25;
+function defaultSocketFactory(url) {
+  const WebSocketCtor = globalThis.WebSocket;
+  if (WebSocketCtor === void 0) {
+    throw new Error("No global WebSocket implementation is available; provide HqPublisherOptions.socketFactory.");
+  }
+  return new WebSocketCtor(url);
+}
+function toClientUrl(baseUrl, token) {
+  const url = new URL(baseUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  if (url.pathname === "/" || url.pathname === "") url.pathname = "/ws/client";
+  if (token !== void 0 && token.length > 0) url.searchParams.set("token", token);
+  return url.toString();
+}
+function addSocketListener(socket, type, listener) {
+  if (socket.addEventListener !== void 0) {
+    socket.addEventListener(type, listener);
+    return;
+  }
+  socket.on?.(type, listener);
+}
+function removeSocketListener(socket, type, listener) {
+  if (socket.removeEventListener !== void 0) {
+    socket.removeEventListener(type, listener);
+    return;
+  }
+  socket.off?.(type, listener);
+}
+var HqPublisher = class {
+  constructor(options) {
+    this.options = options;
+    this.socketFactory = options.socketFactory ?? defaultSocketFactory;
+    this.now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+    this.idFactory = options.idFactory ?? randomUUID;
+    this.capabilities = options.capabilities ?? ["telemetry.publish", "mailbox.summary"];
+    this.reconnect = options.reconnect ?? true;
+    this.reconnectBaseMs = options.reconnectBaseMs ?? DEFAULT_RECONNECT_BASE_MS;
+    this.reconnectMaxMs = options.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
+    this.maxQueuedMessages = options.maxQueuedMessages ?? DEFAULT_MAX_QUEUED_MESSAGES;
+  }
+  options;
+  socketFactory;
+  now;
+  idFactory;
+  capabilities;
+  reconnect;
+  reconnectBaseMs;
+  reconnectMaxMs;
+  maxQueuedMessages;
+  socket = null;
+  seq = 0;
+  queue = [];
+  stopped = false;
+  reconnectAttempt = 0;
+  reconnectTimer = null;
+  commandPollTimer = null;
+  lastCommandId;
+  connect() {
+    if (this.socket !== null || this.stopped) return;
+    const socket = this.socketFactory(toClientUrl(this.options.url, this.options.token), {
+      ...this.options.token !== void 0 ? { token: this.options.token } : {}
+    });
+    this.socket = socket;
+    const onOpen = () => {
+      this.reconnectAttempt = 0;
+      this.sendHello();
+      this.flushQueue();
+      if (this.options.onCommand !== void 0) {
+        this.startCommandPolling();
+        this.pollCommands();
+      }
+    };
+    const onMessage = (event) => {
+      void this.handleServerMessage(event);
+    };
+    const onCloseOrError = () => {
+      removeSocketListener(socket, "open", onOpen);
+      removeSocketListener(socket, "message", onMessage);
+      removeSocketListener(socket, "close", onCloseOrError);
+      removeSocketListener(socket, "error", onCloseOrError);
+      this.stopCommandPolling();
+      if (this.socket === socket) this.socket = null;
+      this.scheduleReconnect();
+    };
+    addSocketListener(socket, "open", onOpen);
+    addSocketListener(socket, "message", onMessage);
+    addSocketListener(socket, "close", onCloseOrError);
+    addSocketListener(socket, "error", onCloseOrError);
+    if (socket.readyState === OPEN_STATE) onOpen();
+  }
+  close() {
+    this.stopped = true;
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.stopCommandPolling();
+    this.queue = [];
+    const socket = this.socket;
+    this.socket = null;
+    socket?.close(1e3, "hq publisher closed");
+  }
+  publishEvent(options) {
+    const event = createHqEventEnvelope({
+      id: this.idFactory(),
+      type: options.type,
+      timestamp: options.timestamp ?? this.now(),
+      clientId: this.options.client.clientId,
+      projectId: this.options.project.projectId,
+      seq: ++this.seq,
+      payload: options.payload,
+      ...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {},
+      ...options.runId !== void 0 ? { runId: options.runId } : {}
+    });
+    this.sendFrame({ type: "client.event", event });
+    return event;
+  }
+  async publishMailboxSnapshot(mailbox, options) {
+    const payload = await createMailboxSnapshotPayloadFromMailbox(mailbox, {
+      ...options,
+      ...this.options.redactionPolicy !== void 0 ? { redactionPolicy: this.options.redactionPolicy } : {}
+    });
+    return this.publishEvent({
+      type: "mailbox.snapshot",
+      payload,
+      ...options.sessionId !== void 0 ? { sessionId: options.sessionId } : {},
+      ...options.timestamp !== void 0 ? { timestamp: options.timestamp } : {}
+    });
+  }
+  publishMailboxEvent(input) {
+    const payload = createMailboxEventPayload({
+      mailboxId: input.mailboxId,
+      action: input.action,
+      ...input.message !== void 0 ? { message: input.message } : {},
+      ...input.agent !== void 0 ? { agent: input.agent } : {},
+      ...input.summary !== void 0 ? { summary: input.summary } : {},
+      ...input.previewLength !== void 0 ? { previewLength: input.previewLength } : {},
+      ...this.options.redactionPolicy !== void 0 ? { redactionPolicy: this.options.redactionPolicy } : {}
+    });
+    return this.publishEvent({
+      type: "mailbox.event",
+      payload,
+      ...input.sessionId !== void 0 ? { sessionId: input.sessionId } : {},
+      ...input.timestamp !== void 0 ? { timestamp: input.timestamp } : {}
+    });
+  }
+  pollCommands() {
+    this.sendFrame({
+      type: "client.command_poll",
+      clientId: this.options.client.clientId,
+      projectId: this.options.project.projectId,
+      ...this.lastCommandId !== void 0 ? { afterCommandId: this.lastCommandId } : {},
+      limit: this.options.commandPollLimit ?? DEFAULT_COMMAND_POLL_LIMIT
+    });
+  }
+  ackCommand(result) {
+    this.sendFrame({
+      type: "client.command_ack",
+      clientId: this.options.client.clientId,
+      projectId: this.options.project.projectId,
+      commandId: result.commandId,
+      status: result.status,
+      ...result.message !== void 0 ? { message: result.message } : {}
+    });
+  }
+  sendHello() {
+    this.sendFrame({
+      type: "client.hello",
+      payload: {
+        protocolVersion: HQ_PROTOCOL_VERSION,
+        client: this.options.client,
+        project: this.options.project,
+        capabilities: this.capabilities
+      }
+    });
+  }
+  sendFrame(frame) {
+    const serialized = JSON.stringify(frame);
+    const socket = this.socket;
+    if (socket?.readyState === OPEN_STATE) {
+      socket.send(serialized);
+      return;
+    }
+    this.enqueue(serialized);
+    this.connect();
+  }
+  enqueue(serialized) {
+    if (this.queue.length >= this.maxQueuedMessages) this.queue.shift();
+    this.queue.push(serialized);
+  }
+  flushQueue() {
+    const socket = this.socket;
+    if (socket?.readyState !== OPEN_STATE) return;
+    const pending = this.queue;
+    this.queue = [];
+    for (const frame of pending) socket.send(frame);
+  }
+  startCommandPolling() {
+    if (this.options.onCommand === void 0 || this.commandPollTimer !== null) return;
+    this.commandPollTimer = setInterval(() => this.pollCommands(), this.options.commandPollIntervalMs ?? DEFAULT_COMMAND_POLL_INTERVAL_MS);
+  }
+  stopCommandPolling() {
+    if (this.commandPollTimer === null) return;
+    clearInterval(this.commandPollTimer);
+    this.commandPollTimer = null;
+  }
+  async handleServerMessage(event) {
+    const message = this.parseServerMessage(event);
+    if (message?.type !== "hq.command_batch") return;
+    await this.handleCommandBatch(message);
+  }
+  parseServerMessage(event) {
+    const data = this.extractMessageData(event);
+    if (data === null) return null;
+    try {
+      const parsed = JSON.parse(data);
+      if (parsed.type !== "hq.command_batch" || !Array.isArray(parsed.commands)) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  extractMessageData(event) {
+    const value = typeof event === "object" && event !== null && "data" in event ? event.data : event;
+    if (typeof value === "string") return value;
+    if (value instanceof ArrayBuffer) return new TextDecoder().decode(value);
+    if (ArrayBuffer.isView(value)) {
+      const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+      return new TextDecoder().decode(bytes);
+    }
+    return null;
+  }
+  async handleCommandBatch(message) {
+    const handler = this.options.onCommand;
+    if (handler === void 0) return;
+    for (const command of message.commands) {
+      this.lastCommandId = command.commandId;
+      try {
+        const result = await handler(command);
+        if (result !== void 0) this.ackCommand(result);
+        else if (command.requiresAck) this.ackCommand({ commandId: command.commandId, status: "accepted" });
+      } catch (err) {
+        this.ackCommand({
+          commandId: command.commandId,
+          status: "failed",
+          message: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  }
+  scheduleReconnect() {
+    if (this.stopped || !this.reconnect || this.reconnectTimer !== null) return;
+    const delay = Math.min(this.reconnectMaxMs, this.reconnectBaseMs * 2 ** this.reconnectAttempt);
+    this.reconnectAttempt += 1;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+};
+async function atomicWrite(targetPath, content, opts = {}) {
+  const dir = path3.dirname(targetPath);
+  await fsp.mkdir(dir, { recursive: true });
+  const tmp = path3.join(dir, `.${path3.basename(targetPath)}.${randomBytes(6).toString("hex")}.tmp`);
+  try {
+    if (typeof content === "string") {
+      await fsp.writeFile(tmp, content, { flag: "wx", encoding: opts.encoding ?? "utf8" });
+    } else {
+      await fsp.writeFile(tmp, content, { flag: "wx" });
+    }
+    try {
+      const fh = await fsp.open(tmp, "r+");
+      try {
+        await fh.sync();
+      } finally {
+        await fh.close();
+      }
+    } catch {
+    }
+    let mode;
+    try {
+      const stat3 = await fsp.stat(targetPath);
+      mode = stat3.mode & 511;
+    } catch {
+      mode = opts.mode;
+    }
+    if (mode !== void 0) {
+      await fsp.chmod(tmp, mode);
+    }
+    await renameWithRetry(tmp, targetPath);
+  } catch (err) {
+    try {
+      await fsp.unlink(tmp);
+    } catch {
+    }
+    throw err;
+  }
+}
+async function withFileLock(targetPath, fn, opts = {}) {
+  const dir = path3.dirname(targetPath);
+  await fsp.mkdir(dir, { recursive: true });
+  const lockPath = path3.join(dir, `.${path3.basename(targetPath)}.lock`);
+  const timeoutMs = opts.timeoutMs ?? 5e3;
+  const staleMs = opts.staleMs ?? 3e4;
+  const started = Date.now();
+  let handle;
+  for (; ; ) {
+    try {
+      handle = await fsp.open(lockPath, "wx");
+      await handle.writeFile(`${process.pid}:${Date.now()}`);
+      break;
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") {
+        await fsp.mkdir(dir, { recursive: true });
+        continue;
+      }
+      if (code !== "EEXIST") throw err;
+      try {
+        const stat3 = await fsp.stat(lockPath);
+        if (Date.now() - stat3.mtimeMs > staleMs) {
+          await fsp.unlink(lockPath);
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() - started >= timeoutMs) {
+        throw new Error(`Timed out waiting for file lock: ${targetPath}`);
+      }
+      await new Promise((resolve3) => setTimeout(resolve3, 25));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    try {
+      await handle?.close();
+    } catch {
+    }
+    try {
+      await fsp.unlink(lockPath);
+    } catch {
+    }
+  }
+}
+var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]);
+async function renameWithRetry(from, to) {
+  if (process.platform !== "win32") {
+    await fsp.rename(from, to);
+    return;
+  }
+  const delays = [10, 25, 60, 120, 250];
+  let lastErr;
+  for (let i = 0; i <= delays.length; i++) {
+    try {
+      await fsp.rename(from, to);
+      return;
+    } catch (err) {
+      lastErr = err;
+      const code = err?.code;
+      if (!code || !TRANSIENT_RENAME_CODES.has(code) || i === delays.length) {
+        throw err;
+      }
+      await new Promise((resolve3) => setTimeout(resolve3, delays[i]));
+    }
+  }
+  throw lastErr;
+}
+function wstackGlobalRoot() {
+  const fromEnv = process.env["WRONGSTACK_HOME"];
+  if (fromEnv && fromEnv.trim().length > 0) return path3.resolve(fromEnv);
+  return path3.join(os.homedir(), ".wrongstack");
+}
+
+// src/coordination/mailbox-types.ts
+function normalizeRecipient(to) {
+  return to.trim().toLowerCase() === "all" ? "*" : to.trim();
+}
+
+// src/coordination/global-mailbox.ts
+var MAILBOX_FILE = "_mailbox.jsonl";
+var CLIENT_REGISTRY_FILE = "_mailbox.clients.json";
+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 GlobalMailbox = class {
+  /** Path to the JSONL message file. */
+  messagePath;
+  /** Path to the JSON agent registry file. */
+  registryPath;
+  /** Path to the JSON client registry file. */
+  clientRegistryPath;
+  /** Optional event bus for emitting agent registration/heartbeat events. */
+  _events;
+  /** Optional HQ publisher for cross-project command-center telemetry. */
+  _hqPublisher;
+  /**
+   * 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
+   * whole point of GlobalMailbox), so a cache served forever would never see
+   * agents registered by other sessions. Writers always bypass it.
+   */
+  _registryCache = null;
+  /** When the registry cache was last refreshed from disk (epoch ms). */
+  _registryCacheAt = 0;
+  /**
+   * Local cache of the client registry to avoid re-reading on every call.
+   * Same reasoning as agent registry cache.
+   */
+  _clientRegistryCache = null;
+  /** When the client registry cache was last refreshed from disk (epoch ms). */
+  _clientRegistryCacheAt = 0;
+  /** Last time each local agent sent a heartbeat (throttle). */
+  _lastHeartbeat = /* @__PURE__ */ new Map();
+  /** Last time each local client sent a heartbeat (throttle). */
+  _lastClientHeartbeat = /* @__PURE__ */ new Map();
+  /**
+   * In-memory mirror of the JSONL message file. The mailbox is shared
+   * ACROSS PROCESSES, so reads cannot trust the cache blindly — we pair it
+   * with an mtime check. The file lock serializes every write, so a
+   * changed mtimeMs is a definitive signal that another process (or this
+   * one) wrote; an unchanged mtimeMs guarantees no write happened and the
+   * cache is current. This collapses the per-iteration `query()` cost from
+   * O(file_size) disk + parse to O(messages) in memory.
+   */
+  _messageCache = null;
+  /** mtimeMs of the file when `_messageCache` was populated. */
+  _messageCacheMtime = -1;
+  /** Size of the file when `_messageCache` was populated (extra guard). */
+  _messageCacheSize = -1;
+  /**
+   * @param projectDir — `~/.wrongstack/projects/<slug>/`
+   * @param events — optional EventBus for real-time TUI/WebUI notifications
+   * @param hqPublisher — optional HQ publisher for cross-project telemetry
+   */
+  constructor(projectDir, events, hqPublisher) {
+    this.messagePath = path3.join(projectDir, MAILBOX_FILE);
+    this.registryPath = path3.join(projectDir, "_mailbox.registry.json");
+    this.clientRegistryPath = path3.join(projectDir, CLIENT_REGISTRY_FILE);
+    this._events = events;
+    this._hqPublisher = hqPublisher;
+  }
+  get hqMailboxId() {
+    return `${path3.basename(path3.dirname(this.messagePath))}:mailbox`;
+  }
+  publishHqMailboxEvent(input) {
+    try {
+      this._hqPublisher?.publishMailboxEvent(input);
+    } catch {
+    }
+  }
+  publishHqMailboxSnapshot() {
+    if (this._hqPublisher === void 0) return;
+    void this._hqPublisher.publishMailboxSnapshot(this, { mailboxId: this.hqMailboxId }).catch(() => {
+    });
+  }
+  // ── Messages ────────────────────────────────────────────────────────────
+  async send(input) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const msg = {
+      id: randomUUID(),
+      from: input.from,
+      // "all" is an accepted spelling of the broadcast address — canonical
+      // form on disk is '*' so every query/checker matches it.
+      to: normalizeRecipient(input.to),
+      type: input.type,
+      subject: input.subject,
+      body: input.body,
+      priority: input.priority ?? "normal",
+      readBy: {},
+      completed: false,
+      timestamp: now,
+      replyTo: input.replyTo,
+      taskContext: input.taskContext
+    };
+    const line = JSON.stringify(msg) + LINE_SEPARATOR;
+    await fsp.mkdir(path3.dirname(this.messagePath), { recursive: true });
+    await withFileLock(this.messagePath, async () => {
+      await fsp.appendFile(this.messagePath, line, "utf8");
+      this._pushToCache(msg);
+    });
+    this.publishHqMailboxEvent({ mailboxId: this.hqMailboxId, action: "message.sent", message: msg });
+    this.publishHqMailboxSnapshot();
+    return msg;
+  }
+  async query(q) {
+    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];
+      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 (order !== null && (order[m.priority] ?? 1) < minPriorityRank) {
+        continue;
+      }
+      if (q.since !== void 0 && m.timestamp <= q.since) continue;
+      out.push(m);
+    }
+    out.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    return out.slice(0, limit).map((m) => ({ ...m, readBy: { ...m.readBy } }));
+  }
+  async ack(input) {
+    const updated = await this.ackMany({ acks: [input] });
+    return updated.length > 0 ? updated[0] : null;
+  }
+  async ackMany(input) {
+    if (input.acks.length === 0) return [];
+    const updated = [];
+    const byId = /* @__PURE__ */ new Map();
+    for (const a of input.acks) {
+      byId.set(a.messageId, a);
+    }
+    let cacheSnapshot = null;
+    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;
+        }
+      }
+      if (changed) {
+        const serialized = all.map((m) => JSON.stringify(m)).join(LINE_SEPARATOR) + LINE_SEPARATOR;
+        await fsp.writeFile(this.messagePath, serialized, "utf8");
+      }
+      cacheSnapshot = all;
+    });
+    if (cacheSnapshot) this._setMessageCache(cacheSnapshot);
+    for (const message of updated) {
+      this.publishHqMailboxEvent({
+        mailboxId: this.hqMailboxId,
+        action: message.completed ? "message.completed" : "message.read",
+        message
+      });
+    }
+    if (updated.length > 0) this.publishHqMailboxSnapshot();
+    return updated;
+  }
+  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++;
+      }
+    }
+    return count;
+  }
+  // ── Agent registry ──────────────────────────────────────────────────────
+  async registerAgent(input) {
+    await this._ensureRegistry();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const agent = {
+      agentId: input.agentId,
+      sessionId: input.sessionId,
+      name: input.name,
+      role: input.role,
+      status: "idle",
+      currentTool: void 0,
+      currentTask: void 0,
+      iterations: 0,
+      toolCalls: 0,
+      registeredAt: now,
+      lastSeenAt: now,
+      pid: input.pid,
+      source: input.source
+    };
+    await withFileLock(this.registryPath, async () => {
+      const registry = await this._readRegistry({ fresh: true });
+      this._pruneStaleInPlace(registry);
+      registry.set(input.agentId, agent);
+      this._registryCache = registry;
+      this._registryCacheAt = Date.now();
+      await this._writeRegistry(registry);
+    });
+    this._events?.emitCustom("mailbox.agent_registered", {
+      agentId: input.agentId,
+      sessionId: input.sessionId,
+      name: input.name,
+      role: input.role,
+      source: input.source
+    });
+    this.publishHqMailboxEvent({
+      mailboxId: this.hqMailboxId,
+      action: "agent.registered",
+      agent: {
+        agentId: input.agentId,
+        name: input.name,
+        ...input.role !== void 0 ? { role: input.role } : {},
+        sessionId: input.sessionId,
+        status: "idle",
+        iterations: 0,
+        toolCalls: 0,
+        lastActivityAt: now,
+        lastSeenAt: now,
+        online: true,
+        pid: input.pid,
+        ...input.source !== void 0 ? { source: input.source } : {}
+      }
+    });
+    this.publishHqMailboxSnapshot();
+  }
+  async heartbeat(input) {
+    const last = this._lastHeartbeat.get(input.agentId) ?? 0;
+    const now = Date.now();
+    if (now - last < HEARTBEAT_THROTTLE_MS) return;
+    this._lastHeartbeat.set(input.agentId, now);
+    await this._ensureRegistry();
+    await withFileLock(this.registryPath, async () => {
+      const registry = await this._readRegistry({ fresh: true });
+      this._pruneStaleInPlace(registry);
+      const agent = registry.get(input.agentId);
+      if (agent) {
+        const iso = (/* @__PURE__ */ new Date()).toISOString();
+        agent.lastSeenAt = iso;
+        if (input.status !== void 0) agent.status = input.status;
+        if (input.currentTool !== void 0) agent.currentTool = input.currentTool;
+        if (input.currentTask !== void 0) agent.currentTask = input.currentTask;
+        if (input.iterations !== void 0) agent.iterations = input.iterations;
+        if (input.toolCalls !== void 0) agent.toolCalls = input.toolCalls;
+      }
+      this._registryCache = registry;
+      this._registryCacheAt = Date.now();
+      await this._writeRegistry(registry);
+    });
+    this._events?.emitCustom("mailbox.agent_heartbeat", {
+      agentId: input.agentId,
+      status: input.status,
+      currentTool: input.currentTool,
+      currentTask: input.currentTask
+    });
+    this.publishHqMailboxEvent({
+      mailboxId: this.hqMailboxId,
+      action: "agent.heartbeat",
+      summary: input.agentId
+    });
+    this.publishHqMailboxSnapshot();
+  }
+  async getAgentStatuses() {
+    await this._ensureRegistry();
+    const registry = await this._readRegistry();
+    this._pruneStaleInPlace(registry);
+    const now = Date.now();
+    return Array.from(registry.values()).map((a) => ({
+      agentId: a.agentId,
+      name: a.name,
+      role: a.role,
+      sessionId: a.sessionId,
+      status: a.status,
+      currentTool: a.currentTool,
+      currentTask: a.currentTask,
+      iterations: a.iterations,
+      toolCalls: a.toolCalls,
+      lastActivityAt: a.lastSeenAt,
+      lastSeenAt: a.lastSeenAt,
+      online: now - new Date(a.lastSeenAt).getTime() < AGENT_STALE_MS,
+      pid: a.pid,
+      source: a.source
+    })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+  }
+  async getOnlineAgents() {
+    const all = await this.getAgentStatuses();
+    return all.filter((a) => a.online);
+  }
+  // ── Client registry ─────────────────────────────────────────────────────
+  async registerClient(input) {
+    await this._ensureClientRegistry();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const client = {
+      clientId: input.clientId,
+      sessionId: input.sessionId,
+      name: input.name,
+      source: input.source,
+      registeredAt: now,
+      lastSeenAt: now,
+      pid: input.pid
+    };
+    await withFileLock(this.clientRegistryPath, async () => {
+      const registry = await this._readClientRegistry({ fresh: true });
+      this._pruneStaleClientsInPlace(registry);
+      registry.set(input.clientId, client);
+      this._clientRegistryCache = registry;
+      this._clientRegistryCacheAt = Date.now();
+      await this._writeClientRegistry(registry);
+    });
+    this._events?.emitCustom("mailbox.client_registered", {
+      clientId: input.clientId,
+      sessionId: input.sessionId,
+      name: input.name,
+      source: input.source
+    });
+  }
+  async clientHeartbeat(input) {
+    const last = this._lastClientHeartbeat.get(input.clientId) ?? 0;
+    const now = Date.now();
+    if (now - last < HEARTBEAT_THROTTLE_MS) return;
+    this._lastClientHeartbeat.set(input.clientId, now);
+    await this._ensureClientRegistry();
+    await withFileLock(this.clientRegistryPath, async () => {
+      const registry = await this._readClientRegistry({ fresh: true });
+      this._pruneStaleClientsInPlace(registry);
+      const client = registry.get(input.clientId);
+      if (client) {
+        client.lastSeenAt = (/* @__PURE__ */ new Date()).toISOString();
+      }
+      this._clientRegistryCache = registry;
+      this._clientRegistryCacheAt = Date.now();
+      await this._writeClientRegistry(registry);
+    });
+    this._events?.emitCustom("mailbox.client_heartbeat", {
+      clientId: input.clientId
+    });
+  }
+  async getClientStatuses() {
+    await this._ensureClientRegistry();
+    const registry = await this._readClientRegistry();
+    this._pruneStaleClientsInPlace(registry);
+    const now = Date.now();
+    return Array.from(registry.values()).map((c) => ({
+      clientId: c.clientId,
+      name: c.name,
+      source: c.source,
+      sessionId: c.sessionId,
+      lastSeenAt: c.lastSeenAt,
+      online: now - new Date(c.lastSeenAt).getTime() < CLIENT_STALE_MS,
+      pid: c.pid
+    })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+  }
+  // ── Lifecycle ───────────────────────────────────────────────────────────
+  async close() {
+    this._registryCache = null;
+    this._clientRegistryCache = null;
+    this._messageCache = null;
+    this._messageCacheMtime = -1;
+    this._messageCacheSize = -1;
+  }
+  async clearAll() {
+    await withFileLock(this.messagePath, async () => {
+      await fsp.writeFile(this.messagePath, "", "utf8");
+    });
+    this._setMessageCache([]);
+  }
+  async purgeStale(opts) {
+    const COMPLETED_MAX_AGE_MS = opts?.completedMaxAgeMs ?? 864e5;
+    const INCOMPLETE_MAX_AGE_MS = opts?.incompleteMaxAgeMs ?? 6048e5;
+    let completedPurged = 0;
+    let incompletePurged = 0;
+    let remaining = 0;
+    await withFileLock(this.messagePath, async () => {
+      const all = await this._readMessagesFresh();
+      const now = Date.now();
+      const cutoffCompleted = now - COMPLETED_MAX_AGE_MS;
+      const cutoffIncomplete = now - INCOMPLETE_MAX_AGE_MS;
+      const kept = [];
+      for (const msg of all) {
+        const msgTime = new Date(msg.timestamp).getTime();
+        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");
+      }
+      this._setMessageCache(kept);
+    });
+    return {
+      completedPurged,
+      incompletePurged,
+      totalPurged: completedPurged + incompletePurged,
+      remaining
+    };
+  }
+  // ── Internal ────────────────────────────────────────────────────────────
+  /**
+   * Read all messages from the JSONL file. Always reads + parses the file.
+   * Callers that can tolerate a stale-by-mtime view should use
+   * {@link _readMessagesCached}; writers that need the post-lock truth
+   * should call this directly (it's what {@link _readMessagesFresh} aliases).
+   */
+  async _readMessages() {
+    try {
+      const raw = await fsp.readFile(this.messagePath, "utf8");
+      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 {
+        }
+      }
+      return messages;
+    } catch (err) {
+      if (err.code === "ENOENT") return [];
+      throw err;
+    }
+  }
+  /**
+   * Read messages, then adopt the result as the in-memory cache. Use this
+   * from writers that just took the file lock — the read reflects the
+   * authoritative post-lock state and should be served to subsequent
+   * queries without re-reading.
+   */
+  async _readMessagesFresh() {
+    const all = await this._readMessages();
+    this._setMessageCache(all);
+    return all;
+  }
+  /**
+   * Read messages, consulting the mtime-bounded in-memory cache first.
+   * The mailbox file is shared across processes; every `send`/`ack`/
+   * `clearAll`/`purgeStale` takes the file lock, so writes are serialized
+   * and a changed mtimeMs is a definitive freshness signal. When the
+   * stat matches the cached mtime+size we return the cached array — no
+   * file read and no JSON.parse — collapsing the per-iteration query
+   * cost on the mailbox-loop hot path.
+   */
+  async _readMessagesCached() {
+    try {
+      const st = await fsp.stat(this.messagePath);
+      if (this._messageCache !== null && this._messageCacheMtime === st.mtimeMs && this._messageCacheSize === st.size) {
+        return this._messageCache;
+      }
+      const all = await this._readMessages();
+      this._setMessageCache(all, st.mtimeMs, st.size);
+      return all;
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        this._setMessageCache([], -1, -1);
+        return [];
+      }
+      throw err;
+    }
+  }
+  /**
+   * Replace the in-memory cache. Caller is responsible for guaranteeing
+   * that `messages` reflects the current on-disk state (e.g. they just
+   * read or wrote it under the file lock).
+   */
+  _setMessageCache(messages, mtime, size) {
+    if (messages.length > MESSAGE_CACHE_MAX_ENTRIES) {
+      this._messageCache = null;
+      this._messageCacheMtime = -1;
+      this._messageCacheSize = -1;
+      return;
+    }
+    this._messageCache = messages;
+    if (mtime !== void 0 && size !== void 0) {
+      this._messageCacheMtime = mtime;
+      this._messageCacheSize = size;
+    } else {
+      void fsp.stat(this.messagePath).then((st) => {
+        this._messageCacheMtime = st.mtimeMs;
+        this._messageCacheSize = st.size;
+      }).catch(() => {
+      });
+    }
+  }
+  /**
+   * Append a single just-sent message to the in-memory cache without
+   * re-reading the file. The caller must hold the file lock (or have
+   * just released it after a successful append) so the cache stays
+   * consistent with on-disk state.
+   */
+  _pushToCache(msg) {
+    if (this._messageCache === null) return;
+    if (this._messageCache.length >= MESSAGE_CACHE_MAX_ENTRIES) {
+      this._messageCache = null;
+      this._messageCacheMtime = -1;
+      this._messageCacheSize = -1;
+      return;
+    }
+    this._messageCache.push(msg);
+  }
+  async _ensureRegistry() {
+    await fsp.mkdir(path3.dirname(this.registryPath), { recursive: true });
+  }
+  async _readRegistry(opts) {
+    if (!opts?.fresh && this._registryCache && Date.now() - this._registryCacheAt < REGISTRY_CACHE_TTL_MS) {
+      return new Map(this._registryCache);
+    }
+    try {
+      const raw = await fsp.readFile(this.registryPath, "utf8");
+      const data = JSON.parse(raw);
+      const map = /* @__PURE__ */ new Map();
+      for (const [id, agent] of Object.entries(data)) {
+        map.set(id, agent);
+      }
+      this._registryCache = map;
+      this._registryCacheAt = Date.now();
+      return new Map(map);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        const empty = /* @__PURE__ */ new Map();
+        this._registryCache = empty;
+        this._registryCacheAt = Date.now();
+        return empty;
+      }
+      throw err;
+    }
+  }
+  _pruneStaleInPlace(registry) {
+    const cutoff = Date.now() - AGENT_STALE_MS;
+    for (const agent of registry.values()) {
+      if (new Date(agent.lastSeenAt).getTime() < cutoff) {
+        agent.status = "idle";
+      }
+    }
+  }
+  async _writeRegistry(registry) {
+    const obj = {};
+    for (const [id, agent] of registry) {
+      obj[id] = agent;
+    }
+    const tmp = `${this.registryPath}.${randomUUID().slice(0, 8)}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(obj, null, 2), "utf8");
+    await fsp.rename(tmp, this.registryPath);
+  }
+  // ── Client registry internals ───────────────────────────────────────────
+  async _ensureClientRegistry() {
+    await fsp.mkdir(path3.dirname(this.clientRegistryPath), { recursive: true });
+  }
+  async _readClientRegistry(opts) {
+    if (!opts?.fresh && this._clientRegistryCache && Date.now() - this._clientRegistryCacheAt < REGISTRY_CACHE_TTL_MS) {
+      return new Map(this._clientRegistryCache);
+    }
+    try {
+      const raw = await fsp.readFile(this.clientRegistryPath, "utf8");
+      const data = JSON.parse(raw);
+      const map = /* @__PURE__ */ new Map();
+      for (const [id, client] of Object.entries(data)) {
+        map.set(id, client);
+      }
+      this._clientRegistryCache = map;
+      this._clientRegistryCacheAt = Date.now();
+      return new Map(map);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        const empty = /* @__PURE__ */ new Map();
+        this._clientRegistryCache = empty;
+        this._clientRegistryCacheAt = Date.now();
+        return empty;
+      }
+      throw err;
+    }
+  }
+  _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();
+      }
+    }
+  }
+  async _writeClientRegistry(registry) {
+    const obj = {};
+    for (const [id, client] of registry) {
+      obj[id] = client;
+    }
+    const tmp = `${this.clientRegistryPath}.${randomUUID().slice(0, 8)}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(obj, null, 2), "utf8");
+    await fsp.rename(tmp, this.clientRegistryPath);
+  }
+};
+var HQ_AUTH_FILE_VERSION = 1;
+function defaultHqDataDir() {
+  return path3.join(wstackGlobalRoot(), "hq");
+}
+function resolveHqDataDir(override, env = process.env) {
+  const raw = override ?? env["WRONGSTACK_HQ_DATA_DIR"]?.trim();
+  if (!raw) return defaultHqDataDir();
+  return path3.isAbsolute(raw) ? path3.resolve(raw) : path3.resolve(process.cwd(), raw);
+}
+function emptyHqAuthFile() {
+  return {
+    version: HQ_AUTH_FILE_VERSION,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function hqAuthFilePath(dataDir) {
+  return path3.join(dataDir, "auth.json");
+}
+async function readHqAuthFile(dataDir, opts = {}) {
+  const file = hqAuthFilePath(dataDir);
+  let raw;
+  try {
+    raw = await fsp.readFile(file, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return emptyHqAuthFile();
+    opts.warn?.(`HQ auth file read failed at ${file}: ${err.message}`);
+    return emptyHqAuthFile();
+  }
+  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;
+  } catch (err) {
+    opts.warn?.(`HQ auth file at ${file} is not valid JSON; ignoring stored policy/tokens: ${err.message}`);
+    return emptyHqAuthFile();
+  }
+}
+async function writeHqAuthFile(dataDir, file) {
+  const target = hqAuthFilePath(dataDir);
+  const payload = {
+    ...file,
+    version: HQ_AUTH_FILE_VERSION,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await atomicWrite(target, `${JSON.stringify(payload, null, 2)}
+`, { mode: 384 });
+}
+async function ensureHqFirstRunAuthFile(dataDir, opts = {}) {
+  const file = hqAuthFilePath(dataDir);
+  try {
+    await fsp.access(file);
+    return { authFile: await readHqAuthFile(dataDir, opts), created: false };
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      opts.warn?.(`HQ auth file access failed at ${file}: ${err.message}`);
+      return { authFile: await readHqAuthFile(dataDir, opts), created: false };
+    }
+  }
+  const browserToken = mintHqToken("first-run browser");
+  const clientToken = mintHqToken("first-run client");
+  const authFile = {
+    version: HQ_AUTH_FILE_VERSION,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    browserTokens: [browserToken],
+    clientTokens: [clientToken]
+  };
+  await writeHqAuthFile(dataDir, authFile);
+  return { authFile: await readHqAuthFile(dataDir, opts), created: true, browserToken, clientToken };
+}
+async function mutateHqAuthFile(dataDir, mutator, opts = {}) {
+  const current = await readHqAuthFile(dataDir, opts);
+  const next = await mutator(current);
+  await writeHqAuthFile(dataDir, next);
+  return next;
+}
+function mintHqToken(label) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    id: randomUUID(),
+    token: randomUUID().replace(/-/g, "") + randomUUID().replace(/-/g, ""),
+    ...label ? { label } : {},
+    createdAt: now
+  };
+}
+var mintHqBrowserToken = mintHqToken;
+function watchHqAuthFile(dataDir, onChange, opts = {}) {
+  const file = hqAuthFilePath(dataDir);
+  const debounceMs = opts.debounceMs ?? 200;
+  let timer;
+  let closed = false;
+  let watcher;
+  try {
+    watcher = syncFs.watch(path3.dirname(file), { recursive: false });
+  } catch (err) {
+    opts.warn?.(`HQ auth watcher could not start: ${err.message}`);
+    return { close: () => {
+    } };
+  }
+  const trigger = () => {
+    if (closed) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = void 0;
+      const readOpts = opts.warn ? { warn: opts.warn } : {};
+      void readHqAuthFile(dataDir, readOpts).then(
+        (next) => {
+          if (!closed) onChange(next);
+        },
+        () => {
+        }
+      );
+    }, debounceMs);
+  };
+  watcher.on("change", (eventType, filename) => {
+    const name = typeof filename === "string" ? filename : "";
+    if (eventType === "rename" || eventType === "change") {
+      if (!name || name === "auth.json" || name === path3.basename(file)) {
+        trigger();
+      }
+    }
+  });
+  watcher.on("error", (err) => {
+    opts.warn?.(`HQ auth watcher error: ${err.message}`);
+  });
+  return {
+    close: () => {
+      closed = true;
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    }
+  };
+}
+
+// src/hq/factory.ts
+function readFirstClientTokenFromAuthFile(dataDir) {
+  try {
+    const raw = syncFs.readFileSync(hqAuthFilePath(dataDir), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.clientTokens?.find((t) => t.token.trim().length > 0)?.token;
+  } catch {
+    return void 0;
+  }
+}
+function resolveHqConfigFromEnv(env = process.env) {
+  return resolveHqConfig({ env });
+}
+function resolveHqConfig(options = {}) {
+  const env = options.env ?? process.env;
+  const fileConfig = options.config;
+  const envUrl = env["WRONGSTACK_HQ_URL"]?.trim();
+  const envToken = env["WRONGSTACK_HQ_TOKEN"]?.trim();
+  const configUrl = fileConfig?.url?.trim();
+  const configToken = fileConfig?.token?.trim();
+  const envEnabledRaw = env["WRONGSTACK_HQ_ENABLED"]?.trim();
+  const enabled = envEnabledRaw !== void 0 && envEnabledRaw.length > 0 ? envEnabledRaw !== "0" : fileConfig?.enabled;
+  const dataDir = resolveHqDataDir(fileConfig?.dataDir, env);
+  const token = envToken || configToken || readFirstClientTokenFromAuthFile(dataDir);
+  const url = envUrl || configUrl;
+  if (!url) {
+    if (enabled === false) return void 0;
+    if (enabled === true || token) {
+      return {
+        url: "http://localhost:3499",
+        enabled: true,
+        ...token ? { token } : {}
+      };
+    }
+    return void 0;
+  }
+  const rawContentEnv = env["WRONGSTACK_HQ_RAW_CONTENT"]?.trim();
+  const projectAliasEnv = env["WRONGSTACK_HQ_PROJECT_ALIAS"]?.trim();
+  return {
+    url,
+    ...token ? { token } : {},
+    ...enabled !== void 0 ? { enabled } : {},
+    ...rawContentEnv ? { rawContent: rawContentEnv === "1" } : fileConfig?.rawContent !== void 0 ? { rawContent: fileConfig.rawContent } : {},
+    ...projectAliasEnv ? { projectAlias: projectAliasEnv } : fileConfig?.projectAlias ? { projectAlias: fileConfig.projectAlias } : {}
+  };
+}
+function stableMachineId() {
+  return createHash("sha256").update(`${hostname()}:${process.pid}`).digest("hex").slice(0, 12);
+}
+function deriveProjectId(projectRoot) {
+  return createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+}
+function createHqPublisherFromEnv(options) {
+  const config = options.config ?? resolveHqConfig({ config: options.appConfig?.hq });
+  if (!config || config.enabled === false) return void 0;
+  const machineId = options.machineId ?? stableMachineId();
+  const host = options.hostnameOverride ?? hostname();
+  const projectName = options.projectName ?? config.projectAlias ?? (basename(options.projectRoot) || "unknown");
+  const client = {
+    clientId: `${machineId}:${options.clientKind}:${process.pid}`,
+    kind: options.clientKind,
+    machineId,
+    ...host ? { hostname: host } : {},
+    pid: process.pid,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const project = {
+    projectId: deriveProjectId(options.projectRoot),
+    projectRoot: options.projectRoot,
+    projectName,
+    machineId,
+    workspaceKind: "git"
+  };
+  const redactionPolicy = options.redactionPolicy || config.rawContent !== void 0 ? {
+    ...config.rawContent !== void 0 ? { rawContent: config.rawContent } : {},
+    ...options.redactionPolicy ?? {}
+  } : void 0;
+  return new HqPublisher({
+    url: config.url,
+    ...config.token ? { token: config.token } : {},
+    client,
+    project,
+    ...options.socketFactory ? { socketFactory: options.socketFactory } : {},
+    ...redactionPolicy !== void 0 ? { redactionPolicy } : {}
+  });
+}
+function createGlobalMailbox(options) {
+  return new GlobalMailbox(options.projectDir, options.events, options.hqPublisher);
+}
+
+export { DEFAULT_HQ_REDACTION_POLICY, HQ_AUTH_FILE_VERSION, HQ_PROTOCOL_VERSION, HqPublisher, createGlobalMailbox, createHqEventEnvelope, createHqPublisherFromEnv, createMailboxEventPayload, createMailboxSnapshotPayload, createMailboxSnapshotPayloadFromMailbox, defaultHqDataDir, emptyHqAuthFile, ensureHqFirstRunAuthFile, hqAuthFilePath, mapMailboxAgentToHqSummary, mapMailboxMessageToHqSummary, mintHqBrowserToken, mintHqToken, mutateHqAuthFile, parseHqEventPayload, parseHqFrame, readHqAuthFile, redactHqEvent, redactHqValue, resolveHqConfig, resolveHqConfigFromEnv, resolveHqDataDir, scrubAndTruncateHqPreview, summarizeHqToolArgs, watchHqAuthFile, writeHqAuthFile };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map