feat(agents): resource discipline for parallel dev agents in one container

Maintainer-reported OOM under parallel dispatch. Memory peaks are the
build/test phases, so heavy phases serialize on a container-wide flock
(/tmp/os-heavy-verify.lock) while editing stays parallel; plus heap caps
(NODE_OPTIONS max-old-space-size), scoped --filter builds/tests, capped
vitest/turbo workers, and worktree cleanup after the PR is up. PM-side:
batch:2 or mode:cloud for build-heavy tasks; OOM-killed agents redispatch
alone.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012C2cd7tL8QDoZ2QKN3djJ5

Author: claude

.claude/agents/os-dev.md

@@ -33,6 +33,23 @@ rules that most often get missed:
    consumer (`??` alias, tolerant parse), the bug is at the producer or in the
    spec — fix it there, or return `needs_decision`.
 
+**Resource discipline — parallel agents share ONE container; unbounded
+build/test runs OOM it.** Binding rules:
+
+1. **Serialize the heavy phase.** Wrap every build and test run in the shared
+   verification lock, so editing parallelizes but memory peaks never stack:
+   `flock -w 7200 /tmp/os-heavy-verify.lock -c '<build/test command>'`
+   (one lock file per container; waiting on it is normal, not a hang).
+2. **Cap the heap.** Prefix heavy commands with
+   `NODE_OPTIONS=--max-old-space-size=4096` (raise only with a reason).
+3. **Scope, don't sweep.** Build and test the affected packages
+   (`pnpm --filter <pkg> build/test`), not the whole repo, unless the task
+   explicitly requires a full pass. Cap test parallelism:
+   vitest `--maxWorkers=2`, turbo `--concurrency=2`.
+4. **Clean up when done**: after the PR is up, remove your worktree
+   (`git worktree remove <path> --force`) — leftover `node_modules` trees
+   exhaust the container's disk, which fails as confusingly as OOM.
+
 Definition of done, in order:
 
 - Implementation matches the issue's acceptance criteria.

.claude/skills/pm-dispatch/SKILL.md

@@ -242,6 +242,19 @@ Follow your operating procedure (you are the os-dev agent). Non-negotiables:
 Return ONLY the JSON report defined in your agent definition.
 ```
 
+#### Resource limits — parallel agents share ONE container
+
+Memory peaks come from **build + test**, not editing, so the fix is not less
+parallelism but serialized heavy phases: the os-dev definition requires every
+build/test run to hold the container-wide verification lock
+(`flock /tmp/os-heavy-verify.lock`), a `NODE_OPTIONS=--max-old-space-size`
+heap cap, scoped `--filter` builds/tests, capped vitest/turbo workers, and
+worktree cleanup after the PR is up. PM-side: treat `batch:3` as assuming
+normal-sized tasks — for build-heavy ones (dependency-family upgrades, full
+regression passes) drop to `batch:2`, or dispatch that issue via
+`mode:cloud` so it gets its own container. If an agent dies with a
+heap/OOM signature, redispatch it alone rather than into a full batch.
+
 #### Dispatch backends
 
 **`mode:subagent` (default).** The `Agent` tool, as described above. The devs