@wrongstack/cli 1.0.10 → 1.0.11

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 {};

package/dist/hq-server/routes/system-handlers.d.ts

@@ -7,9 +7,36 @@
 import type * as http from 'node:http';
 import type { HqAlertEngine, HqCommandAuditLog, HqEventEnvelope, HqPersistence } from '@wrongstack/core/hq';
 import type { WebSocket } from 'ws';
+import type { HqMailboxGatewayHealth } from '../mailbox-gateway-health.js';
 import type { ConnectedClient } from '../types.js';
 export declare function handleApiSystemUpdate(res: http.ServerResponse): Promise<void>;
 export declare function handleApiSystemHealth(res: http.ServerResponse, clients: Map<WebSocket, ConnectedClient>, persistence: HqPersistence, eventLog: HqEventEnvelope[]): Promise<void>;
 export declare function handleApiCommandsAudit(req: http.IncomingMessage, res: http.ServerResponse, auditLog: HqCommandAuditLog): Promise<void>;
 export declare function handleApiAlerts(req: http.IncomingMessage, res: http.ServerResponse, alertEngine: HqAlertEngine): Promise<void>;
+/**
+ * Structural view of the gateway manager this handler needs. Typing the
+ * parameter structurally — rather than importing `MailboxGatewayManager` —
+ * keeps this module out of the type-inclusive cycle
+ * `mailbox-gateway-manager → routes → system-handlers`, which
+ * `check:architecture` reports as unexcepted. The real manager satisfies this
+ * shape, so callers and the wire contract are unaffected.
+ */
+interface MailboxHealthSource {
+    getHealth(): HqMailboxGatewayHealth;
+}
+/**
+ * W2 #14 (RFC hq-improvements-2026-09.md): GET /api/health/mailbox —
+ * mailbox gateway health snapshot for the cockpit's "Mailbox gateway" card.
+ *
+ * Surfaces {@link MailboxHealthSource.getHealth} verbatim. The contract
+ * (basename as `projectId`, full path as `projectRoot`, `actorAttached: false`
+ * on the HQ mount, sorted gateways) is locked by the focused test in
+ * `packages/cli/tests/hq-mailbox-gateway-health.test.ts`.
+ *
+ * No query parameters. No mutation. Same auth contract as
+ * `/api/system/health` — gated by `requireBrowserAuth` upstream in the
+ * router, not duplicated here.
+ */
+export declare function handleApiMailboxHealth(res: http.ServerResponse, mailboxManager: MailboxHealthSource): void;
+export {};
 //# sourceMappingURL=system-handlers.d.ts.map

package/dist/hq-server/routes.d.ts

@@ -13,6 +13,7 @@ import type { createHqPersistence, HqAlertEngine, HqCommandAuditLog, HqEventEnve
 import type { TrustBoundary } from '@wrongstack/core/security';
 import type { WebSocket } from 'ws';
 import * as HqServerAuth from './auth.js';
+import type { HqMailboxGatewayHealth } from './mailbox-gateway-health.js';
 import { type ApplyHqAuthFile } from './routes/auth-handlers.js';
 import * as HqServerUtils from './utils.js';
 export declare const setHqSecurityHeaders: typeof HqServerAuth.setHqSecurityHeaders;
@@ -73,6 +74,16 @@ export interface HqRouterDeps {
     agentMessages: Map<string, HqTranscriptEntry[]>;
     mailboxGateways: Map<string, HqRouterMailboxGateway>;
     mailboxGatewayRateLimiter: MailboxHttpRateLimiter;
+    /**
+     * W2 #14 (RFC hq-improvements-2026-09.md): mailbox gateway manager used
+     * by `/api/health/mailbox` to surface the cockpit "Mailbox gateway"
+     * card. Same manager that owns `mailboxGateways` and
+     * `mailboxGatewayRateLimiter` — passed explicitly so the handler can
+     * call `getHealth()` without reaching into a closure.
+     */
+    mailboxManager: {
+        getHealth(): HqMailboxGatewayHealth;
+    };
     alertEngine: HqAlertEngine;
     auditLog: HqCommandAuditLog;
     persistence: ReturnType<typeof createHqPersistence>;

package/dist/hq-server/snapshot.d.ts

@@ -53,8 +53,21 @@ export declare const HQ_STALE_SNAPSHOT_MS: number;
 export declare function reapStaleClientState(clients: Map<WebSocket, ConnectedClient>, nowMs?: number): void;
 export declare function buildSnapshot(clients: Map<WebSocket, ConnectedClient>, options?: {
     tokenStats?: HqSnapshot['totals']['tokenStats'];
+    /**
+     * Recent command-audit entries (W4 #7). The caller owns the audit ring, so
+     * it hands over the window rather than the builder reaching for a global.
+     */
+    commandAudit?: readonly HqCommandAuditEntry[];
 }): HqSnapshot;
-export declare function createSnapshotBroadcaster(clients: Map<WebSocket, ConnectedClient>, browsers: Set<WebSocket>, persistence?: HqPersistence): HqSnapshotBroadcaster;
+export declare function createSnapshotBroadcaster(clients: Map<WebSocket, ConnectedClient>, browsers: Set<WebSocket>, persistence?: HqPersistence, options?: {
+    /**
+     * W4 #7: command-audit window for the latency roll-up. Passed as a
+     * provider rather than an array because the broadcaster caches its
+     * serialized frame and only rebuilds when marked dirty — reading the ring
+     * at serialize time is what keeps the cached frame current.
+     */
+    commandAudit?: () => readonly HqCommandAuditEntry[];
+}): HqSnapshotBroadcaster;
 export declare function buildProjectDetail(clients: Map<WebSocket, ConnectedClient>, projectId: string): ProjectDetail | null;
 export declare function broadcastEvent(event: HqEventEnvelope, browsers: Set<WebSocket>): void;
 /** Push one control command's lifecycle to every authenticated HQ browser. */

package/dist/hq-server/upgrade-handler.d.ts

@@ -21,6 +21,13 @@ interface HqUpgradeHandlerDeps {
     sessions: Map<string, HqSessionEntry>;
     clients: Map<WebSocket, ConnectedClient>;
     clientSocketTokens: Map<WebSocket, HqToken | undefined>;
+    /**
+     * Session id that authorized each open browser socket, so token revocation
+     * can close only the affected browsers. Absent for a socket that
+     * authenticated with a bare loopback `?token=` rather than a cookie session;
+     * the revocation path treats that absence as "affected" (fail closed).
+     */
+    browserSocketSessions: Map<WebSocket, string>;
     browsers: Set<WebSocket>;
     eventLog: import('@wrongstack/core/hq').HqEventEnvelope[];
     transcripts: Map<string, TranscriptRing>;

package/dist/{hq-server-JJFGFWI5.js → hq-server-KE5YDNGG.js}

@@ -10,7 +10,7 @@ import {
   readLocalSubagentTranscript,
   sanitizeApiError,
   startHqServer
-} from "./chunk-7FPN3QTH.js";
+} from "./chunk-YRC3I3LE.js";
 import "./chunk-HXJYHAR4.js";
 import "./chunk-5EA6OTLJ.js";
 import "./chunk-Q7E3BPDU.js";
@@ -27,4 +27,4 @@ export {
   sanitizeApiError,
   startHqServer
 };
-//# sourceMappingURL=hq-server-JJFGFWI5.js.map
+//# sourceMappingURL=hq-server-KE5YDNGG.js.map

package/dist/index.js

@@ -8,7 +8,7 @@ import {
 } from "./chunk-XJXDOF63.js";
 import {
   parseArgs
-} from "./chunk-EK2P53GL.js";
+} from "./chunk-C3Z4N6A6.js";
 
 // src/cli-entry-main.ts
 async function main(argv) {
@@ -16,14 +16,14 @@ async function main(argv) {
   applySessionShellDefault();
   const earlyFlags = parseArgs(argv).flags;
   if (earlyFlags["help"] === true || earlyFlags["version"] === true) {
-    const { handleHelpVersionShortCircuit } = await import("./short-circuit-flags-LHUNLCZY.js");
+    const { handleHelpVersionShortCircuit } = await import("./short-circuit-flags-72E77TJI.js");
     const earlyExit = await handleHelpVersionShortCircuit(argv);
     if (earlyExit !== null) return earlyExit;
   }
-  const { initializeCli } = await import("./cli-context-6GMXUOXD.js");
+  const { initializeCli } = await import("./cli-context-5IF7ZYEY.js");
   const cliCtx = await initializeCli(argv);
   if (typeof cliCtx === "number") return cliCtx;
-  const { runInteractive } = await import("./cli-main-BU5DEHDO.js");
+  const { runInteractive } = await import("./cli-main-WC5JNIWY.js");
   return runInteractive(cliCtx);
 }
 

package/dist/{mcp-FX7TKPTV.js → mcp-DC5WSBOO.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-YMXXOOFN.js";
 
 // src/subcommands/handlers/mcp.ts
-import { allServers } from "@wrongstack/core/infrastructure";
+import { allServers, resolveMcpServerConfig } from "@wrongstack/core/infrastructure";
 import {
   expectDefined,
   jsonObjectFileExists,
@@ -49,6 +49,15 @@ function parseToolsFlag(flags, positional) {
   );
   return set.size > 0 ? set : null;
 }
+function resolveServeHttpPort(flags) {
+  const raw = typeof flags["port"] === "string" ? flags["port"] : typeof flags["http"] === "string" ? flags["http"] : void 0;
+  if (raw === void 0 || raw.trim() === "") return 0;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`invalid --port "${raw}" \u2014 expected an integer between 0 and 65535`);
+  }
+  return port;
+}
 async function loadSelectedMcpServeContent(flags, cwd) {
   const resources = [];
   const prompts = [];
@@ -287,7 +296,13 @@ async function serveMcpStdio(deps, positional) {
   });
   const mode = yolo ? "yolo: all tools" : "safe: read-only tools";
   if (flags["http"] === true || typeof flags["http"] === "string" || flags["port"] || flags["host"]) {
-    const port = Number(flags["port"] ?? flags["http"] ?? 0) || 0;
+    let port;
+    try {
+      port = resolveServeHttpPort(flags);
+    } catch (err) {
+      log(`wrongstack MCP server: ${err instanceof Error ? err.message : String(err)}`);
+      return 1;
+    }
     const httpHost = typeof flags["host"] === "string" ? flags["host"] : "127.0.0.1";
     const tokenFromArg = typeof flags["token"] === "string" ? flags["token"] : void 0;
     const token = tokenFromArg ?? process.env.WRONGSTACK_MCP_TOKEN?.trim() ?? void 0;
@@ -344,10 +359,13 @@ var mcpCmd = async (args, deps) => {
       deps.renderer.write("Use `wstack mcp add <name>` or set mcpServers in your config.\n");
       return 0;
     }
-    for (const [name, cfg] of Object.entries(servers)) {
-      const status = cfg.enabled === false ? "disabled" : "enabled";
-      const desc = cfg.description ? `  # ${cfg.description}` : "";
-      deps.renderer.write(`  ${name.padEnd(20)} ${cfg.transport.padEnd(16)} ${status}${desc}
+    for (const [name, entry] of Object.entries(servers)) {
+      const cfg = resolveMcpServerConfig(name, entry);
+      const status = entry?.enabled === false ? "disabled" : "enabled";
+      const description = cfg?.description ?? entry?.description;
+      const desc = description ? `  # ${description}` : "";
+      const transport = cfg?.transport ?? "invalid (no transport)";
+      deps.renderer.write(`  ${name.padEnd(20)} ${transport.padEnd(16)} ${status}${desc}
 `);
     }
     return 0;
@@ -391,7 +409,7 @@ async function addMcpServer(args, deps) {
     deps.renderer.write("\nRun `wstack mcp add <name> --enable` to enable immediately.\n");
     return 1;
   }
-  const factory = BUILT_IN_MCP[name];
+  const factory = Object.hasOwn(BUILT_IN_MCP, name) ? BUILT_IN_MCP[name] : void 0;
   if (!factory) {
     deps.renderer.writeError(
       `Unknown server "${name}". Run \`wstack mcp add\` without args to see available servers.
@@ -403,7 +421,7 @@ async function addMcpServer(args, deps) {
   serverCfg.enabled = enable;
   const existing = await readJsonObjectFile(configPath);
   const mcpServers = isRecord(existing.mcpServers) ? existing.mcpServers : {};
-  if (mcpServers[name])
+  if (Object.hasOwn(mcpServers, name))
     deps.renderer.writeWarning(`Server "${name}" already in config. Updating.
 `);
   await updateJsonObjectFile(configPath, (config) => {
@@ -424,7 +442,7 @@ async function removeMcpServer(name, deps) {
   }
   const existing = await readJsonObjectFile(configPath);
   const mcpServers = isRecord(existing.mcpServers) ? existing.mcpServers : {};
-  if (!mcpServers[name]) {
+  if (!Object.hasOwn(mcpServers, name)) {
     deps.renderer.writeError(`Server "${name}" not in config.
 `);
     return 1;
@@ -442,4 +460,4 @@ function isRecord(value) {
 export {
   mcpCmd
 };
-//# sourceMappingURL=mcp-FX7TKPTV.js.map
+//# sourceMappingURL=mcp-DC5WSBOO.js.map

package/dist/mcp-serve.d.ts

@@ -45,6 +45,15 @@ export declare function yoloServePolicy(): AutoApprovePermissionPolicy;
  * "flag present but no list" as an error, never as "no whitelist".
  */
 export declare function parseToolsFlag(flags: Record<string, string | boolean>, positional?: readonly string[]): Set<string> | null;
+/**
+ * Resolve the TCP port for `mcp serve --http`.
+ *
+ * `--http` is also a boolean flag, and the old `Number(flags.port ?? flags.http)`
+ * turned a bare `--http` into `Number(true) === 1` — the server tried to bind
+ * privileged port 1 instead of an ephemeral one. A bare flag now means "pick a
+ * free port" (0); an explicit value must be an integer in 0–65535.
+ */
+export declare function resolveServeHttpPort(flags: Record<string, string | boolean>): number;
 interface SelectedMcpServeContent {
     resources: MCPServerResource[];
     prompts: MCPServerPrompt[];

package/dist/services/mcp-management.d.ts

@@ -1,9 +1,3 @@
-/**
- * Shared MCP management service.
- * Contains the argument parser and the actual management logic shared between
- * the CLI subcommand handler (packages/cli/src/subcommands/handlers/mcp.ts)
- * and the slash-command wiring in index.ts.
- */
 import type { Config, MCPServerConfig } from '@wrongstack/core/types';
 import type { MCPRegistry } from '@wrongstack/mcp';
 export interface McpParsedArgs {

package/dist/{short-circuit-flags-LHUNLCZY.js → short-circuit-flags-72E77TJI.js}

@@ -1,10 +1,10 @@
 import {
   handleHelpVersionShortCircuit
-} from "./chunk-5VPDKQDH.js";
+} from "./chunk-TNZBQG45.js";
 import "./chunk-6WRKAACA.js";
 import "./chunk-XJXDOF63.js";
-import "./chunk-EK2P53GL.js";
+import "./chunk-C3Z4N6A6.js";
 export {
   handleHelpVersionShortCircuit
 };
-//# sourceMappingURL=short-circuit-flags-LHUNLCZY.js.map
+//# sourceMappingURL=short-circuit-flags-72E77TJI.js.map

package/dist/{subcommands-UXWY3OPC.js → subcommands-EJI7DBQS.js}

@@ -1,9 +1,9 @@
 import {
   subcommandNames,
   subcommands
-} from "./chunk-7K3IJGWC.js";
+} from "./chunk-OJR7K3OI.js";
 export {
   subcommandNames,
   subcommands
 };
-//# sourceMappingURL=subcommands-UXWY3OPC.js.map
+//# sourceMappingURL=subcommands-EJI7DBQS.js.map