instar 1.3.647 → 1.3.648

package/dist/core/SpawnCapIntelligenceProvider.js

@@ -0,0 +1,164 @@
+/**
+ * SpawnCapIntelligenceProvider — P1 chokepoint + P3 bounded ingress of the
+ * SIMPLE fork-bomb prevention design (docs/specs/forkbomb-prevention-simple.md).
+ *
+ * A thin WRAPPER provider, layered EXACTLY like wrapIntelligenceWithCircuitBreaker:
+ * its `evaluate()` ACQUIRES a host-wide spawn slot (the HostSpawnSemaphore),
+ * calls the inner provider's `evaluate()` (the actual `claude -p` / `codex exec`
+ * spawn), and RELEASES the slot in a `finally`. It is installed at every return
+ * arm of `buildIntelligenceProvider`, so EVERY provider the factory hands out is
+ * bounded — and the acquire is PER-`evaluate()`, which is load-bearing:
+ * CoherenceGate builds its provider ONCE and fans ~10 reviewers in parallel
+ * through that ONE shared instance (the primary incident driver), so each of the
+ * N concurrent `evaluate()` calls must independently acquire a slot. A
+ * build-time acquire would NOT bind the fan-out.
+ *
+ * P3 — BOUNDED INGRESS (never an unbounded wait queue):
+ *   When the host cap is saturated, acquire POLLS the holder-set on a short
+ *   interval (~100ms) up to `acquireMs` (default 5000ms) — NOT an in-memory
+ *   waiter queue. Each poll is a cheap lock+count; the caller's large prompt
+ *   state stays where it already lives (no queue-node heap growth). A bound on
+ *   CONCURRENT POLLERS (`waitersMax`, default 64) caps the waiters too.
+ *
+ * On genuine exhaustion (timeout OR waiters-full):
+ *   - A GATING call (options.attribution.gating === true) THROWS
+ *     LlmCapacityUnavailableError — the caller's catch fails CLOSED (hold), NOT
+ *     auto-pass. The four gate seams (MessageSentinel / InputGuard /
+ *     MessagingToneGate / CoherenceReviewer) recognize this typed error.
+ *   - A non-gating BACKGROUND call also THROWS LlmCapacityUnavailableError;
+ *     its existing catch degrades to its heuristic/no-LLM path (loud + counted
+ *     via DegradationReporter, never silent) — same shape as a circuit-open
+ *     throw, so existing background catches already handle it.
+ *
+ * This wrapper SHEDS BEFORE the inner provider runs — no subprocess spawns on a
+ * shed, which is the whole point (no `claude -p`, no RSS).
+ */
+import { getHostSpawnSemaphore, configuredSpawnAcquireMs, configuredSpawnWaitersMax, } from './hostSpawnSemaphore.js';
+/**
+ * Thrown when the host-wide spawn cap is saturated and the bounded-acquire
+ * window elapsed (or the concurrent-waiter ceiling was hit). A typed,
+ * recognizable shed — distinct from a rate-limit (LlmCircuitOpenError) and from
+ * a provider error — so each gate seam can fail CLOSED on it specifically.
+ */
+export class LlmCapacityUnavailableError extends Error {
+    reason;
+    waitedMs;
+    capacityUnavailable = true;
+    constructor(reason, waitedMs) {
+        super(`LLM spawn capacity unavailable (${reason}) after ${waitedMs}ms — host concurrent-spawn cap saturated`);
+        this.reason = reason;
+        this.waitedMs = waitedMs;
+        this.name = 'LlmCapacityUnavailableError';
+    }
+}
+/** Narrowing helper for the gate seams (avoids `instanceof` import churn). */
+export function isCapacityUnavailable(err) {
+    return (err instanceof LlmCapacityUnavailableError ||
+        (typeof err === 'object' && err !== null && err.capacityUnavailable === true));
+}
+// Process-wide count of callers currently POLLING for a slot (P3 waiters bound).
+// A waiter is one in-flight `evaluate()` spinning on acquire; bounding it caps
+// the concurrent already-allocated calls, with no per-waiter queue-node heap.
+let _activePollers = 0;
+/** Live count of callers currently polling for a spawn slot (P3 observability). */
+export function activeSpawnPollers() {
+    return _activePollers;
+}
+/** Test seam. */
+export function _resetSpawnPollersForTest() {
+    _activePollers = 0;
+}
+export class SpawnCapIntelligenceProvider {
+    inner;
+    semaphore;
+    acquireMs;
+    waitersMax;
+    pollIntervalMs;
+    now;
+    genId;
+    sleep;
+    constructor(inner, deps = {}) {
+        this.inner = inner;
+        this.semaphore = deps.semaphore ?? getHostSpawnSemaphore();
+        this.acquireMs = deps.acquireMs ?? configuredSpawnAcquireMs();
+        this.waitersMax = deps.waitersMax ?? configuredSpawnWaitersMax();
+        this.pollIntervalMs = deps.pollIntervalMs ?? 100;
+        this.now = deps.now ?? (() => Date.now());
+        this.genId =
+            deps.genId ?? (() => `spawn:${process.pid}:${this.now().toString(36)}:${Math.random().toString(36).slice(2, 10)}`);
+        this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    async evaluate(prompt, options) {
+        const id = this.genId();
+        const startedAt = this.now();
+        // P3 waiters bound — refuse to even start polling past the ceiling. This is
+        // checked BEFORE incrementing so the ceiling is a hard cap on concurrent
+        // pollers. The shed is the same typed error so the gate seams fail closed.
+        if (_activePollers >= this.waitersMax) {
+            throw new LlmCapacityUnavailableError('waiters-full', 0);
+        }
+        _activePollers++;
+        let acquired = false;
+        try {
+            // Fast path — try once immediately (no sleep) before entering the poll loop.
+            if (this.semaphore.acquire(id)) {
+                acquired = true;
+            }
+            else {
+                acquired = await this.pollAcquire(id, startedAt);
+            }
+            if (!acquired) {
+                throw new LlmCapacityUnavailableError('acquire-timeout', this.now() - startedAt);
+            }
+            // Slot held — run the actual spawn. The semaphore is released in finally.
+            return await this.inner.evaluate(prompt, options);
+        }
+        finally {
+            _activePollers--;
+            if (acquired) {
+                // Crash-safe: release is idempotent (unknown id is a no-op).
+                try {
+                    this.semaphore.release(id);
+                }
+                catch {
+                    /* @silent-fallback-ok: a release failure self-heals via prune-dead
+                       (this pid will keep going / eventually die) — never throw out of
+                       finally and mask the real result. */
+                }
+            }
+        }
+    }
+    /** Poll the semaphore every `pollIntervalMs` until acquired or the budget elapses. */
+    async pollAcquire(id, startedAt) {
+        const deadline = startedAt + this.acquireMs;
+        // Defense-in-depth iteration ceiling: the loop is wall-clock bound by
+        // `deadline`, but a frozen/non-advancing clock (a test injection, never
+        // production) could otherwise spin. Cap iterations at the worst-case poll
+        // count plus a margin so the loop ALWAYS terminates.
+        const maxIters = Math.ceil(this.acquireMs / Math.max(1, this.pollIntervalMs)) + 8;
+        for (let iter = 0; iter < maxIters; iter++) {
+            // Sleep first (the immediate try already happened in evaluate()).
+            const remaining = deadline - this.now();
+            if (remaining <= 0)
+                return false;
+            await this.sleep(Math.min(this.pollIntervalMs, remaining));
+            if (this.semaphore.acquire(id))
+                return true;
+            if (this.now() >= deadline)
+                return false;
+        }
+        return false;
+    }
+}
+/**
+ * Wrap a provider with the host spawn cap. No-ops on null (so a possibly-null
+ * factory result passes through unchanged) and is idempotent (never double-wraps).
+ */
+export function wrapIntelligenceWithSpawnCap(provider, deps) {
+    if (!provider)
+        return null;
+    if (provider instanceof SpawnCapIntelligenceProvider)
+        return provider;
+    return new SpawnCapIntelligenceProvider(provider, deps);
+}
+//# sourceMappingURL=SpawnCapIntelligenceProvider.js.map

package/dist/core/SpawnCapIntelligenceProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpawnCapIntelligenceProvider.js","sourceRoot":"","sources":["../../src/core/SpawnCapIntelligenceProvider.ts"],"names":[],"mappings":"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"}

package/dist/core/hostSpawnSemaphore.d.ts

@@ -0,0 +1,188 @@
+/**
+ * hostSpawnSemaphore — P1 of the SIMPLE fork-bomb prevention design.
+ *
+ * Spec: docs/specs/forkbomb-prevention-simple.md (§P1, §P3, §D-CAP).
+ * Source postmortem: the-portal/docs/postmortems/2026-06-20-echo-instar-forkbomb-oom.md.
+ *
+ * THE PRIMARY CONTROL. A single host-local COUNTING SEMAPHORE that bounds how
+ * many LLM subprocesses ("claude -p" / "codex exec" / …) run AT ONCE across
+ * EVERY compliant Instar agent + server instance on this host. The 2026-06-20
+ * incident fork-bombed a 128GB macOS host into OOM twice (~230-289 concurrent
+ * `claude -p` ≈ 90-115GB) because `evaluate()` spawned one subprocess per call
+ * with ZERO concurrency control and CoherenceGate fans ~10 reviewers in
+ * parallel per message. This bounds that.
+ *
+ * MECHANISM — a holder-SET model (NOT decrement/increment counter math):
+ *   A host-local file (`~/.instar/host-spawn-holders.json`, NOT a synced
+ *   volume), guarded by an exclusive O_CREAT|O_EXCL lock (the in-tree
+ *   ProjectRoundLock pattern). The cap is enforced by COUNTING LIVE holder
+ *   records — never by mutating a shared integer:
+ *     - acquire(id): under the lock, prune dead holders, and if
+ *       liveHolders < cap append `{id, pid, hostname, heartbeat}` (atomic
+ *       temp+rename) → true; else false.
+ *     - release(id): under the lock, remove THIS id.
+ *   Crash-safe by construction: a double-release is a no-op (id already gone),
+ *   a pid-reuse can't steal a slot (unique id, not pid), a partial write is
+ *   discarded (temp+rename), a crashed holder is reclaimed by prune-dead
+ *   (pid not alive AND heartbeat stale, on THIS host only).
+ *
+ * HOST-LOCAL-LOCK CONTRACT (mirrors ResumeQueue.ts, the 2026-06-15 lesson):
+ *   - A FOREIGN-hostname holder is NEVER pruned/reclaimed (refuse-loud — a
+ *     pid check is meaningless cross-host on a shared volume).
+ *   - A `df -P` host-local-disk confirmation gates reclaim (fail-closed: if we
+ *     cannot positively confirm the holders file is on a local disk, we NEVER
+ *     prune a holder — we only ever decline to reclaim, never decline to bound).
+ *
+ * BOUNDED INGRESS (P3) lives in the wrapper (SpawnCapIntelligenceProvider) via
+ * poll-retry against `acquire()` — this module is the pure counting primitive.
+ */
+/** One live holder of a spawn slot. */
+export interface SpawnHolder {
+    /** Unique per-acquire id (NOT the pid — pid-reuse must not steal a slot). */
+    id: string;
+    pid: number;
+    hostname: string;
+    /** ms epoch of the last heartbeat (acquire time, refreshed by long holders). */
+    heartbeat: number;
+}
+/** Heartbeat staleness window — a holder is reclaim-eligible (pid dead OR, on a
+ * provably host-local disk, heartbeat older than this) only past it. Kept long
+ * (a slow `claude -p` cold-start + run can legitimately exceed a minute), and
+ * pid-liveness is the PRIMARY signal — heartbeat staleness is secondary and
+ * only consulted when the pid is also gone. */
+export declare const HOLDER_STALE_MS: number;
+/**
+ * FD1 (from ResumeQueue) — is `p` on a HOST-LOCAL filesystem? FAIL-CLOSED:
+ * anything we cannot positively confirm as local returns false, so a holder on
+ * a genuine shared/network volume is NEVER reclaimed (the two-hosts-one-volume
+ * corruption the host-lock invariant protects against). `df -P` device-column
+ * classification — re-implemented here (not imported from monitoring/) so
+ * core/ never depends on monitoring/.
+ */
+export declare function isPathHostLocalDefault(p: string): boolean;
+/** Pure FD1 classifier over the `df -P` device-source column. FAIL-CLOSED. */
+export declare function classifyDfSourceLocal(source: string): boolean;
+export interface HostSpawnSemaphoreDeps {
+    /** Absolute path to the holders file. Default `~/.instar/host-spawn-holders.json`. */
+    holdersPath?: string;
+    /** Concurrent-spawn cap. Default resolved by `resolveSpawnCap()`. */
+    cap?: number;
+    now?: () => number;
+    hostname?: () => string;
+    /** pid liveness probe (tests override). */
+    pidAlive?: (pid: number) => boolean;
+    /** Host-local FS probe (tests override; default `isPathHostLocalDefault`). */
+    isPathHostLocal?: (p: string) => boolean;
+    /** Unique-id generator (tests override for determinism). */
+    genId?: () => string;
+}
+/**
+ * Resolve the concurrent-spawn cap. Precedence (D-CAP):
+ *   INSTAR_HOST_SPAWN_MAX env  >  config intelligence.spawnCap.maxConcurrent  >  8.
+ * A safety FLOOR — read with a plain `??` default, NEVER resolveDevAgentGate
+ * (it is ON by default, ships never-dark). A non-positive / non-finite value
+ * is ignored (falls through to the next source) so a typo can't disable the cap.
+ */
+export declare function resolveSpawnCap(configCap?: number, env?: NodeJS.ProcessEnv): number;
+/**
+ * Resolve the bounded-acquire poll budget in ms (P3). Precedence (D-CAP):
+ *   INSTAR_SPAWN_ACQUIRE_MS env  >  config intelligence.spawnCap.acquireMs  >  5000.
+ * Read with a plain `??` default (safety floor, never resolveDevAgentGate).
+ */
+export declare function resolveSpawnAcquireMs(configMs?: number, env?: NodeJS.ProcessEnv): number;
+/**
+ * Resolve the concurrent-pollers ceiling (P3). Precedence (D-CAP):
+ *   INSTAR_SPAWN_WAITERS_MAX env  >  config intelligence.spawnCap.waitersMax  >  64.
+ */
+export declare function resolveSpawnWaitersMax(configMax?: number, env?: NodeJS.ProcessEnv): number;
+export interface SpawnSemaphoreStatus {
+    cap: number;
+    /** Live holders after pruning, this host + foreign. */
+    liveHolders: number;
+    /** Holders whose hostname is THIS host. */
+    localHolders: number;
+    /** Holders whose hostname is a DIFFERENT host (never reclaimed). */
+    foreignHolders: number;
+    holdersPath: string;
+}
+/**
+ * Host-wide counting semaphore over LLM-subprocess spawns. One instance per
+ * process is fine — the cross-process coordination is the file + flock, not
+ * the object. Stateless beyond the file.
+ */
+export declare class HostSpawnSemaphore {
+    private readonly holdersPath;
+    private readonly cap;
+    private readonly now;
+    private readonly host;
+    private readonly pidAlive;
+    private readonly isPathHostLocal;
+    private readonly genId;
+    /** Memoized host-local determination (a fixed path's FS type can't change at
+     * runtime; the `df -P` probe is expensive + synchronous, so it runs ONCE per
+     * instance — never per acquire() on the hot fan-out path). */
+    private _fsLocalCache;
+    constructor(deps?: HostSpawnSemaphoreDeps);
+    getCap(): number;
+    /**
+     * Try to take a slot under id `id`. Returns true if a slot was appended
+     * (liveHolders < cap after pruning), false if the host is at the cap.
+     * Holds the exclusive flock for the whole read-prune-decide-write window.
+     */
+    acquire(id: string): boolean;
+    /** Release the slot held under `id`. A double-release / unknown id is a no-op. */
+    release(id: string): void;
+    /** Refresh a long-held slot's heartbeat so a slow legit spawn is never reclaimed. */
+    heartbeat(id: string): void;
+    /** Read-only status (count of live holders after a prune). Best-effort: never throws. */
+    status(): SpawnSemaphoreStatus;
+    /**
+     * Prune dead holders. A holder is reclaimable ONLY if:
+     *   - it is on THIS host (a foreign-hostname holder is NEVER reclaimed —
+     *     refuse-loud — the cross-host shared-volume hazard), AND
+     *   - its pid is no longer alive (PRIMARY signal), AND
+     *   - its heartbeat is stale past HOLDER_STALE_MS (SECONDARY signal — a slow
+     *     spawn whose pid is alive is NEVER reclaimed regardless of heartbeat).
+     * AND a `df -P` host-local confirmation gates ALL reclaim (fail-closed: if we
+     * cannot confirm the holders file is on a local disk, we keep ALL holders —
+     * over-counting is the safe direction for a cap; it never under-bounds).
+     */
+    private pruneDead;
+    private readHolders;
+    private writeHolders;
+    /**
+     * Run `fn` while holding the exclusive O_CREAT|O_EXCL lock on `<holdersPath>.lock`.
+     * On a lock-contention failure (another process holds it), returns
+     * `fallbackOnLockFail` — for `acquire`, fallback=false is the SAFE direction
+     * (refuse the slot under contention rather than over-grant past the cap).
+     * The lock is short-held (a file read + JSON parse + write) so contention is
+     * brief; a crashed lock-holder's stale lock is reclaimed by pid-death.
+     */
+    private withLock;
+    /** Remove the lock file if its recorded holder pid is dead (crash recovery). */
+    private reclaimStaleLock;
+    private ensureDir;
+}
+/** Default holders file path: `~/.instar/host-spawn-holders.json` (host-local). */
+export declare function defaultHoldersPath(): string;
+/** Operator config for the spawn cap (intelligence.spawnCap.*). All optional. */
+export interface SpawnCapConfig {
+    maxConcurrent?: number;
+    acquireMs?: number;
+    waitersMax?: number;
+}
+/**
+ * Inject the config-resolved spawn-cap knobs once at server boot (server.ts).
+ * Idempotent: re-resolves the singleton so a later getter sees the configured
+ * cap. The env vars still win inside the `resolve*` helpers.
+ */
+export declare function configureHostSpawnSemaphore(cfg?: SpawnCapConfig): void;
+/** The process-wide semaphore. Lazily constructed with env/config/8 cap. */
+export declare function getHostSpawnSemaphore(): HostSpawnSemaphore;
+/** Config-aware acquire-budget resolver (env > injected config > 5000). */
+export declare function configuredSpawnAcquireMs(): number;
+/** Config-aware waiters-ceiling resolver (env > injected config > 64). */
+export declare function configuredSpawnWaitersMax(): number;
+/** Test seam — reset the singleton + injected config. */
+export declare function _resetHostSpawnSemaphoreForTest(): void;
+//# sourceMappingURL=hostSpawnSemaphore.d.ts.map

package/dist/core/hostSpawnSemaphore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostSpawnSemaphore.d.ts","sourceRoot":"","sources":["../../src/core/hostSpawnSemaphore.ts"],"names":[],"mappings":"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"}