instar 1.3.1145 → 1.3.1147

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

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1145",
+  "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": "4a5b88caa62ae256f4868735dc66735c52ae30604a8272c977ca1f4564086e43",
+  "sha256": "20cdf255a4e7e5577036fc766d33e560f5fdca277d059195494ac048766322aa",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1145"
+  "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.1145"
+  "packageVersion": "1.3.1147"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1145",
+  "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/scripts/lint-no-direct-llm-http.js

@@ -98,6 +98,162 @@ const FORBIDDEN_PATTERNS = [
 
 const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs']);
 
+function lineForOffset(text, offset) {
+  let line = 1;
+  for (let i = 0; i < offset; i++) {
+    if (text[i] === '\n') line++;
+  }
+  return line;
+}
+
+function stripCommentsPreserveLayout(text) {
+  let out = '';
+  let i = 0;
+  let quote = null;
+  let escaped = false;
+
+  while (i < text.length) {
+    const ch = text[i];
+    const next = text[i + 1];
+
+    if (quote) {
+      out += ch;
+      if (escaped) {
+        escaped = false;
+      } else if (ch === '\\') {
+        escaped = true;
+      } else if (ch === quote) {
+        quote = null;
+      }
+      i++;
+      continue;
+    }
+
+    if (ch === '"' || ch === "'" || ch === '`') {
+      quote = ch;
+      out += ch;
+      i++;
+      continue;
+    }
+
+    if (ch === '/' && next === '/') {
+      out += '  ';
+      i += 2;
+      while (i < text.length && text[i] !== '\n') {
+        out += ' ';
+        i++;
+      }
+      continue;
+    }
+
+    if (ch === '/' && next === '*') {
+      out += '  ';
+      i += 2;
+      while (i < text.length) {
+        if (text[i] === '*' && text[i + 1] === '/') {
+          out += '  ';
+          i += 2;
+          break;
+        }
+        out += text[i] === '\n' ? '\n' : ' ';
+        i++;
+      }
+      continue;
+    }
+
+    out += ch;
+    i++;
+  }
+
+  return out;
+}
+
+function skipWhitespace(text, index) {
+  while (index < text.length && /\s/.test(text[index])) index++;
+  return index;
+}
+
+function readStringLiteral(text, start) {
+  const quote = text[start];
+  if (quote !== '"' && quote !== "'" && quote !== '`') return null;
+
+  let value = '';
+  let i = start + 1;
+  let escaped = false;
+  while (i < text.length) {
+    const ch = text[i];
+    if (escaped) {
+      value += ch;
+      escaped = false;
+      i++;
+      continue;
+    }
+    if (ch === '\\') {
+      escaped = true;
+      i++;
+      continue;
+    }
+    if (quote === '`' && ch === '$' && text[i + 1] === '{') {
+      return null;
+    }
+    if (ch === quote) {
+      return { value, end: i + 1 };
+    }
+    value += ch;
+    i++;
+  }
+
+  return null;
+}
+
+function findFoldedStringViolations(text, rel) {
+  const stripped = stripCommentsPreserveLayout(text);
+  const violations = [];
+
+  for (let i = 0; i < stripped.length; i++) {
+    const first = readStringLiteral(stripped, i);
+    if (!first) continue;
+
+    let cursor = skipWhitespace(stripped, first.end);
+    if (stripped[cursor] !== '+') {
+      i = first.end - 1;
+      continue;
+    }
+
+    const parts = [first.value];
+    let end = first.end;
+    let literalCount = 1;
+    while (stripped[cursor] === '+') {
+      const nextStart = skipWhitespace(stripped, cursor + 1);
+      const nextString = readStringLiteral(stripped, nextStart);
+      if (!nextString) break;
+      parts.push(nextString.value);
+      literalCount++;
+      end = nextString.end;
+      cursor = skipWhitespace(stripped, nextString.end);
+    }
+
+    if (literalCount > 1) {
+      const folded = parts.join('');
+      const line = lineForOffset(stripped, i);
+      for (const pat of FORBIDDEN_PATTERNS) {
+        if (folded.includes(pat)) {
+          violations.push({
+            file: rel,
+            line,
+            pattern: pat,
+            text: folded.slice(0, 200),
+            folded: true,
+          });
+        }
+      }
+      i = end - 1;
+    }
+  }
+
+  return violations;
+}
+
 function readGitignoreDirs() {
   // Skip node_modules, dist, .instar/worktrees, etc.
   return new Set(['node_modules', 'dist', 'build', '.instar', '.git', '.next', 'coverage']);
@@ -168,6 +324,7 @@ function checkFile(file) {
       }
     }
   }
+  violations.push(...findFoldedStringViolations(text, rel));
   return violations;
 }
 
@@ -184,7 +341,8 @@ function main() {
   console.error('src/core/ClaudeCliIntelligenceProvider.ts so the burn-detection system can');
   console.error('attribute it. See docs/specs/token-burn-detection-and-self-heal.md Phase 1.\n');
   for (const v of all) {
-    console.error(`  ${v.file}:${v.line} — contains "${v.pattern}"`);
+    const reason = v.folded ? `folds to "${v.pattern}"` : `contains "${v.pattern}"`;
+    console.error(`  ${v.file}:${v.line} — ${reason}`);
     console.error(`    ${v.text}`);
   }
   process.exit(1);

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-14T22:33:19.830Z",
-  "instarVersion": "1.3.1145",
+  "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.1145",
+  "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": "4a5b88caa62ae256f4868735dc66735c52ae30604a8272c977ca1f4564086e43",
+  "sha256": "20cdf255a4e7e5577036fc766d33e560f5fdca277d059195494ac048766322aa",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1145"
+  "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.1145"
+  "packageVersion": "1.3.1147"
 }

package/upgrades/1.3.1146.md

@@ -0,0 +1,22 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-no-direct-llm-http.js` now folds adjacent constant string and no-expression template literals before checking for direct LLM provider hosts. A raw provider URL split as `'https://api.' + 'anthropic.com/v1/messages'` now fails the same build lint as the unsplit host.
+
+The scope is deliberately narrow: literal-plus-literal URL construction only. Dynamic URL construction is not guessed at, and the existing file-level distinction for OAuth/profile/usage metadata endpoints remains unchanged.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+Negative control against the shipped lint: the focused unit file failed 2 tests, both new split-host rejection cases. After the fix, `tests/unit/burn-detection-phase-1.test.ts` passes 20/20, and `node scripts/lint-no-direct-llm-http.js` exits clean against the real tree.

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).

package/upgrades/side-effects/llm-http-constant-folding.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — LLM HTTP lint constant folding
+
+**Version / slug:** `llm-http-constant-folding`
+**Date:** `2026-08-14`
+**Author:** `Instar-codey`
+**Tier:** 1 (one lint script plus focused unit coverage; no runtime code, route, config, migration, or persistence change)
+**Second-pass reviewer:** `not required — CI/pre-commit lint hardening only; no runtime outbound message or session lifecycle decision`
+
+## Summary of the change
+
+`scripts/lint-no-direct-llm-http.js` now folds adjacent constant string and no-expression template literals joined by `+` before checking for known LLM provider hosts. This closes the reproduced split-host bypass (`'api.' + 'anthropic.com/v1/messages'`) while keeping scope at literal URL construction only. `tests/unit/burn-detection-phase-1.test.ts` adds red/green coverage for split Anthropic, OpenAI, and Google host literals plus a non-folded dynamic construction control.
+
+Build location re-grounding: work was built in fresh worktree `/Users/justin_instar_1/.instar/agents/instar-codey/.worktrees/agent-llm-http-constant-folding` from current `JKHeadley/main` (`4731ec6a90356ed319454a996b4eb72edcf38ab2`), created through `npx -y instar@1.3.1144 worktree create ... --base origin/main` after the local wrapper lacked an installed package. Remote verified as `origin https://github.com/JKHeadley/instar.git`; package version verified as `1.3.1144`.
+
+## Decision-point inventory
+
+- `scripts/lint-no-direct-llm-http.js` — modify — build-time block/allow decision for direct provider HTTP references outside the provider chokepoint and named metadata exceptions.
+
+## 1. Over-block
+
+The new over-block risk is a benign constant string in production source that names a provider host across literal pieces without making a call. That is the same policy as the existing unsplit-host lint: production source outside the allowlist should not carry raw provider host literals because they become copyable direct-call paths. The real-tree scan after the fix was clean.
+
+OAuth/profile/usage metadata readers keep their existing allowlist/grandfather treatment; this change did not add endpoint-level bans that would collapse metadata reads into inference calls.
+
+## 2. Under-block
+
+The lint still misses dynamic construction, such as `'https://api.' + providerHost + '/v1/messages'`, computed arrays joined into a host, decoded strings, or runtime config that points at a provider endpoint. That is intentional for this PR: automatic discovery/dataflow was the high-false-positive direction. The closure here is constant URL literals, not semantic HTTP-call proof.
+
+## 3. Level-of-abstraction fit
+
+Correct layer: this is a deterministic CI lint in the existing `lint-no-*` family. The protected invariant is "new production raw LLM provider host literals outside the chokepoint require review." The lower-level primitive is a string-literal scanner, not an authority over runtime user intent.
+
+## 4. Signal vs authority compliance
+
+Reference: [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md).
+
+This change holds blocking authority with brittle logic, but it is a build-time hard invariant/safety guard, not a conversational judgment point. The lint blocks source code containing direct provider endpoint literals outside reviewed locations, analogous to a safety guard on data egress and spend attribution. It does not decide whether a user message is appropriate or whether an agent action should proceed at runtime.
+
+## 4b. Judgment-point check
+
+No new static heuristic at a competing-signals decision point. The input is source text and an enumerated provider-host list; there are no live competing signals such as urgency, recency, ownership, or liveness.
+
+## 5. Interactions
+
+- **Shadowing:** It runs inside the existing `npm run lint` chain. It may fail before later lints, as before; no downstream lint depends on side effects from this script.
+- **Double-fire:** `lint-llm-attribution.js` and other provider-path checks may catch related defects, but this one reports direct HTTP host literals specifically. Duplicate CI failures are acceptable because they point at the same source change.
+- **Races:** No shared state. It reads files and exits.
+- **Feedback loops:** None.
+
+## 6. External surfaces
+
+No runtime external surface changes. Other agents and users only see this as a stricter build/pre-commit/CI failure when source contains a newly-recognized split provider URL. No Telegram, Slack, GitHub API, dashboard, database, ledger, or generated URL behavior changes. No operator-facing action is added.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture
+
+Machine-local by design: this is a repository lint run independently in each checkout/CI runner. It emits no user-facing notices, holds no durable state, and generates no URLs. Multi-machine consistency comes from the shared git commit containing the lint and tests.
+
+## 8. Rollback cost
+
+Pure code/test/docs change. Rollback is a hot-fix revert of the lint folding helper and tests. No data migration, no agent state repair, and no user-visible runtime regression while rollback propagates.
+
+## Conclusion
+
+The real-tree scan stayed clean and the negative control failed for the intended old-lint cases, so the scoped constant-folding fix is clear to ship. No broader automatic actuator discovery or dynamic URL dataflow was added.
+
+## Second-pass review
+
+Not required.
+
+## Evidence pointers
+
+- Old-lint focused run: `npx vitest run tests/unit/burn-detection-phase-1.test.ts` failed 2 of 20 tests, specifically the two new split-host rejection tests.
+- Fixed targeted run: `npx vitest run tests/unit/burn-detection-phase-1.test.ts` passed 20/20.
+- Fixed real-tree scan: `node scripts/lint-no-direct-llm-http.js` exited 0.
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect — not applicable.