@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/providers/native/measured-budget.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The capacity budget for this host, MEASURED rather than assumed.
+ *
+ * `computeCapacityBudget()` with no arguments is a synchronous read of an
+ * ambient figure that stays `null` until `detectMemoryProfile` has run
+ * somewhere in this process (see `detectedGpuVramBytes` in
+ * {@link ./capacity-budget.js}). Truly synchronous callers have no
+ * alternative, which is why the daemon publishes the probe at boot — but
+ * every ASYNC caller that prices an admission should measure instead of
+ * hoping the boot probe landed first.
+ *
+ * A missing card is not a conservative degradation. It removes the
+ * accelerator from the admission budget AND from the live-memory cap at the
+ * same time, so a 12B model's weights alone can overrun free RAM minus the
+ * OS reserve on a machine with room to spare.
+ *
+ * Wild-caught 2026-09-04: a machine engine's first `/v1/remote/admit` — the
+ * cold path every first chat message takes — refused Gemma 4 12B on a
+ * 32 GB / 12 GB-VRAM host against "budget 18.7 GB", the RAM share alone,
+ * while the same preview granted 157k tokens once anything else had happened
+ * to publish the probe.
+ */
+import { type CapacityBudget } from './capacity-budget.js';
+/**
+ * Resolve the auto budget from a live hardware measurement.
+ *
+ * The profile read is cached for a minute inside `detectMemoryProfileCached`,
+ * so calling this per admission costs one `nvidia-smi` per minute at worst.
+ * Measuring also publishes the ambient probe as a side effect, which is what
+ * repairs the synchronous readers for everything that runs after.
+ */
+export declare function measuredCapacityBudget(): Promise<CapacityBudget>;

package/dist/providers/native/measured-budget.js

@@ -0,0 +1,54 @@
+/**
+ * The capacity budget for this host, MEASURED rather than assumed.
+ *
+ * `computeCapacityBudget()` with no arguments is a synchronous read of an
+ * ambient figure that stays `null` until `detectMemoryProfile` has run
+ * somewhere in this process (see `detectedGpuVramBytes` in
+ * {@link ./capacity-budget.js}). Truly synchronous callers have no
+ * alternative, which is why the daemon publishes the probe at boot — but
+ * every ASYNC caller that prices an admission should measure instead of
+ * hoping the boot probe landed first.
+ *
+ * A missing card is not a conservative degradation. It removes the
+ * accelerator from the admission budget AND from the live-memory cap at the
+ * same time, so a 12B model's weights alone can overrun free RAM minus the
+ * OS reserve on a machine with room to spare.
+ *
+ * Wild-caught 2026-09-04: a machine engine's first `/v1/remote/admit` — the
+ * cold path every first chat message takes — refused Gemma 4 12B on a
+ * 32 GB / 12 GB-VRAM host against "budget 18.7 GB", the RAM share alone,
+ * while the same preview granted 157k tokens once anything else had happened
+ * to publish the probe.
+ */
+import { computeCapacityBudget } from './capacity-budget.js';
+/**
+ * Resolve the auto budget from a live hardware measurement.
+ *
+ * The profile read is cached for a minute inside `detectMemoryProfileCached`,
+ * so calling this per admission costs one `nvidia-smi` per minute at worst.
+ * Measuring also publishes the ambient probe as a side effect, which is what
+ * repairs the synchronous readers for everything that runs after.
+ */
+export async function measuredCapacityBudget() {
+    const profile = await (async () => {
+        try {
+            // Dynamic so this module stays importable from the provider layer that
+            // `system/memory.js` itself reaches into for device discovery.
+            const { detectMemoryProfileCached } = await import('../../system/memory.js');
+            return await detectMemoryProfileCached();
+        }
+        catch {
+            return null;
+        }
+    })();
+    // A probe that threw keeps the ambient reading rather than asserting "no
+    // GPU": an explicit `gpuVramBytes: null` would overwrite a card another
+    // caller already measured.
+    if (!profile)
+        return computeCapacityBudget();
+    return computeCapacityBudget({
+        systemRamBytes: profile.totalRamBytes,
+        gpuVramBytes: profile.gpuVramBytes,
+        unifiedMemory: profile.gpuMemoryKind === 'integrated' || profile.gpuMemoryKind === 'unified',
+    });
+}

package/dist/providers/native/port.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pick a free TCP port on 127.0.0.1 for a native engine child
+ * process. Binds to port 0, reads the OS-assigned port, then closes.
+ *
+ * There's an inherent race — another process could grab the port
+ * between close() and the engine's listen() — but the window is
+ * microseconds on a loopback binding and the supervisor's health
+ * check catches anything weird. Good enough for a single-user
+ * desktop app.
+ */
+export declare function pickFreePort(): Promise<number>;

package/dist/providers/native/port.js

@@ -0,0 +1,29 @@
+import { createServer } from 'node:net';
+/**
+ * Pick a free TCP port on 127.0.0.1 for a native engine child
+ * process. Binds to port 0, reads the OS-assigned port, then closes.
+ *
+ * There's an inherent race — another process could grab the port
+ * between close() and the engine's listen() — but the window is
+ * microseconds on a loopback binding and the supervisor's health
+ * check catches anything weird. Good enough for a single-user
+ * desktop app.
+ */
+export async function pickFreePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.unref();
+        server.on('error', reject);
+        server.listen({ port: 0, host: '127.0.0.1' }, () => {
+            const addr = server.address();
+            if (addr && typeof addr === 'object') {
+                const port = addr.port;
+                server.close(() => resolve(port));
+            }
+            else {
+                server.close();
+                reject(new Error('could not determine bound port'));
+            }
+        });
+    });
+}

package/dist/providers/native/provider-pool.d.ts

@@ -0,0 +1,474 @@
+/**
+ * ProviderPool — owns the lifecycle of every local-engine
+ * {@link LLMProvider} instance, keyed by `{provider, modelId,
+ * replicaIdx}`. Replaces the singleton "one supervisor per provider"
+ * model with a fleet so different gezels can run different models
+ * without cold-reload between turns.
+ *
+ * Capacity is enforced through {@link CapacityBroker}: every `ensure`
+ * reserves the model's `residentBytes`; when the budget is exhausted
+ * the pool LRU-evicts entries (shutting them down, releasing
+ * capacity, flushing any disk-cache work in the provider's
+ * `shutdown`) until the new entry fits.
+ *
+ * The pool is intentionally provider-agnostic — it doesn't know how
+ * to launch a llama-server or a Python MLX runtime. Callers inject a
+ * builder per `LocalProviderName`; tests inject a `MockProviderBuilder`
+ * that produces no-op LLMProviders.
+ */
+import type { ProviderQueueDescription } from '@bendyline/gezel/queue-status';
+import type { LLMProvider } from '../types.js';
+import { type CapacityBroker } from './capacity-broker.js';
+import { type LocalProviderName, type ParsedEngineKey } from './engine-key.js';
+import type { GpuSpawnGuard } from './gpu-panic-guard.js';
+import type { NativeEngineLifecycleSnapshot } from './supervisor.js';
+/**
+ * The stable, machine-shaped denial log line. Its shape is a contract
+ * with the eval harness — evals/src/failure-class.ts:118,
+ * evals/src/preflight.ts:196, and evals/src/runner.ts:981 all grep the
+ * daemon log for `capacity broker denied <key>: budget exhausted: …`
+ * to classify capacity denials as infra (not model) failures. Do not
+ * reword either side without updating the other.
+ */
+export declare function capacityDenialLogLine(key: string, reason: string): string;
+/**
+ * Raw reason for a denial the device reading made, not the ledger. Keeps the
+ * `budget exhausted: would commit N against M` shape {@link capacityDenialLogLine}
+ * carries into the eval harness — this IS a capacity denial, measured rather
+ * than reserved, and any other shape would be reported as a model failure.
+ */
+export declare function measuredVramDenialReason(requiredBytes: number, freeBytes: number): string;
+export interface ProviderBuilderArgs {
+    modelId: string;
+    replicaIdx: number;
+}
+/**
+ * A builder produces a fully-initialized provider (after
+ * `provider.initialize()`) plus the working-set bytes the broker
+ * should reserve. Builders are responsible for any per-replica
+ * isolation (unique ports, isolated cache dirs).
+ */
+export type ProviderBuilder = (args: ProviderBuilderArgs) => Promise<{
+    provider: LLMProvider;
+    residentBytes: number;
+    /** Installed parameter payload resident for this replica, when known. */
+    modelWeightsBytes?: number;
+}>;
+export interface ProviderPoolOptions {
+    broker: CapacityBroker;
+    builders: Partial<Record<LocalProviderName, ProviderBuilder>>;
+    /**
+     * Test seam — defaults to `Date.now`. Drives the LRU's
+     * `lastUsedAt` so tests can advance time without `vi.useFakeTimers`.
+     */
+    now?: () => number;
+    /**
+     * Optional hook fired after a successful `ensure` (hit or miss).
+     * Used by the surrounding chat layer for telemetry / status pings.
+     */
+    onChange?: (snapshot: PoolSnapshot) => void;
+    /**
+     * How long a non-forced {@link evict} waits for a busy engine to
+     * drain its in-flight turns before giving up with a "model is busy"
+     * error, for a caller that does not choose its own
+     * {@link EngineWaitOpts.drainWaitMs}. Deliberately short: an indefinite
+     * wait can deadlock via cross-model ask-specialist chains (a turn on
+     * engine X blocks on a consultation that needs engine Y, whose spawn is
+     * waiting for X to go idle). Only a caller that knows no running turn
+     * is waiting on it may wait longer. Default 30s.
+     */
+    drainWaitMs?: number;
+    /** Test seam for the drain poll — defaults to a real setTimeout sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Optional GPU-panic guard. When present, consulted before spawning a new
+     * local GPU engine; a `blocked` decision denies the spawn (same throw path
+     * as a capacity denial) so gezel doesn't re-trigger an Apple GPU-driver
+     * kernel panic right after one. Off macOS / when omitted, no-op.
+     */
+    gpuPanicGuard?: GpuSpawnGuard;
+    /**
+     * Serialize local GPU model LOADS so at most one model maps onto the GPU at
+     * a time (never two `builder()` spawns concurrently). The macOS GPU-driver
+     * kernel panic we defend against is a memory-refcount *underflow*
+     * (`IOGPUMemory` "prepare count underflow") — a concurrency-sensitive bug
+     * that interleaved GPU allocate/free from two simultaneous model loads can
+     * race into. Serializing removes that class of churn. Bounded, deadlock-free
+     * (the lock is held only for the load, which always completes). Default: on
+     * for macOS (`GEZEL_SERIALIZE_GPU_LOADS=off` to disable); off elsewhere.
+     */
+    serializeGpuLoads?: boolean;
+    /**
+     * Optional measured free-accelerator-memory probe, consulted before spawning
+     * a new engine on a discrete card.
+     *
+     * The broker is a reservation ledger, and a per-process one: it is authority
+     * on what THIS daemon has loaded and blind to everything else on the card.
+     * On a captured night a second gezel install read its own empty ledger as
+     * "the whole 12 GB is free" and loaded a model onto a card that already had
+     * 0.3 GB left; both engines then ran ~40x slower for eight hours as the
+     * driver paged GPU memory over PCIe, and no layer ever said why. A device
+     * reading is the only thing that sees a tenant the ledger cannot.
+     */
+    vramHeadroom?: () => Promise<{
+        freeBytes?: number;
+        totalBytes?: number;
+    }>;
+}
+/**
+ * How one caller waits when the model it needs must replace a busy one.
+ * Each caller waits on its own terms: two requests can wait on the same
+ * engine with different patience, and the engine stays draining while
+ * either still waits.
+ */
+export interface EngineWaitOpts {
+    /**
+     * How long to wait for the busy engine's turns to finish. Infinity waits
+     * for the engine's next idle moment — a turn boundary, since a turn holds
+     * its queue slot for its whole tool loop. Defaults to the pool's
+     * `drainWaitMs`.
+     */
+    drainWaitMs?: number;
+    /** Ends the wait with {@link AbortedWhileQueuedError}: the caller gave up. */
+    signal?: AbortSignal;
+    /** Fired when the wait begins and every few seconds while it lasts. */
+    onDrainWait?: (wait: EngineDrainWait) => void;
+}
+/** The engine a caller is waiting on, and whose turns it is waiting for. */
+export interface EngineDrainWait {
+    engineKey: string;
+    modelId: string;
+    holders: Array<{
+        sessionId?: string;
+        gezelId?: string;
+        job?: string;
+        actorLabel?: string;
+    }>;
+}
+export interface PoolEntrySnapshot {
+    key: string;
+    provider: LocalProviderName;
+    modelId: string;
+    replicaIdx: number;
+    residentBytes: number;
+    /** Installed parameter payload resident for this replica, when known. */
+    modelWeightsBytes?: number;
+    lastUsedAt: number;
+    createdAt: number;
+    /** True while a non-forced eviction is waiting for in-flight turns to finish. */
+    draining: boolean;
+    /** Native process state; absent for external/non-supervised providers. */
+    lifecycle?: NativeEngineLifecycleSnapshot;
+}
+export interface PoolSnapshot {
+    entries: PoolEntrySnapshot[];
+    committedBytes: number;
+    budgetBytes: number;
+    enforced: boolean;
+    /** Physical RAM — the Settings slider's ceiling. */
+    systemRamBytes: number;
+    /** What the host would auto-derive; the slider's "Auto" mark. */
+    autoBudgetBytes: number;
+    /** True when `localEngineMemoryGb` is overriding the auto value. */
+    overridden: boolean;
+    /** Which pools back the budget — see {@link CapacityCommitted.pools}. */
+    pools: import('./capacity-broker.js').CapacityCommitted['pools'];
+    /** Whether co-resident models may spill into system RAM, and the ceiling if not. */
+    ramSpillover: import('./capacity-broker.js').CapacityCommitted['ramSpillover'];
+}
+/**
+ * Live queue state for one local provider, folded across every
+ * resident replica of that provider. Shape mirrors a single provider's
+ * `queue.describe()` plus `maxConcurrency`, so `/api/queues` can surface
+ * it in the same slot it uses for singleton providers. See
+ * {@link ProviderPool.queueSummaries}.
+ */
+export type PooledQueueSummary = ProviderQueueDescription & {
+    maxConcurrency: number;
+};
+/**
+ * Concurrent generation width the provider can serve right now.
+ *
+ * A supervised native launch is the strongest source: its retained `slots`
+ * diagnostic is the exact `--parallel` / server-width value of the live
+ * process. Older or wrapper providers may expose only `batch` or the queue's
+ * interactive cap, so use the widest of those compatible signals as the
+ * fallback. Never use total queue concurrency here — local queues carry an
+ * extra logical background lease that is not a native generation slot.
+ */
+export declare function liveProviderConcurrency(provider: LLMProvider): number;
+export declare class ProviderPool {
+    private readonly broker;
+    private readonly builders;
+    private readonly now;
+    private readonly onChange?;
+    private readonly drainWaitMs;
+    private readonly sleep;
+    private readonly gpuPanicGuard?;
+    private readonly vramHeadroom?;
+    private readonly serializeGpuLoads;
+    /** Tail of the serialized-load chain; each load awaits the previous. */
+    private gpuLoadChain;
+    private readonly entries;
+    private readonly buildLocks;
+    private readonly evicting;
+    /** Closed permanently once this user daemon adopts the machine broker. */
+    private retiring;
+    private retirementPromise;
+    constructor(opts: ProviderPoolOptions);
+    /**
+     * Run a model-LOAD (a `builder()` call, which maps weights onto the GPU)
+     * either immediately or serialized behind any in-flight load, per
+     * {@link ProviderPoolOptions.serializeGpuLoads}. Deadlock-free: the chain
+     * only ever waits for a load to finish, never for a turn or an eviction, and
+     * a load's failure doesn't wedge the chain (prior errors are swallowed).
+     */
+    private withGpuLoadSlot;
+    /**
+     * Resolve an engine key to a live, initialized provider. Hits the
+     * cache; on miss, evicts LRU as needed to clear `residentBytes`,
+     * then builds via the injected builder. The cost of eviction
+     * (provider.shutdown) is awaited so the caller never returns to a
+     * partially-spawned state.
+     */
+    ensure(provider: LocalProviderName, modelId: string, replicaIdx: number, residentBytes: number, opts?: EngineWaitOpts): Promise<LLMProvider>;
+    private buildEntry;
+    private installEntry;
+    /**
+     * Mark a key as touched. Called by ChatManager after each turn
+     * so the LRU evictor doesn't kill the engine the user is
+     * actively using.
+     */
+    touch(key: string): void;
+    /** Returns true if the pool currently holds an entry for `key`. */
+    has(key: string): boolean;
+    /**
+     * True while a waiting request is draining `key` so another model can
+     * load. A turn bound to it that can rebind should step aside rather than
+     * start — see `SendAndWaitOpts.queue.yieldToSwap`.
+     */
+    isDraining(key: string): boolean;
+    /**
+     * Drop entries whose engine failed to start, releasing the budget they hold.
+     *
+     * The reservation is taken when the builder returns — before the engine
+     * process exists, because the engine starts lazily on the first turn. A
+     * start that then fails (memory admission refused, spawn error, panic
+     * guard) leaves an entry that owns its whole `residentBytes` while running
+     * nothing, and it is never reclaimed on its own: the idle timer that would
+     * eventually release it is only ever armed by an engine that reached
+     * `running`. Observed as a 9.7 GB reservation on a machine whose engine
+     * process count was zero, against an 11.2 GB budget.
+     *
+     * Eviction is the whole repair. The next `ensure` rebuilds, which re-plans
+     * the context window against memory as it stands then rather than handing
+     * back a provider that will fail the same way.
+     */
+    private sweepFailedStarts;
+    /**
+     * Evict pool entries whose supervised native child has already stopped.
+     * Their bytes are capacity guarantees, not physical residency. Keeping the
+     * wrapper cached is useful until another model actually needs that promise;
+     * a capacity denial is the pressure signal that makes the released entries
+     * expendable.
+     */
+    private reclaimReleasedReservations;
+    /**
+     * Immediately unload one resident engine, but only while it is idle.
+     *
+     * This is the user-triggered counterpart to the idle-retention timer. It
+     * deliberately refuses a busy engine instead of entering the ordinary
+     * bounded drain path: an "Unload now" click must never turn into a delayed
+     * teardown of work that started just after the status surface was sampled.
+     * Returns false when the engine has already gone away.
+     */
+    unloadIdle(key: string): Promise<boolean>;
+    /**
+     * Unload every resident engine that is idle right now, leaving busy ones
+     * running. Returns the keys that stayed resident because they were serving
+     * a turn — the caller reports them; the ordinary LRU / idle-retention path
+     * collects them once they go quiet.
+     *
+     * This is what a live config reset uses. {@link shutdown} is the other
+     * shape — it force-evicts busy engines too — and is only correct when the
+     * process is going away (service shutdown, emergency stop), because a
+     * forced eviction kills whatever turn is streaming.
+     */
+    releaseIdle(): Promise<string[]>;
+    /**
+     * Evict a specific entry. Awaits the provider's `shutdown` so the
+     * disk-cache flush (Tier 1 prior plan) completes before the broker
+     * releases capacity.
+     *
+     * When the engine has in-flight or queued turns and `force` is not
+     * set, the entry is marked `draining` (no new `ensure` hits, no new
+     * binds) and the eviction waits up to the caller's `drainWaitMs` for
+     * the queue to empty. On timeout it throws a "model is busy" error
+     * instead of killing live work — the caller (typically `makeRoom` on
+     * behalf of a request for a *different* model) surfaces that as a
+     * clear temporary-failure to its own caller. `force: true` (service
+     * shutdown) skips the wait entirely.
+     *
+     * Parallel `evict` calls for the same key wait independently, each
+     * with its own deadline and signal, and join the same teardown.
+     */
+    evict(key: string, opts?: EngineWaitOpts & {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * Hold `entry` draining until its queue empties, the entry is replaced,
+     * or this caller's deadline or signal ends the wait. The last caller to
+     * give up clears `draining`, so the engine serves hits again; a caller
+     * that saw it drain leaves the flag set for the teardown that follows.
+     */
+    private drainFor;
+    /**
+     * Wait for someone else's drain of `entry` to end — evicted, or given
+     * up — within this caller's own deadline and signal. Returning while
+     * the entry is still draining is the deadline: the caller takes the
+     * resident engine as it is.
+     */
+    private waitForDrainToSettle;
+    /** Rate-limited {@link EngineWaitOpts.onDrainWait}: once at the start, then every few seconds. */
+    private drainNotifier;
+    /**
+     * Remove `entry` and shut its provider down. The removal is synchronous,
+     * so nothing can bind to it once this is called; the shutdown is shared
+     * by every caller evicting the same entry.
+     */
+    private teardown;
+    /**
+     * Deny a spawn the card cannot physically take, whatever the ledger says.
+     *
+     * Runs after `makeRoom`, so everything this daemon was willing to release is
+     * already gone and the reading reflects what is genuinely left. Discrete
+     * cards only: on a unified host there is one pool, the RAM share already
+     * governs it, and the OS pages normally rather than falling off a cliff.
+     *
+     * A model larger than the card is deliberately streamed from system RAM, so
+     * the requirement is capped at the fast pool — otherwise this would refuse
+     * exactly the big-MoE case the two-pool budget was built to allow.
+     */
+    private measuredVramDenial;
+    /**
+     * Evict entries until the broker reports headroom for `needed`
+     * bytes (or the pool is empty). Victim order: oldest *idle* entries
+     * first; only when every candidate is busy does it pick a busy one —
+     * one already draining for another caller first — whose eviction
+     * then drains on this caller's terms rather than killing in-flight
+     * turns. Pool-internal; callers never invoke directly.
+     *
+     * Idle victims are evicted *concurrently* (a model switch on a
+     * memory-tight box often has to clear several idle resident models
+     * to fit the incoming one): idle `shutdown()` doesn't drain, so the
+     * per-engine disk-cache flush of N victims runs in parallel instead
+     * of paying each one serially before the new model can spawn. The
+     * busy path stays serial to preserve the bounded-drain semantics.
+     */
+    private makeRoom;
+    /**
+     * The idle (non-busy, non-draining) eviction victims — oldest-first —
+     * whose combined `residentBytes`, once released, would give `needed`
+     * room to fit under the budget. Returns `[]` when there are no idle
+     * candidates (the caller then falls back to a single busy eviction)
+     * or when no eviction is required. Lets {@link makeRoom} batch idle
+     * evictions in parallel instead of one-at-a-time.
+     */
+    private idleVictimsFor;
+    private lruKey;
+    /**
+     * Shut down everything the pool owns. Used at service shutdown —
+     * forces eviction without waiting for busy engines to drain.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Permanently close the pool to new work, wait for builds already admitted,
+     * then drain every interactive and background queue before shutdown. Unlike
+     * service shutdown this never force-kills a turn and has no turn-length cap.
+     */
+    retire(): Promise<void>;
+    /**
+     * Reconcile the resident set toward `target` — a map of
+     * `(provider, modelId) → desiredReplicaCount`. Spawns missing
+     * replicas (subject to capacity) and evicts replicas at indices
+     * `>= count`. Used by the UX layer when the user changes the
+     * clone-count picker.
+     *
+     * `ensureRes` resolves residentBytes for `(provider, modelId)`;
+     * typically a closure over the catalog.
+     */
+    reconcile(target: Array<{
+        provider: LocalProviderName;
+        modelId: string;
+        clones: number;
+    }>, ensureRes: (provider: LocalProviderName, modelId: string) => number): Promise<void>;
+    /**
+     * Pick a replica index to bind a new session to. Returns the
+     * least-loaded existing replica of `(provider, modelId)` based on
+     * an external `sessionsPerKey` map (the chat manager owns the
+     * tally; the pool stays state-free about sessions). If no replica
+     * exists, returns 0 so the caller spawns the first one.
+     */
+    pickReplicaForBind(provider: LocalProviderName, modelId: string, sessionsPerKey: ReadonlyMap<string, number>): number;
+    /**
+     * Enumerate `(provider, modelId, replicaIdx)` triples currently
+     * resident. The chat layer uses this to validate a session's
+     * persisted `engineKey` after restart.
+     */
+    resolveExisting(key: string): ParsedEngineKey | null;
+    /**
+     * Existing replica indices for a `(provider, modelId)` pair,
+     * sorted ascending. Used to discover "is replica 1 already
+     * resident?" without scanning the whole pool from the outside.
+     */
+    existingReplicas(provider: LocalProviderName, modelId: string): number[];
+    snapshot(): PoolSnapshot;
+    /**
+     * Return already-created replicas for one exact model without allocating,
+     * initializing, touching LRU state, or evicting anything. Cache warming and
+     * telemetry use this peek so a read-like request cannot cold-start an engine.
+     */
+    peekProvidersForModel(provider: LocalProviderName, modelId: string): LLMProvider[];
+    /**
+     * Fold every resident replica's live queue into one summary per
+     * {@link LocalProviderName}. Under the pool architecture local
+     * providers aren't seeded as singletons in `ChatManager.providers`, so
+     * `/api/queues` — which reads only `getProviderIfReady(name).queue` —
+     * otherwise misses ALL pooled work: chat turns and background one-shots
+     * alike (weekly digest, about.md drafts, memory extraction). That blind
+     * spot is what made the engine pill read "Idle" while a one-shot decoded
+     * on the GPU.
+     *
+     * Counts sum across a provider's replicas; `active` / `pending` (with
+     * their job labels) concatenate. Draining replicas are included — they
+     * can still be finishing in-flight turns. Replicas whose provider
+     * exposes no queue (cloud, test fakes) contribute nothing.
+     */
+    /**
+     * Launch provenance of every pooled provider whose engine process is
+     * live right now — provider + model attribution from the pool key, the
+     * snapshot (pid, start time, granted context) from the provider's
+     * supervisor. Providers without a supervised engine contribute nothing.
+     */
+    engineLaunchSnapshots(): Array<{
+        provider: LocalProviderName;
+        modelId: string;
+        snapshot: import('../types.js').EngineLaunchSnapshot;
+    }>;
+    queueSummaries(): Map<LocalProviderName, PooledQueueSummary>;
+    /**
+     * Cancel a pending queue entry on whichever resident replica of
+     * `provider` holds it — the write side of {@link queueSummaries},
+     * which the singleton `getProviderIfReady` path can't reach for
+     * pool-routed local engines. Queue ids are replica-local (each
+     * {@link ProviderQueue} counts from 1), so we cancel on the first
+     * replica of this provider whose queue knows the id; in the common
+     * single-replica case that is unambiguous, and a stale id simply
+     * matches nothing. Returns true when an entry was removed.
+     */
+    cancelPendingQueueItem(provider: string, id: number): boolean;
+    /** Reorder a pending queue entry across this provider's replicas. See
+     *  {@link cancelPendingQueueItem} for the id-matching contract. */
+    movePendingQueueItem(provider: string, id: number, direction: 'up' | 'down'): boolean;
+    private fireChange;
+}