instar 1.3.414 → 1.3.416

package/upgrades/side-effects/lint-no-blocking-process-scans.md

@@ -0,0 +1,73 @@
+# Side-Effects Review — lint: ban blocking process scans on the runtime hot path
+
+**Version / slug:** `lint-no-blocking-process-scans`
+**Date:** `2026-06-07`
+**Author:** `Echo`
+**Tier:** 1 (a new CI lint + comment-only src annotations + a test; no behavior change, no API/route/config/migration)
+**Second-pass reviewer:** `Echo (self) — Tier-1; preventive gate, no runtime behavior change`
+
+## Summary of the change
+
+Adds `scripts/lint-no-blocking-process-scans.js` (wired into `npm run lint`): in
+`src/monitoring/` and `src/server/`, a SYNCHRONOUS child-process call
+(`spawnSync`/`execSync`/`execFileSync`) whose command literal is a process-
+enumeration tool (`ps`/`pgrep`/`lsof`/`pkill`) now fails CI. This is post-mortem
+standard #3 for the 2026-06-07 "server temporarily down" incident (topic 21816):
+synchronous `ps`/`lsof` scans on a cadence blocked the event loop and starved
+`/health` under load → the supervisor restarted an alive server → the loop.
+#972 fixed SessionWatchdog; this lint stops the class from being re-introduced.
+
+The two existing in-dir call sites are `lsof` one-shots, allowlisted with inline
+`// lint-allow-blocking-scan:` justifications (comment-only edits):
+- `SessionRecovery.ts` — targeted `lsof -p <pid>` (single process, 5s timeout),
+  runs once during a session's JSONL recovery, not on a cadence.
+- `agentWorktreeGit.ts` — full-cwd `lsof` in AgentWorktreeReaper, which ships
+  dark + dry-run by default (not on any live agent's hot path); 15s timeout;
+  async conversion noted as a follow-up.
+
+## Decision-point inventory
+
+- The only decision: which sync calls to fail CI on. Scoped to the documented
+  load-sensitive enumeration commands (`ps`/`pgrep`/`lsof`/`pkill`) in the two
+  runtime hot dirs. tmux/git calls are deliberately NOT covered (bounded, fast,
+  ubiquitous — converting them is a separate, bigger concern and not this
+  incident's cause).
+
+## 1. False positives (flagging a safe call)
+
+A genuinely one-shot, bounded sync scan is excused by an inline
+`// lint-allow-blocking-scan: <reason>` (scanned up to 6 lines above the call to
+allow a multi-line justification). The escape hatch requires a written reason, so
+the decision is reviewed, not silent. Two current sites use it.
+
+## 2. False negatives (missing a real one)
+
+Static detection matches a string-literal command. A sync scan that passes the
+command via a variable (e.g. `execFileSync(file, args)` in `mcpProcessReaperDeps`)
+is not caught — accepted: the lint is a ratchet against the common, copy-pasted
+literal form; the variable-indirection cases are pre-existing and tracked. tmux
+is intentionally out of scope.
+
+## 3. Level-of-abstraction fit
+
+Correct: a CI lint in the existing `lint-no-*` family, modeled on
+`lint-no-unfunneled-headless-launch.js`. Structure > Willpower — a future periodic
+`spawnSync('ps')` fails the build instead of being discovered as a stall in prod.
+
+## 4. Blast radius
+
+CI-only. No runtime code changes (the two src edits are comments). Cannot affect a
+running agent. Worst case of a bug in the lint = a spurious CI failure, fixed by an
+allowlist comment or a lint tweak — never a production impact.
+
+## 5. Rollback
+
+Remove the script + the one `package.json` chain entry; revert the two comment
+annotations. No state/format change.
+
+## 6. Tests
+
+`tests/unit/lint-no-blocking-process-scans.test.ts` (5): flags sync ps; flags
+spawnSync pgrep + execSync lsof; honours the inline allow justification; ignores
+comment-only mentions + async/tmux calls; the real runtime tree is clean. The lint
+also self-validated against a synthetic violation. tsc clean.

package/upgrades/side-effects/subscription-account-email.md

@@ -0,0 +1,58 @@
+# Side-Effects Review — per-account email on the Subscription Pool
+
+## Scope of change
+
+- `src/core/SubscriptionPool.ts` — add optional `email` to `SubscriptionAccount`,
+  `AddAccountInput`, `UpdateAccountInput`; `add()`/`update()` store/patch it.
+- `src/core/QuotaPoller.ts` — new exported `readAccountEmail(configHome)` (reads the
+  PUBLIC `oauthAccount.emailAddress` from the config home's `.claude.json`); `pollAll()`
+  auto-populates `account.email` from it on each poll.
+- `src/server/routes.ts` — POST/PATCH `/subscription-pool` pass `email` through.
+- `dashboard/subscriptions.js` + `dashboard/index.html` — render the email under the
+  account nickname. Tests (unit + render assertion).
+
+## Why
+
+Operator requirement (Justin, topic 20905): accounts must be identified by nickname
+AND email — e.g. "SageMind - Justin" vs "SageMind - Adriana" vs "SageMind - Dawn"
+are the same org, so the email is the disambiguator. The pool previously stored only
+nickname + login location.
+
+## The safety property (load-bearing)
+
+The email is **auto-populated from the account's own login record** (`oauthAccount.
+emailAddress` in the config home), not just operator-typed. So the stored email
+always reflects WHICH account actually authenticated under that config home — a
+login into the wrong account *surfaces* (the email won't match the nickname's intent)
+instead of hiding. This directly serves the operator's stated worry about mislabeling
+accounts. The email is a PUBLIC identifier — never a token/secret.
+
+## What does NOT change
+
+- Additive-optional everywhere: `email` is optional; existing accounts and existing
+  add/update calls (no email) behave exactly as before (`email` stays undefined).
+- No new route, no new authority, no behavior change to selection/swap/poll beyond
+  writing one extra public field. The credential-field guard is unaffected (`email`
+  is not a forbidden field name).
+
+## Framework generality
+
+`readAccountEmail` reads claude-code's `oauthAccount.emailAddress` (the Claude config
+layout), matching the standard's Claude-first scope. The `email` field itself is
+framework-agnostic (any provider's account can carry one); only the auto-populate
+reader is claude-code-specific today. A non-claude account simply gets no auto-filled
+email (operators can still set one via the route) — no behavior regression, and the
+reader extends per-framework when those logins are wired.
+
+## Failure modes considered
+
+- Config home has no `.claude.json` / no `oauthAccount` → `readAccountEmail` returns
+  null → poll leaves `email` unchanged (no throw).
+- Operator passes `email` at add time → stored as-is; a later poll overwrites it with
+  the real logged-in email (reality wins — the safety property).
+- `update({ email: '' })` clears the email (explicit unset).
+
+## Migration / parity
+
+Additive-optional field on an existing store — no migration needed (old records load
+with `email` undefined; the next poll fills it). Ships via dist.