@wrongstack/core 0.291.1 → 0.292.0

package/dist/hq/index.js

@@ -1,3 +1,57 @@
+// src/hq/bridge-context.ts
+function createBridgeContext(options) {
+  const publisher = options.publisher;
+  const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const bridgeSessionId = options.sessionId;
+  const offs = [];
+  function sessionIdTag(eventSessionId) {
+    const tag = eventSessionId ?? bridgeSessionId;
+    return tag !== void 0 && tag.length > 0 ? { sessionId: tag } : {};
+  }
+  function safePublish(publishOptions) {
+    try {
+      publisher.publishEvent(publishOptions);
+    } catch {
+    }
+  }
+  function track(off) {
+    offs.push(off);
+  }
+  function dispose() {
+    for (const off of offs) {
+      try {
+        off();
+      } catch {
+      }
+    }
+    offs.length = 0;
+  }
+  return { now, sessionIdTag, safePublish, track, dispose };
+}
+
+// src/hq/auth-audit.ts
+import { appendFileSync, mkdirSync } from "node:fs";
+import * as path from "node:path";
+function hqAuthAuditPath(dataDir) {
+  return path.join(dataDir, "auth-audit.jsonl");
+}
+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/protocol/tool.ts
 var DEFAULT_HQ_REDACTION_POLICY = {
   rawContent: true,
@@ -1424,7 +1478,7 @@ var HqPublisher = class {
 };
 
 // src/hq/factory.ts
-import { createHash as createHash2, randomUUID as randomUUID4 } from "node:crypto";
+import { createHash as createHash3, randomUUID as randomUUID4 } from "node:crypto";
 import * as fs4 from "node:fs";
 import { hostname } from "node:os";
 import { basename as basename5 } from "node:path";
@@ -1432,23 +1486,23 @@ import { basename as basename5 } from "node:path";
 // src/coordination/global-mailbox.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 import * as fsp from "node:fs/promises";
-import * as path4 from "node:path";
+import * as path5 from "node:path";
 
 // src/utils/atomic-write.ts
 import { randomBytes } from "node:crypto";
 import * as fs2 from "node:fs/promises";
 import { watch as watchDir } from "node:fs";
-import * as path3 from "node:path";
+import * as path4 from "node:path";
 
 // src/utils/session-scoped-path.ts
-import * as path from "node:path";
+import * as path2 from "node:path";
 function sessionScopedPath(dir, sessionId, suffix) {
   if (!sessionId || sessionId.includes("\\") || sessionId.includes("..")) {
     throw invalid(sessionId);
   }
-  const resolved = path.resolve(dir, `${sessionId}${suffix}`);
-  const rel = path.relative(path.resolve(dir), resolved);
-  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+  const resolved = path2.resolve(dir, `${sessionId}${suffix}`);
+  const rel = path2.relative(path2.resolve(dir), resolved);
+  if (rel.startsWith("..") || path2.isAbsolute(rel)) {
     throw invalid(sessionId);
   }
   return resolved;
@@ -1466,21 +1520,21 @@ function invalid(sessionId) {
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
-import * as path2 from "node:path";
+import * as path3 from "node:path";
 function canonicalProjectRoot(absRoot) {
-  const checkoutRoot = path2.resolve(absRoot);
-  const dotGit = path2.join(checkoutRoot, ".git");
+  const checkoutRoot = path3.resolve(absRoot);
+  const dotGit = path3.join(checkoutRoot, ".git");
   try {
     if (!fs.statSync(dotGit).isFile()) return checkoutRoot;
     const gitDirLine = fs.readFileSync(dotGit, "utf8").trim();
     const match = /^gitdir:\s*(.+)$/i.exec(gitDirLine);
     if (!match?.[1]) return checkoutRoot;
-    const gitDir = path2.resolve(checkoutRoot, match[1].trim());
-    const commonDirFile = path2.join(gitDir, "commondir");
+    const gitDir = path3.resolve(checkoutRoot, match[1].trim());
+    const commonDirFile = path3.join(gitDir, "commondir");
     if (!fs.statSync(commonDirFile).isFile()) return checkoutRoot;
-    const commonDir = path2.resolve(gitDir, fs.readFileSync(commonDirFile, "utf8").trim());
-    if (path2.basename(commonDir).toLowerCase() !== ".git") return checkoutRoot;
-    return path2.dirname(commonDir);
+    const commonDir = path3.resolve(gitDir, fs.readFileSync(commonDirFile, "utf8").trim());
+    if (path3.basename(commonDir).toLowerCase() !== ".git") return checkoutRoot;
+    return path3.dirname(commonDir);
   } catch {
     return checkoutRoot;
   }
@@ -1490,7 +1544,7 @@ function projectHash(absRoot) {
 }
 function projectSlug(absRoot) {
   const identityRoot = canonicalProjectRoot(absRoot);
-  const base = slugify(path2.basename(identityRoot));
+  const base = slugify(path3.basename(identityRoot));
   const hash = createHash("sha256").update(identityRoot).digest("hex").slice(0, 6);
   return `${base}-${hash}`;
 }
@@ -1499,83 +1553,83 @@ function slugify(name) {
 }
 function wstackGlobalRoot() {
   const fromEnv = process.env["WRONGSTACK_HOME"];
-  if (fromEnv && fromEnv.trim().length > 0) return path2.resolve(fromEnv);
-  return path2.join(os.homedir(), ".wrongstack");
+  if (fromEnv && fromEnv.trim().length > 0) return path3.resolve(fromEnv);
+  return path3.join(os.homedir(), ".wrongstack");
 }
 function resolveWstackPaths(opts) {
-  const globalRoot = opts.globalRoot ?? (opts.userHome ? path2.join(opts.userHome, ".wrongstack") : wstackGlobalRoot());
+  const globalRoot = opts.globalRoot ?? (opts.userHome ? path3.join(opts.userHome, ".wrongstack") : wstackGlobalRoot());
   const homeDir = opts.userHome ?? os.homedir();
   const hash = projectHash(opts.projectRoot);
   const slug = projectSlug(opts.projectRoot);
-  const projectDir = path2.join(globalRoot, "projects", slug);
+  const projectDir = path3.join(globalRoot, "projects", slug);
   return {
     globalRoot,
     projectRoot: opts.projectRoot,
     homeDir,
     configDir: globalRoot,
-    globalConfig: path2.join(globalRoot, "config.json"),
-    profilesDir: path2.join(globalRoot, "profiles"),
+    globalConfig: path3.join(globalRoot, "config.json"),
+    profilesDir: path3.join(globalRoot, "profiles"),
     profileConfig: (name) => {
       const safe = name.replace(/[/\\:]/g, "_").replace(/\.\./g, "_");
-      return path2.join(globalRoot, "profiles", safe || "default", "config.json");
+      return path3.join(globalRoot, "profiles", safe || "default", "config.json");
     },
     profileStatuslineConfig: (name) => {
       const safe = name.replace(/[/\\:]/g, "_").replace(/\.\./g, "_");
-      return path2.join(globalRoot, "profiles", safe || "default", "statusline.json");
+      return path3.join(globalRoot, "profiles", safe || "default", "statusline.json");
     },
     profileModeConfig: (name) => {
       const safe = name.replace(/[/\\:]/g, "_").replace(/\.\./g, "_");
-      return path2.join(globalRoot, "profiles", safe || "default", "mode.json");
+      return path3.join(globalRoot, "profiles", safe || "default", "mode.json");
     },
     profileProviderStatus: (name) => {
       const safe = name.replace(/[/\\:]/g, "_").replace(/\.\./g, "_");
-      return path2.join(globalRoot, "profiles", safe || "default", "provider-status.json");
+      return path3.join(globalRoot, "profiles", safe || "default", "provider-status.json");
     },
     profileUpdateCache: (name) => {
       const safe = name.replace(/[/\\:]/g, "_").replace(/\.\./g, "_");
-      return path2.join(globalRoot, "profiles", safe || "default", "update-cache.json");
+      return path3.join(globalRoot, "profiles", safe || "default", "update-cache.json");
     },
-    secretsKey: path2.join(globalRoot, ".key"),
-    globalMemory: path2.join(globalRoot, "memory.md"),
-    globalSkills: path2.join(globalRoot, "skills"),
-    globalClaudeSkills: path2.join(homeDir, ".claude", "skills"),
-    globalDesignKits: path2.join(globalRoot, "design-kits"),
-    globalPrompts: path2.join(globalRoot, "prompts"),
-    globalInstructions: path2.join(globalRoot, "instructions"),
-    promptUsage: path2.join(globalRoot, "prompt-usage.json"),
-    cacheDir: path2.join(globalRoot, "cache"),
-    modelsCache: path2.join(globalRoot, "cache", "models.dev.json"),
-    modelsOverlayCache: path2.join(globalRoot, "cache", "models-overlay.json"),
-    historyFile: path2.join(globalRoot, "history"),
-    logFile: path2.join(globalRoot, "logs", "wrongstack.log"),
+    secretsKey: path3.join(globalRoot, ".key"),
+    globalMemory: path3.join(globalRoot, "memory.md"),
+    globalSkills: path3.join(globalRoot, "skills"),
+    globalClaudeSkills: path3.join(homeDir, ".claude", "skills"),
+    globalDesignKits: path3.join(globalRoot, "design-kits"),
+    globalPrompts: path3.join(globalRoot, "prompts"),
+    globalInstructions: path3.join(globalRoot, "instructions"),
+    promptUsage: path3.join(globalRoot, "prompt-usage.json"),
+    cacheDir: path3.join(globalRoot, "cache"),
+    modelsCache: path3.join(globalRoot, "cache", "models.dev.json"),
+    modelsOverlayCache: path3.join(globalRoot, "cache", "models-overlay.json"),
+    historyFile: path3.join(globalRoot, "history"),
+    logFile: path3.join(globalRoot, "logs", "wrongstack.log"),
     projectDir,
-    projectCodebaseIndex: path2.join(projectDir, "codebase-index"),
-    projectMemory: path2.join(projectDir, "memory.md"),
-    projectSessions: path2.join(projectDir, "sessions"),
-    projectTrust: path2.join(projectDir, "trust.json"),
-    projectMeta: path2.join(projectDir, "meta.json"),
-    projectLocalConfig: path2.join(projectDir, "config.local.json"),
-    inProjectConfig: path2.join(opts.projectRoot, ".wrongstack", "config.json"),
-    inProjectAgentsFile: path2.join(opts.projectRoot, ".wrongstack", "AGENTS.md"),
-    inProjectSkills: path2.join(opts.projectRoot, ".wrongstack", "skills"),
-    inProjectClaudeSkills: path2.join(opts.projectRoot, ".claude", "skills"),
-    inProjectPrompts: path2.join(opts.projectRoot, ".wrongstack", "prompts"),
-    inProjectInstructions: path2.join(opts.projectRoot, ".wrongstack", "instructions"),
-    inProjectDesignKits: path2.join(opts.projectRoot, ".wrongstack", "design-kits"),
-    inProjectWorktrees: path2.join(opts.projectRoot, ".wrongstack", "worktrees"),
+    projectCodebaseIndex: path3.join(projectDir, "codebase-index"),
+    projectMemory: path3.join(projectDir, "memory.md"),
+    projectSessions: path3.join(projectDir, "sessions"),
+    projectTrust: path3.join(projectDir, "trust.json"),
+    projectMeta: path3.join(projectDir, "meta.json"),
+    projectLocalConfig: path3.join(projectDir, "config.local.json"),
+    inProjectConfig: path3.join(opts.projectRoot, ".wrongstack", "config.json"),
+    inProjectAgentsFile: path3.join(opts.projectRoot, ".wrongstack", "AGENTS.md"),
+    inProjectSkills: path3.join(opts.projectRoot, ".wrongstack", "skills"),
+    inProjectClaudeSkills: path3.join(opts.projectRoot, ".claude", "skills"),
+    inProjectPrompts: path3.join(opts.projectRoot, ".wrongstack", "prompts"),
+    inProjectInstructions: path3.join(opts.projectRoot, ".wrongstack", "instructions"),
+    inProjectDesignKits: path3.join(opts.projectRoot, ".wrongstack", "design-kits"),
+    inProjectWorktrees: path3.join(opts.projectRoot, ".wrongstack", "worktrees"),
     projectHash: hash,
     projectSlug: slug,
-    projectGoal: path2.join(projectDir, "goal.json"),
-    projectInputHistory: path2.join(projectDir, "input-history.json"),
-    projectSpecs: path2.join(projectDir, "specs"),
-    projectTaskGraphs: path2.join(projectDir, "task-graphs"),
-    projectSddSession: path2.join(projectDir, "sdd-session.json"),
-    projectPlan: path2.join(projectDir, "plan.json"),
-    projectAutophase: path2.join(projectDir, "autophase"),
-    projectSddBoards: path2.join(projectDir, "sdd-boards"),
-    syncConfig: path2.join(globalRoot, "sync.json"),
-    configHistoryDir: path2.join(globalRoot, "config-history"),
-    projectStatus: (projectHash2) => path2.join(globalRoot, "projects", projectHash2, "status.json")
+    projectGoal: path3.join(projectDir, "goal.json"),
+    projectInputHistory: path3.join(projectDir, "input-history.json"),
+    projectSpecs: path3.join(projectDir, "specs"),
+    projectTaskGraphs: path3.join(projectDir, "task-graphs"),
+    projectSddSession: path3.join(projectDir, "sdd-session.json"),
+    projectPlan: path3.join(projectDir, "plan.json"),
+    projectAutophase: path3.join(projectDir, "autophase"),
+    projectSddBoards: path3.join(projectDir, "sdd-boards"),
+    syncConfig: path3.join(globalRoot, "sync.json"),
+    configHistoryDir: path3.join(globalRoot, "config-history"),
+    projectStatus: (projectHash2) => path3.join(globalRoot, "projects", projectHash2, "status.json")
   };
 }
 
@@ -1683,9 +1737,9 @@ var FsError = class extends WrongStackError {
 
 // src/utils/atomic-write.ts
 async function atomicWrite(targetPath, content, opts = {}) {
-  const dir = path3.dirname(targetPath);
+  const dir = path4.dirname(targetPath);
   await fs2.mkdir(dir, { recursive: true });
-  const tmp = path3.join(dir, `.${path3.basename(targetPath)}.${randomBytes(6).toString("hex")}.tmp`);
+  const tmp = path4.join(dir, `.${path4.basename(targetPath)}.${randomBytes(6).toString("hex")}.tmp`);
   try {
     if (typeof content === "string") {
       await fs2.writeFile(tmp, content, { flag: "wx", encoding: opts.encoding ?? "utf8" });
@@ -1727,9 +1781,9 @@ async function atomicWrite(targetPath, content, opts = {}) {
   }
 }
 async function withFileLock(targetPath, fn, opts = {}) {
-  const dir = path3.dirname(targetPath);
+  const dir = path4.dirname(targetPath);
   await fs2.mkdir(dir, { recursive: true });
-  const lockPath = path3.join(dir, `.${path3.basename(targetPath)}.lock`);
+  const lockPath = path4.join(dir, `.${path4.basename(targetPath)}.lock`);
   const timeoutMs = opts.timeoutMs ?? 15e3;
   const staleMs = opts.staleMs ?? 3e4;
   const started = Date.now();
@@ -1788,8 +1842,8 @@ async function withFileLock(targetPath, fn, opts = {}) {
   }
 }
 async function waitForLockRelease(lockPath, remainingMs) {
-  const parentDir = path3.dirname(lockPath);
-  const lockName = path3.basename(lockPath);
+  const parentDir = path4.dirname(lockPath);
+  const lockName = path4.basename(lockPath);
   const intervalMs = Math.min(remainingMs, 100);
   return new Promise((resolve4) => {
     let settled = false;
@@ -2127,15 +2181,15 @@ var GlobalMailbox = class {
    * @param eventEmitter — optional SSE event emitter for HTTP bridge push
    */
   constructor(projectDir, events, hqPublisher, eventEmitter) {
-    this.messagePath = path4.join(projectDir, MAILBOX_FILE);
-    this.registryPath = path4.join(projectDir, "_mailbox.registry.json");
-    this.clientRegistryPath = path4.join(projectDir, CLIENT_REGISTRY_FILE);
+    this.messagePath = path5.join(projectDir, MAILBOX_FILE);
+    this.registryPath = path5.join(projectDir, "_mailbox.registry.json");
+    this.clientRegistryPath = path5.join(projectDir, CLIENT_REGISTRY_FILE);
     this._events = events;
     this._hqPublisher = hqPublisher;
     this.eventEmitter = eventEmitter;
   }
   get hqMailboxId() {
-    return `${path4.basename(path4.dirname(this.messagePath))}:mailbox`;
+    return `${path5.basename(path5.dirname(this.messagePath))}:mailbox`;
   }
   get hqPublisher() {
     return typeof this._hqPublisher === "function" ? this._hqPublisher() : this._hqPublisher;
@@ -2174,7 +2228,7 @@ var GlobalMailbox = class {
       expiresAt: input.ttlMs !== void 0 ? new Date(Date.now() + input.ttlMs).toISOString() : void 0
     };
     const line = JSON.stringify(msg) + LINE_SEPARATOR;
-    await fsp.mkdir(path4.dirname(this.messagePath), { recursive: true });
+    await fsp.mkdir(path5.dirname(this.messagePath), { recursive: true });
     await withFileLock(this.messagePath, async () => {
       await fsp.appendFile(this.messagePath, line, "utf8");
       const { mtimeMs, size } = await this._statMessageFile();
@@ -3148,7 +3202,7 @@ var GlobalMailbox = class {
     this._messageCacheSize = size;
   }
   async _ensureRegistry() {
-    await fsp.mkdir(path4.dirname(this.registryPath), { recursive: true });
+    await fsp.mkdir(path5.dirname(this.registryPath), { recursive: true });
   }
   /** Minimal shape-check for a deserialized agent registry entry.
    *  Logs a warning and returns `false` for structurally invalid data
@@ -3241,7 +3295,7 @@ var GlobalMailbox = class {
   }
   // ── Client registry internals ───────────────────────────────────────────
   async _ensureClientRegistry() {
-    await fsp.mkdir(path4.dirname(this.clientRegistryPath), { recursive: true });
+    await fsp.mkdir(path5.dirname(this.clientRegistryPath), { recursive: true });
   }
   async _readClientRegistry(opts) {
     if (!opts?.fresh && this._clientRegistryCache && Date.now() - this._clientRegistryCacheAt < REGISTRY_CACHE_TTL_MS) {
@@ -3293,21 +3347,30 @@ var GlobalMailbox = class {
 };
 
 // src/hq/auth-store.ts
-import { randomBytes as randomBytes2, randomUUID as randomUUID3, scrypt, timingSafeEqual } from "node:crypto";
+import { createHash as createHash2, randomBytes as randomBytes2, randomUUID as randomUUID3, scrypt, timingSafeEqual } from "node:crypto";
 import * as fs3 from "node:fs/promises";
 import * as syncFs from "node:fs";
-import * as path5 from "node:path";
+import * as path6 from "node:path";
 var HQ_AUTH_FILE_VERSION = 1;
 function defaultHqDataDir() {
-  return path5.join(wstackGlobalRoot(), "hq");
+  return path6.join(wstackGlobalRoot(), "hq");
 }
 function resolveHqDataDir(override, env = process.env) {
   const raw = override ?? env["WRONGSTACK_HQ_DATA_DIR"]?.trim();
   if (!raw) return defaultHqDataDir();
-  return path5.isAbsolute(raw) ? path5.resolve(raw) : path5.resolve(process.cwd(), raw);
+  return path6.isAbsolute(raw) ? path6.resolve(raw) : path6.resolve(process.cwd(), raw);
+}
+function isTokenExpired(token, at = Date.now()) {
+  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;
 }
 function tokenHasCapability(token, capability) {
   if (token === void 0) return false;
+  if (isTokenExpired(token)) return false;
   if (token.capabilities === void 0) return true;
   return token.capabilities.includes(capability);
 }
@@ -3317,11 +3380,32 @@ function emptyHqAuthFile() {
     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.alertRules !== void 0 ? { alertRules: file.alertRules } : {}
+    };
+    const payload = JSON.stringify(projection);
+    return createHash2("sha256").update(payload).digest("hex");
+  } catch {
+    return void 0;
+  }
+}
 function hqAuthFilePath(dataDir) {
-  return path5.join(dataDir, "auth.json");
+  return path6.join(dataDir, "auth.json");
 }
 function hqRuntimeFilePath(dataDir) {
-  return path5.join(dataDir, "runtime.json");
+  return path6.join(dataDir, "runtime.json");
 }
 async function writeHqRuntimeFile(dataDir, file) {
   const payload = {
@@ -3407,7 +3491,23 @@ async function ensureHqFirstRunAuthFile(dataDir, opts = {}) {
           cookieSecret: mintHqCookieSecret()
         };
         await writeHqAuthFile(dataDir, authFile2);
-        return { authFile: await readHqAuthFile(dataDir, opts), created: false };
+        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 };
@@ -3417,8 +3517,14 @@ async function ensureHqFirstRunAuthFile(dataDir, opts = {}) {
       return { authFile: await readHqAuthFile(dataDir, opts), created: false };
     }
   }
-  const browserToken = { ...mintHqToken("first-run browser"), capabilities: ["control.enqueue"] };
-  const clientToken = { ...mintHqToken("first-run client"), capabilities: ["telemetry.publish"] };
+  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(),
@@ -3430,7 +3536,32 @@ async function ensureHqFirstRunAuthFile(dataDir, opts = {}) {
     authFile.cookieSecret = mintHqCookieSecret();
   }
   await writeHqAuthFile(dataDir, authFile);
-  return { authFile: await readHqAuthFile(dataDir, opts), created: true, browserToken, clientToken };
+  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);
@@ -3474,13 +3605,16 @@ async function verifyHqPassword(password, hash) {
 function mintHqCookieSecret() {
   return randomBytes2(32).toString("base64url");
 }
-function mintHqToken(label) {
-  const now = (/* @__PURE__ */ new Date()).toISOString();
+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: randomUUID3(),
     token: randomUUID3().replace(/-/g, "") + randomUUID3().replace(/-/g, ""),
-    ...label ? { label } : {},
-    createdAt: now
+    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;
@@ -3491,7 +3625,7 @@ function watchHqAuthFile(dataDir, onChange, opts = {}) {
   let closed = false;
   let watcher;
   try {
-    watcher = syncFs.watch(path5.dirname(file), { recursive: false });
+    watcher = syncFs.watch(path6.dirname(file), { recursive: false });
   } catch (err) {
     opts.warn?.(`HQ auth watcher could not start: ${err.message}`);
     return { close: () => {
@@ -3515,7 +3649,7 @@ function watchHqAuthFile(dataDir, onChange, opts = {}) {
   watcher.on("change", (eventType, filename) => {
     const name = typeof filename === "string" ? filename : "";
     if (eventType === "rename" || eventType === "change") {
-      if (!name || name === "auth.json" || name === path5.basename(file)) {
+      if (!name || name === "auth.json" || name === path6.basename(file)) {
         trigger();
       }
     }
@@ -3601,10 +3735,10 @@ function resolveHqConfig(options = {}) {
   };
 }
 function stableMachineId() {
-  return createHash2("sha256").update(hostname()).digest("hex").slice(0, 12);
+  return createHash3("sha256").update(hostname()).digest("hex").slice(0, 12);
 }
 function deriveProjectId(projectRoot) {
-  return createHash2("sha256").update(projectRoot).digest("hex").slice(0, 12);
+  return createHash3("sha256").update(projectRoot).digest("hex").slice(0, 12);
 }
 function createHqPublisherFromEnv(options) {
   const config = options.config ?? resolveHqConfig({ config: options.appConfig?.hq });
@@ -4057,7 +4191,7 @@ function startSessionTelemetryBridge(opts) {
 // src/hq/fleet-bridge.ts
 function startFleetTelemetryBridge(opts) {
   const { events, publisher, runId } = opts;
-  const now = opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const ctx = createBridgeContext(opts);
   let lastHash = "";
   function buildPayload(stats) {
     const subagents = stats.subagentStatuses.map((s) => ({
@@ -4080,21 +4214,20 @@ function startFleetTelemetryBridge(opts) {
     };
   }
   const off = events.on("coordinator.stats", (stats) => {
+    const payload = buildPayload(stats);
+    const hash = JSON.stringify(payload);
+    if (hash === lastHash) return;
+    lastHash = hash;
     try {
-      const payload = buildPayload(stats);
-      const hash = JSON.stringify(payload);
-      if (hash === lastHash) return;
-      lastHash = hash;
       publisher.publishFleetSnapshot(payload, {
-        ...opts.sessionId !== void 0 ? { sessionId: opts.sessionId } : {},
-        timestamp: now()
+        ...ctx.sessionIdTag(),
+        timestamp: ctx.now()
       });
     } catch {
     }
   });
-  return () => {
-    off();
-  };
+  ctx.track(off);
+  return ctx.dispose;
 }
 var FLEET_STATUS_MAP = {
   running: "running",
@@ -4134,27 +4267,22 @@ function extractDecisionFields(dec) {
   return out;
 }
 function startBrainTelemetryBridge(opts) {
-  const { events, publisher } = opts;
-  const now = opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const { events } = opts;
+  const ctx = createBridgeContext(opts);
   function publish(kind, payload, at) {
-    try {
-      const full = { kind, at, ...payload };
-      publisher.publishEvent({
-        type: "brain.event",
-        payload: full,
-        ...opts.sessionId !== void 0 ? { sessionId: opts.sessionId } : {},
-        timestamp: now()
-      });
-    } catch {
-    }
+    ctx.safePublish({
+      type: "brain.event",
+      payload: { kind, at, ...payload },
+      ...ctx.sessionIdTag(),
+      timestamp: ctx.now()
+    });
   }
-  const offs = [];
-  offs.push(
+  ctx.track(
     events.on("brain.decision_requested", (p) => {
       publish("decision_requested", extractRequestFields(p.request), p.at);
     })
   );
-  offs.push(
+  ctx.track(
     events.on("brain.decision_answered", (p) => {
       publish("decision_answered", {
         ...extractRequestFields(p.request),
@@ -4162,7 +4290,7 @@ function startBrainTelemetryBridge(opts) {
       }, p.at);
     })
   );
-  offs.push(
+  ctx.track(
     events.on("brain.decision_ask_human", (p) => {
       publish("decision_ask_human", {
         ...extractRequestFields(p.request),
@@ -4170,7 +4298,7 @@ function startBrainTelemetryBridge(opts) {
       }, p.at);
     })
   );
-  offs.push(
+  ctx.track(
     events.on("brain.decision_denied", (p) => {
       publish("decision_denied", {
         ...extractRequestFields(p.request),
@@ -4178,7 +4306,7 @@ function startBrainTelemetryBridge(opts) {
       }, p.at);
     })
   );
-  offs.push(
+  ctx.track(
     events.on("brain.human_answered", (p) => {
       const detail = typeof p.text === "string" ? p.text : p.optionId;
       publish("human_answered", {
@@ -4188,7 +4316,7 @@ function startBrainTelemetryBridge(opts) {
       }, p.at);
     })
   );
-  offs.push(
+  ctx.track(
     events.on("brain.intervention", (p) => {
       publish("intervention", {
         ...extractRequestFields(p.request),
@@ -4198,29 +4326,22 @@ function startBrainTelemetryBridge(opts) {
       }, p.at);
     })
   );
-  return () => {
-    for (const off of offs) off();
-  };
+  return ctx.dispose;
 }
 
 // src/hq/worktree-bridge.ts
 function startWorktreeTelemetryBridge(opts) {
-  const { events, publisher } = opts;
-  const now = opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
-  function publish(payload, sessionId) {
-    try {
-      publisher.publishEvent({
-        type: "worktree.event",
-        payload,
-        ...sessionId !== void 0 && sessionId !== "" ? { sessionId } : {},
-        ...opts.sessionId !== void 0 ? { sessionId: opts.sessionId } : {},
-        timestamp: now()
-      });
-    } catch {
-    }
+  const { events } = opts;
+  const ctx = createBridgeContext(opts);
+  function publish(payload, eventSessionId) {
+    ctx.safePublish({
+      type: "worktree.event",
+      payload,
+      ...ctx.sessionIdTag(eventSessionId),
+      timestamp: ctx.now()
+    });
   }
-  const offs = [];
-  offs.push(
+  ctx.track(
     events.on("worktree.allocated", (p) => {
       publish(
         {
@@ -4236,7 +4357,7 @@ function startWorktreeTelemetryBridge(opts) {
       );
     })
   );
-  offs.push(
+  ctx.track(
     events.on("worktree.committed", (p) => {
       publish(
         {
@@ -4253,7 +4374,7 @@ function startWorktreeTelemetryBridge(opts) {
       );
     })
   );
-  offs.push(
+  ctx.track(
     events.on("worktree.merged", (p) => {
       publish(
         {
@@ -4268,7 +4389,7 @@ function startWorktreeTelemetryBridge(opts) {
       );
     })
   );
-  offs.push(
+  ctx.track(
     events.on("worktree.conflict", (p) => {
       publish(
         {
@@ -4282,7 +4403,7 @@ function startWorktreeTelemetryBridge(opts) {
       );
     })
   );
-  offs.push(
+  ctx.track(
     events.on("worktree.released", (p) => {
       publish(
         {
@@ -4296,7 +4417,7 @@ function startWorktreeTelemetryBridge(opts) {
       );
     })
   );
-  offs.push(
+  ctx.track(
     events.on("worktree.failed", (p) => {
       publish(
         {
@@ -4310,63 +4431,52 @@ function startWorktreeTelemetryBridge(opts) {
       );
     })
   );
-  return () => {
-    for (const off of offs) off();
-  };
+  return ctx.dispose;
 }
 
 // src/hq/tool-bridge.ts
 function startToolTelemetryBridge(opts) {
   const { events, publisher } = opts;
-  const now = opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const ctx = createBridgeContext(opts);
   const inFlight = /* @__PURE__ */ new Map();
-  function sessionIdTag(sessionId) {
-    const tag = sessionId ?? opts.sessionId;
-    return tag !== void 0 ? { sessionId: tag } : {};
-  }
   const offStarted = events.on("tool.started", (p) => {
     inFlight.set(p.id, { name: p.name, startedAt: Date.now() });
-    try {
-      const payload = {
-        toolName: p.name,
-        ...p.input !== void 0 ? {
-          inputSummary: summarizeHqToolArgs(p.input, {
-            policy: publisher.redactionPolicy,
-            ...opts.projectRoot !== void 0 ? { projectRoot: opts.projectRoot } : {}
-          })
-        } : {}
-      };
-      publisher.publishEvent({
-        type: "tool.started",
-        payload,
-        ...sessionIdTag(p.sessionId),
-        timestamp: now()
-      });
-    } catch {
-    }
+    const payload = {
+      toolName: p.name,
+      ...p.input !== void 0 ? {
+        inputSummary: summarizeHqToolArgs(p.input, {
+          policy: publisher.redactionPolicy,
+          ...opts.projectRoot !== void 0 ? { projectRoot: opts.projectRoot } : {}
+        })
+      } : {}
+    };
+    ctx.safePublish({
+      type: "tool.started",
+      payload,
+      ...ctx.sessionIdTag(p.sessionId),
+      timestamp: ctx.now()
+    });
   });
   const offExecuted = events.on("tool.executed", (p) => {
     const id = p.id;
     if (id !== void 0) inFlight.delete(id);
-    try {
-      const payload = {
-        toolName: p.name,
-        status: p.ok ? "success" : "error",
-        durationMs: p.durationMs,
-        ...p.output !== void 0 && p.output.length > 0 ? { outputSummary: truncateForSummary(p.output, publisher.redactionPolicy) } : {}
-      };
-      publisher.publishEvent({
-        type: "tool.completed",
-        payload,
-        ...sessionIdTag(p.sessionId),
-        timestamp: now()
-      });
-    } catch {
-    }
+    const payload = {
+      toolName: p.name,
+      status: p.ok ? "success" : "error",
+      durationMs: p.durationMs,
+      ...p.output !== void 0 && p.output.length > 0 ? { outputSummary: truncateForSummary(p.output, publisher.redactionPolicy) } : {}
+    };
+    ctx.safePublish({
+      type: "tool.completed",
+      payload,
+      ...ctx.sessionIdTag(p.sessionId),
+      timestamp: ctx.now()
+    });
   });
+  ctx.track(offStarted);
+  ctx.track(offExecuted);
   return () => {
-    offStarted();
-    offExecuted();
+    ctx.dispose();
     inFlight.clear();
   };
 }
@@ -4381,38 +4491,35 @@ function truncateForSummary(output, policy, max = 280) {
 
 // src/hq/cost-bridge.ts
 function startCostTelemetryBridge(opts) {
-  const { events, publisher } = opts;
-  const now = opts.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  const { events } = opts;
+  const ctx = createBridgeContext(opts);
   const off = events.on("token.accounted", (p) => {
-    try {
-      const payload = {
-        inputTokens: p.usage.input,
-        outputTokens: p.usage.output,
-        totalTokens: p.usage.input + p.usage.output,
-        costUsd: p.cost.total
-      };
-      if (p.provider !== void 0) payload.provider = p.provider;
-      if (p.model !== void 0) payload.model = p.model;
-      if (p.usage.cacheRead !== void 0) payload.cacheRead = p.usage.cacheRead;
-      if (p.usage.cacheWrite !== void 0) payload.cacheWrite = p.usage.cacheWrite;
-      const sessionId = opts.sessionId ?? p.sessionId;
-      publisher.publishEvent({
-        type: "session.usage",
-        payload,
-        ...sessionId !== void 0 ? { sessionId } : {},
-        timestamp: now()
-      });
-    } catch {
-    }
+    const usage = p.deltaUsage ?? p.usage;
+    const payload = {
+      inputTokens: usage.input,
+      outputTokens: usage.output,
+      totalTokens: usage.input + usage.output,
+      costUsd: p.cost.total
+    };
+    if (p.provider !== void 0) payload.provider = p.provider;
+    if (p.model !== void 0) payload.model = p.model;
+    if (usage.cacheRead !== void 0) payload.cacheRead = usage.cacheRead;
+    if (usage.cacheWrite !== void 0) payload.cacheWrite = usage.cacheWrite;
+    const sessionId = opts.sessionId ?? p.sessionId;
+    ctx.safePublish({
+      type: "session.usage",
+      payload,
+      ...sessionId !== void 0 ? { sessionId } : {},
+      timestamp: ctx.now()
+    });
   });
-  return () => {
-    off();
-  };
+  ctx.track(off);
+  return ctx.dispose;
 }
 
 // src/hq/persistence.ts
 import * as fs6 from "node:fs/promises";
-import * as path6 from "node:path";
+import * as path7 from "node:path";
 var DEFAULT_EVENT_LOG_MAX_LINES = 5e4;
 var DEFAULT_EVENT_LOG_ROTATE_KEEP = 2e4;
 var HqEventLog = class {
@@ -4423,7 +4530,7 @@ var HqEventLog = class {
   lineCount = 0;
   counted = false;
   constructor(opts) {
-    this.filePath = path6.join(opts.dataDir, "events.jsonl");
+    this.filePath = path7.join(opts.dataDir, "events.jsonl");
     this.maxLines = opts.maxLines ?? DEFAULT_EVENT_LOG_MAX_LINES;
     this.rotateKeep = opts.rotateKeep ?? DEFAULT_EVENT_LOG_ROTATE_KEEP;
   }
@@ -4507,7 +4614,7 @@ var HqSnapshotStore = class {
   filePath;
   writeChain = Promise.resolve();
   constructor(opts) {
-    this.filePath = path6.join(opts.dataDir, "snapshot.json");
+    this.filePath = path7.join(opts.dataDir, "snapshot.json");
   }
   /** Persist a snapshot. Best-effort, never rejects. */
   save(snapshot) {
@@ -4536,7 +4643,7 @@ var HqTimeseriesStore = class {
   buckets = /* @__PURE__ */ new Map();
   flushChain = Promise.resolve();
   constructor(opts) {
-    this.filePath = path6.join(opts.dataDir, "timeseries.jsonl");
+    this.filePath = path7.join(opts.dataDir, "timeseries.jsonl");
     this.bucketMs = opts.bucketMs ?? 5 * 60 * 1e3;
     this.maxBuckets = opts.maxBuckets ?? 2016;
   }
@@ -4655,7 +4762,7 @@ var HqSimpleLog = class {
   filePath;
   writeChain = Promise.resolve();
   constructor(dataDir, filename) {
-    this.filePath = path6.join(dataDir, filename);
+    this.filePath = path7.join(dataDir, filename);
   }
   /** Append one record as a JSON line. Best-effort, never rejects. */
   append(record) {
@@ -4825,7 +4932,8 @@ var HqCommandAuditLog = class {
 var DEFAULT_CONFIG = {
   costThresholdUsd: 50,
   staleMachineSeconds: 120,
-  maxAgents: 0
+  maxAgents: 0,
+  tokenExpiryWarningHours: 24
 };
 function resolveConfig(config) {
   return { ...DEFAULT_CONFIG, ...config ?? {} };
@@ -4882,6 +4990,27 @@ var RULES = [
       }
       return null;
     }
+  },
+  {
+    id: "token-expired-present",
+    severity: "error",
+    evaluate: (snapshot) => {
+      if (snapshot === null) return null;
+      const stats = snapshot.totals.tokenStats;
+      if (stats === void 0 || stats.expired <= 0) return null;
+      return `${stats.expired} expired token(s) filtered from live auth \u2014 rotate or revoke them`;
+    }
+  },
+  {
+    id: "token-expiry-imminent",
+    severity: "warn",
+    evaluate: (snapshot, config) => {
+      if (snapshot === null) return null;
+      if (config.tokenExpiryWarningHours <= 0) return null;
+      const stats = snapshot.totals.tokenStats;
+      if (stats === void 0 || stats.expiringSoon <= 0) return null;
+      return `${stats.expiringSoon} token(s) expire within ${config.tokenExpiryWarningHours}h \u2014 mint replacements before they lapse`;
+    }
   }
 ];
 var HqAlertEngine = class {
@@ -4987,6 +5116,7 @@ function toAlertMessage(alert) {
 }
 export {
   DEFAULT_HQ_REDACTION_POLICY,
+  HQ_AUTH_CONTENT_HASH_REDACTED,
   HQ_AUTH_FILE_VERSION,
   HQ_CLI_DEFAULT_HOST,
   HQ_COMMAND_TYPES,
@@ -5000,9 +5130,11 @@ export {
   HqSimpleLog,
   HqSnapshotStore,
   HqTimeseriesStore,
+  appendHqAuthAudit,
   assessHqExposure,
   buildTranscriptFromEvents,
   classifyMailboxRecipient,
+  createBridgeContext,
   createGlobalMailbox,
   createHqEventEnvelope,
   createHqPersistence,
@@ -5015,10 +5147,14 @@ export {
   emptyHqAuthFile,
   ensureHqFirstRunAuthFile,
   hashHqPassword,
+  hqAuthAuditPath,
+  hqAuthContentHash,
   hqAuthFilePath,
   hqRuntimeFilePath,
   isLoopbackHost,
   isOpenMode,
+  isTokenExpired,
+  logHqAuthAudit,
   mapMailboxAgentToHqSummary,
   mapMailboxMessageToHqSummary,
   mapSessionEventToEntries,