@wrongstack/cli 1.0.10 → 1.0.12

package/dist/{cli-main-BU5DEHDO.js → cli-main-6LMQSS66.js}

@@ -6,7 +6,7 @@ import {
   removeSuggestions,
   runGit,
   setSuggestions
-} from "./chunk-SXJTVNWF.js";
+} from "./chunk-OWNC7LMD.js";
 import {
   setupPlugins
 } from "./chunk-XJ7K67PP.js";
@@ -102,7 +102,7 @@ import {
   runAuthLocal,
   runProviderAuthLogin,
   validateFamily
-} from "./chunk-FSZ5QU3M.js";
+} from "./chunk-RDHFXOJM.js";
 import "./chunk-2VMJ3E5Z.js";
 import {
   appendHistory
@@ -116,7 +116,7 @@ import {
 } from "./chunk-YMXXOOFN.js";
 import {
   parseSpawnFlags
-} from "./chunk-EK2P53GL.js";
+} from "./chunk-C3Z4N6A6.js";
 import "./chunk-SIGUWXAA.js";
 import "./chunk-DAKVBMD4.js";
 import {
@@ -6231,7 +6231,7 @@ async function runCliExecution(params) {
     governanceHandle,
     setConfig
   } = params;
-  const { execute } = await import("./execution-4RXQLDAF.js");
+  const { execute } = await import("./execution-EXDRBS4F.js");
   return execute(
     toExecuteDeps({
       core: {
@@ -8419,6 +8419,7 @@ ${diff}`;
 }
 
 // src/services/mcp-management.ts
+import { resolveMcpServerConfig } from "@wrongstack/core/infrastructure";
 import {
   color as color7,
   expectDefined as expectDefined4,
@@ -8534,7 +8535,7 @@ async function runAdd(name, enable, configured, configPath, mcpRegistry, all) {
   }
   try {
     if (mcpRegistry.list().some((server) => server.name === name)) {
-      await mcpRegistry.restart(name);
+      await mcpRegistry.restart(name, { ...nextCfg, name });
     } else {
       await mcpRegistry.start(nextCfg);
     }
@@ -8572,24 +8573,21 @@ async function runRemove(name, configured, configPath, mcpRegistry) {
 async function runEnable(name, configured, configPath, mcpRegistry) {
   const cfg = configured[name];
   if (!cfg) return `Server "${name}" is not in config. Run \`/mcp add ${name} --enable\` first.`;
+  const resolved = resolveMcpServerConfig(name, cfg);
+  if (!resolved) return `Server "${name}" has no transport and matches no preset.`;
+  const startCfg = { ...resolved, enabled: true };
+  const registered = mcpRegistry.list().some((server) => server.name === name);
   if (cfg.enabled !== false) {
-    try {
-      await mcpRegistry.restart(name);
-      return `${color7.green("\u25CF")} "${name}" is already enabled and running.`;
-    } catch {
-      await mcpRegistry.start({ ...cfg, enabled: true });
-      return `${color7.green("Enabled")} "${name}" and started.`;
-    }
+    if (registered) await mcpRegistry.restart(name, startCfg);
+    else await mcpRegistry.start(startCfg);
+    return `${color7.green("\u25CF")} "${name}" is already enabled and running.`;
   }
   await updateJsonObjectFile(configPath, (full) => {
     const current = isMcpServerRecord(full.mcpServers) ? full.mcpServers : {};
     setJsonPath(full, ["mcpServers", name], { ...cfg, ...current[name], enabled: true });
   });
-  try {
-    await mcpRegistry.restart(name);
-  } catch {
-    await mcpRegistry.start({ ...cfg, enabled: true });
-  }
+  if (registered) await mcpRegistry.restart(name, startCfg);
+  else await mcpRegistry.start(startCfg);
   return `${color7.green("Enabled")} "${name}" and started.`;
 }
 async function runDisable(name, configured, configPath, mcpRegistry) {
@@ -8642,6 +8640,8 @@ function stateBadge(state) {
       return color7.dim("\u25CB disconnected");
     case "failed":
       return color7.red("\u2717 failed");
+    case "dormant":
+      return color7.dim("\u25CC dormant (spawns on first call)");
     default:
       return color7.dim(state);
   }
@@ -8781,7 +8781,7 @@ async function checkUncommittedChanges(projectRoot) {
       stdout += data;
     });
     child.on("error", reject);
-    child.on("close", (code) => resolve9({ stdout, code: code ?? 0 }));
+    child.on("close", (code) => resolve9({ stdout, code: code ?? 1 }));
   });
   if (!result.stdout.trim()) return void 0;
   const count = result.stdout.split("\n").filter(Boolean).length;
@@ -11230,10 +11230,10 @@ function buildCodebaseMapCommand(opts) {
       const check = /(^|\s)--check(\s|$)/.test(text);
       const enrich = /(^|\s)--enrich(\s|$)/.test(text);
       const embed = /(^|\s)--embed(\s|$)/.test(text);
-      const exportMatch = /(^|\s)--export(?:[= ]([^\s]+))?(\s|$)/.exec(text);
+      const exportMatch = /(^|\s)--export(?:[= ]([^\s-][^\s]*))?(\s|$)/.exec(text);
       const maxFilesMatch = /--max-files[= ](\d+)/.exec(text);
       const tokensMatch = /--tokens[= ](\d+)/.exec(text);
-      const maxTokens = tokensMatch ? Number(tokensMatch[1]) : void 0;
+      const maxTokens = tokensMatch ? Math.min(Math.max(Number(tokensMatch[1]), MIN_MAP_TOKENS), MAX_MAP_TOKENS) : void 0;
       const projectRoot = opts.projectRoot;
       try {
         if (embed) {
@@ -11321,6 +11321,8 @@ function buildCodebaseMapCommand(opts) {
   };
 }
 var DEFAULT_EXPORT_FILE = "atlas.html";
+var MIN_MAP_TOKENS = 100;
+var MAX_MAP_TOKENS = 2e4;
 function noIndexMessage() {
   return color17.yellow(
     `No codebase index for this project yet. Run ${color17.bold("/codebase-reindex")} first.`
@@ -11405,14 +11407,17 @@ function buildCodebaseReindexCommand(opts) {
       "refresh \u2014 e.g. after a large branch switch, merge, or external edit."
     ].join("\n"),
     async run(args, _ctx) {
-      const force = /\b(force|--force|-f)\b/.test(args.trim());
+      const force = /(^|\s)(force|--force|-f)(\s|$)/.test(args.trim());
       opts.renderer.write(color18.dim(`${force ? "Rebuilding" : "Reindexing"} codebase index\u2026
 `));
       try {
         resetIndexCircuitBreaker();
         const r = await runStartupIndex({ projectRoot: opts.projectRoot, force });
-        const summary = `${color18.green("\u2713")} codebase index ${force ? "rebuilt" : "updated"} ` + color18.dim(`\u2014 ${r.symbolsIndexed} symbols \xB7 ${r.filesIndexed} files \xB7 ${r.durationMs}ms`) + (r.errors.length ? `
-${color18.yellow(`  ${r.errors.length} file(s) had errors`)}` : "");
+        const outcomes = r.fileOutcomes;
+        const fileSummary = outcomes ? `${outcomes.parsed} parsed \xB7 ${outcomes.skipped} unchanged` + (outcomes.failed > 0 ? ` \xB7 ${outcomes.failed} failed` : "") : `${r.filesIndexed} files`;
+        const summary = `${color18.green("\u2713")} codebase index ${force || r.autoRecovered ? "rebuilt" : "updated"} ` + color18.dim(`\u2014 ${r.symbolsIndexed} symbols \xB7 ${fileSummary} \xB7 ${r.durationMs}ms`) + (r.autoRecovered ? `
+${color18.yellow("  corrupt index detected \u2014 rebuilt from scratch")}` : "") + (r.errors.length ? `
+${color18.yellow(`  ${r.errors.length} error(s) reported`)}` : "");
         return { message: summary };
       } catch (err) {
         const msg = `${color18.red("Codebase reindex failed:")} ${toErrorMessage7(err)}`;
@@ -28231,7 +28236,7 @@ async function runGit2(args, cwd) {
       stdout += d;
     });
     child.on("error", () => resolve9({ stdout, code: 1 }));
-    child.on("close", (code) => resolve9({ stdout, code: code ?? 0 }));
+    child.on("close", (code) => resolve9({ stdout, code: code ?? 1 }));
   });
 }
 async function getChangedFiles(cwd) {
@@ -34711,7 +34716,7 @@ import * as path29 from "node:path";
 import { getSharedProjectMailbox as getSharedProjectMailbox10 } from "@wrongstack/core/coordination";
 import { CouncilOrchestrator, OneShotOrchestrator as OneShotOrchestrator3 } from "@wrongstack/core/execution";
 import { countShellHooks, HookRegistry as HookRegistry2, HookRunner as HookRunner2, shellHooksEqual } from "@wrongstack/core/hooks";
-import { allServers as allServers3 } from "@wrongstack/core/infrastructure";
+import { resolveMcpServerConfig as resolveMcpServerConfig2 } from "@wrongstack/core/infrastructure";
 import { TOKENS as TOKENS11 } from "@wrongstack/core/kernel";
 import { NotifierImpl } from "@wrongstack/core/notifications";
 import {
@@ -35781,18 +35786,23 @@ async function setupLifecycleAndPlugins(deps) {
     log: logger,
     lazyMode: normalizeTokenSavingTier5(config.features.tokenSavingMode) !== "off",
     cacheDir: wpaths.cacheDir,
+    // Presets say `--project-root .`; resolve it against the project, not
+    // wherever this process happens to be running.
+    cwd: wpaths.projectRoot,
     authorizationProviderFactory: createVaultBackedMcpAuthorizationProviderFactory({
       store: mcpTokenStore
     }),
     authorizationManager: mcpAuthorizationManager
   });
   if (config.features.mcp) {
-    const presets = allServers3();
-    for (const cfg of Object.values(config.mcpServers ?? {})) {
-      const preset = presets[cfg.name];
-      const merged = preset ? { ...preset, ...cfg } : cfg;
-      void mcpRegistry.start(merged).catch((err) => {
-        logger.warn(`MCP server "${cfg.name}" failed to start`, err);
+    for (const [name, entry] of Object.entries(config.mcpServers ?? {})) {
+      const resolved = resolveMcpServerConfig2(name, entry);
+      if (!resolved) {
+        logger.warn(`MCP server "${name}" has no transport and matches no preset \u2014 skipped`);
+        continue;
+      }
+      void mcpRegistry.start(resolved).catch((err) => {
+        logger.warn(`MCP server "${name}" failed to start`, err);
       });
     }
   }
@@ -36683,7 +36693,38 @@ import {
   setContextQueryEmbedder,
   shutdownCodebaseIndexHost
 } from "@wrongstack/tools";
-var FILE_EDIT_TOOLS = /* @__PURE__ */ new Set(["write", "edit"]);
+function editedFilePaths(toolName2, input, cwd) {
+  const args = input ?? {};
+  const resolve9 = (value, base = cwd) => typeof value === "string" && value.length > 0 ? [path30.resolve(base, value)] : [];
+  switch (toolName2) {
+    case "write":
+    case "edit":
+      return resolve9(args["path"]);
+    case "codebase-ast-replace":
+      return resolve9(args["file"]);
+    case "format": {
+      if (args["check"] === true) return [];
+      const files = args["files"];
+      const base = typeof args["cwd"] === "string" ? path30.resolve(cwd, args["cwd"]) : cwd;
+      return (Array.isArray(files) ? files : [files]).flatMap((file) => resolve9(file, base));
+    }
+    case "patch": {
+      if (args["dry_run"] === true || typeof args["patch"] !== "string") return [];
+      const base = typeof args["directory"] === "string" ? path30.resolve(cwd, args["directory"]) : cwd;
+      const strip = typeof args["strip"] === "number" ? args["strip"] : 1;
+      const out = /* @__PURE__ */ new Set();
+      for (const match of args["patch"].matchAll(/^(?:\+\+\+|---) ([^\t\r\n]+)/gm)) {
+        const header = (match[1] ?? "").trim().replace(/^"(.*)"$/, "$1");
+        if (!header || header === "/dev/null") continue;
+        const stripped = header.split("/").slice(strip).join("/");
+        if (stripped) out.add(path30.resolve(base, stripped));
+      }
+      return [...out];
+    }
+    default:
+      return [];
+  }
+}
 async function setupCodebaseIndexing(deps) {
   const { config, context, pipelines, projectRoot, logger } = deps;
   const idx = config.indexing;
@@ -36722,16 +36763,17 @@ async function setupCodebaseIndexing(deps) {
       handler: async (payload, next) => {
         try {
           const tool = payload.tool;
-          if (tool?.mutating && FILE_EDIT_TOOLS.has(tool.name) && !payload.result.is_error) {
-            const fp = payload.toolUse.input?.path;
-            if (typeof fp === "string" && fp.length > 0) {
-              const activeRoot = payload.ctx.projectRoot;
-              const abs = path30.resolve(payload.ctx.cwd, fp);
-              const rel = path30.relative(activeRoot, abs);
-              const inside = rel !== ".." && !rel.startsWith(`..${path30.sep}`) && !path30.isAbsolute(rel);
-              if (inside && isIndexableFile(abs)) {
-                enqueueReindex({ projectRoot: activeRoot, files: [abs], debounceMs, onError });
+          if (tool && !payload.result.is_error) {
+            const activeRoot = payload.ctx.projectRoot;
+            const files = editedFilePaths(tool.name, payload.toolUse.input, payload.ctx.cwd).filter(
+              (abs) => {
+                const rel = path30.relative(activeRoot, abs);
+                const inside = rel !== ".." && !rel.startsWith(`..${path30.sep}`) && !path30.isAbsolute(rel);
+                return inside && isIndexableFile(abs);
               }
+            );
+            if (files.length > 0) {
+              enqueueReindex({ projectRoot: activeRoot, files, debounceMs, onError });
             }
           }
         } catch {
@@ -38950,4 +38992,4 @@ export {
   CLI_VERSION,
   runInteractive
 };
-//# sourceMappingURL=cli-main-BU5DEHDO.js.map
+//# sourceMappingURL=cli-main-6LMQSS66.js.map

package/dist/{diag-doctor-PCER6KHH.js → diag-doctor-ANPRUYFM.js}

@@ -13,6 +13,7 @@ import {
 import * as fs2 from "node:fs/promises";
 import * as os from "node:os";
 import * as path2 from "node:path";
+import { resolveMcpServerConfig } from "@wrongstack/core/infrastructure";
 import { color, toErrorMessage } from "@wrongstack/core/utils";
 import {
   applyProxyConfig,
@@ -328,8 +329,17 @@ var doctorCmd = async (args, deps) => {
     });
   }
   const mcpEntries = Object.entries(cfg.mcpServers ?? {});
-  for (const [name, srv] of mcpEntries) {
-    if (!srv.enabled) continue;
+  for (const [name, entry] of mcpEntries) {
+    if (entry.enabled === false) continue;
+    const srv = resolveMcpServerConfig(name, entry);
+    if (!srv) {
+      checks.push({
+        name: `mcp:${name}`,
+        status: "fail",
+        detail: "no transport and no built-in preset of this name"
+      });
+      continue;
+    }
     if ((srv.transport === "sse" || srv.transport === "streamable-http") && !srv.url)
       checks.push({ name: `mcp:${name}`, status: "fail", detail: "transport requires url" });
     else if (srv.transport === "stdio" && !srv.command)
@@ -382,4 +392,4 @@ export {
   doctorCmd,
   proxyCmd
 };
-//# sourceMappingURL=diag-doctor-PCER6KHH.js.map
+//# sourceMappingURL=diag-doctor-ANPRUYFM.js.map

package/dist/{execution-4RXQLDAF.js → execution-EXDRBS4F.js}

@@ -4,7 +4,7 @@ import {
   runGit,
   setAutoSuggestions,
   setSuggestions
-} from "./chunk-SXJTVNWF.js";
+} from "./chunk-OWNC7LMD.js";
 import {
   deriveFsAccessPair,
   filterSafeForProject,
@@ -6953,4 +6953,4 @@ export {
   execute,
   resolveReviewerFallbackModels
 };
-//# sourceMappingURL=execution-4RXQLDAF.js.map
+//# sourceMappingURL=execution-EXDRBS4F.js.map

package/dist/{hq-DQTUE7RC.js → hq-NO2NWGU4.js}

@@ -14,9 +14,11 @@ import {
 
 // src/subcommands/handlers/hq.ts
 import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import {
   HQ_AUTH_FILE_VERSION,
   HQ_CLI_DEFAULT_HOST,
+  HqAlertEngine,
   HqInsecureExposureError,
   hqAuthAuditPath,
   hqAuthContentHash,
@@ -25,6 +27,7 @@ import {
   logHqAuthAudit,
   mintHqToken,
   mutateHqAuthFile,
+  readHqAlertsConfig,
   readHqAuthFile,
   resolveHqDataDir
 } from "@wrongstack/core/hq";
@@ -48,6 +51,9 @@ var hqCmd = async (args, deps) => {
   if (sub === "audit") {
     return hqAuditCmd(args.slice(1), deps);
   }
+  if (sub === "alerts") {
+    return hqAlertsCmd(args.slice(1), deps);
+  }
   if (sub === "service") {
     const { hqServiceCmd } = await import("./hq-service-L5INQFM4.js");
     return hqServiceCmd(args.slice(1), deps);
@@ -62,7 +68,7 @@ var hqCmd = async (args, deps) => {
   return 1;
 };
 async function startServer(deps) {
-  const { startHqServer } = await import("./hq-server-JJFGFWI5.js");
+  const { startHqServer } = await import("./hq-server-KE5YDNGG.js");
   const dataDir = resolveDataDir(deps);
   const flags = deps.flags ?? {};
   const rawPublicUrl = typeof flags["hq-public-url"] === "string" ? flags["hq-public-url"] : process.env.WRONGSTACK_HQ_PUBLIC_URL;
@@ -188,7 +194,7 @@ async function startServer(deps) {
     ipAllowlist === void 0 ? "Network allowlist: disabled (authentication remains required when configured).\n" : `Network allowlist: active (${ipAllowlist.length} configured rule${ipAllowlist.length === 1 ? "" : "s"} + loopback).
 `
   );
-  await new Promise((resolve) => {
+  await new Promise((resolve2) => {
     const shutdown = async () => {
       try {
         await handle.close();
@@ -196,7 +202,7 @@ async function startServer(deps) {
         deps.renderer.write(`HQ server close error: ${String(err)}
 `);
       }
-      resolve();
+      resolve2();
     };
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
@@ -807,7 +813,7 @@ function printAuditHelp(deps) {
 `
   );
   deps.renderer.write(
-    `                           auth.json and print it so an operator can compare
+    `                           on-disk auth.json and print it so an operator can compare
 `
   );
   deps.renderer.write(
@@ -825,8 +831,150 @@ function printAuditHelp(deps) {
   deps.renderer.write(`Run \`wstack hq --help\` for the full HQ command list.
 `);
 }
+async function hqAlertsCmd(args, deps) {
+  const action = args[0];
+  if (deps.flags?.["help"] === true || action === "help" || action === "--help") {
+    printAlertsHelp(deps);
+    return 0;
+  }
+  if (action === "eval" || action === void 0) {
+    return hqAlertsEval(args.slice(1), deps);
+  }
+  deps.renderer.writeError(`Unknown hq alerts subcommand: ${action ?? "(none)"}
+`);
+  printAlertsHelp(deps);
+  return 1;
+}
+async function hqAlertsEval(_args, deps) {
+  const flags = deps.flags ?? {};
+  const snapshotArg = typeof flags["snapshot"] === "string" ? flags["snapshot"] : void 0;
+  let snapshotPath;
+  try {
+    if (snapshotArg !== void 0) {
+      snapshotPath = path.resolve(snapshotArg);
+    } else {
+      const dataDir2 = resolveDataDir(deps);
+      snapshotPath = path.join(dataDir2, "snapshot.json");
+    }
+  } catch (err) {
+    deps.renderer.writeError(`Failed to resolve snapshot path: ${err.message}
+`);
+    return 2;
+  }
+  let raw;
+  try {
+    raw = await fs.readFile(snapshotPath, "utf8");
+  } catch (err) {
+    deps.renderer.writeError(
+      `Cannot read snapshot at ${snapshotPath}: ${err.message}
+Pass --snapshot <path> to evaluate against a specific file.
+`
+    );
+    return 2;
+  }
+  let snapshot;
+  try {
+    snapshot = JSON.parse(raw);
+  } catch (err) {
+    deps.renderer.writeError(
+      `Snapshot at ${snapshotPath} is not valid JSON: ${err.message}
+`
+    );
+    return 2;
+  }
+  const dataDir = resolveDataDir(deps);
+  let thresholds;
+  try {
+    const config = await readHqAlertsConfig(dataDir);
+    thresholds = config.thresholds;
+  } catch {
+  }
+  const engine = new HqAlertEngine({
+    onAlert: () => {
+    }
+  });
+  let fired;
+  try {
+    fired = engine.evaluate(snapshot, thresholds);
+  } catch (err) {
+    deps.renderer.writeError(`Alert evaluation failed: ${err.message}
+`);
+    return 2;
+  }
+  if (fired.length === 0) {
+    deps.renderer.write(`No alert rules fired against ${snapshotPath}.
+`);
+    if (thresholds === void 0) {
+      deps.renderer.write(
+        "(No persisted thresholds; using built-in defaults. Run `wstack hq alerts` with a populated alerts-config.json to override.)\n"
+      );
+    }
+    return 0;
+  }
+  deps.renderer.write(`${fired.length} alert rule(s) fired against ${snapshotPath}:
+`);
+  for (const alert of fired) {
+    deps.renderer.write(`  [${alert.severity}] ${alert.ruleId}: ${alert.message}
+`);
+  }
+  return 1;
+}
+function printAlertsHelp(deps) {
+  deps.renderer.write(`Usage: wstack hq alerts <eval>
+`);
+  deps.renderer.write("\n");
+  deps.renderer.write(
+    `  wstack hq alerts eval [--snapshot <path>]   Run HqAlertEngine.evaluate() against a
+`
+  );
+  deps.renderer.write(
+    `                                            snapshot file (or the live <dataDir>/
+`
+  );
+  deps.renderer.write(
+    `                                            snapshot.json). Pure-function dry run;
+`
+  );
+  deps.renderer.write(
+    `                                            no server required. Exits 0 when no
+`
+  );
+  deps.renderer.write(
+    `                                            rules fire, 1 when rules fire, 2 on errors.
+`
+  );
+  deps.renderer.write("\n");
+  deps.renderer.write(
+    `Persisted thresholds (<dataDir>/alerts-config.json) are loaded automatically when
+`
+  );
+  deps.renderer.write(
+    `present; otherwise the engine's built-in defaults apply. Snoozes are NOT honored
+`
+  );
+  deps.renderer.write(
+    `by this command \u2014 eval is a "what would fire RIGHT NOW if there were no snoozes"
+`
+  );
+  deps.renderer.write(`probe.
+`);
+  deps.renderer.write("\n");
+  deps.renderer.write(`Flags:
+`);
+  deps.renderer.write(
+    `  --snapshot <path>   Evaluate against this snapshot file instead of the live one.
+`
+  );
+  deps.renderer.write(
+    `  --data-dir <path>   Override HQ data directory (default ~/.wrongstack/hq).
+`
+  );
+  deps.renderer.write("\n");
+  deps.renderer.write(`Run \`wstack hq --help\` for the full HQ command list.
+`);
+}
 export {
   hqCmd,
   resolveAuditActor
 };
-//# sourceMappingURL=hq-DQTUE7RC.js.map
+//# sourceMappingURL=hq-NO2NWGU4.js.map

package/dist/hq-server/auth-state.d.ts

@@ -26,6 +26,17 @@ interface HqAuthStateOptions {
      * makes the latch unconditional.
      */
     onApplied?: ((mutableAuth: HqRouterMutableAuth) => void) | undefined;
+    /**
+     * Invoked when browser tokens stopped being live — revoked by hand, or aged
+     * out — during an {@link HqAuthState.apply}. `keys` are the stored verifiers,
+     * `ids` the token ids of those that had one.
+     *
+     * W4 #15: an open WebSocket never re-presents its credential, so before this
+     * a revoked operator kept a working dashboard until the idle-eviction pass
+     * happened to catch them. Reporting the change at the single projection
+     * choke point is what lets the server close those sockets immediately.
+     */
+    onTokensRevoked?: ((keys: readonly string[], ids: readonly string[]) => void) | undefined;
 }
 /**
  * Project an `auth.json` document onto the live `mutableAuth` used by every

package/dist/hq-server/mailbox-gateway-health.d.ts

@@ -0,0 +1,67 @@
+/**
+ * W2 #14 (RFC hq-improvements-2026-09.md): Mailbox gateway health types.
+ *
+ * These types are the wire contract for `/api/health/mailbox`. They live in
+ * their own module so both the gateway manager (producer) and the HTTP
+ * handler (consumer) can import them without a circular dependency.
+ *
+ * Critical contract (from SAGE memory, surfaced multiple times in this work):
+ *
+ *   - Mailbox credential `projectId` is the **basename** of the project
+ *     directory, not the full path. `mailbox-serve.ts:192` derives it via
+ *     `path.basename(projectDir)`. The dashboard MUST render `projectId`
+ *     from this surface so it matches what other mailbox surfaces see.
+ *
+ *   - HQ's `MailboxGatewayManager` binds gateways with the **full filesystem
+ *     path** (from `resolveHqProjectRoot(...)` in `mailbox-handlers.ts:90`).
+ *     We surface the full path as `projectRoot` so operators can debug
+ *     path-mismatch issues without grepping the source.
+ *
+ *   - HQ never attaches a `MailboxActorContext` to its mailbox authorization
+ *     decisions (see `authorizeMailboxGateway` in `mailbox-gateway-manager.ts:57-96`).
+ *     The aggregate `actorAttached: false` flag surfaces this truth so the
+ *     dashboard can render "no actor context" honestly.
+ *
+ * @module hq-server/mailbox-gateway-health
+ */
+/**
+ * One mailbox gateway entry — one per bound `projectDir` in the manager.
+ */
+export interface HqMailboxGatewayHealthEntry {
+    /**
+     * Credential contract key: `path.basename(projectRoot)`. Matches the
+     * `projectId` used by `mailbox-serve.ts` and other mailbox surfaces.
+     */
+    projectId: string;
+    /** Full filesystem path the gateway is bound to. */
+    projectRoot: string;
+    /** Whether the gateway has any open HTTP streams right now. */
+    hasActiveStreams: boolean;
+    /** Epoch ms of the last `getMailboxGateway` / `authorizeMailboxGateway` hit, or null if never used. */
+    lastUsedAt: number | null;
+    /** Convenience: `Date.now() - lastUsedAt`, or null when `lastUsedAt` is null. */
+    idleForMs: number | null;
+}
+/**
+ * Aggregate health snapshot for the HQ cockpit "Mailbox gateway" card.
+ */
+export interface HqMailboxGatewayHealth {
+    /** Total number of bound gateways. */
+    gatewayCount: number;
+    /** Whether the rate limiter is configured. Always `true` on the HQ mount. */
+    rateLimiterConfigured: boolean;
+    /**
+     * Whether the gateway manager attaches a `MailboxActorContext` to its
+     * authorization decisions. HQ is a read-mostly operator dashboard and
+     * never attaches one — this flag is `false` on the HQ mount and is
+     * surfaced so the dashboard can render the truthful state.
+     */
+    actorAttached: boolean;
+    /** Per-gateway health entries, sorted by `projectId` for stable rendering. */
+    gateways: readonly HqMailboxGatewayHealthEntry[];
+    /** Idle-eviction sweep interval in ms (mirrors the manager's private constant). */
+    sweepIntervalMs: number;
+    /** Idle TTL after which a gateway is eligible for eviction. */
+    idleTtlMs: number;
+}
+//# sourceMappingURL=mailbox-gateway-health.d.ts.map

package/dist/hq-server/mailbox-gateway-manager.d.ts

@@ -6,6 +6,7 @@
 import type { IncomingMessage } from 'node:http';
 import { type MailboxHttpAccessDecision, MailboxHttpRateLimiter } from '@wrongstack/core/coordination';
 import type { HqAuthState } from './auth-state.js';
+import type { HqMailboxGatewayHealth } from './mailbox-gateway-health.js';
 import { type HqRouterMailboxGateway } from './routes.js';
 import type { HqSessionEntry } from './types.js';
 interface MailboxGatewayManagerDeps {
@@ -27,6 +28,43 @@ export declare class MailboxGatewayManager {
     authorizeMailboxGateway(req: IncomingMessage, projectDir: string): MailboxHttpAccessDecision;
     getMailboxGateway(projectDir: string): HqRouterMailboxGateway;
     private evictIdleGateways;
+    /**
+     * W2 #14 (RFC hq-improvements-2026-09.md): health snapshot for the cockpit
+     * "Mailbox gateway" card.
+     *
+     * Per-gateway entry surfaces the three diagnostic facts an operator
+     * needs:
+     *
+     *   - `projectId`: the **basename** of the project directory, matching
+     *     the credential contract used by `mailbox-serve.ts:192` (where
+     *     `path.basename(projectDir)` is the `projectId` key for mailbox
+     *     data). HQ binds the gateway with the full filesystem path
+     *     (`resolveHqProjectRoot(...)` from `mailbox-handlers.ts:90`), so
+     *     reporting the basename here means the dashboard's projectId
+     *     matches what other mailbox surfaces see.
+     *   - `projectRoot`: the full filesystem path the manager actually
+     *     binds against. Surfaced separately so operators can debug
+     *     path-mismatch issues without grepping the source.
+     *   - `hasActiveStreams`: whether the gateway has any open HTTP streams
+     *     right now. A gateway with `false` is a candidate for the next
+     *     idle eviction; one with `true` is being watched.
+     *   - `lastUsedAt`: epoch ms of the most recent `getMailboxGateway()`
+     *     call (or the last `authorizeMailboxGateway` hit that resolved to
+     *     this gateway). Surfaced so the dashboard can render the same
+     *     "fresh / quiet / stale" staleness buckets the publisher health
+     *     tile uses.
+     *   - `idleForMs`: convenience — `Date.now() - lastUsedAt`. `Infinity`
+     *     when the gateway was never used (shouldn't happen, since
+     *     `getMailboxGateway` always stamps `mailboxGatewayLastUsed`).
+     *
+     * The aggregate `actor` field is **explicitly absent** on the HQ mount:
+     * `authorizeMailboxGateway` (L57-96) never attaches a `MailboxActorContext`
+     * to its decision, because HQ is a read-mostly operator dashboard, not
+     * a producer-side mailbox client. We surface this truth with a stable
+     * `actorAttached: false` so the dashboard can render "no actor
+     * context" honestly rather than papering over it.
+     */
+    getHealth(): HqMailboxGatewayHealth;
     close(): void;
 }
 export {};