instar 1.3.647 → 1.3.648

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.647",
+  "version": "1.3.648",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,9 @@
     "test:contract": "node scripts/run-contract-tests.js",
     "test:contract:raw": "vitest run --config vitest.contract.config.ts",
     "test:all": "vitest run && vitest run --config vitest.integration.config.ts && vitest run --config vitest.e2e.config.ts",
-    "lint": "tsc --noEmit && node scripts/lint-no-direct-destructive.js && node scripts/lint-no-direct-llm-http.js && node scripts/lint-no-direct-url-log.js && node scripts/lint-no-unfunneled-topic-creation.js && node scripts/lint-no-unfunneled-headless-launch.js && node scripts/lint-no-unfunneled-credential-write.js && node scripts/lint-state-registry.js && node scripts/lint-store-retention-declared.js && node scripts/lint-no-wholefile-sync-read.js && node scripts/lint-cas-emit-placement.js && node scripts/lint-journal-actuation-ban.js && node scripts/lint-no-blocking-process-scans.js && node scripts/lint-sync-subprocess-chokepoint.js && node scripts/lint-dev-agent-dark-gate.js && node scripts/lint-guard-manifest.js && node scripts/lint-llm-attribution.js && node scripts/lint-no-mainthread-cartographer-walk.js && node scripts/lint-scrape-fixture-realness.js && node scripts/check-codex-rule1-drift.js",
+    "lint": "tsc --noEmit && node scripts/lint-no-direct-destructive.js && node scripts/lint-no-direct-llm-http.js && node scripts/lint-no-direct-url-log.js && node scripts/lint-no-unfunneled-topic-creation.js && node scripts/lint-no-unfunneled-headless-launch.js && node scripts/lint-no-unbounded-llm-spawn.js && node scripts/lint-no-unfunneled-credential-write.js && node scripts/lint-state-registry.js && node scripts/lint-store-retention-declared.js && node scripts/lint-no-wholefile-sync-read.js && node scripts/lint-cas-emit-placement.js && node scripts/lint-journal-actuation-ban.js && node scripts/lint-no-blocking-process-scans.js && node scripts/lint-sync-subprocess-chokepoint.js && node scripts/lint-dev-agent-dark-gate.js && node scripts/lint-guard-manifest.js && node scripts/lint-llm-attribution.js && node scripts/lint-no-mainthread-cartographer-walk.js && node scripts/lint-scrape-fixture-realness.js && node scripts/check-codex-rule1-drift.js",
+    "lint:no-unbounded-llm-spawn": "node scripts/lint-no-unbounded-llm-spawn.js",
+    "lint:no-unbounded-llm-spawn:staged": "node scripts/lint-no-unbounded-llm-spawn.js --staged",
     "lint:destructive": "node scripts/lint-no-direct-destructive.js",
     "lint:dev-agent-dark-gate": "node scripts/lint-dev-agent-dark-gate.js",
     "lint:guard-manifest": "node scripts/lint-guard-manifest.js",

package/scripts/lint-no-direct-destructive.js

@@ -86,6 +86,10 @@ const ALLOWLIST = new Set([
   // Same bootstrap-escape pattern (june15-headless-spawn-reroute funnel
   // lint) — read-only `git diff --cached --name-only` only.
   'scripts/lint-no-unfunneled-headless-launch.js',
+  // Same bootstrap-escape pattern (fork-bomb spawn-cap funnel lint) —
+  // read-only `git diff --cached --name-only` for --staged. Cannot depend on
+  // the TS funnel because TS is not compiled when the lint runs in pre-push.
+  'scripts/lint-no-unbounded-llm-spawn.js',
   // Same bootstrap-escape pattern (Step 4b credential-write funnel lint) —
   // read-only `git diff --cached --name-only` for --staged. Cannot depend on
   // the TS funnel because TS is not compiled when the lint runs in pre-push.

package/scripts/lint-no-unbounded-llm-spawn.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * lint-no-unbounded-llm-spawn.js — refuses a raw LLM-CLI provider construction
+ * outside the spawn-cap funnel.
+ *
+ * Part of the SIMPLE fork-bomb prevention design
+ * (docs/specs/forkbomb-prevention-simple.md §P1). The host-wide concurrent-spawn
+ * cap is enforced by the SpawnCapIntelligenceProvider wrapper, which is installed
+ * at EVERY return arm of `buildIntelligenceProvider` (the factory funnel). Any
+ * code that constructs an LLM-CLI provider DIRECTLY —
+ *   new ClaudeCliIntelligenceProvider(...)
+ *   new CodexCliIntelligenceProvider(...)
+ *   new GeminiCliIntelligenceProvider(...)
+ *   new PiCliIntelligenceProvider(...)
+ * — bypasses that wrapper, re-introducing an UN-CAPPED spawn path: the exact
+ * 2026-06-20 fork-bomb vector (one `claude -p` per call, zero concurrency
+ * control). That bypass must fail CI, not be discovered on the next OOM.
+ *
+ * RULE: outside the allowlist below, no source file may construct one of those
+ * providers directly. Route through `buildIntelligenceProvider(...)` (the
+ * factory), which applies the spawn cap + circuit breaker.
+ *
+ * Exit codes: 0 — clean; 1 — at least one violation.
+ *
+ * Usage:
+ *   node scripts/lint-no-unbounded-llm-spawn.js            # full repo
+ *   node scripts/lint-no-unbounded-llm-spawn.js --staged   # staged files
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(__filename), '..');
+
+// The LLM-CLI provider classes — constructing any of them is a SPAWN-capable
+// path (their evaluate() shells out to the CLI binary).
+const PROVIDER_CLASSES = [
+  'ClaudeCliIntelligenceProvider',
+  'CodexCliIntelligenceProvider',
+  'GeminiCliIntelligenceProvider',
+  'PiCliIntelligenceProvider',
+];
+
+// ── Allowlist (closed). Adding an entry requires review of WHY the callsite
+//    cannot route through buildIntelligenceProvider() (where the spawn-cap
+//    wrapper is installed), and how its spawn is otherwise bounded. ─────────
+const ALLOWLIST = new Set([
+  // THE funnel — the spawn-cap wrapper is installed here, around every
+  // construction (wrapForFunnel).
+  'src/core/intelligenceProviderFactory.ts',
+  // The provider definitions themselves (their own class bodies).
+  'src/core/ClaudeCliIntelligenceProvider.ts',
+  'src/core/CodexCliIntelligenceProvider.ts',
+  'src/core/GeminiCliIntelligenceProvider.ts',
+  'src/core/PiCliIntelligenceProvider.ts',
+  // This lint file mentions the symbols it greps for.
+  'scripts/lint-no-unbounded-llm-spawn.js',
+]);
+
+const SCAN_DIRS = ['src', 'scripts', 'templates'];
+const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs']);
+
+// `new <ProviderClass>(` — the construction. An IMPORT of the class is fine
+// (the factory imports them); only a direct `new …(` outside the funnel is a
+// bypass.
+const PATTERNS = PROVIDER_CLASSES.map((cls) => new RegExp(`\\bnew\\s+${cls}\\s*\\(`));
+
+function listFiles() {
+  const staged = process.argv.includes('--staged');
+  if (staged) {
+    const out = execSync('git diff --cached --name-only', { cwd: ROOT, encoding: 'utf-8' });
+    return out.split('\n').filter(Boolean);
+  }
+  const explicit = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+  if (explicit.length) return explicit;
+
+  const files = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (EXTENSIONS.has(path.extname(e.name))) files.push(path.relative(ROOT, full));
+    }
+  };
+  for (const d of SCAN_DIRS) walk(path.join(ROOT, d));
+  return files;
+}
+
+let violations = 0;
+for (const rel of listFiles()) {
+  const normalized = rel.split(path.sep).join('/');
+  if (ALLOWLIST.has(normalized)) continue;
+  if (!EXTENSIONS.has(path.extname(normalized))) continue;
+  // Test files exercise the providers directly with stubs / real spawns under
+  // controlled conditions — they are not a production spawn path.
+  if (/(^|\/)tests\//.test(normalized) || /\.test\.[cm]?[jt]sx?$/.test(normalized)) continue;
+  const full = path.isAbsolute(normalized) ? normalized : path.join(ROOT, normalized);
+  let content;
+  try {
+    content = fs.readFileSync(full, 'utf-8');
+  } catch {
+    continue;
+  }
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    // Comment-only mentions are documentation, not a construction.
+    const trimmed = lines[i].trimStart();
+    if (/^(\/\/|\*|\/\*|#)/.test(trimmed)) continue;
+    for (const pattern of PATTERNS) {
+      if (pattern.test(lines[i])) {
+        console.error(
+          `${normalized}:${i + 1} — direct LLM-CLI provider construction outside the spawn-cap funnel. ` +
+          `Build it through buildIntelligenceProvider() (which installs the host-wide spawn cap + circuit breaker), ` +
+          `or add an allowlist entry here with a spawn-bounding justification.`,
+        );
+        violations++;
+      }
+    }
+  }
+}
+
+if (violations > 0) {
+  console.error(`\nlint-no-unbounded-llm-spawn: ${violations} violation(s). ` +
+    `See docs/specs/forkbomb-prevention-simple.md (§P1 — every spawn-capable provider must ride the spawn-cap funnel).`);
+  process.exit(1);
+}
+console.log('lint-no-unbounded-llm-spawn: clean');