Distillation

Date: Sep 16, 2026

• 🔴 (23:53) User stated constrained memory must never be admitted from a stale cgroup directory or a cached discovery miss.
• 🔴 (23:53) User stated sibling cgroup usage must never be subtracted from the wrong scope.
• 🔴 (23:53) User stated a host logger or sink must never interrupt stream consumption.
• 🔴 (23:53) User stated embedding-pool growth must never multiply memory pressure on a constrained host.
• 🔴 (23:53) User stated memory clamping may only lower the reported figure, never raise it, so it never increases memory use.
• 🟡 (23:53) Added packages/core/src/cgroup-memory.ts as a new 205-line module for container/cgroup-aware memory discovery, including hybrid cgroup v1/v2 handling and octal escape decoding via String.fromCharCode(Number.parseInt(octal, 8)).
• 🟡 (23:53) Cgroup discovery is fail-closed for constrained hierarchies: stale cgroup directories, cached discovery misses, and unreadable constrained mount roots cannot contribute unsafe memory headroom.
• 🟡 (23:53) Cgroup scope handling requires the matching usage file to remain readable before calculating headroom, preventing sibling usage from being subtracted from an unrelated limit.
• 🟡 (23:53) The memory-sizing implementation now exports availableMemoryHeadroom.
• 🟡 (23:53) Replaced exported PER_WORKER_MEM_BUDGET_BYTES with internal MODELED_WORKER_MEM_BUDGET_BYTES, calculated as EMBED_MODEL_BASELINE_BYTES + EMBED_ATTENTION_BYTES_PER_TOKEN_SQ * EMBED_POOL_BUDGET_REF_TOKENS * EMBED_POOL_BUDGET_REF_TOKENS; it represents the model plus a 2048-token attention estimate and is the lower bound for pool admission.
• 🟡 (23:53) Constrained-memory sizing returns 0 when a finite limit exists but usable headroom cannot be established: if (Number.isFinite(limit) && !hasHeadroom) return 0.
• 🟡 (23:53) Added packages/core/test/cgroup-memory.test.ts coverage for unified cgroup v2 paths such as 0::/worker.slice, escaped mount paths such as /run/cgroup mount/worker.slice, legacy cgroup v1 memory paths such as 3:memory:/legacy/worker, fail-closed behavior when a constrained mount root is unreadable, v1 headroom, and oversized v1 unlimited sentinels treated as max.
• 🟡 (23:53) Cgroup tests exercise scoped files including /run/cgroup/system.slice/opencode.service/memory.current, /run/cgroup/job/memory.max, /run/cgroup/tenant/memory.max, and /run/memory/memory.limit_in_bytes, with sample values including 600, 2000, and max.
• 🟡 (23:53) packages/core/test/embedding-pool-memory.test.ts documents Onur’s report that the pool grew to N workers while workers independently sized themselves; guards test that each worker sizes from its free / ceiling share rather than full free memory, and that pool workers collectively remain within one memory-fraction budget.
• 🟡 (23:53) packages/core/test/embedding-pool-memory.test.ts covers use of the token floor when constrained primary-worker headroom is unknown via _setAvailableMemoryForTest(Number.NaN), and OOM recovery where memory collapses before EMBED_OOM_EXIT_CODE, the worker respawns, and the same request is resubmitted with a cap sized to the reduced live memory.
• 🟡 (23:53) Embedding-memory tests use _setConstrainedMemoryForTest(12 * GB) to model constrained memory independently of host free memory.
• 🟡 (23:53) packages/core/test/embedding-pool.test.ts covers container-aware pool admission: remaining at one worker when a cgroup limit cannot fit a second worker, remaining at one worker when current cgroup headroom cannot fit a second, and reserving headroom while an admitted worker is still initializing so the same headroom cannot be spent twice.
• 🟡 (23:53) The pool tests specifically assert that clamping to 256 MiB, below one per-worker budget, must not load a second native ONNX worker and risk exceeding memory.max via SIGKILL.