instar 1.3.1146 → 1.3.1147

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1146",
+  "packageVersion": "1.3.1147",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "675498ac7f3b9a5fd07a57a530eba5cc8645d84aede82b6f03348f7f502edb8a",
+  "sha256": "20cdf255a4e7e5577036fc766d33e560f5fdca277d059195494ac048766322aa",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1146"
+  "packageVersion": "1.3.1147"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1146"
+  "packageVersion": "1.3.1147"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1146",
+  "version": "1.3.1147",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/lint-no-blocking-process-scans.js

@@ -25,6 +25,29 @@
  * line or the line directly above:
  *     // lint-allow-blocking-scan: <why this can't run periodically>
  *
+ * ── 2026-08-14: the command name does not have to be written at the callsite.
+ * The original pattern required the scan command as a string literal INSIDE the
+ * call, so putting the name one step away walked past it — while the event loop
+ * stalled just the same, because the incident was about what the process DOES,
+ * not how the argument was spelled. instar-codey reproduced the concatenation
+ * form (`const cmd = 'pg' + 'rep'; execFileSync(cmd, ['node'])` → exit 0) while
+ * auditing rename-defeatable checks, and scoped the fix.
+ *
+ * NOW RESOLVED before the decision: literal `+` chains, local `const` string
+ * bindings, and import aliases of the sync entry points. The VALUE decides, so
+ * `const pgrep = 'tmux'` is legal and `const cmd = 'psql'` is not a `ps`.
+ *
+ * DELIBERATELY NOT CLOSED, so it is stated rather than implied:
+ *   · A call split across MULTIPLE LINES. This lint is line-oriented; making it
+ *     multi-line means an AST, which is a different check at a different layer.
+ *     Pre-existing, not introduced here.
+ *   · A command read from config, an argv, or another module. Not foldable
+ *     without dataflow analysis, and guessing would over-block correct code —
+ *     the more expensive failure for a check that blocks commits.
+ *   · Scope: bindings are collected file-wide rather than per-scope, so an
+ *     identifier bound twice to DIFFERENT values is treated as unresolvable and
+ *     never flagged. That is the safe direction, chosen on purpose.
+ *
  * Exit codes: 0 — clean; 1 — at least one violation.
  *
  * Usage:
@@ -46,11 +69,112 @@ const ROOT = path.resolve(path.dirname(__filename), '..');
 const SCAN_DIRS = ['src/monitoring', 'src/server'];
 const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs']);
 
-// A synchronous child-process call whose command literal is a process-scan tool.
-// Matches e.g.  spawnSync('pgrep', …)   execFileSync('lsof', …)   execSync('ps …')
-const VIOLATION = /\b(spawnSync|execSync|execFileSync)\s*\(\s*['"`]\s*(ps|pgrep|lsof|pkill)\b/;
+// The scan commands themselves. Word-boundary matched against the RESOLVED
+// command value, so `psql` never counts as `ps`.
+const SCAN_COMMAND = /^(ps|pgrep|lsof|pkill)\b/;
+
+// The synchronous child-process entry points. Import aliases of these are
+// resolved per-file below — `import { execFileSync as run }` then `run('pgrep')`
+// stalls the loop exactly as much as calling it by its own name.
+const SYNC_BUILTINS = ['spawnSync', 'execSync', 'execFileSync'];
+
 const ALLOW = /lint-allow-blocking-scan:/;
 
+/** A string literal, or a `+` chain of string literals. Nothing else folds. */
+const FOLDABLE = /^\s*(?:(?:'[^'\\]*'|"[^"\\]*"|`[^`\\$]*`)\s*\+\s*)*(?:'[^'\\]*'|"[^"\\]*"|`[^`\\$]*`)\s*$/;
+
+/**
+ * Fold an expression to its string value, or null if it is not a pure literal
+ * chain. `'pg' + 'rep'` → `pgrep`. A template with `${}` never folds.
+ */
+function foldLiteral(expr) {
+  if (!FOLDABLE.test(expr)) return null;
+  const parts = expr.match(/'[^'\\]*'|"[^"\\]*"|`[^`\\$]*`/g);
+  if (!parts) return null;
+  return parts.map((p) => p.slice(1, -1)).join('');
+}
+
+/**
+ * Local `const NAME = <literal chain>` bindings, file-wide.
+ *
+ * Deliberately NOT scope-aware: this is a line-oriented lint, not a compiler.
+ * The safe direction for a check that BLOCKS COMMITS is to refuse to resolve
+ * anything ambiguous, so an identifier bound more than once to DIFFERENT values
+ * is recorded as unresolvable and never produces a violation. Over-blocking
+ * correct code is the more expensive failure here.
+ */
+function collectStringConsts(lines) {
+  const map = new Map();
+  const conflicted = new Set();
+  const DECL = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::\s*[^=]+?)?=\s*([^;\n]+)/g;
+  for (const line of lines) {
+    const trimmed = line.trimStart();
+    if (/^(\/\/|\*|\/\*)/.test(trimmed)) continue; // a commented-out const binds nothing
+    DECL.lastIndex = 0;
+    let m;
+    while ((m = DECL.exec(line)) !== null) {
+      const [, name, rhs] = m;
+      const value = foldLiteral(rhs);
+      if (value === null) { conflicted.add(name); continue; }
+      if (map.has(name) && map.get(name) !== value) conflicted.add(name);
+      else map.set(name, value);
+    }
+  }
+  for (const name of conflicted) map.delete(name);
+  return map;
+}
+
+/** Names in this file that reach a synchronous child-process call. */
+function collectSyncNames(text) {
+  const names = new Set(SYNC_BUILTINS);
+  const IMPORT = /import\s*\{([^}]*)\}\s*from\s*['"]node:child_process['"]/g;
+  let m;
+  while ((m = IMPORT.exec(text)) !== null) {
+    for (const clause of m[1].split(',')) {
+      const alias = clause.match(/([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*)/);
+      if (alias && SYNC_BUILTINS.includes(alias[1])) names.add(alias[2]);
+    }
+  }
+  return names;
+}
+
+/**
+ * The first argument of `name(` starting at `from`, as source text. Bounded to
+ * the line, matching this lint's existing granularity — a call split across
+ * lines is a separate, pre-existing gap, declared in the header rather than
+ * silently implied.
+ */
+function firstArg(line, from) {
+  let depth = 0;
+  for (let i = from; i < line.length; i++) {
+    const c = line[i];
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') {
+      if (depth === 0) return line.slice(from, i);
+      depth--;
+    } else if (c === ',' && depth === 0) return line.slice(from, i);
+  }
+  return line.slice(from);
+}
+
+/**
+ * Does this line perform a synchronous scan? Resolves the command through
+ * literal folding and local constants before deciding.
+ */
+function scanViolation(line, syncNames, constMap) {
+  for (const name of syncNames) {
+    const call = new RegExp(`\\b${name}\\s*\\(`, 'g');
+    let m;
+    while ((m = call.exec(line)) !== null) {
+      const arg = firstArg(line, m.index + m[0].length).trim();
+      let value = foldLiteral(arg);
+      if (value === null && /^[A-Za-z_$][\w$]*$/.test(arg)) value = constMap.get(arg) ?? null;
+      if (value !== null && SCAN_COMMAND.test(value.trim())) return true;
+    }
+  }
+  return false;
+}
+
 const inScanDir = (p) => SCAN_DIRS.some((d) => p.startsWith(d + '/'));
 
 function listFiles() {
@@ -86,10 +210,12 @@ for (const rel of listFiles()) {
   let content;
   try { content = fs.readFileSync(full, 'utf-8'); } catch { continue; }
   const lines = content.split('\n');
+  const syncNames = collectSyncNames(content);
+  const constMap = collectStringConsts(lines);
   for (let i = 0; i < lines.length; i++) {
     const trimmed = lines[i].trimStart();
     if (/^(\/\/|\*|\/\*)/.test(trimmed)) continue; // comment-only mention
-    if (!VIOLATION.test(lines[i])) continue;
+    if (!scanViolation(lines[i], syncNames, constMap)) continue;
     // Inline justification on this line or within the comment block directly
     // above (scan back up to 4 lines so a multi-line reason is honoured).
     let allowed = false;

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-14T22:54:06.076Z",
-  "instarVersion": "1.3.1146",
+  "generatedAt": "2026-08-14T23:03:50.148Z",
+  "instarVersion": "1.3.1147",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1146",
+  "packageVersion": "1.3.1147",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "675498ac7f3b9a5fd07a57a530eba5cc8645d84aede82b6f03348f7f502edb8a",
+  "sha256": "20cdf255a4e7e5577036fc766d33e560f5fdca277d059195494ac048766322aa",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1146"
+  "packageVersion": "1.3.1147"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1146"
+  "packageVersion": "1.3.1147"
 }

package/upgrades/1.3.1147.md

@@ -0,0 +1,55 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-no-blocking-process-scans.js` enforces root cause #4 of the 2026-06-07 "server temporarily
+down" post-mortem: a synchronous `ps`/`pgrep`/`lsof`/`pkill` on a runtime hot path blocks the single-threaded
+event loop, those commands get slow under exactly the load that makes monitors fire, and the cumulative
+stall starved `/health` until the supervisor restarted a server that was alive the whole time.
+
+The check required the scan command as a string literal inside the call, so the name one step away walked
+past it while the event loop stalled identically:
+
+```js
+const cmd = 'pgrep';        execFileSync(cmd, ['node']);   // was not caught
+const cmd = 'pg' + 'rep';   execFileSync(cmd, ['node']);   // was not caught
+import { execFileSync as run } from 'node:child_process';
+                            run('pgrep', ['node']);        // was not caught
+```
+
+instar-codey reproduced the concatenation form against the shipped lint (exit 0) while auditing
+rename-defeatable checks, and scoped the remedy. The command is now resolved before the rule is applied:
+literal `+` chains fold, local `const` string bindings resolve, and import aliases of the three sync entry
+points are followed.
+
+Three choices keep it from flagging correct code, each with its own test: the resolved VALUE decides and
+never the variable name (`const pgrep = 'tmux'` is legal); matching is whole-word (`psql` is not `ps`); and
+an identifier bound to two different values in one file is treated as unresolvable and never flagged. Async
+calls stay legal — moving to async is the remedy the rule exists to push toward.
+
+Deliberately left open and stated in the header: calls split across multiple lines (line-oriented lint;
+closing it means an AST), and commands read from config/argv/another module (needs dataflow analysis, and
+guessing would over-block).
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- `tests/unit/lint-no-blocking-process-scans.test.ts` — 14/14 green (5 original + 9 added).
+- Negative control: tests written BEFORE the fix and run against the shipped lint — **4 of 14 fail**
+  (const concatenation, plain variable, inline concatenation, import alias). The other 10 pass both ways,
+  which is what makes them controls.
+- Real-tree verdict: `node scripts/lint-no-blocking-process-scans.js` → `clean`, exit 0 — no new flags on
+  existing code.
+- Full `npm run lint` chain green.
+- Side-effects review: `upgrades/side-effects/blocking-process-scan-command-resolution.md`.
+- ELI16: `docs/specs/blocking-process-scan-command-resolution.eli16.md`.

package/upgrades/side-effects/blocking-process-scan-command-resolution.md

@@ -0,0 +1,109 @@
+# Side-Effects Review — blocking-process-scan lint resolves the command before deciding
+
+**Version / slug:** `blocking-process-scan-command-resolution`
+**Date:** `2026-08-14`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — Tier 1 declared (CI-only tooling, riskFloor 1). No spec change: the §rule is unchanged; the check now resolves the command value before applying the same rule.`
+
+## Summary of the change
+
+`scripts/lint-no-blocking-process-scans.js` enforces the topic-21816 post-mortem's root cause #4: a
+synchronous `ps`/`pgrep`/`lsof`/`pkill` on a runtime hot path blocks the single-threaded event loop, and those
+commands get slow under exactly the load that makes monitors fire — the cumulative stall starved `/health`,
+the supervisor declared the live server unresponsive, and restarted it.
+
+The check required the scan command as a string literal INSIDE the call:
+`/\b(spawnSync|execSync|execFileSync)\s*\(\s*['"\`]\s*(ps|pgrep|lsof|pkill)\b/`. Putting the name one step
+away walked past it, while the event loop stalled just the same — the incident was about what the process
+DOES, not how the argument was spelled. instar-codey reproduced the concatenation form against the shipped
+lint (`const cmd = 'pg' + 'rep'; execFileSync(cmd, ['node'])` → exit 0) and scoped the fix.
+
+The command is now RESOLVED before the rule is applied: literal `+` chains fold, local `const` string bindings
+resolve, and import aliases of the three sync entry points are followed.
+
+## Decision-point inventory
+
+- `scanViolation()` — REPLACES the literal-only regex — resolves then decides. CI-time only; never runtime.
+- `foldLiteral()` — ADD — pure literal chains only; a template with `${}` never folds.
+- `collectStringConsts()` — ADD — file-wide, and **deliberately refuses ambiguity** (see §1).
+- `collectSyncNames()` — ADD — follows `import { execFileSync as run } from 'node:child_process'`.
+- The allow comment, the comment-only skip, the scan dirs, and the async remedy are all unchanged.
+- No runtime block/allow decisions added or modified. This runs in `npm run lint` and CI only.
+
+## 1. Over-block
+
+This is the failure that matters here: the lint blocks commits, so flagging correct code costs more than
+missing a case. Three structural choices push against it, and each has a test:
+
+- **The VALUE decides, never the name.** `const pgrep = 'tmux'` is legal; the identifier being called `pgrep`
+  is irrelevant.
+- **Word-boundary on the resolved value.** `psql` is not `ps`; `pstree` is not `ps`.
+- **Ambiguity resolves to NOT-flagged.** Bindings are collected file-wide rather than per-scope (a
+  line-oriented lint is not a compiler). An identifier bound more than once to DIFFERENT values is recorded as
+  unresolvable and never produces a violation — the safe direction, chosen on purpose.
+
+Async calls are untouched: `execFile(cmd, …)` with a folded command stays legal, because async yielding the
+loop IS the remedy this lint exists to push people toward.
+
+Verified against the real tree: `src/monitoring` + `src/server` report clean, exit 0 — the widened check
+introduces no new flags on existing code.
+
+## 2. Under-block
+
+Stated in the header rather than implied:
+
+- **A call split across multiple lines.** This lint is line-oriented; making it multi-line means an AST, which
+  is a different check at a different layer. Pre-existing — not introduced here.
+- **A command read from config, argv, or another module.** Not foldable without dataflow analysis, and
+  guessing would over-block.
+- Scope is still the two hot dirs (`src/monitoring`, `src/server`). `src/core`'s tmux-heavy session plumbing
+  remains the separate, larger conversion tracked in the post-mortem follow-up.
+
+## 3. Level-of-abstraction fit
+
+Same layer as the shipped check — line-oriented regex over source, no AST, no type information, no new
+dependency. The added machinery (fold, const map, alias map, first-arg extractor) is the minimum needed to
+answer "what command does this actually run?" without climbing to a parser. Codey rated this scope
+"low/medium FP risk if limited to child_process sync aliases plus literal/constant-folded command values in
+src/monitoring and src/server" — that is exactly the scope implemented.
+
+## 4. Signal vs authority compliance
+
+Unchanged. A CI guard, not a runtime authority. It forbids a synchronous enumeration on the hot path; the
+async equivalent remains the sanctioned path, and the reviewed one-shot escape hatch still works.
+
+## 5. Interactions
+
+- `npm run lint` chain (`package.json`) — position unchanged; full chain green.
+- `--staged` path and explicit-file args unchanged in behaviour.
+- Husky pre-commit / CI run the same chain.
+- No source module, route, config key, or state file is touched.
+
+## 6. External surfaces
+
+None. No HTTP route, no config key, no user-visible message, no CLAUDE.md template change (developer-facing
+tooling, not an agent capability). Agent Awareness Standard does not apply.
+
+## 7. Rollback cost
+
+`git revert` of one script plus one test file. No migration, no state, no deployed artifact.
+
+## Conclusion
+
+Ship. Four evasions closed, each with a test that fails without the fix; six anti-over-block controls added
+alongside; real tree verified clean.
+
+## Second-pass review (if required)
+
+Not required at Tier 1. Independent corroboration exists regardless: instar-codey reproduced the evasion
+separately and pre-scoped the remedy, including the warning not to overmatch all sync child-process calls.
+
+## Evidence pointers
+
+- `tests/unit/lint-no-blocking-process-scans.test.ts` — 14/14 green (5 original + 9 added).
+- Negative control: tests written BEFORE the fix and run against the shipped lint — **4 of 14 fail**
+  (const concatenation, plain variable, inline concatenation, import alias); the 10 others pass both ways,
+  which is what makes the controls controls.
+- Real-tree verdict: `node scripts/lint-no-blocking-process-scans.js` → `clean`, exit 0.
+- Full `npm run lint` chain green.
+- Source incident: `docs/postmortems/2026-06-07-server-temporarily-down.md` (root cause #4).