fix(limits): clamp CODEMAN_MAX_SESSIONS to 500 and document it

Review follow-up. Other bounds assume a small session count: an owner's
tab layout holds at most MAX_TAB_REFS (512) refs and PUT
/api/session-order accepts at most 500 ids, so with
CODEMAN_MAX_SESSIONS=600 the 513th session creation answered HTTP 500
instead of the capacity message. The value is now clamped to a named
MAX_CONCURRENT_SESSIONS_CEILING of 500; any digit string above it
(including one past the safe-integer range) resolves to 500 instead of
falling back to 50. The resolver reads process.env directly, the unused
env parameter is gone.

Docs: a CODEMAN_MAX_SESSIONS row in the Settings Reference environment
table, the env name next to the cap in the cron guide and the
architecture invariants, and both copies of the skill's endpoints
reference now give the per-user cap as half the global cap (25 by
default). The changeset says "1 to 500". The test drops the
`as unknown as string` casts and adds '1000', '501' and an
out-of-range value, each refusing at 500.

Co-Authored-By: Christian Haberl <116439789+christianhaberl@users.noreply.github.com>
Co-Authored-By: Claude <noreply@anthropic.com>

src/config/map-limits.ts

@@ -22,21 +22,31 @@
 const DEFAULT_MAX_CONCURRENT_SESSIONS = 50;
 
 /**
- * Resolve the session cap from `CODEMAN_MAX_SESSIONS` (a positive integer).
- * 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.
+ * Highest value `CODEMAN_MAX_SESSIONS` can raise the cap to. Other bounds assume
+ * the session count stays small: an owner's tab layout holds at most
+ * `MAX_TAB_REFS` (512) refs and `PUT /api/session-order` accepts at most 500 ids,
+ * so a larger cap would let session creation fail with a 500 instead of the
+ * capacity message.
  */
-function resolveMaxConcurrentSessions(env: NodeJS.ProcessEnv = process.env): number {
-  const raw = env.CODEMAN_MAX_SESSIONS?.trim();
+export const MAX_CONCURRENT_SESSIONS_CEILING = 500;
+
+/**
+ * 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 Number.isSafeInteger(n) && n >= 1 ? n : DEFAULT_MAX_CONCURRENT_SESSIONS;
+  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; read once at startup.
+ * 50 unless `CODEMAN_MAX_SESSIONS` says otherwise (1 to 500); read once at startup.
  */
 export const MAX_CONCURRENT_SESSIONS = resolveMaxConcurrentSessions();
 

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 by default) — 500 leaves ample headroom while
+  // its open-tab order (max sessions is 50 by default, at most 500 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),
 });