@mcpmake/core 0.3.3 → 0.3.5

package/dist/emitter/python-templates/server.py.hbs

@@ -3,10 +3,11 @@
 import os
 import json
 import httpx
+from typing import Annotated, Literal, Optional, Any
 from urllib.parse import quote
 from dotenv import load_dotenv
-from mcp.server import Server
-from mcp.server.stdio import stdio_server
+from pydantic import BaseModel, Field, ConfigDict
+from mcp.server.fastmcp import FastMCP
 from mcp.types import TextContent
 
 load_dotenv()
@@ -37,12 +38,20 @@ API_KEY = os.environ.get("{{envVarName}}", "")
 {{/if}}
 {{/each}}
 
-server = Server("{{serverName}}")
+server = FastMCP("{{serverName}}")
 
 # Hard per-request deadline (seconds) and response-size cap (bytes). A stalled or
 # runaway upstream otherwise keeps tool calls alive indefinitely or exhausts memory.
-_REQUEST_TIMEOUT_S = float(os.environ.get("MCP_REQUEST_TIMEOUT_MS", "30000")) / 1000.0
-_MAX_RESPONSE_BYTES = int(os.environ.get("MCP_MAX_RESPONSE_BYTES", str(10 * 1024 * 1024)))
+try:
+    _timeout_ms = float(os.environ.get("MCP_REQUEST_TIMEOUT_MS", "30000"))
+    _REQUEST_TIMEOUT_S = _timeout_ms / 1000.0 if _timeout_ms > 0 else 30.0
+except (ValueError, TypeError):
+    _REQUEST_TIMEOUT_S = 30.0
+try:
+    _max_bytes = int(os.environ.get("MCP_MAX_RESPONSE_BYTES", str(10 * 1024 * 1024)))
+    _MAX_RESPONSE_BYTES = _max_bytes if _max_bytes > 0 else 10 * 1024 * 1024
+except (ValueError, TypeError):
+    _MAX_RESPONSE_BYTES = 10 * 1024 * 1024
 client = httpx.AsyncClient(timeout=_REQUEST_TIMEOUT_S)
 
 
@@ -84,9 +93,17 @@ def _auth_query_params() -> dict[str, str]:
     return params
 
 
+{{#if pydanticModels}}
+# Request-body models (A4-H2). Each plain-object request body is modelled as a
+# Pydantic BaseModel so FastMCP infers a full-fidelity nested-object input schema
+# (typed properties, required set, descriptions). Fields whose wire name is not a
+# valid Python identifier use Field(alias=...) + populate_by_name; the handler
+# serializes with by_alias=True to restore the original key on the wire.
+{{{pydanticModels}}}
+{{/if}}
 {{#each tools}}
-@server.tool()
-async def {{functionName}}({{#each pyPathParams}}{{pyName}}: str, {{/each}}{{#each pyQueryParams}}{{pyName}}: str = "", {{/each}}{{#each pyHeaderParams}}{{pyName}}: str = "", {{/each}}{{#each pyCookieParams}}{{pyName}}: str = "", {{/each}}{{#if hasRequestBody}}body: dict | None = None{{/if}}) -> list[TextContent]:
+@server.tool(name="{{pyStr name}}")
+async def {{functionName}}({{{pySignature}}}) -> list[TextContent]:
     """{{pyDocstring description}}"""
     url = BASE_URL + "{{pyStr pathTemplate}}"
     {{#each pyPathParams}}
@@ -94,7 +111,8 @@ async def {{functionName}}({{#each pyPathParams}}{{pyName}}: str, {{/each}}{{#ea
     {{/each}}
     {{#if pyQueryParams.length}}
     params = { {{#each pyQueryParams}}"{{pyStr apiName}}": {{pyName}}, {{/each}} }
-    params = {k: v for k, v in params.items() if v}
+    # Drop only unset (None) optionals — a legitimate 0/false/"" must still be sent.
+    params = {k: v for k, v in params.items() if v is not None}
     {{#if @root.hasQueryApiKey}}
     params.update(_auth_query_params())
     {{/if}}
@@ -108,13 +126,13 @@ async def {{functionName}}({{#each pyPathParams}}{{pyName}}: str, {{/each}}{{#ea
     # names, merged over the auth headers. Empty values are omitted.
     req_headers = dict(_headers())
     {{#each pyHeaderParams}}
-    if {{pyName}}:
-        req_headers["{{pyStr wireName}}"] = {{pyName}}
+    if {{pyName}} is not None:
+        req_headers["{{pyStr wireName}}"] = str({{pyName}})
     {{/each}}
     {{#if pyCookieParams.length}}
     _cookie_parts = []
     {{#each pyCookieParams}}
-    if {{pyName}}:
+    if {{pyName}} is not None:
         _cookie_parts.append("{{pyStr wireName}}=" + quote(str({{pyName}}), safe=""))
     {{/each}}
     if _cookie_parts:
@@ -123,45 +141,63 @@ async def {{functionName}}({{#each pyPathParams}}{{pyName}}: str, {{/each}}{{#ea
         req_headers["Cookie"] = (_existing + "; " + _joined) if _existing else _joined
     {{/if}}
     {{/if}}
+    {{#if hasRequestBody}}
+    {{#if bodyIsModel}}
+    # Pydantic body → plain dict for httpx. by_alias restores any non-identifier
+    # wire keys; exclude_none drops unset optionals so they are omitted, not nulled.
+    _body = body.model_dump(exclude_none=True, by_alias=True) if body is not None else None
+    {{else}}
+    # Scalar / array / free-form body kept as the raw typed value.
+    _body = body
+    {{/if}}
+    {{/if}}
     try:
-        resp = await client.request(
+        async with client.stream(
             "{{method}}",
             url,
             headers={{#if (or pyHeaderParams.length pyCookieParams.length)}}req_headers{{else}}_headers(){{/if}},
-            {{#if (or queryParams.length @root.hasQueryApiKey)}}
+            {{#if (or pyQueryParams.length @root.hasQueryApiKey)}}
             params=params,
             {{/if}}
             {{#if hasRequestBody}}
             {{#if (eq bodyEncoding "form")}}
-            data=body,
+            data=_body,
             {{else}}
             {{#if (eq bodyEncoding "multipart")}}
-            files=body,
+            files=_body,
             {{else}}
-            json=body,
+            json=_body,
             {{/if}}
             {{/if}}
             {{/if}}
-        )
-        # Cap the buffered response so a runaway upstream cannot exhaust memory.
-        if len(resp.content) > _MAX_RESPONSE_BYTES:
-            return [TextContent(type="text", text=f"Error: response exceeded {_MAX_RESPONSE_BYTES}-byte cap")]
-        # Never echo upstream 4xx/5xx bodies to the MCP caller — they can leak
-        # internal/upstream detail. Surface only the status code + generic reason.
-        if resp.status_code >= 400:
-            return [TextContent(type="text", text=f"Error: upstream returned {resp.status_code} {resp.reason_phrase}".rstrip())]
-        data = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else resp.text
-        return [TextContent(type="text", text=json.dumps(data, indent=2) if isinstance(data, (dict, list)) else str(data))]
+        ) as resp:
+            # Never echo upstream 4xx/5xx bodies to the MCP caller — they can leak
+            # internal/upstream detail. Surface only the status code + generic reason.
+            if resp.status_code >= 400:
+                return [TextContent(type="text", text=f"Error: upstream returned {resp.status_code} {resp.reason_phrase}".rstrip())]
+            # Read with a hard cap so a runaway upstream cannot exhaust memory.
+            # Streaming means we abort mid-transfer — the full body is never buffered.
+            chunks: list[bytes] = []
+            total = 0
+            async for chunk in resp.aiter_bytes():
+                total += len(chunk)
+                if total > _MAX_RESPONSE_BYTES:
+                    return [TextContent(type="text", text=f"Error: response exceeded {_MAX_RESPONSE_BYTES}-byte cap")]
+                chunks.append(chunk)
+            raw = b"".join(chunks)
+            content_type = resp.headers.get("content-type", "")
+            if content_type.startswith("application/json"):
+                try:
+                    data = json.loads(raw)
+                except ValueError:
+                    data = raw.decode("utf-8", "replace")
+            else:
+                data = raw.decode("utf-8", "replace")
+            return [TextContent(type="text", text=json.dumps(data, indent=2) if isinstance(data, (dict, list)) else str(data))]
     except Exception as e:
         return [TextContent(type="text", text=f"Error: {e}")]
 
 
 {{/each}}
-async def main():
-    async with stdio_server() as (read_stream, write_stream):
-        await server.run(read_stream, write_stream, server.create_initialization_options())
-
-
 if __name__ == "__main__":
-    import asyncio
-    asyncio.run(main())
+    server.run()

package/dist/emitter/site-templates/browser-manager.ts.hbs

@@ -28,6 +28,10 @@ const sessionCreations = new Map<string, Promise<{ page: Page; sessionId: string
 // Single-flight the browser launch so concurrent cold starts can't spawn
 // multiple Chromium processes.
 let browserLaunch: Promise<Browser> | undefined;
+// Incremented whenever closeBrowser() begins. A launch captures the current
+// generation and must close itself instead of becoming active if teardown
+// invalidated it while chromium.launch() was still pending.
+let browserGeneration = 0;
 
 const DEFAULT_SESSION = '__default__';
 
@@ -99,13 +103,35 @@ async function getBrowser(): Promise<Browser> {
 
   // Only disable sandbox when running as root in a container.
   const isRoot = process.getuid?.() === 0;
+  const generation = browserGeneration;
   browserLaunch = chromium
     .launch({
       headless: config.headless,
       args: isRoot ? ['--no-sandbox', '--disable-setuid-sandbox'] : [],
     })
-    .then((b) => {
+    .then(async (b) => {
+      // closeBrowser() may have run while Chromium was launching. Never publish
+      // that stale browser into manager state: close it and fail the waiting
+      // creation so no resident process escapes the pool/cap.
+      if (generation !== browserGeneration) {
+        await b.close().catch(() => {});
+        throw new Error('Browser launch aborted: browser manager shut down');
+      }
       browser = b;
+      // If the whole browser process dies, every session's context is dead.
+      // Reclaim them all: emit one session_end each (skipping reserved slots
+      // that never started) and clear the pool + idle timer so occupancy frees
+      // promptly. No-ops for our own browser.close() (the pool is already empty
+      // and `browser` already nulled by then).
+      b.on('disconnected', () => {
+        if (browser !== b) return;
+        browser = undefined;
+        clearIdleTimer();
+        for (const [id, session] of [...sessions]) {
+          sessions.delete(id);
+          if (session.context) telemetry.sessionEnded(id, 'crash');
+        }
+      });
       return b;
     })
     .finally(() => {
@@ -125,20 +151,24 @@ async function getBrowser(): Promise<Browser> {
 export async function getOrCreateSession(sessionId?: string): Promise<{ page: Page; sessionId: string }> {
   const id = sessionId ?? DEFAULT_SESSION;
 
-  // Reuse existing session
+  // Join an in-flight creation for this id FIRST. createSession reserves its slot
+  // synchronously (before its first await), so a concurrent second call that
+  // checked `sessions` first would observe that placeholder and return its
+  // not-yet-assigned (undefined) page. The in-flight promise resolves to the
+  // real page, so coalescing here gives every concurrent caller a usable page
+  // and a single shared context.
+  const inFlight = sessionCreations.get(id);
+  if (inFlight) return inFlight;
+
+  // Reuse a fully-created session (a placeholder reservation has no context yet
+  // and is always covered by the in-flight check above).
   const existing = sessions.get(id);
-  if (existing) {
+  if (existing && existing.context) {
     existing.lastAccessedAt = Date.now();
-    resetIdleTimer();
+    ensureIdleTimer();
     return { page: existing.page, sessionId: id };
   }
 
-  // Coalesce concurrent creations for the same id (notably the default
-  // session) onto one promise so we don't create duplicate contexts or
-  // double-count capacity.
-  const inFlight = sessionCreations.get(id);
-  if (inFlight) return inFlight;
-
   const creation = createSession(id).finally(() => {
     sessionCreations.delete(id);
   });
@@ -153,8 +183,8 @@ async function createSession(id: string): Promise<{ page: Page; sessionId: strin
   const maxSessions = config.maxSessions ?? 10;
   if (sessions.size >= maxSessions) {
     throw new Error(
-      `Session pool at capacity (${maxSessions}). ` +
-      'Close an existing session before creating a new one.'
+      `Browser session limit reached (${maxSessions}). ` +
+      'Close an existing session and retry.'
     );
   }
   const reserved: BrowserSession = {
@@ -164,28 +194,61 @@ async function createSession(id: string): Promise<{ page: Page; sessionId: strin
   };
   sessions.set(id, reserved);
 
+  let context: BrowserContext | undefined;
   try {
     const activeBrowser = await getBrowser();
-    const context = await activeBrowser.newContext({
+    context = await activeBrowser.newContext({
       viewport: config.viewport,
       ...(config.userAgent ? { userAgent: config.userAgent } : {}),
     });
     const page = await context.newPage();
 
+    // If the manager was torn down (shutdown/disconnect) while we awaited the
+    // browser/context/page, our reservation was cleared. Do NOT resurrect it:
+    // bail so the catch below closes this fresh context. Otherwise we would
+    // orphan a live Chromium context outside the pool — escaping the cap, never
+    // reaped, and emitting a session_start AFTER its session_end. There is no
+    // await between here and `return`, so once this check passes the rest of
+    // creation is atomic with respect to teardown.
+    if (sessions.get(id) !== reserved) {
+      throw new Error('Session creation aborted: browser manager shut down');
+    }
+
     reserved.context = context;
     reserved.page = page;
     reserved.lastAccessedAt = Date.now();
 
-    resetIdleTimer();
+    ensureIdleTimer();
 
     // The browser context is now resident — start billing this session (no-op
     // unless the host injected telemetry env).
     telemetry.sessionStarted(id);
 
+    // Reclaim the slot exactly once if this session dies on its own — a Chromium
+    // context close, a renderer (page) crash, or an external close. Every
+    // intentional teardown path deletes the map entry BEFORE closing, so the
+    // `=== reserved` guard makes this a no-op for those and lets it fire only on
+    // an unexpected death, freeing host occupancy promptly instead of waiting
+    // out the idle grace. The guard also dedupes a page crash that then closes
+    // the context (only the first reclaim wins).
+    const reclaim = (reason: string): void => {
+      if (sessions.get(id) !== reserved) return;
+      sessions.delete(id);
+      context?.close().catch(() => {});
+      telemetry.sessionEnded(id, reason);
+      if (sessions.size === 0) void closeBrowser();
+    };
+    context.on('close', () => reclaim('crash'));
+    page.on('crash', () => reclaim('crash'));
+
     return { page, sessionId: id };
   } catch (err) {
-    // Release the reserved slot if context creation failed.
-    sessions.delete(id);
+    // Release the slot AND close any context we created, so a failed or aborted
+    // creation never leaks a live Chromium context or pins the cap slot. Only
+    // delete the entry if it is still ours (a concurrent shutdown may have
+    // already cleared it).
+    if (sessions.get(id) === reserved) sessions.delete(id);
+    await context?.close().catch(() => {});
     throw err;
   }
 }
@@ -198,10 +261,18 @@ export async function closeSession(sessionId?: string): Promise<void> {
   const session = sessions.get(id);
   if (!session) return;
 
-  await session.context?.close().catch(() => {});
+  // Claim the teardown AND emit session_end SYNCHRONOUSLY, before the first
+  // await. Deleting the map entry and removing the telemetry token together,
+  // up front, means: (a) a concurrent idle sweep or second close sees the slot
+  // gone and skips it; and (b) a same-id session re-created during the
+  // context-close await below gets its OWN fresh telemetry token instead of
+  // sharing this one (which would suppress its later session_end). Exactly one
+  // session_end per teardown.
   sessions.delete(id);
   telemetry.sessionEnded(id, 'explicit');
 
+  await session.context?.close().catch(() => {});
+
   // If no sessions remain, close the browser
   if (sessions.size === 0) {
     await closeBrowser();
@@ -213,17 +284,42 @@ export async function closeSession(sessionId?: string): Promise<void> {
  */
 export async function closeBrowser(): Promise<void> {
   clearIdleTimer();
-
-  for (const [id, session] of sessions) {
+  // Invalidate a chromium.launch() already in progress. Its completion handler
+  // will close the resulting process rather than assigning it to `browser`.
+  browserGeneration++;
+  const launching = browserLaunch;
+
+  // Null `browser` synchronously BEFORE awaiting its close. While close() is in
+  // flight the instance still reports isConnected() === true, so without this a
+  // concurrent getOrCreateSession would be handed the dying browser and build a
+  // context on it that dies immediately. Nulling up front forces a relaunch
+  // instead, and single-flights closeBrowser (a second concurrent call sees no
+  // browser and skips the redundant close()).
+  const dying = browser;
+  browser = undefined;
+
+  // Snapshot and clear the pool, then emit every session_end SYNCHRONOUSLY
+  // (before any await) so a same-id session re-created during the context-close
+  // awaits gets its own telemetry token rather than sharing a snapshotted one.
+  // Reserved-but-unstarted slots are skipped: no context to close, and no
+  // session_start to balance (the in-flight createSession aborts itself once it
+  // sees its reservation cleared).
+  const entries = [...sessions];
+  sessions.clear();
+  for (const [id, session] of entries) {
+    if (session.context) telemetry.sessionEnded(id, 'shutdown');
+  }
+  for (const [, session] of entries) {
     await session.context?.close().catch(() => {});
-    sessions.delete(id);
-    telemetry.sessionEnded(id, 'shutdown');
   }
 
-  if (browser) {
-    await browser.close().catch(() => {});
-    browser = undefined;
+  if (dying) {
+    await dying.close().catch(() => {});
   }
+  // Wait for an invalidated launch to finish its self-cleanup. This makes
+  // closeBrowser() a real lifecycle barrier: after it resolves, no Chromium
+  // process from work that began before teardown can still become resident.
+  await launching?.catch(() => {});
 }
 
 /**
@@ -235,7 +331,9 @@ export async function takeScreenshot(
 ): Promise<Buffer> {
   const id = sessionId ?? DEFAULT_SESSION;
   const session = sessions.get(id);
-  if (!session) {
+  // A reserved, mid-creation slot is in the map but has no page yet — treat it
+  // as not-yet-active so callers get the clear error, not a TypeError.
+  if (!session || !session.context) {
     throw new Error(`No active session: ${id}`);
   }
   session.lastAccessedAt = Date.now();
@@ -243,10 +341,13 @@ export async function takeScreenshot(
 }
 
 /**
- * List active session IDs.
+ * List active session IDs. Excludes reserved, mid-creation slots (no page yet)
+ * so a returned id is always usable with takeScreenshot/tool calls.
  */
 export function listSessions(): string[] {
-  return Array.from(sessions.keys());
+  return Array.from(sessions.entries())
+    .filter(([, session]) => session.context !== undefined)
+    .map(([id]) => id);
 }
 
 /**
@@ -258,24 +359,36 @@ export function isBrowserRunning(): boolean {
 
 // ─── Idle Timer ─────────────────────────────────────────────────────
 
-function resetIdleTimer(): void {
-  clearIdleTimer();
+// Start the idle reaper once and let it tick at a FIXED cadence. It must NOT be
+// reset on session access: resetting on every access would let a busy container
+// (one session touched within each interval) starve the reaper so it never
+// fires, leaving genuinely-idle sibling sessions resident forever. Eviction
+// keys off each session's own lastAccessedAt, so a steady tick is sufficient —
+// touching a session keeps only that session alive.
+function ensureIdleTimer(): void {
+  if (idleTimer) return;
   idleTimer = setInterval(() => {
     const now = Date.now();
     // Close idle sessions. Skip slots still being created (no context yet).
     for (const [id, session] of sessions) {
       if (!session.context) continue;
       if (now - session.lastAccessedAt > config.idleTimeoutMs) {
-        session.context.close().catch(() => {});
+        // Delete before closing so the context's own 'close' handler (and any
+        // concurrent teardown) sees the slot already claimed — session_end is
+        // emitted once, here, with reason 'idle'.
         sessions.delete(id);
+        session.context.close().catch(() => {});
         telemetry.sessionEnded(id, 'idle');
       }
     }
-    // Close browser if no sessions
+    // Close browser if no sessions. `void` so a rejected closeBrowser()
+    // (e.g. Playwright throwing during browser.close()) can't become an
+    // unhandled promise rejection in this sync interval callback.
     if (sessions.size === 0) {
-      closeBrowser();
+      void closeBrowser();
     }
   }, 30_000); // Check every 30 seconds
+  idleTimer.unref?.();
 }
 
 function clearIdleTimer(): void {

package/dist/emitter/site-templates/config.ts.hbs

@@ -11,18 +11,35 @@ export interface AppConfig {
   browser: BrowserConfig;
 }
 
+const posInt = (v: string | undefined, d: number): number => {
+  const n = parseInt(v ?? '', 10);
+  return Number.isInteger(n) && n > 0 ? n : d;
+};
+
+// Hard ceiling on concurrently-resident browser sessions for THIS container.
+// The cloud host injects MCP_MAX_BROWSER_SESSIONS at container start to pin the
+// owner's per-plan concurrent-browser limit, making the container's hard cap the
+// plan cap. MAX_SESSIONS is the legacy/self-host alias. Either env var, when a
+// valid positive integer, overrides the baked-in default; an unset or invalid
+// value falls through to the next source. DEFAULT_MAX_SESSIONS is the safe
+// fallback. The browser manager refuses to launch a session past this cap.
+const DEFAULT_MAX_SESSIONS = {{#if browserConfig.maxSessions}}{{browserConfig.maxSessions}}{{else}}10{{/if}};
+
 export function loadConfig(): AppConfig {
   return {
     baseUrl: process.env.BASE_URL ?? '{{{baseUrl}}}',
     browser: {
       headless: process.env.HEADLESS !== 'false',
-      idleTimeoutMs: parseInt(process.env.IDLE_TIMEOUT_MS ?? '{{browserConfig.idleTimeoutMs}}', 10),
+      idleTimeoutMs: posInt(process.env.IDLE_TIMEOUT_MS, {{browserConfig.idleTimeoutMs}}),
       viewport: {
-        width: parseInt(process.env.VIEWPORT_WIDTH ?? '{{browserConfig.viewport.width}}', 10),
-        height: parseInt(process.env.VIEWPORT_HEIGHT ?? '{{browserConfig.viewport.height}}', 10),
+        width: posInt(process.env.VIEWPORT_WIDTH, {{browserConfig.viewport.width}}),
+        height: posInt(process.env.VIEWPORT_HEIGHT, {{browserConfig.viewport.height}}),
       },
       userAgent: process.env.USER_AGENT || undefined,
-      maxSessions: parseInt(process.env.MAX_SESSIONS ?? '{{browserConfig.maxSessions}}', 10) || 10,
+      maxSessions: posInt(
+        process.env.MCP_MAX_BROWSER_SESSIONS,
+        posInt(process.env.MAX_SESSIONS, DEFAULT_MAX_SESSIONS),
+      ),
     },
   };
 }

package/dist/emitter/site-templates/env.example.hbs

@@ -10,6 +10,14 @@ VIEWPORT_WIDTH={{browserConfig.viewport.width}}
 VIEWPORT_HEIGHT={{browserConfig.viewport.height}}
 # USER_AGENT=
 
+# Hard cap on concurrently-resident browser sessions (Chromium contexts) this
+# server will hold. A tool call that would open one past the cap is refused with
+# a clear error rather than launching another browser. Managed hosting injects
+# this to enforce the plan's concurrent-browser limit. MAX_SESSIONS is a legacy
+# alias; MCP_MAX_BROWSER_SESSIONS wins when both are set.
+MCP_MAX_BROWSER_SESSIONS={{#if browserConfig.maxSessions}}{{browserConfig.maxSessions}}{{else}}10{{/if}}
+# MAX_SESSIONS={{#if browserConfig.maxSessions}}{{browserConfig.maxSessions}}{{else}}10{{/if}}
+
 # Browser-session telemetry (managed hosting only — leave UNSET to self-host).
 # When the host sets these, the server reports exact browser-session lifetime
 # for metering. It NEVER phones home unless MCPMAKE_TELEMETRY_URL is set.

package/dist/emitter/site-templates/server-main-http.ts.hbs

@@ -74,6 +74,10 @@ let isReady = false;
 
 if (process.env.TRANSPORT === 'http') {
   const port = parseInt(process.env.PORT ?? '3000', 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    log('error', 'Invalid PORT value, must be 1-65535', { PORT: process.env.PORT });
+    process.exit(1);
+  }
   const allowedOrigin = process.env.ALLOWED_ORIGIN;
 
   const httpServer = http.createServer(async (req, res) => {
@@ -159,8 +163,10 @@ if (process.env.TRANSPORT === 'http') {
   const shutdown = async () => {
     log('info', 'Shutting down...');
     await closeBrowser();
-    httpServer.close();
-    setTimeout(() => process.exit(0), 5000);
+    // Exit as soon as the server finishes draining; the timer is only a
+    // forced-exit backstop and is unref'd so it never holds the loop open.
+    httpServer.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 5000).unref();
   };
 
   process.on('SIGTERM', shutdown);
@@ -172,8 +178,11 @@ if (process.env.TRANSPORT === 'http') {
   await server.connect(transport);
   isReady = true;
 
-  process.on('SIGTERM', async () => {
+  const shutdown = async () => {
     await closeBrowser();
     process.exit(0);
-  });
+  };
+
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
 }

package/dist/emitter/site-templates/server-main.ts.hbs

@@ -17,7 +17,10 @@ registerAllTools(server, config);
 const transport = new StdioServerTransport();
 await server.connect(transport);
 
-process.on('SIGTERM', async () => {
+const shutdown = async () => {
   await closeBrowser();
   process.exit(0);
-});
+};
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);

package/dist/emitter/site-templates/telemetry.ts.hbs

@@ -66,10 +66,16 @@ export function sessionStarted(sessionId: string): void {
   ensureTimer();
 }
 
-/** Record that a browser session was torn down (idle | explicit | shutdown). */
+/** Record that a browser session was torn down (idle | explicit | shutdown |
+ *  crash). Idempotent: emits at most one session_end per session. A second end
+ *  for the same id (e.g. an explicit close that resumes after flushOnShutdown
+ *  already ended it on SIGTERM, or a crash racing a teardown) is a no-op, and an
+ *  end for a session that never started (a reserved-but-unstarted slot) emits
+ *  nothing — so the host's occupancy ledger can never be double-decremented. */
 export function sessionEnded(sessionId: string, reason: string): void {
   if (!ENABLED) return;
-  openSessions.delete(sessionId);
+  // openSessions is the source of truth: only the call that removes the id emits.
+  if (!openSessions.delete(sessionId)) return;
   pushEvent({ type: 'session_end', sessionId, ts: Date.now(), reason });
   // Flush promptly so the host can finalize this session's billing.
   void flush();
@@ -108,6 +114,11 @@ async function flush(): Promise<void> {
 /** Best-effort final flush on shutdown: end every open session and send. */
 export async function flushOnShutdown(reason = 'shutdown'): Promise<void> {
   if (!ENABLED) return;
+  // Stop the heartbeat interval so no flush can fire after this final boundary.
+  if (flushTimer) {
+    clearInterval(flushTimer);
+    flushTimer = undefined;
+  }
   const now = Date.now();
   for (const id of [...openSessions]) {
     openSessions.delete(id);