High memory consumption in tsc (~8 GB) causing red memory pressure and swap thrashing on 16 GB Apple Silicon (M4)

[RealYusufIsmail]

Summary

When running typecheck / build tasks on Apple Silicon (tested on an M4 Mac with 16 GB unified memory), the TypeScript compiler (tsc) balloons up to ~8 GB of memory (Activity Monitor reports 7.99 GB). This sends macOS memory pressure into the critical red zone and pushes the system into heavy swap thrashing (6.46 GB swap, 5.93 GB compressed memory).

As a result, system responsiveness drops sharply and other applications hang or become unresponsive (e.g., Microsoft Word (Not Responding)).

---

Evidence & System State

Process Details (tsc PID 90385)

• Path: node_modules/.pnpm/typescript@.../bin/tsc
• Parent Process: node (PID 90357)
• Activity Monitor Memory: 7.99 GB
• Real Memory Size: 1,013.4 MB
• Virtual Memory Size: 451.32 GB
• Private Memory Size: 1,000.0 MB
• CPU Usage: ~32%

System Memory Metrics (16.00 GB Physical RAM)

• Memory Pressure: Solid Red (Critical)
• Memory Used: 13.31 GB
• Compressed Memory: 5.93 GB
• Swap Used: 6.46 GB
• App Memory: 3.77 GB | Wired Memory: 3.02 GB | Cached Files: 1.42 GB
• Side effects: High swap I/O pressure, background apps freezing.

---

Likely Factors

1. Complex Generics & Effect-TS Type Graph:
   The monorepo relies heavily on Effect schemas, services, and large union/intersection types across apps/server, packages/client-runtime, and packages/contracts. Deep recursive type inference or un-memoized intermediate types can cause tsc's internal type caches and ASTs to expand dramatically.
2. Typecheck Concurrency vs. Memory Footprint:
   While root scripts cap concurrency (e.g. vp run -r --concurrency-limit 2 typecheck), concurrent typechecking across large packages without conservative Node heap limits (--max-old-space-size) can quickly overwhelm a 16 GB machine when running alongside normal development workloads.

---

Suggested Directions & Mitigations

1. Profile Type Instantiations with Type Tracing:
   • Run tsc --generateTrace and inspect with @typescript/analyze-trace to identify which files and symbols consume the most check time and instantiate the most types.
   • Run tsc --extendedDiagnostics on the heaviest packages (apps/server, packages/client-runtime) to check memory and instantiation counts.
2. Refactor Pathological Schema / Union Types:
   • Simplify or break apart deeply nested conditional/union types into explicit interfaces or pre-computed types where possible.
3. Project References / Cache Boundaries:
   • Ensure clean boundaries between packages so TypeScript does not retain unnecessary dependent project trees simultaneously in memory.
4. Tune Local Memory Budgets:
   • Ensure typecheck commands run within sensible memory ceilings so local development on base 16 GB M-series Macs doesn't trigger severe swap thrashing.

---

Questions:

1. Have others noticed tsc memory spikes or extreme memory pressure during local typechecking or build runs on 16 GB Macs?
2. Are there known packages or schema files identified as the primary type-check bottlenecks?
3. Would PRs focusing on profiling and optimizing heavy type inference bottlenecks or refining concurrency settings be welcome?

[RealYusufIsmail]

Root Cause Update & Proposed Fixes

Following up after deeper profiling into the process tree and repository history:

1. tsc is a native Go executable (tsgo / @effect/tsgo)

In PR #10663 and commit 6b3050ee74, the monorepo migrated TypeScript checks to TypeScript 7.0.2 (typescript-go / tsgo), patched by @effect/tsgo (embedding Effect's language service directly into the native Go compiler binary).

• In the Activity Monitor inspector, the telltale signature is Virtual Memory Size: 451.32 GB. That is the Go runtime memory allocator reserving its 64-bit virtual memory address space (sysReserve), not a V8/Node heap.
• The parent process node (90357) is the vp (Vite+) / pnpm runner invoking the native tsc binary.

2. Thread-isolated typecheckers duplicating Effect type caches

• Unlike single-threaded Node tsc, tsgo parallelizes checking across worker threads matching CPU core counts. On an Apple Silicon M4 (10 cores), tsgo launches 10 worker threads.
• To prevent locking contention between threads, each worker thread maintains its own duplicate symbol and type cache.
• The monorepo has an extensive Effect type graph (hundreds of Schema classes, tagged unions, and service interfaces). Multiplying that across 10 threads means 10 distinct copies of heavy symbol tables.
• Combined with vp run -r --concurrency-limit 2 typecheck, up to 20 worker caches are instantiated in parallel across the two packages.

3. Unconstrained Go GC on 16 GB Macs

• Go defaults to GOGC=100 and has no GOMEMLIMIT set by default in the repo scripts or environment.
• The Go heap continues expanding past 4–8 GB before triggering a collection.
• On a 16 GB Mac, macOS cannot satisfy an 8 GB active footprint without compressing dirty pages (5.93 GB compressed) and swapping to disk (6.46 GB swap), triggering the critical red memory pressure and UI freezes shown in the screenshot.

---

Immediate Mitigations (Local & CI)

Because tsc is a native Go binary, standard Go runtime environment variables immediately control its memory ceiling and thread count:

1. Set GOMEMLIMIT and GOGC:
   Cap the Go heap ceiling so the GC reclaims memory before pushing macOS into swap:

   GOMEMLIMIT=3GiB GOGC=60 pnpm typecheck

2. Restrict thread explosion on 16 GB machines:
   Prevent 10+ parallel checker caches from exhausting memory:

   GOMAXPROCS=4 GOMEMLIMIT=3GiB pnpm typecheck

   Or pass --checkers 4 (or --singleThreaded) directly to tsc.

---

Auto-Optimization Strategy (T3 Code Perspective)

Rather than expecting every developer on an M-series Mac to manually export shell variables or pass flags:

1. Dynamic Resource Auto-Tuning in Repo Scripts:
   A tiny script or runner wrapper can inspect os.totalmem() and os.cpus():
   • On machines with $\le 16\text{ GB}$ RAM: automatically export GOMEMLIMIT=3GiB, GOMAXPROCS=4, and GOGC=60.
   • On 32 GB+ workstations: scale up to higher concurrency (GOMEMLIMIT=8GiB).
2. T3 Code Host Environment Auto-Configuration:
   In T3 Code's runner (scripts/dev-runner.ts / HostProcessEnvironment):
   • When spawning dev, build, or typecheck tasks, T3 Code can detect host architecture and unified memory limits and automatically inject safe defaults (GOMEMLIMIT, GOMAXPROCS, and NODE_OPTIONS) into child process environments.

[RealYusufIsmail]

Proposal: Auto-Optimization Architecture (T3 Code Perspective)

Following up on the root-cause diagnosis, rather than requiring individual developers on 16 GB Apple Silicon Macs to manually discover and export shell variables (GOMEMLIMIT, GOMAXPROCS), here is a proposal for how T3 Code can automatically tune resource budgets out-of-the-box based on host hardware:

flowchart TD
    Hardware["Hardware Probing (os.totalmem & os.cpus)"] --> Profile["Adaptive Resource Profiler"]
    Profile --> Runner["1. scripts/dev-runner.ts & Repo Scripts"]
    Profile --> Server["2. T3 Code Host Process Layer (apps/server & Desktop)"]
    Profile --> LSP["3. Language Service / Extension Settings"]
    
    subgraph Auto_Tuning ["Auto-Tuned Variables"]
      Runner --> V1["GOMEMLIMIT: ~25% RAM (3GiB on 16GB)"]
      Runner --> V2["GOMAXPROCS: Capped to 4 on 16GB"]
      Runner --> V3["GOGC: 60 (more aggressive GC)"]
      Runner --> V4["NODE_OPTIONS: --max-old-space-size"]
    end

Loading

---

1. Hardware-Aware Adaptive Profiler (scripts/dev-runner.ts & Repo Scripts)

T3 Code's dev server runner already manages environment loading via loadRepoEnv(). We can add a lightweight adaptive helper that automatically sets safe defaults if not explicitly overridden by the developer:

import * as NodeOS from "node:os";

export function resolveAdaptiveEnvironment(): Record<string, string> {
  const totalMemGb = Math.round(NodeOS.totalmem() / (1024 ** 3));
  const cpuCount = NodeOS.cpus().length;
  const isConstrained = totalMemGb <= 16;

  return {
    // Soft memory limit for Go runtime binaries (tsgo / @effect/tsgo / tsc)
    GOMEMLIMIT: process.env.GOMEMLIMIT ?? (isConstrained ? "3GiB" : totalMemGb <= 32 ? "6GiB" : "12GiB"),

    // Prevent 10+ M4 worker threads from each duplicating symbol caches
    GOMAXPROCS: process.env.GOMAXPROCS ?? String(isConstrained ? Math.min(cpuCount, 4) : cpuCount),

    // Collect dead ASTs/types earlier before swap pressure builds
    GOGC: process.env.GOGC ?? (isConstrained ? "60" : "100"),

    // Node V8 heap ceiling
    NODE_OPTIONS: process.env.NODE_OPTIONS ?? `--max-old-space-size=${isConstrained ? 4096 : 8192}`,
  };
}

---

2. T3 Code Host Execution Environment (packages/shared/src/hostProcess.ts & apps/server)

T3 Code manages process execution for background tasks, worktrees, and agent commands via HostProcessEnvironment and resolveSpawnCommand.

When booting on Apple Silicon (darwin-arm64) with $\le 16\text{ GB}$ Unified Memory:

• T3 Code can automatically inject calibrated runtime boundaries (GOMEMLIMIT, GOMAXPROCS, NODE_OPTIONS) into child process environments.
• Explicit user configurations (in .env or system environment) continue to take precedence.

---

3. Dynamic Package Concurrency in package.json (vp run)

In root package.json:

"typecheck": "vp run -r --concurrency-limit 2 typecheck"

On a 16 GB M4, running 2 heavy packages concurrently while each spawns 10 internal tsgo worker threads creates up to 20 simultaneous typecheckers.

• A small runner script or dynamic Vite+ config can scale package concurrency to 1 when physical memory is $\le 16\text{ GB}$, while allowing 2 (or higher) on 32 GB+ workstations.

---

4. Editor / Language Service Defaults

In workspace .vscode/settings.json, supply default bounds for the native preview language server so it doesn't quietly expand during editing sessions:

{
  "typescript.nativePreview.goMemLimit": "3GiB"
}