@wrongstack/core 0.313.0 → 0.316.1

package/dist/chunk-NIOAGFPB.js

@@ -0,0 +1,1510 @@
+import {
+  DEFAULT_HQ_REDACTION_POLICY,
+  HQ_PROTOCOL_VERSION,
+  HQ_TRANSCRIPT_TEXT_CAP,
+  createHqEventEnvelope
+} from "./chunk-Z2IJUO45.js";
+import {
+  SESSION_RECIPIENT_PREFIX
+} from "./chunk-FWNLEZYG.js";
+import {
+  DefaultSecretScrubber
+} from "./chunk-QSTSJOCK.js";
+import {
+  SECRET_FILE_MODE,
+  restrictFilePermissions
+} from "./chunk-6FHWXLPT.js";
+import {
+  readProjectIdentitySync
+} from "./chunk-HI3JGZR2.js";
+import {
+  isPidAlive
+} from "./chunk-TRT2HRWZ.js";
+import {
+  atomicWrite
+} from "./chunk-OSGLYW5J.js";
+import {
+  wstackGlobalRoot
+} from "./chunk-SAFHACFA.js";
+
+// src/hq/auth-audit.ts
+import { appendFileSync, readFileSync, mkdirSync } from "node:fs";
+import * as path from "node:path";
+function hqAuthAuditPath(dataDir) {
+  return path.join(dataDir, "auth-audit.jsonl");
+}
+function readHqAuthAuditTail(dataDir, maxEntries = 50) {
+  const filePath = hqAuthAuditPath(dataDir);
+  let content;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch {
+    return [];
+  }
+  const lines = content.trimEnd().split("\n");
+  const tail = lines.slice(-maxEntries);
+  const entries = [];
+  for (const line of tail) {
+    if (!line) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return entries.reverse();
+}
+function appendHqAuthAudit(dataDir, entry, options) {
+  try {
+    mkdirSync(dataDir, { recursive: true });
+    const line = `${JSON.stringify(entry)}
+`;
+    appendFileSync(hqAuthAuditPath(dataDir), line, { encoding: "utf8", flag: "a" });
+  } catch (err) {
+    options?.onError?.(err instanceof Error ? err : new Error(String(err)));
+  }
+}
+function logHqAuthAudit(dataDir, partial, options) {
+  const at = partial.at ?? (options?.now?.() ?? Date.now());
+  const { at: _omit, ...rest } = partial;
+  void _omit;
+  appendHqAuthAudit(dataDir, { at, ...rest }, options);
+}
+
+// src/hq/auth-store.ts
+import { createHash, randomBytes, randomUUID, scrypt, timingSafeEqual } from "node:crypto";
+import * as syncFs from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path2 from "node:path";
+var HQ_AUTH_FILE_VERSION = 1;
+function defaultHqDataDir() {
+  return path2.join(wstackGlobalRoot(), "hq");
+}
+function resolveHqDataDir(override, env = process.env) {
+  const raw = override ?? env["WRONGSTACK_HQ_DATA_DIR"]?.trim();
+  if (!raw) return defaultHqDataDir();
+  return path2.isAbsolute(raw) ? path2.resolve(raw) : path2.resolve(process.cwd(), raw);
+}
+function hqTokenVerifier(secret) {
+  return createHash("sha256").update(secret, "utf8").digest("hex");
+}
+function hqTokenKey(token) {
+  if (token.verifier !== void 0 && token.verifier.length > 0) return token.verifier;
+  return token.token ? hqTokenVerifier(token.token) : "";
+}
+function hashBrowserToken(token) {
+  if (token.verifier !== void 0 && token.verifier.length > 0) {
+    return token.token ? { ...token, token: "" } : token;
+  }
+  if (!token.token) return token;
+  return { ...token, verifier: hqTokenVerifier(token.token), token: "" };
+}
+function isTokenExpired(token, at = Date.now(), clockSkewMs = 0) {
+  if (token === void 0) return false;
+  const expiresAt = token.expiresAt;
+  if (expiresAt === void 0) return false;
+  const parsed = Date.parse(expiresAt);
+  if (!Number.isFinite(parsed)) return false;
+  return at >= parsed - Math.max(0, clockSkewMs);
+}
+function tokenHasCapability(token, capability, clockSkewMs = 0) {
+  if (token === void 0) return false;
+  if (isTokenExpired(token, Date.now(), clockSkewMs)) return false;
+  if (token.capabilities === void 0) return true;
+  return token.capabilities.includes(capability);
+}
+function emptyHqAuthFile() {
+  return {
+    version: HQ_AUTH_FILE_VERSION,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+var HQ_AUTH_CONTENT_HASH_REDACTED = "<redacted>";
+function hqAuthContentHash(file) {
+  const REDACTED = HQ_AUTH_CONTENT_HASH_REDACTED;
+  const redactToken = (t) => ({ ...t, token: REDACTED });
+  try {
+    const projection = {
+      version: file.version,
+      updatedAt: file.updatedAt,
+      ...file.redactionPolicy !== void 0 ? { redactionPolicy: file.redactionPolicy } : {},
+      ...file.browserTokens !== void 0 ? { browserTokens: file.browserTokens.map(redactToken) } : {},
+      ...file.clientTokens !== void 0 ? { clientTokens: file.clientTokens.map(redactToken) } : {},
+      ...file.passwordHash !== void 0 ? { passwordHash: REDACTED } : {},
+      ...file.cookieSecret !== void 0 ? { cookieSecret: REDACTED } : {},
+      ...file.totpSecret !== void 0 ? { totpSecret: REDACTED } : {},
+      ...file.totpPendingSecret !== void 0 ? { totpPendingSecret: REDACTED } : {},
+      ...file.totpRecoveryCodes !== void 0 ? { totpRecoveryCodes: file.totpRecoveryCodes.map(() => REDACTED) } : {},
+      ...file.totpLastUsedCounter !== void 0 ? { totpLastUsedCounter: file.totpLastUsedCounter } : {},
+      ...file.alertRules !== void 0 ? { alertRules: file.alertRules } : {}
+    };
+    const payload = JSON.stringify(projection);
+    return createHash("sha256").update(payload).digest("hex");
+  } catch {
+    return void 0;
+  }
+}
+function hqAuthFilePath(dataDir) {
+  return path2.join(dataDir, "auth.json");
+}
+function hqRuntimeFilePath(dataDir) {
+  return path2.join(dataDir, "runtime.json");
+}
+async function writeHqRuntimeFile(dataDir, file) {
+  const payload = {
+    ...file,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const target = hqRuntimeFilePath(dataDir);
+  await atomicWrite(target, `${JSON.stringify(payload, null, 2)}
+`, { mode: SECRET_FILE_MODE });
+  await restrictFilePermissions(target, { label: "hq-runtime" });
+}
+function readHqRuntimeFileSync(dataDir) {
+  try {
+    const parsed = JSON.parse(
+      syncFs.readFileSync(hqRuntimeFilePath(dataDir), "utf8")
+    );
+    if (typeof parsed.url !== "string" || parsed.url.trim().length === 0) return void 0;
+    if (typeof parsed.pid === "number" && !isPidAlive(parsed.pid)) return void 0;
+    return {
+      url: parsed.url,
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : "",
+      ...typeof parsed.pid === "number" ? { pid: parsed.pid } : {}
+    };
+  } catch {
+    return void 0;
+  }
+}
+async function readHqAuthFile(dataDir, _opts = {}) {
+  const file = hqAuthFilePath(dataDir);
+  let raw;
+  try {
+    raw = await fs.readFile(file, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") 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 {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    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);
+  const payload = {
+    ...file,
+    version: HQ_AUTH_FILE_VERSION,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    // WS-044: browser secrets never touch the disk. Any legacy cleartext in
+    // the incoming file is converted here, so the first write after an
+    // upgrade migrates the whole list — no separate migration step to forget
+    // to run, and no window where an old file stays cleartext because nothing
+    // happened to rewrite it.
+    ...file.browserTokens !== void 0 ? { browserTokens: file.browserTokens.map(hashBrowserToken) } : {}
+  };
+  await atomicWrite(target, `${JSON.stringify(payload, null, 2)}
+`, { mode: SECRET_FILE_MODE });
+  await restrictFilePermissions(target, { label: "hq-auth" });
+}
+async function ensureHqFirstRunAuthFile(dataDir, opts = {}) {
+  const file = hqAuthFilePath(dataDir);
+  try {
+    await fs.access(file);
+    const existing = await readHqAuthFile(dataDir, opts);
+    if (opts.password) {
+      const passwordUnchanged = existing.passwordHash !== void 0 && await verifyHqPassword(opts.password, existing.passwordHash);
+      if (!passwordUnchanged) {
+        const authFile2 = {
+          ...existing,
+          passwordHash: await hashHqPassword(opts.password),
+          // Rotating the cookie secret invalidates sessions created with the
+          // previous password. This matters when --password is used to
+          // recover or deliberately change an existing HQ installation.
+          cookieSecret: mintHqCookieSecret()
+        };
+        await writeHqAuthFile(dataDir, authFile2);
+        const persisted2 = await readHqAuthFile(dataDir, opts);
+        const hash2 = hqAuthContentHash(persisted2);
+        const actorField2 = opts.actor ? { actor: opts.actor } : {};
+        logHqAuthAudit(
+          dataDir,
+          {
+            kind: "password-rotate",
+            scope: "browser",
+            tokenId: "(password-rotation)",
+            ...hash2 !== void 0 ? { contentHash: hash2 } : {},
+            ...actorField2
+          },
+          {
+            onError: (err) => opts.warn?.(`HQ password-rotate audit write failed: ${err.message}`)
+          }
+        );
+        return { authFile: persisted2, created: false };
+      }
+    }
+    return { authFile: existing, 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({ label: "first-run browser", ttlMs: opts.tokenTtlMs }),
+    capabilities: ["control.enqueue"]
+  };
+  const clientToken = {
+    ...mintHqToken({ label: "first-run client", ttlMs: opts.tokenTtlMs }),
+    capabilities: ["telemetry.publish"]
+  };
+  const authFile = {
+    version: HQ_AUTH_FILE_VERSION,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    browserTokens: [browserToken],
+    clientTokens: [clientToken]
+  };
+  if (opts.password) {
+    authFile.passwordHash = await hashHqPassword(opts.password);
+    authFile.cookieSecret = mintHqCookieSecret();
+  }
+  await writeHqAuthFile(dataDir, authFile);
+  const persisted = await readHqAuthFile(dataDir, opts);
+  const hash = hqAuthContentHash(persisted);
+  const hashField = hash !== void 0 ? { contentHash: hash } : {};
+  const actorField = opts.actor ? { actor: opts.actor } : {};
+  for (const [scope, token] of [
+    ["browser", browserToken],
+    ["client", clientToken]
+  ]) {
+    logHqAuthAudit(
+      dataDir,
+      {
+        kind: "first-run",
+        scope,
+        tokenId: token.id,
+        ...hashField,
+        ...token.label ? { label: token.label } : {},
+        capabilities: token.capabilities,
+        ...token.expiresAt ? { expiresAt: token.expiresAt } : {},
+        ...actorField
+      },
+      {
+        onError: (err) => opts.warn?.(`HQ first-run audit write failed: ${err.message}`)
+      }
+    );
+  }
+  return { authFile: persisted, 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;
+}
+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((resolve2, reject) => {
+    const salt = randomBytes(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")}`;
+      resolve2(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((resolve2, reject) => {
+    scrypt(password, salt, expected.length, HQ_PASSWORD_SCRYPT_PARAMS, (err, key) => {
+      if (err) reject(err);
+      else resolve2(key);
+    });
+  });
+  return timingSafeEqual(derived, expected);
+}
+function mintHqCookieSecret() {
+  return randomBytes(32).toString("base64url");
+}
+function mintHqToken(labelOrOptions) {
+  const opts = typeof labelOrOptions === "string" ? { label: labelOrOptions } : labelOrOptions ?? {};
+  const at = opts.now ?? Date.now();
+  const createdAtIso = new Date(at).toISOString();
+  return {
+    id: randomUUID(),
+    token: randomUUID().replace(/-/g, "") + randomUUID().replace(/-/g, ""),
+    createdAt: createdAtIso,
+    ...opts.label ? { label: opts.label } : {},
+    ...opts.ttlMs !== void 0 && Number.isFinite(opts.ttlMs) && opts.ttlMs > 0 ? { expiresAt: new Date(at + opts.ttlMs).toISOString() } : {}
+  };
+}
+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(path2.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("error", (err) => {
+    opts.warn?.(`HQ auth watcher error: ${err.message}`);
+    try {
+      watcher.close();
+    } catch {
+    }
+  });
+  watcher.on("change", (eventType, filename) => {
+    const name = typeof filename === "string" ? filename : "";
+    if (eventType === "rename" || eventType === "change") {
+      if (!name || name === "auth.json" || name === path2.basename(file)) {
+        trigger();
+      }
+    }
+  });
+  return {
+    close: () => {
+      closed = true;
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    }
+  };
+}
+
+// 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",
+  "text",
+  "partialText",
+  "assistantMessage",
+  "userMessage",
+  "stdout",
+  "stderr",
+  "output",
+  "toolInput",
+  "toolOutput",
+  "outputSummary",
+  "body",
+  "mailboxBody",
+  "messageBody",
+  "outcome",
+  "fileContent",
+  "diff",
+  "patch",
+  "transcript",
+  "logs"
+]);
+var HQ_PROJECT_STATE_EVENT_TYPES = /* @__PURE__ */ new Set(["kanban.snapshot"]);
+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 resolveHqRedactionPolicy(policy) {
+  return {
+    ...DEFAULT_HQ_REDACTION_POLICY,
+    ...policy
+  };
+}
+function tightenHqRedactionPolicy(publisherPolicy, operatorPolicy) {
+  if (operatorPolicy === void 0) return publisherPolicy;
+  const toolRank = {
+    none: 0,
+    summary: 1,
+    redacted: 2,
+    full: 3
+  };
+  const pathRank = {
+    none: 0,
+    redacted: 0,
+    "project-relative": 1,
+    full: 2
+  };
+  const requestedToolArgs = operatorPolicy.toolArgs;
+  const requestedPaths = operatorPolicy.paths;
+  return {
+    rawContent: publisherPolicy.rawContent && (operatorPolicy.rawContent === void 0 || operatorPolicy.rawContent),
+    toolArgs: requestedToolArgs !== void 0 && toolRank[requestedToolArgs] < toolRank[publisherPolicy.toolArgs] ? requestedToolArgs : publisherPolicy.toolArgs,
+    paths: requestedPaths !== void 0 && pathRank[requestedPaths] < pathRank[publisherPolicy.paths] ? requestedPaths : publisherPolicy.paths
+  };
+}
+function isPlainObject(value) {
+  return Object.prototype.toString.call(value) === "[object Object]";
+}
+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 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, scrub) {
+  const scrubbed = scrub ? defaultScrubber.scrub(value) : value;
+  if (scrubbed.length <= maxSummaryLength) return scrubbed;
+  return `${scrubbed.slice(0, maxSummaryLength)}\u2026[truncated:${scrubbed.length - maxSummaryLength}]`;
+}
+function scrubAndTruncateHqPreview(value, maxLength = 280) {
+  if (typeof value !== "string" || value.length === 0) return void 0;
+  return summarizeString(value, maxLength, true);
+}
+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.preserveRawContentKeys && !options.policy.rawContent && key !== void 0 && isRawContentKey(key)) {
+      return { value: RAW_CONTENT_REPLACEMENT, redacted: true };
+    }
+    const scrubbed = summarizeString(value, options.maxSummaryLength, true);
+    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 redactHqValueInternal(value, options, preserveRawContentKeys) {
+  const result = visitValue(value, {
+    policy: resolveHqRedactionPolicy(options.policy),
+    ...options.projectRoot !== void 0 ? { projectRoot: options.projectRoot } : {},
+    maxSummaryLength: options.maxSummaryLength ?? 500,
+    preserveRawContentKeys,
+    seen: /* @__PURE__ */ new WeakSet()
+  });
+  return { value: result.value, redacted: result.redacted };
+}
+function redactHqValue(value, options = {}) {
+  return redactHqValueInternal(value, options, false);
+}
+function redactHqEventPayload(type, payload, options = {}) {
+  return redactHqValueInternal(payload, options, HQ_PROJECT_STATE_EVENT_TYPES.has(type));
+}
+function redactHqEvent(event, options = {}) {
+  const payload = redactHqEventPayload(event.type, event.payload, options);
+  const nextEvent = {
+    ...event,
+    payload: payload.value
+  };
+  return { value: nextEvent, redacted: payload.redacted };
+}
+function summarizeHqToolArgs(value, options = {}) {
+  const policy = resolveHqRedactionPolicy(options.policy);
+  if (policy.toolArgs === "full") return redactHqValue(value, options).value;
+  if (policy.toolArgs === "none") return "[REDACTED:hq_tool_args]";
+  if (policy.toolArgs === "redacted") return redactHqValue(value, options).value;
+  if (value === null || typeof value !== "object") return redactHqValue(value, options).value;
+  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, true);
+    } 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;
+  if (policy?.rawContent === false) return "[REDACTED:hq_raw_content]";
+  if (policy?.rawContent === true) {
+    if (value.length <= maxLength) return value;
+    return `${value.slice(0, maxLength)}\u2026`;
+  }
+  return scrubAndTruncateHqPreview(value, maxLength);
+}
+function readCount(message) {
+  return Object.keys(message.readBy).length;
+}
+function classifyMailboxRecipient(to) {
+  if (to === "*" || to === "all") return { scope: "project" };
+  if (to.startsWith(SESSION_RECIPIENT_PREFIX)) {
+    const recipientSessionId = to.slice(SESSION_RECIPIENT_PREFIX.length);
+    if (recipientSessionId.length === 0) return { scope: "agent" };
+    return { scope: "session", recipientSessionId };
+  }
+  return { scope: "agent" };
+}
+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 ?? 500;
+  const bodyPreview = previewText(message.body, previewLength, options.redactionPolicy);
+  const outcomePreview = previewText(message.outcome, previewLength, options.redactionPolicy);
+  const task = taskSummary(message);
+  const recipient = classifyMailboxRecipient(message.to);
+  return {
+    mailId: message.id,
+    // unique UUID per message record, used for deduplication
+    messageId: message.id,
+    from: message.from,
+    to: message.to,
+    scope: recipient.scope,
+    ...recipient.recipientSessionId !== void 0 ? { recipientSessionId: recipient.recipientSessionId } : {},
+    type: message.type,
+    ...message.audience !== void 0 ? { audience: message.audience } : {},
+    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) ?? "" } : {}
+  };
+}
+
+// src/hq/publisher.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import * as v8 from "node:v8";
+var TRANSCRIPT_EVENT_TYPES = /* @__PURE__ */ new Set(["session.transcript", "agent.message"]);
+var OPEN_STATE = 1;
+var CONNECT_WARN_AFTER_FAILURES = 5;
+var DEFAULT_CONNECT_WARN_COOLDOWN_MS = 5 * 6e4;
+var DEFAULT_RECONNECT_BASE_MS = 1e3;
+var DEFAULT_RECONNECT_MAX_MS = 3e4;
+var DEFAULT_DISCOVERY_POLL_MS = 5e3;
+var DEFAULT_MAX_QUEUED_MESSAGES = 2e3;
+var DEFAULT_MAX_QUEUED_BYTES = Math.min(
+  16 * 1024 * 1024,
+  Math.floor(v8.getHeapStatistics().heap_size_limit * 0.1)
+);
+var DEFAULT_COMMAND_POLL_INTERVAL_MS = 500;
+var DEFAULT_COMMAND_POLL_LIMIT = 25;
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 25e3;
+var warnedEndpoints = /* @__PURE__ */ new Set();
+function resetHqPublisherWarningStateForTests() {
+  warnedEndpoints.clear();
+}
+function queuedFrameCoalesceKey(frame) {
+  if (frame.type !== "client.event" || !frame.event.type.endsWith(".snapshot")) {
+    return void 0;
+  }
+  const payload = frame.event.payload;
+  const chunk = typeof payload?.chunkIndex === "number" && Number.isFinite(payload.chunkIndex) ? String(payload.chunkIndex) : "";
+  return [frame.event.type, frame.event.sessionId ?? "", frame.event.runId ?? "", chunk].join("|");
+}
+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 ?? randomUUID2;
+    this.capabilities = options.capabilities ?? [
+      "telemetry.publish",
+      "mailbox.summary",
+      "fleet.summary",
+      "session.summary"
+    ];
+    this.reconnect = options.reconnect ?? true;
+    this.reconnectBaseMs = options.reconnectBaseMs ?? DEFAULT_RECONNECT_BASE_MS;
+    this.reconnectMaxMs = options.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
+    this.connectWarnAfterFailures = options.connectWarnAfterFailures ?? CONNECT_WARN_AFTER_FAILURES;
+    this.connectWarnCooldownMs = options.connectWarnCooldownMs ?? DEFAULT_CONNECT_WARN_COOLDOWN_MS;
+    this.maxQueuedMessages = options.maxQueuedMessages ?? DEFAULT_MAX_QUEUED_MESSAGES;
+    this.maxQueuedBytes = options.maxQueuedBytes ?? DEFAULT_MAX_QUEUED_BYTES;
+    this.resolvedRedactionPolicy = resolveHqRedactionPolicy(options.redactionPolicy);
+    this.logger = options.logger;
+  }
+  options;
+  socketFactory;
+  now;
+  idFactory;
+  capabilities;
+  reconnect;
+  reconnectBaseMs;
+  reconnectMaxMs;
+  connectWarnAfterFailures;
+  connectWarnCooldownMs;
+  maxQueuedMessages;
+  maxQueuedBytes;
+  resolvedRedactionPolicy;
+  logger;
+  socket = null;
+  seq = 0;
+  queue = [];
+  queueBytes = 0;
+  /**
+   * Cumulative count of frames dropped by the bounded outbound queue when the
+   * count/byte cap is exceeded while HQ is unreachable. Lifetime statistic —
+   * intentionally NOT reset on close()/reconnect, so it reflects total
+   * telemetry loss to overflow for this publisher instance.
+   */
+  droppedFrames = 0;
+  /** Cumulative UTF-8 bytes of frames dropped on overflow (see droppedFrames). */
+  droppedBytes = 0;
+  /** Obsolete state snapshots replaced in-place while HQ was unreachable. */
+  coalescedFrames = 0;
+  /** UTF-8 bytes released by snapshot coalescing. */
+  coalescedBytes = 0;
+  stopped = false;
+  reconnectAttempt = 0;
+  connectWarningEmitted = false;
+  lastAttempt = null;
+  reconnectTimer = null;
+  commandPollTimer = null;
+  heartbeatTimer = null;
+  lastCommandId;
+  connect() {
+    if (this.socket !== null || this.stopped) return;
+    if (this.reconnectTimer !== null) return;
+    let url = this.options.url;
+    let token = this.options.token;
+    if (this.options.resolveEndpoint !== void 0) {
+      const endpoint = this.options.resolveEndpoint();
+      if (endpoint === void 0) {
+        this.scheduleDiscoveryPoll();
+        return;
+      }
+      url = endpoint.url;
+      token = endpoint.token ?? token;
+    }
+    this.lastAttempt = { url, hadToken: token !== void 0 };
+    let socket;
+    try {
+      socket = this.socketFactory(toClientUrl(url, token), {
+        ...token !== void 0 ? { token } : {}
+      });
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    this.socket = socket;
+    const onOpen = () => {
+      this.reconnectAttempt = 0;
+      this.connectWarningEmitted = false;
+      if (this.lastAttempt?.url) {
+        warnedEndpoints.delete(this.lastAttempt.url);
+      }
+      if (this.options.url) {
+        warnedEndpoints.delete(this.options.url);
+      }
+      this.sendHelloNow();
+      this.flushQueue();
+      this.startHeartbeat();
+      if (this.options.onCommand !== void 0) {
+        this.startCommandPolling();
+        this.pollCommands();
+      }
+    };
+    const onMessage = (event) => {
+      this.handleServerMessage(event).catch((error) => {
+        const message = `WrongStack HQ publisher: server message handling failed: ${error instanceof Error ? error.message : String(error)}`;
+        if (this.logger) {
+          this.logger.warn(message, { event: "hq.publisher.message_failed" });
+          return;
+        }
+        process.emitWarning(message, { code: "WRONGSTACK_HQ_MESSAGE_FAILED" });
+      });
+    };
+    const onCloseOrError = () => {
+      removeSocketListener(socket, "open", onOpen);
+      removeSocketListener(socket, "message", onMessage);
+      removeSocketListener(socket, "close", onCloseOrError);
+      removeSocketListener(socket, "error", onCloseOrError);
+      this.stopCommandPolling();
+      this.stopHeartbeat();
+      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.stopHeartbeat();
+    this.queue = [];
+    this.queueBytes = 0;
+    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 } : {}
+    });
+    const maxSummaryLength = options.maxSummaryLength ?? (TRANSCRIPT_EVENT_TYPES.has(options.type) ? HQ_TRANSCRIPT_TEXT_CAP : void 0);
+    const redacted = redactHqEvent(event, {
+      policy: this.resolvedRedactionPolicy,
+      projectRoot: this.options.project.projectRoot,
+      ...maxSummaryLength !== void 0 ? { maxSummaryLength } : {}
+    }).value;
+    this.sendFrame({ type: "client.event", event: redacted });
+    return redacted;
+  }
+  async publishMailboxSnapshot(mailbox, options) {
+    const payload = await createMailboxSnapshotPayloadFromMailbox(mailbox, {
+      ...options,
+      redactionPolicy: this.resolvedRedactionPolicy
+    });
+    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 } : {},
+      redactionPolicy: this.resolvedRedactionPolicy
+    });
+    return this.publishEvent({
+      type: "mailbox.event",
+      payload,
+      ...input.sessionId !== void 0 ? { sessionId: input.sessionId } : {},
+      ...input.timestamp !== void 0 ? { timestamp: input.timestamp } : {}
+    });
+  }
+  /** The client identity this publisher announced (clientId, kind, machineId, …). */
+  get identity() {
+    return this.options.client;
+  }
+  /** The project identity this publisher is bound to. */
+  get project() {
+    return this.options.project;
+  }
+  /** Effective publisher-side policy applied before any event leaves this process. */
+  get redactionPolicy() {
+    return this.resolvedRedactionPolicy;
+  }
+  /** Current outbound queue pressure — useful for flow control in telemetry bridges. */
+  getQueueStats() {
+    return {
+      entries: this.queue.length,
+      bytes: this.queueBytes,
+      maxBytes: this.maxQueuedBytes,
+      droppedFrames: this.droppedFrames,
+      droppedBytes: this.droppedBytes,
+      coalescedFrames: this.coalescedFrames,
+      coalescedBytes: this.coalescedBytes
+    };
+  }
+  /** Publish a live session/terminal snapshot (state + agents). */
+  publishSessionSnapshot(payload, opts) {
+    return this.publishEvent({
+      type: "session.snapshot",
+      payload,
+      sessionId: payload.sessionId,
+      ...opts?.timestamp !== void 0 ? { timestamp: opts.timestamp } : {}
+    });
+  }
+  /** Publish an incremental batch of transcript turns for a session. */
+  publishTranscriptAppend(payload, opts) {
+    return this.publishEvent({
+      type: "session.transcript",
+      payload,
+      sessionId: payload.sessionId,
+      ...opts?.timestamp !== void 0 ? { timestamp: opts.timestamp } : {}
+    });
+  }
+  /** Mark a session/terminal as ended. */
+  publishSessionEnded(payload, opts) {
+    return this.publishEvent({
+      type: "session.ended",
+      payload,
+      sessionId: payload.sessionId,
+      ...opts?.timestamp !== void 0 ? { timestamp: opts.timestamp } : {}
+    });
+  }
+  /** Publish a fleet (multi-agent coordinator) snapshot. */
+  publishFleetSnapshot(payload, opts) {
+    return this.publishEvent({
+      type: "fleet.snapshot",
+      payload,
+      runId: payload.runId,
+      ...opts?.sessionId !== void 0 ? { sessionId: opts.sessionId } : {},
+      ...opts?.timestamp !== void 0 ? { timestamp: opts.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 } : {}
+    });
+  }
+  createHelloFrame() {
+    return {
+      type: "client.hello",
+      payload: {
+        protocolVersion: HQ_PROTOCOL_VERSION,
+        client: this.options.client,
+        project: this.options.project,
+        capabilities: this.capabilities,
+        redactionPolicy: this.resolvedRedactionPolicy
+      }
+    };
+  }
+  sendHelloNow() {
+    const socket = this.socket;
+    if (socket?.readyState !== OPEN_STATE) {
+      this.sendFrame(this.createHelloFrame());
+      return;
+    }
+    socket.send(JSON.stringify(this.createHelloFrame()));
+  }
+  sendFrame(frame) {
+    const serialized = JSON.stringify(frame);
+    const socket = this.socket;
+    if (socket?.readyState === OPEN_STATE && this.queue.length === 0) {
+      socket.send(serialized);
+      return;
+    }
+    this.enqueue(serialized, queuedFrameCoalesceKey(frame));
+    this.connect();
+  }
+  enqueue(serialized, coalesceKey) {
+    const bytes = Buffer.byteLength(serialized, "utf8");
+    if (bytes > this.maxQueuedBytes) {
+      this.droppedFrames += 1;
+      this.droppedBytes += bytes;
+      process.emitWarning(
+        `HQ telemetry frame of ${bytes} bytes exceeds the ${this.maxQueuedBytes}-byte offline queue cap and was dropped.`,
+        { code: "WRONGSTACK_HQ_FRAME_TOO_LARGE" }
+      );
+      return;
+    }
+    if (coalesceKey !== void 0) {
+      let existingIndex = -1;
+      for (let index = this.queue.length - 1; index >= 0; index -= 1) {
+        if (this.queue[index]?.coalesceKey === coalesceKey) {
+          existingIndex = index;
+          break;
+        }
+      }
+      if (existingIndex !== -1) {
+        const [obsolete] = this.queue.splice(existingIndex, 1);
+        if (obsolete !== void 0) {
+          this.queueBytes -= obsolete.bytes;
+          this.coalescedFrames += 1;
+          this.coalescedBytes += obsolete.bytes;
+        }
+      }
+    }
+    while ((this.queue.length >= this.maxQueuedMessages || this.queueBytes + bytes > this.maxQueuedBytes) && this.queue.length > 0) {
+      const dropped = this.queue.shift();
+      if (dropped !== void 0) {
+        this.queueBytes -= dropped.bytes;
+        this.droppedFrames += 1;
+        this.droppedBytes += dropped.bytes;
+      }
+    }
+    this.queue.push({ serialized, bytes, coalesceKey });
+    this.queueBytes += bytes;
+  }
+  /** Batch-dequeue up to 50 frames at a time, yielding to the microtask
+   *  queue between batches so we don't starve the event loop on reconnect. */
+  flushQueue() {
+    const socket = this.socket;
+    if (socket?.readyState !== OPEN_STATE || this.queue.length === 0) return;
+    const batch = this.queue.splice(0, 50);
+    for (const frame of batch) {
+      socket.send(frame.serialized);
+      this.queueBytes -= frame.bytes;
+    }
+    this.queueBytes = Math.max(0, this.queueBytes);
+    if (this.queue.length > 0) setImmediate(() => this.flushQueue());
+  }
+  startCommandPolling() {
+    if (this.options.onCommand === void 0 || this.commandPollTimer !== null) return;
+    this.commandPollTimer = setInterval(
+      () => this.pollCommands(),
+      this.options.commandPollIntervalMs ?? DEFAULT_COMMAND_POLL_INTERVAL_MS
+    );
+    this.commandPollTimer.unref?.();
+  }
+  stopCommandPolling() {
+    if (this.commandPollTimer === null) return;
+    clearInterval(this.commandPollTimer);
+    this.commandPollTimer = null;
+  }
+  startHeartbeat() {
+    if (this.heartbeatTimer !== null) return;
+    this.heartbeatTimer = setInterval(
+      () => this.publishHeartbeat(),
+      this.options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS
+    );
+    this.heartbeatTimer.unref?.();
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer === null) return;
+    clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+  }
+  publishHeartbeat() {
+    const startedAt = Date.parse(this.options.client.startedAt);
+    const now = Date.parse(this.now());
+    this.publishEvent({
+      type: "client.heartbeat",
+      payload: {
+        uptimeMs: Number.isFinite(startedAt) && Number.isFinite(now) ? Math.max(0, now - startedAt) : 0,
+        status: "idle"
+      }
+    });
+  }
+  async handleServerMessage(event) {
+    const message = this.parseServerMessage(event);
+    if (message?.type === "hq.command_batch") {
+      await this.handleCommandBatch(message);
+      return;
+    }
+    if (message?.type === "hq.kanban_snapshot") {
+      await this.options.onKanbanSnapshot?.(message.payload);
+    }
+  }
+  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 parsed;
+      }
+      if (parsed.type === "hq.kanban_snapshot") {
+        const payload = parsed.payload;
+        if (payload !== void 0 && typeof payload === "object" && typeof payload.projectId === "string" && payload.projectId === this.options.project.projectId && Array.isArray(payload.boards) && Array.isArray(payload.tombstones)) {
+          return parsed;
+        }
+      }
+      return null;
+    } 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) {
+      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)
+        });
+      }
+      this.lastCommandId = command.commandId;
+    }
+  }
+  scheduleReconnect() {
+    if (this.stopped || !this.reconnect || this.reconnectTimer !== null) return;
+    const delay = Math.min(this.reconnectMaxMs, this.reconnectBaseMs * 2 ** this.reconnectAttempt);
+    this.reconnectAttempt += 1;
+    if (!this.connectWarningEmitted && this.reconnectAttempt >= this.connectWarnAfterFailures) {
+      this.connectWarningEmitted = true;
+      this.emitConnectWarning();
+    }
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+    this.reconnectTimer.unref?.();
+  }
+  emitConnectWarning() {
+    const targetUrl = this.lastAttempt?.url ?? this.options.url;
+    if (this.connectWarnCooldownMs > 0) {
+      if (warnedEndpoints.has(targetUrl)) {
+        return false;
+      }
+      warnedEndpoints.add(targetUrl);
+    }
+    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 true;
+    }
+    const warn = this.options.warn ?? ((msg) => console.warn(
+      JSON.stringify({
+        level: "warn",
+        event: "hq.publisher.connect_failed",
+        message: msg,
+        timestamp: this.now()
+      })
+    ));
+    try {
+      warn(message);
+    } catch {
+    }
+    return true;
+  }
+  /**
+   * Dormant re-check while no HQ endpoint is discoverable. Uses a FIXED
+   * interval (not the exponential reconnect backoff): the check is a cheap
+   * local file read, and backing off would delay attaching to an HQ the
+   * user just started — the whole point of auto-discovery.
+   */
+  scheduleDiscoveryPoll() {
+    if (this.stopped || !this.reconnect || this.reconnectTimer !== null) return;
+    this.reconnectAttempt = 0;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, this.options.discoveryPollMs ?? DEFAULT_DISCOVERY_POLL_MS);
+    this.reconnectTimer.unref?.();
+  }
+};
+
+// src/hq/factory.ts
+import { createHash as createHash2, randomUUID as randomUUID3 } from "node:crypto";
+import * as fs2 from "node:fs";
+import { hostname } from "node:os";
+import { basename as basename2 } from "node:path";
+function discoverLocalHqEndpoint(options = {}) {
+  const dataDir = resolveHqDataDir(options.dataDir, options.env ?? process.env);
+  const runtime = readHqRuntimeFileSync(dataDir);
+  if (runtime === void 0) return void 0;
+  if (!isLoopbackHqUrl(runtime.url)) return void 0;
+  const token = readFirstClientTokenFromAuthFile(dataDir);
+  return { url: runtime.url, ...token ? { token } : {} };
+}
+function readFirstClientTokenFromAuthFile(dataDir) {
+  try {
+    const raw = fs2.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 isLoopbackHqUrl(url) {
+  try {
+    const host = new URL(url).hostname.toLowerCase();
+    return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]" || host === "0.0.0.0";
+  } catch {
+    return false;
+  }
+}
+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 explicitToken = envToken || configToken;
+  const runtimeUrl = readHqRuntimeFileSync(dataDir)?.url.trim();
+  const url = envUrl || configUrl;
+  const localFallbackToken = !url || isLoopbackHqUrl(url) ? readFirstClientTokenFromAuthFile(dataDir) : void 0;
+  const token = explicitToken || localFallbackToken;
+  const rawContentEnv = env["WRONGSTACK_HQ_RAW_CONTENT"]?.trim();
+  const explicitRawContent = rawContentEnv ? rawContentEnv === "1" : fileConfig?.rawContent;
+  const projectAliasEnv = env["WRONGSTACK_HQ_PROJECT_ALIAS"]?.trim();
+  const projectAlias = projectAliasEnv || fileConfig?.projectAlias;
+  if (!url) {
+    if (enabled === false) return void 0;
+    return {
+      url: runtimeUrl || "http://127.0.0.1:3499",
+      enabled: true,
+      discover: true,
+      dataDir,
+      rawContent: explicitRawContent ?? true,
+      ...token ? { token } : {},
+      ...projectAlias ? { projectAlias } : {}
+    };
+  }
+  const rawContent = explicitRawContent ?? true;
+  return {
+    url,
+    ...token ? { token } : {},
+    ...enabled !== void 0 ? { enabled } : {},
+    ...rawContent !== void 0 ? { rawContent } : {},
+    ...projectAlias ? { projectAlias } : {}
+  };
+}
+function stableMachineId() {
+  return createHash2("sha256").update(hostname()).digest("hex").slice(0, 12);
+}
+function deriveHqProjectId(projectRoot, projectAlias) {
+  const projectIdentity = readProjectIdentitySync(projectRoot);
+  if (projectIdentity) return projectIdentity.projectId;
+  const alias = projectAlias?.trim();
+  if (!alias && projectRoot.startsWith("alias:")) {
+    throw new Error('projectRoot must not use the reserved "alias:" HQ identity prefix');
+  }
+  const identity = alias ? `alias:${alias}` : projectRoot;
+  return createHash2("sha256").update(identity).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 projectAlias = config.projectAlias?.trim() || void 0;
+  const projectName = projectAlias ?? options.projectName ?? (basename2(options.projectRoot) || "unknown");
+  const client = {
+    clientId: `${machineId}:${options.clientKind}:${process.pid}:${randomUUID3().slice(0, 8)}`,
+    kind: options.clientKind,
+    machineId,
+    ...host ? { hostname: host } : {},
+    pid: process.pid,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const project = {
+    projectId: deriveHqProjectId(options.projectRoot, projectAlias),
+    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;
+  const discoveryDataDir = config.dataDir;
+  return new HqPublisher({
+    url: config.url,
+    ...config.token ? { token: config.token } : {},
+    client,
+    project,
+    ...options.socketFactory ? { socketFactory: options.socketFactory } : {},
+    ...redactionPolicy !== void 0 ? { redactionPolicy } : {},
+    ...options.capabilities !== void 0 ? { capabilities: options.capabilities } : {},
+    ...options.maxQueuedMessages !== void 0 ? { maxQueuedMessages: options.maxQueuedMessages } : {},
+    ...options.onCommand !== void 0 ? { onCommand: options.onCommand } : {},
+    ...options.onKanbanSnapshot !== void 0 ? { onKanbanSnapshot: options.onKanbanSnapshot } : {},
+    // 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.logger !== void 0 ? { logger: options.logger } : {}
+  });
+}
+
+export {
+  hqAuthAuditPath,
+  readHqAuthAuditTail,
+  appendHqAuthAudit,
+  logHqAuthAudit,
+  HQ_AUTH_FILE_VERSION,
+  defaultHqDataDir,
+  resolveHqDataDir,
+  hqTokenVerifier,
+  hqTokenKey,
+  isTokenExpired,
+  tokenHasCapability,
+  emptyHqAuthFile,
+  HQ_AUTH_CONTENT_HASH_REDACTED,
+  hqAuthContentHash,
+  hqAuthFilePath,
+  hqRuntimeFilePath,
+  writeHqRuntimeFile,
+  readHqRuntimeFileSync,
+  readHqAuthFile,
+  writeHqAuthFile,
+  ensureHqFirstRunAuthFile,
+  mutateHqAuthFile,
+  hashHqPassword,
+  verifyHqPassword,
+  mintHqCookieSecret,
+  mintHqToken,
+  mintHqBrowserToken,
+  watchHqAuthFile,
+  resolveHqRedactionPolicy,
+  tightenHqRedactionPolicy,
+  scrubAndTruncateHqPreview,
+  redactHqValue,
+  redactHqEventPayload,
+  redactHqEvent,
+  summarizeHqToolArgs,
+  classifyMailboxRecipient,
+  mapMailboxMessageToHqSummary,
+  mapMailboxAgentToHqSummary,
+  createMailboxSnapshotPayload,
+  createMailboxSnapshotPayloadFromMailbox,
+  createMailboxEventPayload,
+  resetHqPublisherWarningStateForTests,
+  HqPublisher,
+  discoverLocalHqEndpoint,
+  resolveHqConfigFromEnv,
+  resolveHqConfig,
+  deriveHqProjectId,
+  createHqPublisherFromEnv
+};
+//# sourceMappingURL=chunk-NIOAGFPB.js.map