@gluecharm-lab/easyspecs-cli 0.0.26 → 0.0.28

package/commands.md

@@ -68,9 +68,11 @@ Environment (stderr styling): `**NO_COLOR`** (any non-empty value) disables ANSI
 
 ---
 
-## Workstation host inventory (**SRS-64** / **SRS-62**)
+## Workstation host inventory (**SRS-69** / **SRS-62**)
 
-`**easyspecs-cli workstation info**` prints the CPU count used for the **SRS-64 §4.1** heuristic, total installed RAM, **`N_sys`** (JSON key **`maxSystemConcurrentAiWorkstations`**), and **`hostHardMaxConcurrentAi`** = **`min(N_sys, 64)`** (product agent ceiling per **SRS-62**). **macOS** (`darwin`) and **Linux** only; on other platforms the CLI exits **non-zero**, writes a short message to stderr, and does **not** print JSON on stdout (even if **`--json`** was passed).
+`**easyspecs-cli workstation info**` prints the CPU count used for the **SRS-69 §4** heuristic, total installed RAM, **`N_sys`** (JSON key **`maxSystemConcurrentAiWorkstations`**), and **`hostHardMaxConcurrentAi`** = **`min(N_sys, 64)`** (product agent ceiling per **SRS-62**). **macOS** (`darwin`) and **Linux** only; on other platforms the CLI exits **non-zero**, writes a short message to stderr, and does **not** print JSON on stdout (even if **`--json`** was passed).
+
+**Formula (SRS-69 §4 — supersedes SRS-64 §4.1):** `N_float = min(P, R_GiB / 8)` where **`P`** is the physical CPU count and **`R_GiB`** is total installed RAM in GiB. Then **`N_sys = max(1, Math.round(N_float))`** and **`hostHardMax = min(64, N_sys)`**. In plain English: **one AI workstation per physical core, but never more than one per 8 GiB of installed RAM** — whichever dimension is tighter wins. **Worked example:** **`P=11, R=44 GiB → N_sys = 6 → hostHardMax = 6`** (was 100 under SRS-64). Operators on shared / interactive hosts (laptops also running an IDE + browser + chat apps) should set **`easyspecs.workstations.maxConcurrentAi`** *below* the reported `hostHardMax`. See live signals via **`[host-pool]`** / **`[host-pool-rec]`** (**SRS-68**).
 
 Use the **global** **`--json`** flag (before the subcommand) for one parseable summary line. JSON includes **`totalMemBytes`**, **`platform`**, **`cpusForCap`**, **`cpusForCapSource`**, **`physicalCpus`** (integer when physical cores are known, else **`null`**), **`maxSystemConcurrentAiWorkstations`**, and **`hostHardMaxConcurrentAi`**.
 
@@ -83,7 +85,16 @@ When Analysis (or other callers) passes a **`diagnosticLog`** sink into the exte
 - **`scope=host`** — machine-wide **RAM** (**total** / **free** / **used** bytes) plus **1-minute load average**, logical **CPU** count, and **load / CPUs** (not the same metric as the **SRS-62** runtime pool **CPU guard** — see **[SRS-65](../../.gluecharm/docs/srs/srs-65.md)**).
 - **`scope=child`** — once per run: **child CPU time** (milliseconds) and **RSS** bytes for that **PID** (**Linux**: **`/proc`**, **macOS**: **`ps`**), or **`childRssBytes=unknown`** on unsupported platforms / read errors.
 
-Tune concurrent agents with **`easyspecs.workstations.maxConcurrentAi`**, **`applyHostConcurrencyCap`**, and **`easyspecs-cli workstation info`** (**SRS-62** / **SRS-64**); these lines help interpret **live** pressure alongside that configuration.
+Tune concurrent agents with **`easyspecs.workstations.maxConcurrentAi`**, **`applyHostConcurrencyCap`**, and **`easyspecs-cli workstation info`** (**SRS-62** / **SRS-69**); these lines help interpret **live** pressure alongside that configuration.
+
+### Workstation pool host pressure (**SRS-68**)
+
+While the synthesis / remediation **workstation pool** has **≥ 1** in-flight OpenCode run, **`easyspecs-cli`** (human **`diagnosticLog`** / stderr path) emits a **pair** of lines every **45 seconds** (not configurable in v1 — **no** env/flag to disable):
+
+1. **`[host-pool]`** — **`activeWorkstations`**, **`staticMaxConcurrentAi`**, **`adaptiveMaxConcurrentAi`**, host RAM bytes, **`load1`**, **`load1PerCpu`**, optional Linux **`swapTotalB` / `swapFreeB`**, and four hints: **`hintScheduler`**, **`hintMemory`**, **`hintLimits`**, **`hintIo`** each **`OK`**, **`KO`**, or **`UNK`**. Hints are **heuristic** (not proof of root cause).
+2. **`[host-pool-rec]`** — **`kind=none`** when no hint is **`KO`**; otherwise **`kind=advice text=…`** with short guidance tuned for **dedicated workers** (e.g. **Celery** running only this task): lower **`easyspecs.workstations.maxConcurrentAi`**, worker memory/CPU limits, **`ulimit`**, disk checks — **not** “close other desktop apps”. **`text=`** is capped in length and may truncate with **` …`**.
+
+See **[SRS-68](../../.gluecharm/docs/srs/srs-68.md)** and **`USER-MANUAL-SRS-68.md`**.
 
 ---