feat(usage-limits): full kill-switch + flip default to opt-in

Default flip (false) — AIF_USAGE_LIMITS_ENABLED now defaults off so the
live refresh path (Codex FS scan, Claude identity lookup) is skipped
unless explicitly enabled. Perf win on /runtime-profiles cold: 6794ms →
109ms (62× faster); k6 throughput 3.2×.

Extended the gate beyond /runtime-profiles + UI surfaces to cover the
remaining paths that previously kept running regardless of the flag:
  * runtime.ts — observeRuntimeLimitEvent /
    extractLatestRuntimeLimitSnapshot / extractRuntimeLimitSnapshotFromError
    wrap-functions short-circuit; broadcastRuntimeLimitUpdate early-returns
    (no project:runtime_limit_updated WS fan-out)
  * chat.ts — normalizeOptionalRuntimeLimitSnapshot returns null when
    disabled, so chat responses no longer carry runtimeLimitSnapshot
  * stageErrorHandler.ts — limitSnapshot not persisted onto tasks
  * ChatPanel — CHAT_USAGE_LIMIT fallback banner gated on the flag

Tests updated to seed AIF_USAGE_LIMITS_ENABLED=true where they assert on
snapshot persistence / emission (stageErrorHandler, coordinator,
chat.test, runtimeService.test, runtimeProfiles.test, hooks.test).

Adjacent dev-loop fixes bundled in the same change because they share
the Ctrl+C / port-3009 failure surface users hit when iterating on the
gate:
  * api/index.ts + ws.ts — SIGINT/SIGTERM handler terminates all
    WebSocket clients and calls server.close() synchronously so the
    port frees on shutdown
  * mcp/src/index.ts — same handler in HTTP transport
  * api / agent / mcp dev scripts — tsx watch → node --watch --import tsx,
    removes the "Previous process hasn't exited yet. Force killing..."
    restart race (node --watch still needs 2× Ctrl+C by design,
    accepted tradeoff)
  * turbo.json — globalPassThroughEnv so env changes don't break task
    hashing

Docs: docs/configuration.md + .env.example describe the full list of
gated surfaces, not just the live-refresh path.

Author: lee-to

.env.example

@@ -173,13 +173,22 @@ LOG_LEVEL=debug
 # AGENT_WAKE_ENABLED=true
 
 # ----------------------------------------------------------
-# Usage-limits feature toggle
-# ----------------------------------------------------------
-# When true (default) the API refreshes Codex/Claude rate-limit snapshots on
-# every /runtime-profiles request. On machines with thousands of Codex session
-# rollouts this incurs filesystem scans. Set to false to disable the live
-# refresh (persisted snapshots are still returned but never updated).
-# AIF_USAGE_LIMITS_ENABLED=true
+# Usage-limits feature toggle (master switch)
+# ----------------------------------------------------------
+# Default false. When false the full usage-limits pipeline is off:
+#   * /runtime-profiles skips the ~/.codex/sessions filesystem scan and the
+#     Claude provider-identity lookup.
+#   * Runtime service skips observeRuntimeLimitEvent /
+#     extractLatestRuntimeLimitSnapshot / extractRuntimeLimitSnapshotFromError
+#     during every runtime run, and suppresses the
+#     project:runtime_limit_updated WebSocket broadcast.
+#   * Agent stage error handler does not persist limitSnapshot onto tasks.
+#   * Chat API omits runtimeLimitSnapshot from responses.
+#   * Web UI hides the USAGE button, TaskCard/TaskDetailHeader badges,
+#     Recent Limit Signals panel, and Chat active-limit banner.
+# Persisted snapshots are still returned on read but never refreshed.
+# Enable only if you actively monitor rate-limit windows.
+# AIF_USAGE_LIMITS_ENABLED=false
 
 # ----------------------------------------------------------
 # Codex OAuth login in Docker (dev-only broker)

docs/configuration.md

@@ -6,7 +6,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "tsx watch src/index.ts",
+    "dev": "node --watch --import tsx src/index.ts",
     "build": "tsc",
     "start": "node dist/index.ts",
     "test": "vitest run --configLoader runner",

packages/agent/package.json

@@ -1,9 +1,14 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { tasks, projects, runtimeProfiles } from "@aif/shared";
+import { tasks, projects, runtimeProfiles, resetEnvCache } from "@aif/shared";
 import { createTestDb } from "@aif/shared/server";
 import { RuntimeExecutionError } from "@aif/runtime";
 import { eq } from "drizzle-orm";
 
+// Flag defaults to false (opt-in). Coordinator tests assert on persisted
+// limitSnapshot, which requires the gate to be open.
+process.env.AIF_USAGE_LIMITS_ENABLED = "true";
+resetEnvCache();
+
 // Set up test db
 const testDb = { current: createTestDb() };
 const blockTaskForRuntimeGateIfEligibleMock = vi.fn();

packages/agent/src/__tests__/coordinator.test.ts

@@ -67,7 +67,7 @@ function makeEnv(overrides: Record<string, unknown> = {}) {
     AGENT_AUTO_REVIEW_STRATEGY: "full_re_review" as const,
     AGENT_USE_SUBAGENTS: true,
     AGENT_FIRST_ACTIVITY_TIMEOUT_MS: 60_000,
-    AIF_USAGE_LIMITS_ENABLED: true,
+    AIF_USAGE_LIMITS_ENABLED: false,
     AIF_ENABLE_CODEX_LOGIN_PROXY: false,
     AIF_CODEX_LOGIN_BROKER_PORT: 3010,
     AIF_CODEX_LOGIN_LOOPBACK_PORT: 1455,

packages/agent/src/__tests__/hooks.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { RuntimeExecutionError, type RuntimeLimitSnapshot } from "@aif/runtime";
+import { resetEnvCache } from "@aif/shared";
+
+// Flag defaults to false (opt-in). These tests assert on limitSnapshot
+// persistence, which requires the gate to be open.
+process.env.AIF_USAGE_LIMITS_ENABLED = "true";
+resetEnvCache();
 
 const { mockWarn, mockError } = vi.hoisted(() => ({
   mockWarn: vi.fn(),

packages/agent/src/__tests__/stageErrorHandler.test.ts

@@ -6,6 +6,7 @@
 
 import type { RuntimeLimitSnapshot } from "@aif/runtime";
 import {
+  getEnv,
   logger,
   mapSafeRuntimeErrorReason,
   redactProviderTextForLogs,
@@ -80,7 +81,12 @@ function resolveRetryAfter(err: unknown): {
   limitSnapshot: RuntimeLimitSnapshot | null;
 } {
   const runtimeError = findRuntimeExecutionError(err);
-  const limitSnapshot = runtimeError?.limitSnapshot ?? null;
+  // When usage-limits feature is disabled, don't persist the limit snapshot
+  // onto the task. Retry/backoff still applies — we just skip the surface
+  // that feeds the (also-gated) UI.
+  const limitSnapshot = getEnv().AIF_USAGE_LIMITS_ENABLED
+    ? (runtimeError?.limitSnapshot ?? null)
+    : null;
 
   if (runtimeError?.resetAt) {
     const resetAtMs = Date.parse(runtimeError.resetAt);
@@ -126,7 +132,9 @@ export function classifyStageError(input: StageErrorInput): ErrorRecovery {
   if (runtimeError && NON_RETRYABLE_RUNTIME_CATEGORIES.has(runtimeError.category)) {
     const safeReason = mapSafeRuntimeErrorReason(runtimeError);
     const blockedReason = `${safeReason.reason} Manual action required before retry.`;
-    const limitSnapshot = runtimeError.limitSnapshot ?? null;
+    const limitSnapshot = getEnv().AIF_USAGE_LIMITS_ENABLED
+      ? (runtimeError.limitSnapshot ?? null)
+      : null;
 
     logActivity(
       taskId,

packages/agent/src/stageErrorHandler.ts

@@ -6,7 +6,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "tsx watch src/index.ts",
+    "dev": "node --watch --import tsx src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
     "test": "vitest run --configLoader runner",

packages/api/package.json

@@ -1,6 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { Hono } from "hono";
 import { RuntimeExecutionError, type RuntimeAdapter, type RuntimeRunInput } from "@aif/runtime";
+import { resetEnvCache } from "@aif/shared";
+
+// Flag defaults to false (opt-in). These tests assert on runtime limit
+// snapshots being emitted to chat responses, which needs the gate open.
+process.env.AIF_USAGE_LIMITS_ENABLED = "true";
+resetEnvCache();
 
 const mockFindProjectById = vi.fn();
 const mockFindTaskById = vi.fn();
@@ -119,6 +125,7 @@ vi.mock("@aif/shared", async (importOriginal) => {
       AGENT_CHAT_MAX_TURNS: 50,
       AIF_DEFAULT_RUNTIME_ID: "claude",
       AIF_DEFAULT_PROVIDER_ID: "anthropic",
+      AIF_USAGE_LIMITS_ENABLED: true,
     }),
   };
 });

packages/api/src/__tests__/chat.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { Hono } from "hono";
 import { eq } from "drizzle-orm";
 import { createTestDb } from "@aif/shared/server";
@@ -62,8 +62,15 @@ function createApp() {
 
 describe("runtimeProfiles API", () => {
   let app: ReturnType<typeof createApp>;
+  let previousUsageLimitsEnv: string | undefined;
 
   beforeEach(() => {
+    previousUsageLimitsEnv = process.env.AIF_USAGE_LIMITS_ENABLED;
+    // Flag defaults to false (opt-in). Most tests here exercise the live
+    // refresh path, so enable it per-test. Cases that need the disabled
+    // path override and restore this inside the test body.
+    process.env.AIF_USAGE_LIMITS_ENABLED = "true";
+    resetEnvCache();
     testDb.current = createTestDb();
     app = createApp();
     mockValidateConnection.mockReset();
@@ -109,6 +116,15 @@ describe("runtimeProfiles API", () => {
     ]);
   });
 
+  afterEach(() => {
+    if (previousUsageLimitsEnv === undefined) {
+      delete process.env.AIF_USAGE_LIMITS_ENABLED;
+    } else {
+      process.env.AIF_USAGE_LIMITS_ENABLED = previousUsageLimitsEnv;
+    }
+    resetEnvCache();
+  });
+
   it("lists runtime descriptors", async () => {
     const res = await app.request("/runtime-profiles/runtimes");
     expect(res.status).toBe(200);