Merge pull request #668: feat(limits): make the global session cap configurable with CODEMAN_MAX_SESSIONS

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/config/map-limits.ts

@@ -18,11 +18,40 @@
 // Session Tracking Limits
 // ============================================================================
 
+/** Default cap on concurrent sessions when `CODEMAN_MAX_SESSIONS` is not set. */
+const DEFAULT_MAX_CONCURRENT_SESSIONS = 50;
+
+/**
+ * Highest value `CODEMAN_MAX_SESSIONS` can raise the cap to. An owner's tab layout
+ * holds at most `MAX_TAB_REFS` (512) refs, and those count saved web tabs as well
+ * as sessions; an owner can save up to `MAX_WEBVIEWS` (50 by default) web tabs.
+ * 512 - 50 = 462 keeps session creation answering with the capacity message
+ * instead of failing with a 500 on the layout limit, at the default `MAX_WEBVIEWS`
+ * and with no pinned closed sessions: a pinned session stays in the layout as a
+ * stopped record after it is closed, and it shares the same 512-ref budget.
+ * (`PUT /api/session-order` accepts up to 500 ids, which stays above this.)
+ */
+export const MAX_CONCURRENT_SESSIONS_CEILING = 462;
+
+/**
+ * Resolve the session cap from `CODEMAN_MAX_SESSIONS` (a positive integer,
+ * clamped to {@link MAX_CONCURRENT_SESSIONS_CEILING}). Anything else (unset,
+ * empty, 0, negative, fractional, not a number) falls back to
+ * {@link DEFAULT_MAX_CONCURRENT_SESSIONS}, so a typo never locks session creation.
+ */
+function resolveMaxConcurrentSessions(): number {
+  const raw = process.env.CODEMAN_MAX_SESSIONS?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return DEFAULT_MAX_CONCURRENT_SESSIONS;
+  const n = Number(raw);
+  return n >= 1 ? Math.min(n, MAX_CONCURRENT_SESSIONS_CEILING) : DEFAULT_MAX_CONCURRENT_SESSIONS;
+}
+
 /**
  * Maximum concurrent sessions allowed.
  * Each session consumes significant resources (PTY, buffers, watchers).
+ * 50 unless `CODEMAN_MAX_SESSIONS` says otherwise (1 to 462); read once at startup.
  */
-export const MAX_CONCURRENT_SESSIONS = 50;
+export const MAX_CONCURRENT_SESSIONS = resolveMaxConcurrentSessions();
 
 // ============================================================================
 // SSE Client Limits

src/web/schemas.ts

@@ -1981,7 +1981,8 @@ export const CaseOrderSchema = z.object({
 /** PUT /api/session-order — global tab order (ordered sessionIds), COD-131 */
 export const SessionOrderUpdateSchema = z.object({
   // Bounded defensively: ids are uuid-ish (<=100 chars) and the client pushes only
-  // its open-tab order (max sessions is 50) — 500 leaves ample headroom while
+  // its open-tab order (max sessions is 50 by default, at most 462 via CODEMAN_MAX_SESSIONS,
+  // see MAX_CONCURRENT_SESSIONS_CEILING) — 500 leaves enough room while
   // keeping a hostile/buggy client from persisting megabytes into state.json.
   order: z.array(z.string().max(100)).max(500),
 });