instar 1.3.415 → 1.3.417

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/secret-retrieval-first-standard.md

@@ -0,0 +1,24 @@
+# Side-Effects Review — Secret-Retrieval-First Standard
+
+**Version / slug:** `secret-retrieval-first-standard`
+**Date:** `2026-06-07`
+**Author:** `echo`
+**Tier:** `1` (docs/template + idempotent migration; no runtime behavior, no deps/routes/stores)
+**Second-pass reviewer:** `not-required (Tier-1 guidance/template change; correctness self-owned + covered by 3 unit tests)`
+
+## Summary of the change
+Inverts the CLAUDE.md Secret Drop "When to use" guidance from "use Secret Drop the moment you need a credential — the ONLY correct way" to **agent-retrieves-first; Secret Drop is the last resort**. Applied across all three Migration-Parity surfaces: the template (`generateClaudeMd`), the migrator inject-block (agents missing the section), and a new content-sniff patch in `migrateClaudeMd` that rewrites the harmful trigger for already-deployed agents.
+
+Files: `src/scaffold/templates.ts` (template guidance), `src/core/PostUpdateMigrator.ts` (inject-block text + new content-sniff patch), `tests/unit/PostUpdateMigrator-secretDropHardenedRetrieve.test.ts` (+3 tests), `docs/specs/secret-retrieval-first-standard.md` (+ .eli16).
+
+## Decision-point inventory
+- **Runtime behavior change?** None. This is agent-facing guidance text only — no code path, route, store, config, or scheduler is touched. Secret Drop itself (endpoints, retrieve script, durability) is unchanged.
+- **New dependency / state / route / config?** None → trips none of the SqliteRegistry-wiring / feature-delivery-completeness / docs-coverage(new-class) guard classes.
+- **Migration parity?** Satisfied on all three surfaces (template for new inits; inject-block for agents lacking the section; content-sniff patch for agents with the old section). The content-sniff patch is **idempotent** — it anchors on the stable old phrase `It is the ONLY correct way to collect a secret.` and skips once `AGENT-RETRIEVES-FIRST` / the new wording is present. Unit-tested (rewrite / idempotent / fresh-inject).
+- **Silent fallbacks?** None added. No new `try/catch`; pure string edits + one guarded `content.replace`.
+- **Shadow-capability slicer (AGENTS.md for Codex/Gemini)?** Inherits the corrected CLAUDE.md text automatically (the slicer copies sections from CLAUDE.md) — no separate edit needed; this is a positive side-effect (shadows stop carrying the wrong default too).
+- **Secret-handling safety baked into the new guidance:** explicitly tells agents to extract only the needed var, never print the value, and delete multi-secret temp files immediately — codifying the safe-retrieval discipline I followed pulling the value from `the-portal` env.
+- **Rollback?** Trivial — revert the three edits; guidance returns to prior wording, no state to unwind.
+
+## Why ship
+A wrong default in the template propagates to every agent (and every shadow). Justin flagged it as a UX violation (2026-06-07) and directed the standards amendment. Fixing it in the artifact agents read — not by per-agent willpower — is the Structure > Willpower path.