typecheck-hygiene.mdc1.9 KBView on GitHub ---
description: Scoped typechecks/tests, timeouts, and orphan cleanup — prevents OOM that kills Vite/dev.
alwaysApply: true
---
# Agent resource hygiene (typecheck + vitest)
Full-project `tsc` and full-suite `vitest run` are expensive (hundreds of MB–GB each, many
workers). Abandoned agent runs OOM the machine and make `localhost` hang. Follow this every session.
## Typecheck — do
- Package-scoped only (unless the user asks for a full monorepo gate):
- `timeout 300 pnpm --filter @zero/mail run types`
- `timeout 300 pnpm --filter @zero/mail run types:test`
- `timeout 300 pnpm --filter @zero/server run types`
- `timeout 300 pnpm --filter @zero/server run types:test`
- Always wrap scoped typecheck/vitest with `timeout 300 …`. Wait for completion — never background and walk away.
- Full server vitest suite only when asked: `timeout 600 pnpm --filter @zero/server exec vitest run`
- Filter output: `… 2>&1 | rg "YourFile|error TS" | head`
## Vitest (server) — do
- **Scope to the files you changed** (or their `__tests__` neighbors). Examples:
- `timeout 300 pnpm --filter @zero/server exec vitest run src/services/crm/__tests__/foo.test.ts`
- `timeout 300 pnpm --filter @zero/server exec vitest run src/trpc/routes/__tests__/user-tasks`
- Prefer one path/directory over the whole suite.
- Wait for completion (or timeout). Never background a full `vitest run` and walk away.
## Don't
- Repo-wide `pnpm types` or bare `npx vitest run` / `vitest run` with no path for routine checks
- Parallel bare `tsc --noEmit` **and** `tsc -b` on the same package
- Leaving typechecks or vitest workers running after the turn ends
## When the laptop/dev is strained
`pnpm cleanup:orphans` — kills leftover agent `tsc`, abandoned `vitest`, and orphaned esbuild
(ppid=1). Then restart `pnpm dev` / `pnpm run dev:axiom` if needed.
Canonical write-up: `AGENTS.md` → “Typecheck hygiene” and “Vitest hygiene”.