@otto-code/brain 0.8.12 → 0.8.14

package/dist/commands/bench.js

@@ -8,7 +8,7 @@
  */
 import http from "node:http";
 import path from "node:path";
-import { forModel, getCalibration, loadBrainConfig, loadProfilesStore, resolveBrainPaths, } from "../config/index.js";
+import { forModel, getCalibrationForBudget, loadBrainConfig, loadProfilesStore, resolveBrainPaths, } from "../config/index.js";
 import { query as queryGpu } from "../gpu.js";
 import { pickModel, scanModels } from "../models/index.js";
 import { CommandError } from "../output/types.js";
@@ -172,7 +172,7 @@ async function runBenchSuite(options, _command) {
         // that ran is the profile that was configured, and the calibration is what
         // says whether the fit's own VRAM figures were measured or guessed. A score
         // read without them is a score nobody can diagnose.
-        const calibration = getCalibration(store, model, profile);
+        const calibration = getCalibrationForBudget(store, model, profile);
         let fit = null;
         const gpu = await queryGpu();
         if (gpu) {

package/dist/commands/calibrate.js

@@ -1,4 +1,4 @@
-import { getCalibration, forModel, loadBrainConfig, loadProfilesStore, putCalibration, saveProfilesStore, } from "../config/index.js";
+import { getCalibrationForBudget, forModel, loadBrainConfig, loadProfilesStore, putCalibration, saveProfilesStore, } from "../config/index.js";
 import { query as queryGpu } from "../gpu.js";
 import { pickModel, scanModels } from "../models/index.js";
 import { CommandError } from "../output/types.js";
@@ -35,12 +35,12 @@ export async function runCalibrateCommand(options, _command) {
     const catalog = scanModels(config);
     const model = pickModel(catalog, options.model ?? store.lastModelId ?? undefined);
     const profile = forModel(store, model, config.defaults);
-    // A measurement from the previous run is the best prior on bytes/token for
-    // this exact profile shape. The sample cap uses it so the high sample never
-    // lands at a context that would spill the KV cache to CPU and bias the new
-    // slope low. Inherited family calibrations are excluded: they were measured
-    // on another file and are not a trustworthy budget input here.
-    const prior = getCalibration(store, model, profile);
+    // The last direct measurement is the best prior on bytes/token available for
+    // capping the next sample. It keeps the calibration path stable while a
+    // changed profile is awaiting a fresh measurement. Inherited family
+    // calibrations are excluded: they were measured on another file and are not
+    // a trustworthy budget input here.
+    const prior = getCalibrationForBudget(store, model, profile);
     // Announced so the Brain rail can show the host as busy: a calibrate loads the
     // model at several context sizes and will make anything else queue behind it.
     const measurement = await withActivity("calibrate", { target: model.displayName }, () => calibrate({
@@ -66,7 +66,7 @@ export async function runCalibrateCommand(options, _command) {
         ? vram.maxContextThatFits({
             model,
             profile,
-            calibration: getCalibration(store, model, profile),
+            calibration: getCalibrationForBudget(store, model, profile),
             totalVramBytes: gpu.totalBytes,
         })
         : null;

package/dist/commands/pull.d.ts

@@ -1,7 +1,7 @@
 /**
  * `otto brain pull <model>` - download a model from the catalog into the managed
  * models directory, using only Node's fetch (no external downloader). The catalog
- * is the same one seeded from docs/candidate-models.md. `--list-quants` shows what
+ * is the same one seeded from docs/brain-model-catalog.md. `--list-quants` shows what
  * quantizations the repo offers and `--quant <label>` downloads a specific one.
  */
 import type { Command } from "commander";

package/dist/config/index.d.ts

@@ -4,7 +4,7 @@ export { ensurePrivateDirectory, writePrivateFileAtomicSync } from "./private-fi
 export { resolveBrainPaths, packageRoot, type BrainPaths } from "./paths.js";
 export { parseBooleanEnv, applyEnvOverrides } from "./env.js";
 export { loadBrainConfig, loadPersistedConfig, saveBrainConfig, loadProfilesStore, saveProfilesStore, loadCatalog, } from "./store.js";
-export { defaultProfile, forModel, put, calibrationKey, geometryKey, getCalibration, putCalibration, hasStaleCalibration, } from "./profiles.js";
+export { defaultProfile, forModel, put, calibrationKey, geometryKey, getCalibration, getCalibrationForBudget, getLastCalibration, putCalibration, hasStaleCalibration, } from "./profiles.js";
 export { effectiveHostingProfile, resolveHostingProfileForLaunch } from "./hosting-profiles.js";
 export { calibrationInfo, nativeContextLimit, profileFieldDescriptors, profileWarnings, sanitizeProfilePatch, formatReasoningBudget, CACHE_TYPE_CYCLE, REASONING_BUDGET_CYCLE, UNRESTRICTED_REASONING_BUDGET, PRESERVE_REASONING_CYCLE, SAMPLING_RANGES, preserveReasoningFromOption, preserveReasoningOption, type CalibrationInfo, type CalibrationState, type ProfileFieldDescriptor, type ProfileWarning, } from "./profile-edit.js";
 export * from "./schema.js";

package/dist/config/index.js

@@ -4,7 +4,7 @@ export { ensurePrivateDirectory, writePrivateFileAtomicSync } from "./private-fi
 export { resolveBrainPaths, packageRoot } from "./paths.js";
 export { parseBooleanEnv, applyEnvOverrides } from "./env.js";
 export { loadBrainConfig, loadPersistedConfig, saveBrainConfig, loadProfilesStore, saveProfilesStore, loadCatalog, } from "./store.js";
-export { defaultProfile, forModel, put, calibrationKey, geometryKey, getCalibration, putCalibration, hasStaleCalibration, } from "./profiles.js";
+export { defaultProfile, forModel, put, calibrationKey, geometryKey, getCalibration, getCalibrationForBudget, getLastCalibration, putCalibration, hasStaleCalibration, } from "./profiles.js";
 export { effectiveHostingProfile, resolveHostingProfileForLaunch } from "./hosting-profiles.js";
 export { calibrationInfo, nativeContextLimit, profileFieldDescriptors, profileWarnings, sanitizeProfilePatch, formatReasoningBudget, CACHE_TYPE_CYCLE, REASONING_BUDGET_CYCLE, UNRESTRICTED_REASONING_BUDGET, PRESERVE_REASONING_CYCLE, SAMPLING_RANGES, preserveReasoningFromOption, preserveReasoningOption, } from "./profile-edit.js";
 export * from "./schema.js";

package/dist/config/profile-edit.js

@@ -19,7 +19,7 @@
  */
 import os from "node:os";
 import { CACHE_TYPE_BYTES, formatGiB, promptCacheSize } from "../vram.js";
-import { getCalibration, hasStaleCalibration } from "./profiles.js";
+import { getCalibration, getCalibrationForBudget, hasStaleCalibration } from "./profiles.js";
 /**
  * Sampler ranges. llama.cpp itself bounds almost none of these - it will take a
  * temperature of 50 - so the bounds are the useful range rather than the legal
@@ -329,8 +329,10 @@ export function profileWarnings(profile, model, store) {
     // A count above 0 can only be priced from a measurement: without one the
     // theoretical KV cost runs to multiples of the real one, and naming a figure
     // derived from it would invite reserving several times the RAM actually
-    // needed. So the unmeasured count falls back to the calibration request.
-    const calibration = model && store ? getCalibration(store, model, profile) : null;
+    // needed. Once a model has been measured, keep its last value while edits are
+    // pending recalibration; the stale calibration state makes the reduced trust
+    // visible without making the number jump.
+    const calibration = model && store ? getCalibrationForBudget(store, model, profile) : null;
     const cache = model ? promptCacheSize(model, profile, calibration) : null;
     const hasCount = (profile.cachedChats ?? 0) > 0;
     if (hasCount && (!cache || cache.source !== "measured")) {
@@ -359,7 +361,7 @@ export function profileWarnings(profile, model, store) {
         warnings.push({
             field: "contextMultiplier",
             severity: "warn",
-            message: `YaRN ×${profile.contextMultiplier} extrapolates beyond the native context. Recalibrate before relying on this profile.`,
+            message: "YaRN extrapolates beyond the native context.",
             blocksStart: false,
         });
     }
@@ -370,7 +372,7 @@ export function profileWarnings(profile, model, store) {
         warnings.push({
             field: "cacheTypeK",
             severity: "info",
-            message: "Cache types changed since the last measurement. Recalibrate for a real budget.",
+            message: "Cache types changed since the last measurement.",
             blocksStart: false,
         });
     }
@@ -382,24 +384,22 @@ export function profileWarnings(profile, model, store) {
  * model's layer count, which the UI must never present as measured on this file.
  */
 export function calibrationInfo(store, model, profile) {
-    // A historical measurement is invalid as soon as any VRAM-affecting setting
-    // changes. Keep the data for comparison, but do not present or use it as the
-    // current model budget until a calibration commits the new profile.
-    if (profile.calibrationRequired) {
+    const current = getCalibration(store, model, profile);
+    const calibration = getCalibrationForBudget(store, model, profile);
+    if (!calibration) {
         return {
-            state: "theoretical",
+            state: hasStaleCalibration(store, model, profile) ? "stale" : "theoretical",
             kvBytesPerToken: null,
             measuredAt: null,
             measuredOn: null,
         };
     }
-    const calibration = getCalibration(store, model, profile);
-    if (!calibration) {
+    if (profile.calibrationRequired || !current) {
         return {
-            state: hasStaleCalibration(store, model, profile) ? "stale" : "theoretical",
-            kvBytesPerToken: null,
-            measuredAt: null,
-            measuredOn: null,
+            state: "stale",
+            kvBytesPerToken: calibration.kvBytesPerToken,
+            measuredAt: calibration.measuredAt ?? null,
+            measuredOn: calibration.measuredOn ?? null,
         };
     }
     return {

package/dist/config/profiles.d.ts

@@ -14,9 +14,9 @@ export declare function put(store: ProfilesStore, model: Model, profile: Profile
 /** Calibration is keyed by cache types, since those change bytes/token. */
 export declare function calibrationKey(profile: Profile): string;
 /**
- * True when this model has a stored calibration, but for different cache types
- * than the profile currently uses - i.e. the measurement is stale and the budget
- * has fallen back to the theoretical estimate. Drives the "recalibrate" prompt.
+ * True when this model has stored calibrations but none for the profile's
+ * current calibration key. Historical entries do not make an exact current
+ * measurement stale when the matching key is also present.
  */
 export declare function hasStaleCalibration(store: ProfilesStore, model: Model, profile: Profile): boolean;
 /**
@@ -30,5 +30,21 @@ export declare function hasStaleCalibration(store: ProfilesStore, model: Model,
  */
 export declare function geometryKey(model: Model, profile: Profile): string | null;
 export declare function getCalibration(store: ProfilesStore, model: Model, profile: Profile): Calibration | null;
+/**
+ * Return the most recent direct calibration stored for a model, regardless of
+ * which profile key produced it. A stale measurement is still the stable value
+ * the UI and budget math should keep showing until a new calibration replaces
+ * it; callers use the calibration state to make its reduced trust visible.
+ */
+export declare function getLastCalibration(store: ProfilesStore, model: Model): Calibration | null;
+/**
+ * Resolve the calibration used by VRAM budgeting and launch arguments.
+ *
+ * An exact or inherited current-profile calibration remains preferred while the
+ * profile is current. Once an edit requires recalibration, retain the model's
+ * most recent direct measurement instead of jumping to the theoretical formula.
+ * The profile/calibration state still tells the caller that this value is stale.
+ */
+export declare function getCalibrationForBudget(store: ProfilesStore, model: Model, profile: Profile): Calibration | null;
 export declare function putCalibration(store: ProfilesStore, model: Model, profile: Profile, measurement: Calibration): ProfilesStore;
 //# sourceMappingURL=profiles.d.ts.map

package/dist/config/profiles.js

@@ -115,16 +115,16 @@ export function calibrationKey(profile) {
         : `${profile.cacheTypeK}:${profile.cacheTypeV}${multiplier}`;
 }
 /**
- * True when this model has a stored calibration, but for different cache types
- * than the profile currently uses - i.e. the measurement is stale and the budget
- * has fallen back to the theoretical estimate. Drives the "recalibrate" prompt.
+ * True when this model has stored calibrations but none for the profile's
+ * current calibration key. Historical entries do not make an exact current
+ * measurement stale when the matching key is also present.
  */
 export function hasStaleCalibration(store, model, profile) {
     const measured = store.calibrations?.[model.id];
     if (!measured)
         return false;
     const key = calibrationKey(profile);
-    return Object.keys(measured).some((k) => k !== key);
+    return !Object.hasOwn(measured, key) && Object.keys(measured).length > 0;
 }
 /**
  * KV cost per token is a property of the attention geometry, not of the particular
@@ -167,6 +167,38 @@ export function getCalibration(store, model, profile) {
         inherited: true,
     };
 }
+/**
+ * Return the most recent direct calibration stored for a model, regardless of
+ * which profile key produced it. A stale measurement is still the stable value
+ * the UI and budget math should keep showing until a new calibration replaces
+ * it; callers use the calibration state to make its reduced trust visible.
+ */
+export function getLastCalibration(store, model) {
+    const entries = Object.values(store.calibrations?.[model.id] ?? {});
+    if (entries.length === 0)
+        return null;
+    return entries.reduce((latest, candidate) => {
+        const latestTime = latest.measuredAt ? Date.parse(latest.measuredAt) : Number.NEGATIVE_INFINITY;
+        const candidateTime = candidate.measuredAt
+            ? Date.parse(candidate.measuredAt)
+            : Number.NEGATIVE_INFINITY;
+        return candidateTime >= latestTime ? candidate : latest;
+    });
+}
+/**
+ * Resolve the calibration used by VRAM budgeting and launch arguments.
+ *
+ * An exact or inherited current-profile calibration remains preferred while the
+ * profile is current. Once an edit requires recalibration, retain the model's
+ * most recent direct measurement instead of jumping to the theoretical formula.
+ * The profile/calibration state still tells the caller that this value is stale.
+ */
+export function getCalibrationForBudget(store, model, profile) {
+    const current = getCalibration(store, model, profile);
+    if (!profile.calibrationRequired && current)
+        return current;
+    return getLastCalibration(store, model) ?? current;
+}
 export function putCalibration(store, model, profile, measurement) {
     if (!store.calibrations)
         store.calibrations = {};

package/dist/config/schema.d.ts

@@ -1516,6 +1516,10 @@ export declare const BrainConfigSchema: z.ZodObject<{
     modelsDir: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     hfToken: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     defaultModel: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    /** Maximum independently hosted llama-server model processes. */
+    maxLoadedModels: z.ZodDefault<z.ZodNumber>;
+    /** Stable ids selected for residency while model locking is enabled. */
+    lockedModels: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     lockModel: z.ZodDefault<z.ZodBoolean>;
     allowRemoteConfig: z.ZodDefault<z.ZodBoolean>;
     allowInsecureBind: z.ZodDefault<z.ZodBoolean>;
@@ -1571,6 +1575,8 @@ export declare const BrainConfigSchema: z.ZodObject<{
     modelsDir: string | null;
     hfToken: string | null;
     defaultModel: string | null;
+    maxLoadedModels: number;
+    lockedModels: string[];
     lockModel: boolean;
     allowRemoteConfig: boolean;
     allowInsecureBind: boolean;
@@ -1612,6 +1618,8 @@ export declare const BrainConfigSchema: z.ZodObject<{
     modelsDir?: string | null | undefined;
     hfToken?: string | null | undefined;
     defaultModel?: string | null | undefined;
+    maxLoadedModels?: number | undefined;
+    lockedModels?: string[] | undefined;
     lockModel?: boolean | undefined;
     allowRemoteConfig?: boolean | undefined;
     allowInsecureBind?: boolean | undefined;

package/dist/config/schema.js

@@ -251,9 +251,13 @@ export const BrainConfigSchema = z
     // persisted fallback so users can set it once (config set hfToken <token>).
     hfToken: z.string().nullable().default(null),
     defaultModel: z.string().nullable().default(null),
-    // Pin the host to a single model: serve only the default/resident model and
-    // refuse completion requests that name a different one, instead of queuing a
-    // switch. For hosts that load one model and must not thrash between clients.
+    /** Maximum independently hosted llama-server model processes. */
+    maxLoadedModels: z.number().int().min(1).max(16).default(1),
+    /** Stable ids selected for residency while model locking is enabled. */
+    lockedModels: z.array(z.string()).default([]),
+    // Pin the host to the selected resident set and refuse completion requests
+    // that name a different model. With a one-process host this preserves the
+    // original single-model lock behavior.
     lockModel: z.boolean().default(false),
     // Sharing/control gates (off by default - a brain is not remotely
     // controllable until its owner opts in). `allowRemoteConfig`: a client with

package/dist/ops/archive.d.ts

@@ -1,4 +1,17 @@
 import type { Model } from "../types.js";
+/**
+ * Raw model output archive.
+ *
+ * Scoring is a separate, replayable pass over stored transcripts rather than
+ * something that only happens live. This exists because a bug in the scorer
+ * (a filename matcher that attributed every test block to the wrong file) made
+ * seven models look identical, and fixing it cost a full re-run on the GPU. The
+ * model outputs had been correct all along - only the grading was wrong.
+ *
+ * With the transcript on disk, a scorer fix re-grades history in seconds.
+ */
+/** Resolve the writable transcript store for a given host environment. */
+declare function resolveArchiveDir(env?: NodeJS.ProcessEnv): string;
 declare const ARCHIVE_DIR: string;
 /** One archived request/response exchange. */
 export interface TranscriptEntry {
@@ -30,5 +43,5 @@ declare function load(id: string): Record<string, TranscriptEntry[]>;
 declare function list(): string[];
 /** Total bytes held, so the archive can be pruned knowingly. */
 declare function size(): number;
-export { ARCHIVE_DIR, runId, runDir, put, load, list, size };
+export { ARCHIVE_DIR, resolveArchiveDir, runId, runDir, put, load, list, size };
 //# sourceMappingURL=archive.d.ts.map

package/dist/ops/archive.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
-import { fileURLToPath } from "node:url";
+import { resolveBrainPaths } from "../config/paths.js";
 /**
  * Raw model output archive.
  *
@@ -13,9 +13,13 @@ import { fileURLToPath } from "node:url";
  *
  * With the transcript on disk, a scorer fix re-grades history in seconds.
  */
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const ROOT = path.resolve(HERE, "..", "..");
-const ARCHIVE_DIR = path.join(ROOT, "results", "transcripts");
+/** Resolve the writable transcript store for a given host environment. */
+function resolveArchiveDir(env = process.env) {
+    return path.join(resolveBrainPaths(env).resultsDir, "transcripts");
+}
+// Raw benchmark exchanges are host state too. They must follow the score store
+// into OTTO_HOME rather than attempting to write beside the installed package.
+const ARCHIVE_DIR = resolveArchiveDir();
 function runId(model, timestamp = new Date()) {
     const stamp = timestamp.toISOString().replace(/[:.]/g, "-");
     const slug = String(model?.displayName || "unknown")
@@ -101,5 +105,5 @@ function size() {
     }
     return bytes;
 }
-export { ARCHIVE_DIR, runId, runDir, put, load, list, size };
+export { ARCHIVE_DIR, resolveArchiveDir, runId, runDir, put, load, list, size };
 //# sourceMappingURL=archive.js.map

package/dist/ops/results.d.ts

@@ -1,6 +1,26 @@
 import type { GpuInfo, Model, ModelFeatures } from "../types.js";
 import type { Calibration, Profile } from "../config/schema.js";
 import type { FitResult } from "../vram.js";
+/**
+ * Persistent benchmark history.
+ *
+ * One JSON file per run, so results accumulate across sessions and can be
+ * compared and charted later. Runs record the configuration they were measured
+ * under, because a score is meaningless without the quant, context size and
+ * reasoning budget that produced it.
+ *
+ * **A run records every value it was measured with, not a summary of them.** A
+ * bad score is far more often a bad setup than a bad model, and the difference
+ * is only visible from the settings: a context the VRAM fit had to cut, a
+ * reasoning budget the model spends entirely on thinking, a KV quant that
+ * wrecked recall, weights that fell off the GPU because `gpuLayers` did not
+ * cover them, a budget estimated from the formula rather than measured. None of
+ * that is recoverable after the fact, so it is all written down at save time -
+ * including the exact llama-server argv the run was served with, which is the
+ * only true statement of what ran.
+ */
+/** Resolve the writable store for benchmark scores for a given host environment. */
+declare function resolveResultsDir(env?: NodeJS.ProcessEnv): string;
 declare const RESULTS_DIR: string;
 /** Aggregate of a numeric health series (nvidia-smi samples during a run). */
 export interface AggStat {
@@ -368,5 +388,5 @@ declare function variance(records?: RunRecord[]): VarianceRow[];
 declare function rankModels(records?: RunRecord[]): RankedModel[];
 /** All task ids seen across a set of records, in a stable order. */
 declare function taskColumns(records: RunRecord[]): TaskColumn[];
-export { RESULTS_DIR, save, loadAll, latestPerConfig, grouped, variance, stats, rankModels, taskColumns, configKey, slugify, ENGINE_SAMPLER_DEFAULTS, };
+export { RESULTS_DIR, resolveResultsDir, save, loadAll, latestPerConfig, grouped, variance, stats, rankModels, taskColumns, configKey, slugify, ENGINE_SAMPLER_DEFAULTS, };
 //# sourceMappingURL=results.d.ts.map

package/dist/ops/results.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolveBrainPaths } from "../config/paths.js";
 /**
  * Persistent benchmark history.
  *
@@ -19,9 +19,14 @@ import { fileURLToPath } from "node:url";
  * including the exact llama-server argv the run was served with, which is the
  * only true statement of what ran.
  */
-const HERE = path.dirname(fileURLToPath(import.meta.url));
-const ROOT = path.resolve(HERE, "..", "..");
-const RESULTS_DIR = path.join(ROOT, "results");
+/** Resolve the writable store for benchmark scores for a given host environment. */
+function resolveResultsDir(env = process.env) {
+    return resolveBrainPaths(env).resultsDir;
+}
+// Benchmark history is host state, not package data. Keeping it beside the
+// Brain config also makes the service work from packaged/Electron installs,
+// where the package directory may be an archive or read-only.
+const RESULTS_DIR = resolveResultsDir();
 function slugify(text) {
     return String(text)
         .toLowerCase()
@@ -383,5 +388,5 @@ function taskColumns(records) {
     }
     return [...seen.entries()].map(([id, category]) => ({ id, category }));
 }
-export { RESULTS_DIR, save, loadAll, latestPerConfig, grouped, variance, stats, rankModels, taskColumns, configKey, slugify, ENGINE_SAMPLER_DEFAULTS, };
+export { RESULTS_DIR, resolveResultsDir, save, loadAll, latestPerConfig, grouped, variance, stats, rankModels, taskColumns, configKey, slugify, ENGINE_SAMPLER_DEFAULTS, };
 //# sourceMappingURL=results.js.map

package/dist/service/activity.d.ts

@@ -73,6 +73,41 @@ export interface InferenceActivitySnapshot {
      */
     slotStages?: Record<string, InferenceStage>;
 }
+/**
+ * A caller's exclusive claim on one tracked request.
+ *
+ * Handed out by `ReasoningTracker.begin` and released exactly once. Releasing
+ * is terminal: every method on a released lease is a no-op, so a chunk that
+ * arrives after the client has gone cannot revive the request it names. That is
+ * not a theoretical concern - it is the shape of the bug this type exists to
+ * make impossible (see `begin`).
+ */
+export interface InferenceLease {
+    /** This request's id, for logs and for joining to an engine slot. */
+    readonly id: string;
+    observe(text: string): void;
+    setSlot(slotId: number): void;
+    /** Idempotent, and safe to call from every branch that can end a stream. */
+    end(): void;
+}
+/** What the engine says about itself, for `ReasoningTracker.reconcile`. */
+export interface EngineSlotTruth {
+    /**
+     * Slot ids llama-server reports as actively processing, or null when this
+     * build reports a count but no per-slot rows. Null demotes every request to
+     * the conservative unpinned rule.
+     */
+    busySlots: ReadonlySet<number> | null;
+    /** How many slots are busy, or null when the sample failed - which reaps nothing. */
+    busyCount: number | null;
+}
+/** One request the reaper cleared, and the evidence worth logging about it. */
+export interface ReapedRequest {
+    id: string;
+    stage: InferenceStage;
+    slotId: number | null;
+    ageMs: number;
+}
 /**
  * Which in-flight completions are currently mid-thought.
  *
@@ -97,23 +132,69 @@ export declare class ReasoningTracker {
      * one stage do not notify; slot sampling owns bounded token-rate updates.
      */
     onChange(listener: () => void): () => void;
-    /** A completion was dispatched to llama-server and awaits its first output delta. */
-    begin(requestId: string): void;
     /**
-     * Record the engine slot this request was pinned to. Called exactly once per
-     * request, at dispatch - the pin is injected into the outbound body before
-     * the request goes out, so the association exists before the first chunk and
-     * `observe` never has to learn about it.
+     * Open a lease for a completion that has just been dispatched to
+     * llama-server and awaits its first output delta.
+     *
+     * A lease rather than an id the caller carries around, because every stuck
+     * "thinking" this tracker has produced was a release that did not happen on
+     * some branch of the proxy's event wiring. A lease makes both halves of that
+     * bug unrepresentable: nothing can advance a request without holding its
+     * lease, and a released lease is inert, so a chunk that lands after the
+     * release cannot resurrect the request it belongs to. (The same shape as
+     * `beginActivity` above, for the same reason.)
+     *
+     * Ids are minted here rather than by the caller: two callers sharing one id
+     * would silently share one request's state.
+     */
+    begin(): InferenceLease;
+    /**
+     * Forget every slot pin, because the engine's slots did not survive its
+     * relaunch.
+     *
+     * The mirror of `Scheduler.forgetSlots`, and required for the same reason: a
+     * pin that outlives the process it named is no longer evidence. Worse than
+     * useless, in fact - a stale pin can collide with a NEW request's slot id,
+     * and the reaper would read that unrelated busy row as proof the dead request
+     * is still alive. Dropping the pins demotes those requests to the
+     * conservative unpinned rule, which clears them once the engine is quiet.
+     */
+    forgetSlots(): void;
+    /**
+     * Drop tracked requests the engine's own account of itself contradicts.
+     *
+     * The safety net under the lease, and it exists because `active` outranks
+     * every engine signal on the rail: one release that never happened claims
+     * "thinking" until the service restarts. The ops tracker already refuses that
+     * bargain by probing the recorded pid, on the principle that a status stuck
+     * on "calibrating" forever is worse than no status at all. This is the
+     * inference half of the same rule.
+     *
+     * **It must never clear valid work**, so it acts only on positive evidence,
+     * and only on evidence a live request could not produce:
+     *
+     *  1. A request that has sent a chunk (or been pinned, or been dispatched)
+     *     within `INFERENCE_QUIET_MS` is alive. A streaming request is therefore
+     *     never a candidate at all, whatever the engine says this instant.
+     *  2. A PINNED request is checked against its own slot. llama-server marks a
+     *     slot processing for the whole task, prefill included, so a request that
+     *     is genuinely running makes its row busy. That row being idle is the
+     *     contradiction. This is what lets one chat's leak be cleared while
+     *     another chat keeps generating.
+     *  3. An UNPINNED request - or any request when the engine reports no
+     *     per-slot rows - cannot be attributed to a row, so it is cleared only
+     *     when the engine reports nothing running at all. Ambiguity is not
+     *     evidence.
+     *  4. The contradiction has to hold for `INFERENCE_STRIKES` samples in a row.
+     *     A single sample can race the dispatch window, where a request has been
+     *     begun and the engine has not picked it up yet; a run of them cannot.
+     *
+     * A failed slot sample is not evidence either, and reconciles nothing.
      *
-     * Idempotent and self-cleaning: a repeat for the same slot is a no-op, and a
-     * different slot replaces it, so a request that somehow moves slots (a
-     * restarted engine hands a task out again) reports where it is now.
+     * Returns what it reaped, so the caller can log a leak rather than silently
+     * paper over it.
      */
-    setSlot(requestId: string, slotId: number): void;
-    /** Note a chunk of `requestId`'s stream. Cheap enough to call per chunk. */
-    observe(requestId: string, text: string): void;
-    /** Forget the request. Must be called on end *and* on error, or the flag sticks. */
-    end(requestId: string): void;
+    reconcile(truth: EngineSlotTruth): ReapedRequest[];
     get active(): boolean;
     get count(): number;
     /** Aggregate request stages. Counts stay exact even with several parallel slots. */