@qvac/harness 1.0.0-rc.1 → 1.0.0-rc.2

package/dist-lib/index.js

@@ -4,69 +4,49 @@ import process from 'process';
 import ReadyResource from 'ready-resource';
 import { probeGpuStats } from './lib/hardware/gpu-probe.js';
 import { probeCapabilityProfile } from './lib/hardware/capability-probe.js';
-import { closePythonWorker } from './lib/tools/exec/adapters/python/worker/active.js';
-import { trackCompletion } from './lib/completion-lifecycle.js';
-import { createHarnessLifecycle } from './lib/harness-lifecycle.js';
-import { didDrainTimeOut, raceDrain } from './lib/machine/index.js';
-import { completion, imageSettingsFrom } from './lib/capabilities/completion.js';
+import { Lifecycle } from './lib/lifecycle/index.js';
+import { didDrainTimeOut, raceDrain } from './lib/helpers/drain.js';
+import { CompletionEngine } from './lib/capabilities/completion-engine/index.js';
+import { imageSettingsFrom } from './lib/helpers/image-settings.js';
 import { detectLanguage } from './lib/capabilities/detect-language.js';
 import { invoke } from './lib/capabilities/invoke.js';
 import { previewModelSource } from './lib/capabilities/preview-model-source.js';
 import { expandImagePrompt } from './lib/capabilities/enhance.js';
-import { cleanAnswer } from './lib/helpers/clean-answer.js';
-import { isTranslationModel } from './lib/models/nmt-catalog.js';
-import { createTranslateTool, createTranslationRuntime } from './lib/tools/translate.js';
 import { download } from './lib/capabilities/download.js';
-import { createEmbedLane } from './lib/capabilities/embed.js';
+import { Embeddings } from './lib/embeddings/index.js';
 import { deleteAllKvCaches, deleteKvCacheKey } from './lib/capabilities/kv-cache.js';
-import { pcmForTranscription } from './lib/capabilities/audio-resample.js';
-import { buildWavBuffer } from './lib/wav-encode.js';
-import { createVoiceLane, packSamples, speakOnce, speakStreamOnce, transcribeOnce, transcribeStreaming, SUPERTONIC_SAMPLE_RATE } from './lib/capabilities/voice.js';
 import { pushQueue } from './lib/queue.js';
-import { AbortedError, raceAbort } from './lib/helpers/race-abort.js';
-import { audioGenDownloadMetadata, customProjectionMap, defaultProjectionMap, defaultTtsFor, defaultVoiceModel, diffusionDownloadMetadata, curatedModelAsset, infraModelsFor, modelAddonOf, modelNameToCapabilityProfile, musicModelSet, residentSrc, setCustomModels } from './lib/models/model-catalog.js';
-import { createModelStatusCache, customModelRows, invalidateModelStatusCache, mergeCustomRows, listModels } from './lib/models/model-list.js';
+import { AbortedError } from './lib/helpers/race-abort.js';
+import { audioGenDownloadMetadata, categoryDownloadMetadata, customProjectionMap, defaultProjectionMap, defaultVoiceModel, diffusionDownloadMetadata, infraModelsFor, modelNameToCapabilityProfile, residentSrc, setCustomModels } from './lib/models/model-catalog.js';
+import { customModelRows, mergeCustomRows, listModels } from './lib/models/model-list.js';
 import { deleteModelFiles, summarizeDelete } from './lib/models/model-delete.js';
-import { createEmbedPool, createLoadTracker, createModelPool, createVoicePool, ModelUnloadError, awaitModelCapacity, evictIdle, evictIdleWhere, evictModel, evictModelWithin, isResident, leaseResidentModel, leaseCount, loadedModels, loadingModels, settledModels, modelKey, modelOf, releaseModel, resolveCtxSize, resolveLoadOptions, progressState } from './lib/models/model-pool.js';
-import { defaultContextSize } from './lib/models/context.js';
-import { resolveMainGpu } from './lib/models/gpu-selection.js';
-import { createIdleReaper } from './lib/models/idle-unload.js';
+import { createLoadTracker, createVoicePool, evictIdle, evictIdleWhere, isResident, leaseResidentModel, loadedModels, releaseModel, progressState } from './lib/models/model-pool.js';
 import { openclCacheDir } from './lib/models/opencl-cache.js';
-import { assertEmbedDevice, createEmbedConfig } from './lib/models/embed-config.js';
-import { createGpuFaultState, isSdkGpuDeviceLostError, isSdkModelWedgedError } from './lib/models/sdk-faults.js';
+import { isSdkModelWedgedError } from './lib/models/sdk-faults.js';
 import { createSdkLoader } from './lib/sdk-loader.js';
-import { installAbortControllerPolyfill } from './lib/capabilities/completion-engine/abort-polyfill.js';
-import { prepareCompletionRuntime } from './lib/capabilities/completion-runtime.js';
-import { createEditImageTool } from './lib/tools/edit-image.js';
+import { installAbortControllerPolyfill } from './lib/helpers/abort-polyfill.js';
+import { Residency } from './lib/residency/index.js';
 import { toolCatalog } from './lib/tools/catalog.js';
-import { createDiffusionRuntime, createGenerateImageTool } from './lib/tools/generate-image.js';
-import { createGenerateMusicTool, createMusicRuntime } from './lib/tools/generate-music.js';
-import { availableSkills, detectPlatform, loadSkillCatalog, resolveSkillStatuses, skillSupportsPlatform, versionProbeSkills } from './lib/tools/skills/catalog.js';
-import { ensureBundledSkillsDir } from './lib/tools/skills/bundled-dir.js';
-import { ensureSkillsOverlayDir } from './lib/tools/skills/overlay-dir.js';
-import { copyBaseForEdit, deleteOverlaySkill, listManagedSkills, readSkillFile, writeSkillFile } from './lib/tools/skills/overlay-crud.js';
-import { watchSkillsOverlay } from './lib/tools/skills/overlay-watch.js';
+import { SkillsHost } from './lib/skills-host/index.js';
 import { errorMessage, isRecord } from './lib/guards.js';
 import { redactedRecoveryFields } from './lib/wire.js';
 import { hlog } from './lib/log.js';
 import { installResolutionDetector, resolutionDetail } from './lib/resolution-detector.js';
-import { probeBinVersions } from './lib/tools/skills/bin-check.js';
 import { bareRuntime } from './lib/tools/exec/bare-runtime.js';
 import { runCommand } from './lib/tools/exec/runner.js';
 import { createLocalRoots } from './lib/tools/fs/local.js';
 import { createRemoteRoots } from './lib/tools/fs/remote.js';
-import { resetCredentialHealth as resetCredentialHealthAfterSnapshot } from './lib/tools/skills/credential-health.js';
-import { isDeviceSharedCredentialKey, scopeKey } from './lib/tools/skills/scope-key.js';
-import { settingsScopeKey } from './lib/tools/skills/skill-settings.js';
-export * from './lib/capabilities/completion.js';
+export { CompletionEngine } from './lib/capabilities/completion-engine/index.js';
+export const CONTEXT_OVERFLOW_MESSAGE = CompletionEngine.CONTEXT_OVERFLOW_MESSAGE;
+export { imageSettingsFrom } from './lib/helpers/image-settings.js';
+export { skillInContext, unreadySkillState } from './lib/capabilities/skill-entry.js';
+export { toSdkTool } from './lib/capabilities/sdk-tool.js';
 export { attachmentTurn, loadedSkillsFrom, skillLoadedTurn } from './lib/capabilities/tool-turns.js';
 export { CAPABILITIES, isCapability } from './lib/capabilities/invoke.js';
-export { EURONANO_LANGUAGES, NMT_FROM_ENGLISH, NMT_TO_ENGLISH, SLM_LANGUAGE_CODES, SLM_LANGUAGE_NAMES, translationPlanFor } from './lib/models/nmt-catalog.js';
 export * from './lib/capabilities/download.js';
 export * from './lib/models/model-catalog.js';
 export * from './lib/models/model-list.js';
 export { harnessChild, spawnHarness } from './lib/spawn.js';
-export { settingsDimension, settingsSteps } from './lib/tools/generate-image.js';
 export * from './lib/tools/skills/catalog.js';
 export { requiredSettings, settingEnvName } from './lib/tools/skills/skill-settings.js';
 export { TOOLSETS, toolsetEnabled } from './lib/tools/toolsets.js';
@@ -76,455 +56,337 @@ export { isAvailableState, SKILL_STATE } from './lib/tools/skills/skill-state.js
 export { connectHarness, HARNESS_DIED, RemoteHarness } from './lib/connect.js';
 export { serveHarness } from './lib/serve.js';
 export { hlog, setHarnessLog, setHarnessLogSink } from './lib/log.js';
-export { harnessHooks } from './lib/hooks/registry.js';
-export { EgressGuardHook, SkillCatalogGuardHook } from './lib/hooks/built-in/index.js';
-const BIN_VERSION_PROBE_TTL_MS = 45_000;
+import { HookPipeline } from './lib/hooks/index.js';
+import { Agent } from './lib/agent/index.js';
+export { HookPipeline };
+import { createGuardedFetch } from './lib/guarded-fetch.js';
+import { PluginRegistry } from './lib/plugins/index.js';
+import { createExecTool } from './lib/tools/exec.js';
+import { deniedRootsFor } from './lib/tools/fs/scope.js';
+export const PLUGIN_API_VERSION = PluginRegistry.API_VERSION;
 const SUSPEND_SETTLE_MS = 500;
-const TRANSCRIBE_STREAM_MIN_BYTES = 16_000 * 2 * 60;
-const TRANSCRIPTION_MODEL_LABEL = 'transcription model';
-const DIFFUSION_EVICT_WAIT_MS = 15_000;
-const MUSIC_EVICT_WAIT_MS = 15_000;
-const WEDGED_EVICT_WAIT_MS = 10_000;
-const MODEL_ROOM_WAIT_MS = 300_000;
-const WARM_ROOM_WAIT_MS = 2_000;
-const UNLOAD_LEASE_WAIT_MS = 10_000;
-const DEFAULT_COMPLETION_MODEL_CAP = 1;
-const WEDGED_EVICT_LEASED_MS = 120_000;
-const TTS_MODEL_CONFIG = {
-    ttsEngine: 'supertonic',
-    language: 'en',
-    ttsSpeed: 1.175,
-    ttsNumInferenceSteps: 5
-};
+const SPEECH_PLUGIN_MISSING = 'speech needs the speech plugin';
+const KNOWLEDGE_PLUGIN_MISSING = 'knowledge needs the knowledge plugin';
+function execOptions(exec) {
+    if (!exec)
+        return null;
+    return exec === true ? {} : exec;
+}
 export class Harness extends ReadyResource {
+    _hostTools;
     _tools;
+    _capabilities = [];
     _sdk;
     _loads = createLoadTracker();
-    _pinned = new Set();
-    _replying = [];
-    _modelStatus = createModelStatusCache();
-    _models;
-    _embedModels;
-    _retiredEmbedModels;
-    _faultedEmbedKeys = new WeakMap();
-    _embedLane = createEmbedLane();
-    _embedFaults;
-    _embedGpuLayers;
-    _embedBatchSize;
-    _embedControl;
-    _ttsModels;
-    _transcriptionModels;
-    _voiceLane = createVoiceLane();
-    _lifecycle = createHarnessLifecycle({
-        suspend: () => this._suspendRuntimes(),
-        resume: () => this._resumeRuntimes()
-    });
-    _detachedRuns = new Set();
-    _effectDrainWaiters = new Set();
-    _activeWork = 0;
-    _workDrainWaiters = new Set();
-    _runtimeDraining = false;
-    _runtimeUnloadFailed = false;
-    _poolUnloadFailed = false;
-    _poolCleanupFailed = false;
-    _failedModelUnloads = new Set();
-    _sdkClosed = false;
-    _runtimesReleased = false;
+    _residency;
+    _embeddings;
+    _voicePools = new Map();
+    _skills;
+    _lifecycle;
     _closeRetryNeeded = false;
-    _closeRequested = false;
-    _skillsDir;
     _modelsDir;
-    _overlayWatcher = null;
-    _supportedSkills;
+    _skillsDir;
+    _exec;
+    _deniedRoots;
     _projectionModel;
     _customProjection = {};
-    _llmDevice;
-    _llmGpuLayers;
-    _contextSize;
-    _kvCacheK;
-    _kvCacheV;
-    _transcriptionDevice;
     _gpuStats;
-    _completionModelCap;
-    _allSkills;
-    _credentialStore;
-    _credentials = new Map();
-    _settings = new Map();
-    _platform;
-    _diffusionSdk;
-    _imageRuntime;
-    _musicSdk;
-    _translationSdk;
-    _musicRuntime;
-    _completionRuns;
-    _translationRuntime;
-    _capabilityTools;
     _capability = null;
     _capabilityInflight = null;
-    _modelFaults = new Map();
-    _idle;
-    constructor({ tools = [], sdkLoader, skillsDir, modelsDir, projectionModel, imageModel, imageClamps, musicModel, musicClamps, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats } = {}) {
+    _hostHooks;
+    _hooks;
+    _plugins;
+    _pluginMode;
+    _pluginsStarted = null;
+    constructor({ tools = [], sdkLoader, skillsDir, modelsDir, sdkHome, exec, projectionModel, llmDevice, llmGpuLayers, contextSize, kvCacheK, kvCacheV, llmLoad, slots, embedDevice, embedGpuLayers, embedBatchSize, transcriptionDevice, completionModelCap, credentialStore, platform, gpuStats, hooks, plugins = [], pluginMode = 'frozen' } = {}) {
         super();
+        this._exec = execOptions(exec);
+        if (this._exec && tools.some((tool) => tool.name === PluginRegistry.EXEC_TOOL)) {
+            throw new Error(`tools has '${PluginRegistry.EXEC_TOOL}', which the harness builds when exec is set`);
+        }
+        this._deniedRoots = sdkHome === undefined ? undefined : deniedRootsFor(sdkHome);
+        this._plugins = new PluginRegistry(plugins, {
+            services: { models: this._modelHost(transcriptionDevice), embed: this._embedHost() },
+            exec: this._exec !== null,
+            deniedRoots: this._deniedRoots ?? []
+        });
+        this._pluginMode = pluginMode;
         installAbortControllerPolyfill();
+        this._hostHooks = Object.freeze([...(hooks ?? HookPipeline.defaults())]);
+        this._hooks = this._hostHooks;
         this._sdk = sdkLoader ?? createSdkLoader();
-        this._llmDevice = llmDevice;
-        this._gpuStats = gpuStats;
-        this._llmGpuLayers = llmGpuLayers;
-        this._contextSize = contextSize;
-        this._kvCacheK = kvCacheK;
-        this._kvCacheV = kvCacheV;
-        this._transcriptionDevice = transcriptionDevice;
-        this._completionModelCap = completionModelCap ?? DEFAULT_COMPLETION_MODEL_CAP;
-        const embedConfig = createEmbedConfig({
-            device: embedDevice,
-            gpuLayers: embedGpuLayers,
-            batchSize: embedBatchSize
+        this._lifecycle = new Lifecycle({
+            resource: this,
+            sdk: { peek: () => this._sdk.peek() },
+            loads: this._loads,
+            releases: {
+                pools: () => [
+                    this._residency.destroy(),
+                    this._embeddings.destroy(),
+                    ...[...this._voicePools.values()].map((entry) => entry.pool.destroy())
+                ],
+                runtimes: () => [],
+                plugins: () => this._plugins.unload()
+            },
+            models: () => loadedModels(this._residency.pool).map((entry) => entry.model),
+            recreate: () => {
+                this._residency.recreate();
+                this._embeddings.recreate();
+                for (const entry of this._voicePools.values()) {
+                    entry.pool = this._createVoicePool(entry.spec);
+                }
+            },
+            statusChanged: () => this._residency.invalidateStatus(),
+            teardown: async () => {
+                this._skills.close();
+                await this._teardownPlugins();
+            }
         });
-        this._embedGpuLayers = embedConfig.gpuLayers;
-        this._embedBatchSize = embedConfig.batchSize;
-        this._retiredEmbedModels = new Set();
-        this._embedControl = Promise.resolve();
-        this._embedFaults = createGpuFaultState({
-            device: embedConfig.device,
-            gpuLayers: embedConfig.gpuLayers
+        this._gpuStats = gpuStats;
+        this._hostTools = tools;
+        this._tools = tools;
+        this._projectionModel = projectionModel ?? defaultProjectionMap();
+        this._modelsDir = modelsDir;
+        this._skillsDir = skillsDir;
+        this._skills = new SkillsHost({
+            skillsDir,
+            platform,
+            credentialStore,
+            tools: () => this._tools,
+            startPlugins: () => this._startPlugins()
         });
-        const imageTransfers = new Map();
-        const image = typeof imageModel === 'string' ? { model: imageModel } : imageModel;
-        this._imageRuntime = image
-            ? createDiffusionRuntime({
-                ...image,
-                loads: this._loads,
-                loadSdk: () => this._loadDiffusionSdk(),
-                onProgress: (model, progress) => {
-                    const state = progressState(model, progress);
-                    if (state.status === 'downloading' &&
-                        typeof progress.percentage === 'number' &&
-                        progress.percentage < 100) {
-                        imageTransfers.set(model, state);
-                    }
-                    this.emit('model', state.status === 'downloading' && !imageTransfers.has(model)
-                        ? { ...state, status: 'loading' }
-                        : state);
-                },
-                onLoaded: (model) => {
-                    const transfer = imageTransfers.get(model);
-                    if (!transfer) {
-                        return;
-                    }
-                    imageTransfers.delete(model);
-                    invalidateModelStatusCache(this._modelStatus);
-                    this.emit('model', { ...transfer, status: 'downloaded' });
-                },
-                onBeforeLoad: async (signal) => {
-                    if (this._models.destroyed)
-                        return;
-                    const evicted = await awaitModelCapacity(this._models, {
-                        cap: 1,
-                        deadlineMs: DIFFUSION_EVICT_WAIT_MS,
-                        signal
-                    });
-                    if (signal?.aborted) {
-                        throw new AbortedError();
-                    }
-                    if (!evicted) {
-                        throw new Error('the chat model is busy; try the image again once the current reply finishes');
-                    }
+        this._residency = new Residency({
+            llmDevice,
+            llmGpuLayers,
+            contextSize,
+            kvCacheK,
+            kvCacheV,
+            llmLoad,
+            slots,
+            completionModelCap,
+            sdk: { load: () => this._sdk.load() },
+            loads: this._loads,
+            gate: this._lifecycle,
+            emit: (state) => this.emit('model', state),
+            projectionFor: (model) => this._projectionFor(model),
+            pools: () => [
+                ...this._embeddings.pools(),
+                ...[...this._voicePools.values()].map((entry) => entry.pool)
+            ],
+            poolFor: (addon, model) => {
+                if (addon === 'embeddings') {
+                    return this._embeddings.target(model);
                 }
-            })
-            : null;
-        const music = typeof musicModel === 'string' ? (musicModelSet(musicModel) ?? undefined) : musicModel;
-        this._musicRuntime = music
-            ? createMusicRuntime({
-                ...music,
-                loads: this._loads,
-                loadSdk: () => this._loadMusicSdk(),
-                onProgress: (model, progress) => {
-                    const state = progressState(model, progress);
-                    this.emit('model', state);
-                },
-                onBeforeLoad: async (signal) => {
-                    if (this._models.destroyed)
-                        return;
-                    const evicted = await awaitModelCapacity(this._models, {
-                        cap: 1,
-                        deadlineMs: MUSIC_EVICT_WAIT_MS,
-                        signal
-                    });
-                    if (signal?.aborted) {
-                        throw new AbortedError();
-                    }
-                    if (!evicted) {
-                        throw new Error('the chat model is busy; try the music again once the current reply finishes');
-                    }
+                const entry = this._voicePools.get(addon);
+                if (!entry) {
+                    throw new Error(SPEECH_PLUGIN_MISSING);
                 }
-            })
-            : null;
-        this._translationRuntime = createTranslationRuntime({
-            loads: this._loads,
-            loadSdk: () => this._loadTranslationSdk(),
-            onProgress: (model, progress) => this.emit('model', progressState(model, progress))
+                const key = residentSrc(model, addon);
+                return {
+                    pool: entry.pool,
+                    key,
+                    needsRoom: entry.spec.needsRoom?.(key) ?? false,
+                    open: () => entry.pool.open(key, key)
+                };
+            },
+            embedRoom: (model, target) => this._embeddings.makeRoom(model, target),
+            evictIdle: () => [
+                ...this._embeddings.evictIdle(),
+                ...[...this._voicePools.values()].map((entry) => evictIdle(entry.pool))
+            ],
+            unloadIdlePlugins: () => this._plugins.unloadIdle(),
+            tools: () => this._tools,
+            skills: (agentId, model) => this._skills.completionSkills(agentId, model)
         });
-        this._capabilityTools = [
-            createTranslateTool(this._translationRuntime, {
-                slm: (...args) => this._slmTranslate(...args)
-            })
-        ];
-        this._tools = [
-            ...tools,
-            ...(this._imageRuntime
-                ? [
-                    createGenerateImageTool(this._imageRuntime, imageClamps),
-                    createEditImageTool(this._imageRuntime, {}, imageClamps)
-                ]
-                : []),
-            ...(this._musicRuntime ? [createGenerateMusicTool(this._musicRuntime, musicClamps)] : [])
-        ];
-        this._projectionModel = projectionModel ?? defaultProjectionMap();
-        this._skillsDir = skillsDir;
-        this._modelsDir = modelsDir;
-        this._supportedSkills = [];
-        this._allSkills = [];
-        this._credentialStore = credentialStore;
-        this._platform = platform;
-        this._diffusionSdk = null;
-        this._musicSdk = null;
-        this._completionRuns = new Set();
-        this._translationSdk = null;
-        this._models = this._createPool();
-        this._embedModels = this._createEmbedPool();
-        this._ttsModels = this._createTtsPool();
-        this._transcriptionModels = this._createTranscriptionPool();
-        this._idle = createIdleReaper({
-            sweep: () => this._unloadIdleModels(),
-            waitMs: WEDGED_EVICT_WAIT_MS,
-            onError: (err) => hlog('idle unload failed', { err: errorMessage(err) })
+        this._embeddings = new Embeddings({
+            device: embedDevice,
+            gpuLayers: embedGpuLayers,
+            batchSize: embedBatchSize,
+            sdk: { loadEmbed: () => this._sdk.loadEmbed() },
+            loads: this._loads,
+            gate: this._lifecycle,
+            notify: (state) => this._residency.notify(state),
+            settleFit: (query) => this._residency.fit.settle(query),
+            evictIdleChat: () => this._residency.evictIdleChat()
         });
     }
     async _open() {
         try {
             installResolutionDetector(import.meta);
-            await this._reloadSkills();
-            await this._startOverlayWatch();
-            hlog('open', { skills: this._supportedSkills.length, tools: this._tools.length });
+            await this._startPlugins();
+            await this._loadAddons();
+            await this._skills.open();
+            hlog('open', { skills: this._skills.names.length, tools: this._tools.length });
         }
         catch (error) {
+            await this._teardownPlugins();
             throw error;
         }
     }
+    _startPlugins() {
+        this._pluginsStarted ??= this._runPluginStart();
+        return this._pluginsStarted;
+    }
+    async _runPluginStart() {
+        const reserved = this._hostTools.map((tool) => tool.name);
+        if (this._exec) {
+            reserved.push(PluginRegistry.EXEC_TOOL);
+        }
+        const started = await this._plugins.start([...reserved, Agent.TRANSFER_TOOL_NAME, Agent.DELEGATE_TOOL_NAME], {
+            fetch: (signal, mayConnect) => createGuardedFetch({ signal, mayConnect }),
+            publish: (swapped) => this._publishPlugins(swapped)
+        });
+        this._publishPlugins(started);
+    }
+    _publishPlugins({ tools, capabilities, hooks, skills, exec }) {
+        const pre = hooks.filter((hook) => hook.phase === 'preToolCall');
+        const rest = hooks.filter((hook) => hook.phase !== 'preToolCall');
+        this._tools = Object.freeze([...this._hostTools, ...this._execTools(exec), ...tools]);
+        this._capabilities = Object.freeze(capabilities);
+        this._hooks = Object.freeze([...pre, ...this._hostHooks, ...rest]);
+        this._skills.publish(skills);
+    }
+    _execTools(exec) {
+        if (!this._exec) {
+            return [];
+        }
+        return [
+            createExecTool({
+                ...this._exec,
+                ...exec,
+                deniedRoots: this._deniedRoots,
+                skillsDir: this._skillsDir,
+                skillSettings: (skill, agentId) => this._skills.skillSettings(skill, agentId)
+            })
+        ];
+    }
+    async addPlugin(plugin) {
+        await this._dynamicPlugins();
+        await this._plugins.add(plugin);
+    }
+    async removePlugin(name) {
+        await this._dynamicPlugins();
+        await this._plugins.remove(name);
+    }
+    async reloadPlugin(name, plugin) {
+        await this._dynamicPlugins();
+        await this._plugins.reload(name, plugin);
+    }
+    async _dynamicPlugins() {
+        if (this._pluginMode !== 'dynamic') {
+            throw new Error("plugins are frozen: construct the harness with pluginMode 'dynamic'");
+        }
+        if (!this.opened)
+            await this.ready();
+        this._lifecycle.assertNotClosing();
+    }
+    _modelHost(transcriptionDevice) {
+        return {
+            transcriptionDevice,
+            sdk: () => this._sdk.load(),
+            track: (load, sdk) => this._loads.track(load, sdk),
+            makeRoom: (signal, busyMessage) => this._residency.makeRoomForPlugin(signal, busyMessage),
+            completionModel: (model, signal) => this._residency.borrow(model, signal),
+            emit: (state) => this.emit('model', state),
+            progressState,
+            statusChanged: () => this._residency.statusChanged(),
+            registerPool: (spec) => this._registerPool(spec),
+            enterWork: () => {
+                if (this._lifecycle.suspended) {
+                    throw new Error('harness is suspended');
+                }
+                return this._lifecycle.enterWork();
+            }
+        };
+    }
+    _registerPool(spec) {
+        const entry = { spec, pool: this._createVoicePool(spec) };
+        this._voicePools.set(spec.addon, entry);
+        return {
+            open: (model) => {
+                const pool = entry.pool;
+                const handle = pool.open(model, model);
+                return {
+                    load: async () => {
+                        const { modelId } = await handle.load();
+                        this._lifecycle.assertNotClosing();
+                        return { modelId };
+                    },
+                    peek: () => handle.peek(),
+                    release: () => releaseModel(pool, model)
+                };
+            },
+            resident: (model) => isResident(entry.pool, model),
+            evictIdle: (wanted) => evictIdleWhere(entry.pool, wanted)
+        };
+    }
+    _createVoicePool({ sdk, label, openclCache, ...spec }) {
+        return createVoicePool(() => sdk(), (state) => this._residency.notify(label ? { ...state, model: label } : state), {
+            ...spec,
+            openclCacheDir: openclCache ? openclCacheDir : undefined,
+            loads: this._loads,
+            onUnloadFailure: (modelId, error) => this._lifecycle.recordModelUnloadFailure(modelId, error)
+        });
+    }
+    _embedHost() {
+        return {
+            embed: (request) => this.embed(request),
+            sdk: () => this._sdk.loadEmbed()
+        };
+    }
+    async _loadAddons() {
+        await Promise.all([
+            PluginRegistry.loadAddons('the harness', this._sdk.addons),
+            ...this._tools.map((tool) => PluginRegistry.loadAddons(`tool '${tool.name}'`, tool.addons))
+        ]);
+    }
+    _teardownPlugins() {
+        return this._plugins.teardown((plugin, error) => hlog('plugin teardown failed', { plugin, err: errorMessage(error) }));
+    }
     get suspended() {
         return this._lifecycle.suspended;
     }
     get skillNames() {
-        return this._supportedSkills.map((skill) => skill.name);
+        return this._skills.names;
     }
     setCredentials(entries) {
-        const previous = this._credentials;
-        const next = new Map();
-        for (const { key, token, expiresAt, agentId, skill } of entries) {
-            if (!token)
-                continue;
-            const storeKey = scopeKey({ agentId, skill, key });
-            const record = typeof expiresAt === 'number' && expiresAt > 0 ? { token, expiresAt } : { token };
-            const current = previous.get(storeKey);
-            if (!current || current.token !== record.token || current.expiresAt !== record.expiresAt) {
-                resetCredentialHealthAfterSnapshot(key, agentId, skill);
-            }
-            next.set(storeKey, record);
-        }
-        this._credentials = next;
+        this._skills.setCredentials(entries);
     }
     setSkillSettings(entries) {
-        const next = new Map();
-        for (const { skill, key, value, agentId } of entries) {
-            if (!skill || !key || typeof value !== 'string')
-                continue;
-            const scope = settingsScopeKey(skill, agentId);
-            const bucket = next.get(scope) ?? {};
-            bucket[key] = value;
-            next.set(scope, bucket);
-        }
-        this._settings = next;
+        this._skills.setSkillSettings(entries);
     }
     skillSettings(skill, agentId) {
-        return {
-            ...this._settings.get(settingsScopeKey(skill, null)),
-            ...(agentId ? this._settings.get(settingsScopeKey(skill, agentId)) : undefined)
-        };
+        return this._skills.skillSettings(skill, agentId);
     }
-    async _baseSkillsDir() {
-        return this._skillsDir ?? (await ensureBundledSkillsDir());
+    listManagedSkills() {
+        return this._skills.listManagedSkills();
     }
-    async listManagedSkills() {
-        return listManagedSkills(await this._baseSkillsDir(), await ensureSkillsOverlayDir());
+    readSkillFile(name) {
+        return this._skills.readSkillFile(name);
     }
-    async readSkillFile(name) {
-        return readSkillFile(await this._baseSkillsDir(), await ensureSkillsOverlayDir(), name);
+    writeSkillFile(name, content) {
+        return this._skills.writeSkillFile(name, content);
     }
-    async writeSkillFile(name, content) {
-        const overlay = await ensureSkillsOverlayDir();
-        if (!overlay) {
-            throw new Error('no writable skills overlay is configured');
-        }
-        await writeSkillFile(overlay, name, content);
-        await this._reloadSkills();
-        return { ok: true };
-    }
-    async copyBaseForEdit(name) {
-        const overlay = await ensureSkillsOverlayDir();
-        if (!overlay) {
-            throw new Error('no writable skills overlay is configured');
-        }
-        const result = await copyBaseForEdit(await this._baseSkillsDir(), overlay, name);
-        if (result.copied) {
-            await this._reloadSkills();
-        }
-        return result;
+    copyBaseForEdit(name) {
+        return this._skills.copyBaseForEdit(name);
     }
-    async deleteOverlaySkill(name) {
-        const overlay = await ensureSkillsOverlayDir();
-        if (!overlay) {
-            throw new Error('no writable skills overlay is configured');
-        }
-        const result = await deleteOverlaySkill(overlay, name);
-        if (result.removed) {
-            await this._reloadSkills();
-        }
-        return result;
+    deleteOverlaySkill(name) {
+        return this._skills.deleteOverlaySkill(name);
     }
     resolveCredential(key, ctx) {
-        if (this._credentialStore) {
-            return this._credentialStore(key, ctx);
-        }
-        const agentId = ctx?.agentId ?? null;
-        const deviceShared = isDeviceSharedCredentialKey(key);
-        for (const skill of ctx?.skills ?? []) {
-            const owned = this._credentials.get(scopeKey({ agentId, skill, key })) ??
-                (agentId && deviceShared ? this._credentials.get(scopeKey({ skill, key })) : undefined);
-            if (owned) {
-                return owned;
-            }
-        }
-        if (agentId) {
-            const scoped = this._credentials.get(scopeKey({ agentId, key }));
-            if (scoped) {
-                return scoped;
-            }
-        }
-        if (!agentId || deviceShared) {
-            return this._credentials.get(scopeKey({ key })) ?? null;
-        }
-        return null;
-    }
-    async _completionSkills(agentId, model) {
-        const statuses = new Map((await this.skills(agentId, model, { skipCredentialProbe: true, skipBinProbe: true })).map((entry) => [entry.name, entry.status]));
-        return availableSkills(this._supportedSkills, new Set(this._tools.map((tool) => tool.name)), modelNameToCapabilityProfile(model)).map((entry) => ({
-            ...entry,
-            status: statuses.get(entry.name)
-        }));
+        return this._skills.resolveCredential(key, ctx);
     }
     async skills(agentId, modelName, options) {
         if (!this.opened)
             await this.ready();
-        this._assertNotClosing();
-        const platform = this._platform ?? detectPlatform();
-        const refresh = options?.refresh === true;
-        return resolveSkillStatuses(this._allSkills, {
-            installedTools: new Set(this._tools.map((tool) => tool.name)),
-            credentialStore: (key, ctx) => this.resolveCredential(key, ctx),
-            settingsStore: (skill, agentId) => this.skillSettings(skill, agentId),
-            platform,
-            agentId,
-            binVersions: options?.skipBinProbe === true
-                ? (this._binVersionCache?.bySkill ?? new Map())
-                : await this._probeBinVersions(platform, refresh),
-            refresh,
-            skipCredentialProbe: options?.skipCredentialProbe === true,
-            activeProfile: modelName ? modelNameToCapabilityProfile(modelName) : undefined
-        });
-    }
-    async _reloadSkills() {
-        const skillsDir = this._skillsDir ?? (await ensureBundledSkillsDir());
-        this._allSkills = await loadSkillCatalog(skillsDir, { platform: null });
-        const platform = this._platform ?? detectPlatform();
-        const supported = this._allSkills.filter((skill) => skillSupportsPlatform(skill, platform));
-        this._supportedSkills = availableSkills(supported, new Set(this._tools.map((t) => t.name)));
-    }
-    async _startOverlayWatch() {
-        if (this._overlayWatcher)
-            return;
-        try {
-            const overlay = await ensureSkillsOverlayDir();
-            if (!overlay) {
-                return;
-            }
-            this._overlayWatcher = watchSkillsOverlay(overlay, () => {
-                this._reloadSkills().catch((err) => hlog('overlay reload failed', { err: errorMessage(err) }));
-            });
-        }
-        catch (err) {
-            hlog('overlay watch unavailable', { err: errorMessage(err) });
-        }
+        this._lifecycle.assertNotClosing();
+        return this._skills.statuses(agentId, modelName, options);
     }
     async tools() {
+        if (!this.opened)
+            await this.ready();
         return toolCatalog(this._tools);
     }
-    _binVersionCache = null;
-    _binVersionInflight = null;
-    async _probeBinVersions(platform, refresh = false) {
-        const now = Date.now();
-        if (!refresh && this._binVersionCache && this._binVersionCache.expiresAt > now) {
-            return this._binVersionCache.bySkill;
-        }
-        if (this._binVersionInflight) {
-            return this._binVersionInflight;
-        }
-        this._binVersionInflight = this._runBinVersionProbes(platform)
-            .then((bySkill) => {
-            this._binVersionCache = {
-                expiresAt: Date.now() + BIN_VERSION_PROBE_TTL_MS,
-                bySkill
-            };
-            return bySkill;
-        })
-            .finally(() => {
-            this._binVersionInflight = null;
-        });
-        return this._binVersionInflight;
-    }
-    async _runBinVersionProbes(platform) {
-        if (process.env.QVAC_NO_SKILL_BIN_PROBE) {
-            return new Map();
-        }
-        const installed = new Set(this._tools.map((tool) => tool.name));
-        const candidates = versionProbeSkills(this._allSkills, installed, platform);
-        if (candidates.length === 0) {
-            return new Map();
-        }
-        let runtime;
-        try {
-            runtime = await bareRuntime();
-        }
-        catch {
-            return new Map();
-        }
-        const run = async (command) => {
-            try {
-                const result = await runCommand(command, { ...runtime, timeoutMs: 5_000 });
-                return result.exitCode === 0 ? result.stdout : null;
-            }
-            catch {
-                return null;
-            }
-        };
-        const bySkill = new Map();
-        for (const skill of candidates) {
-            const states = await probeBinVersions(skill.requires, { platform, run });
-            if (states.size > 0) {
-                bySkill.set(skill.name, states);
-            }
-        }
-        return bySkill;
-    }
     get toolNames() {
         return this._tools.map((tool) => tool.name);
     }
@@ -554,550 +416,65 @@ export class Harness extends ReadyResource {
         this._customProjection = customProjectionMap();
     }
     setModelIdleTimeout(ms) {
-        this._idle.configure(ms);
+        this._residency.setIdleTimeout(ms);
     }
     previewModelSource(context) {
-        return previewModelSource(context, { assessFit: (query) => this._assessFit(query) });
-    }
-    async _assessFit({ sha256Checksum, name, contextTokens }) {
-        const sdk = await this._sdk.load();
-        const result = await sdk.assessModelFit({
-            models: [{ model: { sha256Checksum, name }, workload: { kind: 'llm', contextTokens } }]
-        });
-        const model = result.models[0];
-        return {
-            fit: model?.verdict ?? result.verdict,
-            fitReasons: [...(model?.reasons ?? result.reasons)]
-        };
+        return previewModelSource(context, { assessFit: (query) => this._residency.fit.assess(query) });
     }
     async describe() {
         if (!this.opened)
             await this.ready();
         return {
             toolNames: this.toolNames,
-            skills: this._supportedSkills.map((skill) => skill.name),
+            skills: this._skills.names,
             supportsImages: this.supportsImages,
             supportsKvCacheDeletion: true
         };
     }
     diagnostics() {
         return {
-            models: this.opened ? this._loadedModels() : [],
+            models: this.opened ? this._residency.loaded() : [],
             suspended: this.suspended,
             sdkLoaded: this._sdk.peek() !== null,
             toolNames: this.toolNames,
-            skills: this._supportedSkills.map((skill) => skill.name),
-            device: this._llmDevice
-        };
-    }
-    _loadedModels() {
-        return this._pools().flatMap((pool) => loadedModels(pool));
-    }
-    _loadingModels() {
-        return new Set(this._pools().flatMap((pool) => loadingModels(pool)));
-    }
-    _settledModels() {
-        return new Set(this._pools().flatMap((pool) => settledModels(pool)));
-    }
-    _pools() {
-        return [
-            this._models,
-            this._embedModels,
-            ...this._retiredEmbedModels,
-            this._ttsModels,
-            this._transcriptionModels
-        ];
-    }
-    _loadPluginSdk(current, store, importPlugin) {
-        let pending = current();
-        if (!pending) {
-            pending = (async () => {
-                const sdk = await this._sdk.load();
-                const [plugin, { registerPlugin }] = await Promise.all([
-                    importPlugin(),
-                    import('@qvac/sdk/plugins')
-                ]);
-                try {
-                    registerPlugin(plugin);
-                }
-                catch { }
-                return sdk;
-            })().catch((err) => {
-                store(null);
-                throw err;
-            });
-            store(pending);
-        }
-        return pending;
-    }
-    _loadDiffusionSdk() {
-        return this._loadPluginSdk(() => this._diffusionSdk, (sdk) => {
-            this._diffusionSdk = sdk;
-        }, () => import('@qvac/sdk/sdcpp-generation/plugin').then((m) => m.diffusionPlugin));
-    }
-    async _slmTranslate(model, { text, from, to }, signal) {
-        const loadOpts = resolveLoadOptions({}, this._deviceConfig());
-        const key = modelKey(model, loadOpts);
-        const pool = this._models;
-        if (!isResident(pool, key)) {
-            await this._makeRoomForCompletion(model, { ctxSize: loadOpts.ctxSize, signal });
-        }
-        try {
-            const { modelId } = await raceAbort(pool.open(key, model, loadOpts).load(), signal);
-            const sdk = await this._sdk.load();
-            const answer = await raceAbort(sdk.translate({ modelId, text, from, to, stream: false, modelType: 'llm' }).text, signal);
-            return cleanAnswer(answer, text);
-        }
-        finally {
-            releaseModel(pool, key);
-        }
-    }
-    _loadTranslationSdk() {
-        return this._loadPluginSdk(() => this._translationSdk, (sdk) => {
-            this._translationSdk = sdk;
-        }, () => import('@qvac/sdk/nmtcpp-translation/plugin').then((m) => m.nmtPlugin));
-    }
-    _loadMusicSdk() {
-        return this._loadPluginSdk(() => this._musicSdk, (sdk) => {
-            this._musicSdk = sdk;
-        }, () => import('@qvac/sdk/audiogen-ggml/plugin').then((m) => m.audioGenPlugin));
-    }
-    _deviceConfig() {
-        return {
-            device: this._llmDevice,
-            gpuLayers: this._llmGpuLayers,
-            contextSize: this._contextSize,
-            kvCacheK: this._kvCacheK,
-            kvCacheV: this._kvCacheV,
-            mainGpu: resolveMainGpu,
-            openclCacheDir
-        };
-    }
-    _createPool() {
-        const loadSdk = () => this._loadModelLifecycleSdk();
-        return createModelPool(loadSdk, (state) => this._notifyModel(state), {
-            deviceConfig: this._deviceConfig(),
-            loads: this._loads,
-            onUnloadFailure: (modelId, error) => this._recordModelUnloadFailure(modelId, error)
-        });
-    }
-    _loadModelLifecycleSdk() {
-        return this._sdk.load();
-    }
-    _createEmbedPool() {
-        const loadSdk = () => this._sdk.loadEmbed();
-        return createEmbedPool(loadSdk, (state) => this._notifyModel(state), {
-            faults: this._embedFaults,
-            batchSize: this._embedBatchSize,
-            openclCacheDir,
-            loads: this._loads,
-            onUnloadFailure: (modelId, error) => this._recordModelUnloadFailure(modelId, error)
-        });
-    }
-    _createTtsPool() {
-        const loadSdk = () => this._sdk.loadVoice();
-        return createVoicePool(loadSdk, (state) => this._notifyModel(state), {
-            modelType: 'tts-ggml',
-            addon: 'tts',
-            modelConfig: TTS_MODEL_CONFIG,
-            loads: this._loads,
-            onUnloadFailure: (modelId, error) => this._recordModelUnloadFailure(modelId, error)
-        });
-    }
-    _createTranscriptionPool() {
-        const loadSdk = () => this._sdk.loadVoice();
-        return createVoicePool(loadSdk, (state) => this._notifyModel({ ...state, model: TRANSCRIPTION_MODEL_LABEL }), {
-            modelType: 'parakeet-transcription',
-            addon: 'parakeet',
-            modelConfig: { useGPU: this._transcriptionDevice !== 'cpu' },
-            openclCacheDir,
-            loads: this._loads,
-            onUnloadFailure: (modelId, error) => this._recordModelUnloadFailure(modelId, error)
-        });
-    }
-    _recordModelUnloadFailure(modelId, error) {
-        this._failedModelUnloads.add(modelId);
-        this._poolUnloadFailed = true;
-        this._runtimeUnloadFailed = true;
-        hlog('model unload failed', { modelId, err: errorMessage(error) });
-    }
-    _notifyModel(state) {
-        if (state.status === 'ready' || state.status === 'unloaded' || state.status === 'error') {
-            invalidateModelStatusCache(this._modelStatus);
-        }
-        if (state.status === 'unloaded') {
-            for (const key of this._pinned) {
-                if (!isResident(this._models, key)) {
-                    this._pinned.delete(key);
-                }
-            }
-        }
-        this.emit('model', {
-            ...state,
-            catalogChanged: state.catalogChanged === true,
-            loaded: this._loadedModels()
-        });
-    }
-    async _collectRetiredEmbedPool(pool) {
-        if (!this._retiredEmbedModels.has(pool) || pool.idle !== pool.size)
-            return;
-        try {
-            await pool.destroy();
-        }
-        catch (error) {
-            if (!(error instanceof ModelUnloadError)) {
-                this._poolCleanupFailed = true;
-                this._poolUnloadFailed = true;
-                this._runtimeUnloadFailed = true;
-            }
-            throw error;
-        }
-        this._retiredEmbedModels.delete(pool);
-    }
-    async _releaseEmbedResource(pool, key) {
-        releaseModel(pool, key);
-        const faulted = this._faultedEmbedKeys.get(pool);
-        if (faulted?.has(key)) {
-            await evictIdle(pool);
-            if (!isResident(pool, key)) {
-                faulted.delete(key);
-            }
-        }
-        await this._collectRetiredEmbedPool(pool);
-    }
-    async _releaseEmbedResourceBeforeWork(releasing, releaseWork) {
-        try {
-            await releasing;
-        }
-        finally {
-            releaseWork();
-        }
-    }
-    _markEmbedFault({ pool, key, faults, generation }) {
-        faults.recordFault(generation);
-        let faulted = this._faultedEmbedKeys.get(pool);
-        if (!faulted) {
-            faulted = new Set();
-            this._faultedEmbedKeys.set(pool, faulted);
-        }
-        faulted.add(key);
-    }
-    _releaseEmbedResourceAfter(settled, fault) {
-        return settled
-            .then(() => this._releaseEmbedResource(fault.pool, fault.key), (error) => {
-            if (isSdkGpuDeviceLostError(error)) {
-                this._markEmbedFault(fault);
-            }
-            return this._releaseEmbedResource(fault.pool, fault.key);
-        })
-            .catch(noop);
-    }
-    async _destroyEmbedPools() {
-        const pools = [this._embedModels, ...this._retiredEmbedModels].filter((pool) => Boolean(pool));
-        const outcomes = await Promise.allSettled(pools.map(async (pool) => {
-            await pool.destroy();
-            this._retiredEmbedModels.delete(pool);
-        }));
-        const generic = outcomes.find((outcome) => outcome.status === 'rejected' && !(outcome.reason instanceof ModelUnloadError));
-        if (generic?.status === 'rejected') {
-            throw generic.reason;
-        }
-        const failed = outcomes.find((outcome) => outcome.status === 'rejected');
-        if (failed?.status === 'rejected') {
-            throw failed.reason;
-        }
-    }
-    _enqueueEmbedControl(run) {
-        const next = this._embedControl.then(run, run);
-        this._embedControl = next.catch(noop);
-        return next;
-    }
-    async _runLifecycle(type, { open = true } = {}) {
-        if (!this.opened) {
-            if (open) {
-                await this.ready();
-            }
-        }
-        if (this._closeRequested || this.closing) {
-            return;
-        }
-        await this._lifecycle.send(type);
-    }
-    _abortCompletions() {
-        for (const run of this._completionRuns) {
-            run.abort();
-        }
-    }
-    _assertNotClosing() {
-        if (this._closeRequested || this.closing || this.closed) {
-            throw new Error('harness is closing');
-        }
-    }
-    _enterWork() {
-        this._assertNotClosing();
-        if (this._runtimeDraining) {
-            throw new Error('harness is suspended');
-        }
-        if (this._runtimeUnloadFailed) {
-            throw new Error('Runtime unload failed; close the harness before loading models again');
-        }
-        this._activeWork++;
-        let released = false;
-        return () => {
-            if (released)
-                return;
-            released = true;
-            if (--this._activeWork !== 0) {
-                return;
-            }
-            for (const resolve of this._workDrainWaiters) {
-                resolve();
-            }
-            this._workDrainWaiters.clear();
+            skills: this._skills.names,
+            device: this._residency.deviceConfig().device
         };
     }
-    _waitForWorkDrain() {
-        if (!this._activeWork) {
-            return Promise.resolve();
-        }
-        return new Promise((resolve) => this._workDrainWaiters.add(resolve));
-    }
-    _effectsSettled() {
-        return !this._detachedRuns.size && ![...this._completionRuns].some((run) => run.started);
-    }
-    _notifyEffectDrain() {
-        if (!this._effectsSettled())
-            return;
-        for (const resolve of this._effectDrainWaiters) {
-            resolve();
-        }
-        this._effectDrainWaiters.clear();
-    }
-    _waitForEffectDrain() {
-        if (this._effectsSettled()) {
-            return Promise.resolve();
-        }
-        return new Promise((resolve) => this._effectDrainWaiters.add(resolve));
-    }
-    _trackDetachedRun(pending, runId) {
-        const tracked = pending.catch((error) => {
-            hlog('detached completion effect failed', { runId, err: errorMessage(error) });
-        });
-        this._detachedRuns.add(tracked);
-        void tracked
-            .finally(() => {
-            this._detachedRuns.delete(tracked);
-            this._notifyEffectDrain();
-        })
-            .catch(noop);
-    }
-    async _closeCompletions(runs = this._completionRuns) {
-        const closed = await Promise.allSettled([...runs].map((run) => run.close()));
-        for (const outcome of closed) {
-            if (outcome.status === 'rejected') {
-                hlog('completion close failed', {
-                    err: errorMessage(outcome.reason)
-                });
-            }
-        }
-    }
     getEmbeddingDevice() {
-        return this._embedFaults.device;
+        return this._embeddings.device;
     }
     setEmbeddingDevice(device) {
-        assertEmbedDevice(device);
-        return this._enqueueEmbedControl(() => this._setEmbeddingDevice(device));
-    }
-    async _setEmbeddingDevice(device) {
-        if (!this.opened)
-            await this.ready();
-        if (this.suspended) {
-            this._assertNotClosing();
-            if (this._embedFaults.device === device) {
-                return;
-            }
-            this._embedFaults = createGpuFaultState({ device, gpuLayers: this._embedGpuLayers });
-            return;
-        }
-        const releaseWork = this._enterWork();
-        try {
-            if (this._embedFaults.device === device) {
-                return;
-            }
-            this._embedFaults = createGpuFaultState({ device, gpuLayers: this._embedGpuLayers });
-            if (this.suspended) {
-                return;
-            }
-            const retired = this._embedModels;
-            this._retiredEmbedModels.add(retired);
-            this._embedModels = this._createEmbedPool();
-            await this._collectRetiredEmbedPool(retired);
-        }
-        finally {
-            releaseWork();
-        }
+        return this._embeddings.setDevice(device);
     }
     async presuspend() {
-        await this._runLifecycle('PRESUSPEND', { open: false });
+        await this._lifecycle.send('PRESUSPEND', { open: false });
     }
     async suspend() {
-        const result = await raceDrain(this._runLifecycle('SUSPEND'), SUSPEND_SETTLE_MS);
+        const result = await raceDrain(this._lifecycle.send('SUSPEND'), SUSPEND_SETTLE_MS);
         if (didDrainTimeOut(result)) {
             throw new Error('Harness suspend is still waiting for active work to settle');
         }
     }
-    async _suspendRuntimes() {
-        this._runtimeDraining = true;
-        hlog('suspending', { models: loadedModels(this._models).map((entry) => entry.model) });
-        this._abortCompletions();
-        this._loads.drain();
-        await this._closeCompletions([...this._completionRuns].filter((run) => run.started));
-        await this._waitForEffectDrain();
-        const pending = this._sdk.peek();
-        if (pending) {
-            const sdk = await pending.catch(noop);
-            if (sdk) {
-                this._loads.drain(sdk);
-            }
-        }
-        await this._waitForWorkDrain();
-        if (!(await this._releaseRuntimes())) {
-            throw new Error('Runtime unload failed; close the harness before loading models again');
-        }
-        invalidateModelStatusCache(this._modelStatus);
-        await this._sdkLifecycle('suspend');
-        hlog('suspended');
-    }
-    async _sdkLifecycle(op) {
-        const sdk = await this._sdk.peek()?.catch(noop);
-        if (!sdk) {
-            return;
-        }
-        try {
-            await sdk[op]();
-        }
-        catch (err) {
-            hlog(`sdk ${op} failed`, { err: errorMessage(err) });
-            if (op === 'suspend') {
-                throw err;
-            }
-            await sdk.resume().catch((retryErr) => {
-                hlog('sdk resume retry failed', {
-                    err: errorMessage(retryErr)
-                });
-                throw retryErr;
-            });
-        }
-    }
-    async _releaseRuntimes() {
-        const released = await Promise.allSettled([
-            this._models?.destroy(),
-            this._destroyEmbedPools(),
-            this._ttsModels?.destroy(),
-            this._transcriptionModels?.destroy(),
-            this._imageRuntime?.unload(),
-            this._musicRuntime?.unload(),
-            this._translationRuntime.unload()
-        ]);
-        for (const [index, outcome] of released.entries()) {
-            if (outcome.status !== 'rejected')
-                continue;
-            if (index < 4 && !(outcome.reason instanceof ModelUnloadError)) {
-                this._poolCleanupFailed = true;
-            }
-            const err = outcome.reason;
-            hlog('unload failed', { err: errorMessage(err) });
-        }
-        const sdk = await this._sdk.peek()?.catch(noop);
-        if (sdk) {
-            for (const modelId of this._failedModelUnloads) {
-                try {
-                    await sdk.unloadModel({ modelId });
-                    this._failedModelUnloads.delete(modelId);
-                    invalidateModelStatusCache(this._modelStatus);
-                }
-                catch (error) {
-                    hlog('model unload retry failed', {
-                        modelId,
-                        err: errorMessage(error)
-                    });
-                }
-            }
-        }
-        this._poolUnloadFailed = this._poolCleanupFailed || this._failedModelUnloads.size > 0;
-        this._runtimeUnloadFailed =
-            this._poolUnloadFailed || released.slice(4).some((outcome) => outcome.status === 'rejected');
-        return !this._runtimeUnloadFailed;
-    }
-    async _unloadIdleModels() {
-        if (!this.opened || this.closing || this.suspended || this._runtimeDraining) {
-            return;
-        }
-        hlog('idle unload', { models: this._loadedModels().map((entry) => entry.model) });
-        const released = await Promise.allSettled([
-            evictIdle(this._models),
-            evictIdle(this._embedModels),
-            ...[...this._retiredEmbedModels].map((pool) => this._collectRetiredEmbedPool(pool)),
-            evictIdle(this._ttsModels),
-            evictIdle(this._transcriptionModels),
-            this._imageRuntime?.unloadIdle(),
-            this._musicRuntime?.unloadIdle(),
-            this._translationRuntime.unload()
-        ]);
-        for (const outcome of released) {
-            if (outcome.status !== 'rejected')
-                continue;
-            hlog('idle unload failed', { err: errorMessage(outcome.reason) });
-        }
-        invalidateModelStatusCache(this._modelStatus);
-    }
     async resume() {
-        await this._runLifecycle('RESUME');
-    }
-    async _resumeRuntimes() {
-        this._assertNotClosing();
-        if (this._runtimeUnloadFailed) {
-            throw new Error('Runtime unload failed; close the harness before loading models again');
-        }
-        hlog('resuming', { pools: 'recreated' });
-        this._loads.undrain();
-        this._models = this._createPool();
-        this._embedModels = this._createEmbedPool();
-        this._ttsModels = this._createTtsPool();
-        this._transcriptionModels = this._createTranscriptionPool();
-        try {
-            await this._sdkLifecycle('resume');
-            this._runtimeDraining = false;
-        }
-        catch (error) {
-            const sdk = await this._sdk.peek()?.catch(noop);
-            if (sdk) {
-                this._loads.drain(sdk);
-            }
-            await this._releaseRuntimes();
-            throw error;
-        }
+        await this._lifecycle.send('RESUME');
     }
     async wakeup() {
-        await this._runLifecycle('WAKEUP');
+        await this._lifecycle.send('WAKEUP');
     }
     ready() {
-        if (this._closeRequested || this.closing || this.closed) {
+        if (this._lifecycle.closeRequested || this.closing || this.closed) {
             return Promise.reject(new Error('harness is closing'));
         }
         return super.ready();
     }
     async _close() {
         hlog('closing');
-        this._idle.close();
-        this._lifecycle.cancelPending();
-        this._abortCompletions();
-        this._loads.drain();
-        await this._lifecycle.settled();
-        await this._finishClose();
+        this._residency.closeIdle();
+        await this._lifecycle.close();
     }
     close() {
-        this._closeRequested = true;
+        this._lifecycle.requestClose();
         if (this._closeRetryNeeded) {
             this.closing = null;
             this._closeRetryNeeded = false;
@@ -1120,80 +497,33 @@ export class Harness extends ReadyResource {
         if (this.closing)
             return this.closing;
         const opening = this.opening;
+        const pluginsClosing = this._teardownPlugins();
         const pending = (async () => {
             await opening?.catch(noop);
-            this._abortCompletions();
+            await pluginsClosing;
+            this._lifecycle.abortCompletions();
             this._loads.drain();
-            await this._finishClose();
+            await this._lifecycle.finishClose();
             this.closed = true;
             this.emit('close');
         })();
         this.closing = pending;
         return pending;
     }
-    async _finishClose() {
-        let completed = false;
-        try {
-            const pending = this._sdk.peek();
-            if (pending) {
-                const sdk = await pending.catch(noop);
-                if (sdk) {
-                    this._loads.drain(sdk);
-                }
-            }
-            await this._closeCompletions();
-            await this._waitForEffectDrain();
-            await this._waitForWorkDrain();
-            this._overlayWatcher?.stop();
-            this._overlayWatcher = null;
-            if (!this._runtimesReleased) {
-                let [released] = await Promise.all([this._releaseRuntimes(), closePythonWorker()]);
-                if (!released && !this._poolUnloadFailed) {
-                    released = await this._releaseRuntimes();
-                }
-                this._runtimesReleased = released;
-            }
-            let sdkCloseFailed = false;
-            let sdkCloseError;
-            const sdk = !this._sdkClosed && !this._runtimeUnloadFailed ? await this._sdk.peek()?.catch(noop) : null;
-            if (sdk) {
-                try {
-                    await sdk.close();
-                    this._sdkClosed = true;
-                }
-                catch (error) {
-                    sdkCloseFailed = true;
-                    sdkCloseError = error;
-                    hlog('sdk close failed', { err: errorMessage(error) });
-                }
-            }
-            if (sdkCloseFailed) {
-                throw sdkCloseError;
-            }
-            if (this._runtimeUnloadFailed) {
-                throw new Error('Runtime unload failed; model cleanup could not be confirmed');
-            }
-            completed = true;
-        }
-        finally {
-            if (completed) {
-                this._lifecycle.stop();
-            }
-        }
-    }
     download(args) {
-        this._assertNotClosing();
+        this._lifecycle.assertNotClosing();
         let releaseWork = null;
         const projection = (args.addon ?? 'llm') === 'llm' ? this._projectionFor(args.model) : undefined;
         const multiFile = diffusionDownloadMetadata(args.model, args.addon) ??
-            audioGenDownloadMetadata(args.model, args.addon);
+            audioGenDownloadMetadata(args.model, args.addon) ??
+            categoryDownloadMetadata(args.model, args.addon);
         return download(async () => {
             if (!this.opened)
                 await this.ready();
-            releaseWork = this._enterWork();
+            releaseWork = this._lifecycle.enterWork();
             try {
                 const sdk = await this._sdk.load();
-                this._assertNotClosing();
+                this._lifecycle.assertNotClosing();
                 return sdk;
             }
             catch (error) {
@@ -1206,264 +536,100 @@ export class Harness extends ReadyResource {
             projection,
             companions: multiFile?.companions,
             assetSizes: multiFile?.assetSizes
-        }, () => invalidateModelStatusCache(this._modelStatus), () => {
+        }, () => this._residency.invalidateStatus(), () => {
             releaseWork?.();
             releaseWork = null;
         });
     }
     embed(context) {
-        return this._busy(() => this._embed(context));
+        return this._residency.busy(() => this._embeddings.embed(context));
     }
-    async _embed({ model, texts, signal }) {
+    async _speechService() {
         if (!this.opened)
             await this.ready();
-        this._assertNotClosing();
-        if (this.suspended) {
-            throw new Error('harness is suspended');
-        }
-        if (texts.length === 0) {
-            return [];
-        }
-        const pool = this._embedModels;
-        const faults = this._embedFaults;
-        const generation = faults.generation;
-        const key = faults.key(residentSrc(model, 'embeddings'));
-        const releaseWork = this._enterWork();
-        let handle;
-        try {
-            handle = pool.open(key, model);
-        }
-        catch (error) {
-            releaseWork();
-            throw error;
-        }
-        let loaded = null;
-        let job = null;
-        let releaseAfter = null;
-        let drainWorkAfter = null;
-        try {
-            loaded = await raceAbort(handle.load(), signal);
-            const sdk = await this._sdk.loadEmbed();
-            this._assertNotClosing();
-            job = this._embedLane(sdk, { modelId: loaded.modelId, texts });
-            const vectors = await raceAbort(job, signal);
-            faults.reset();
-            return vectors;
-        }
-        catch (err) {
-            if (err instanceof AbortedError) {
-                if (job || this._retiredEmbedModels.has(pool)) {
-                    releaseAfter = job ?? handle.peek();
-                }
-                else {
-                    drainWorkAfter = handle.peek();
-                }
-            }
-            if (isSdkGpuDeviceLostError(err)) {
-                this._markEmbedFault({ pool, key, faults, generation });
-            }
-            throw err;
-        }
-        finally {
-            if (releaseAfter) {
-                void this._releaseEmbedResourceAfter(releaseAfter, {
-                    pool,
-                    key,
-                    faults,
-                    generation
-                }).finally(releaseWork);
-            }
-            else {
-                const releasing = this._releaseEmbedResource(pool, key);
-                if (drainWorkAfter) {
-                    void Promise.allSettled([releasing, drainWorkAfter]).then(releaseWork);
-                }
-                else {
-                    await this._releaseEmbedResourceBeforeWork(releasing, releaseWork);
-                }
-            }
+        if (!this._plugins.ctx.speech) {
+            throw new Error(SPEECH_PLUGIN_MISSING);
         }
+        return this._plugins.ctx.speech;
     }
-    async _defaultVoiceSrc(category) {
-        if (category !== 'tts') {
-            return defaultVoiceModel(category);
-        }
-        try {
-            const { capabilityProfile } = await this.capability();
-            return defaultTtsFor(capabilityProfile).asset.src;
-        }
-        catch {
-            return defaultVoiceModel('tts');
-        }
-    }
-    async _voiceJob(pool, { category, model, signal }, run) {
+    async _knowledgeService() {
         if (!this.opened)
             await this.ready();
-        if (this.suspended)
-            throw new Error('harness is suspended');
-        const addon = category === 'tts' ? 'tts' : 'parakeet';
-        const name = residentSrc(model || (await this._defaultVoiceSrc(category)), addon);
-        this._assertNotClosing();
-        const releaseWork = this._enterWork();
-        let handle;
-        try {
-            handle = pool.open(name, name);
-        }
-        catch (error) {
-            releaseWork();
-            throw error;
-        }
-        let job = null;
-        let releaseAfter = null;
-        let sdk = null;
-        let modelId = null;
-        try {
-            modelId = (await raceAbort(handle.load(), signal)).modelId;
-            sdk = (await this._sdk.loadVoice());
-            this._assertNotClosing();
-            const boundSdk = sdk;
-            const boundId = modelId;
-            job = this._voiceLane(() => run(boundSdk, boundId));
-            return await raceAbort(job, signal);
-        }
-        catch (err) {
-            if (err instanceof AbortedError) {
-                if (sdk && modelId) {
-                    void sdk.cancel({ modelId, operation: 'inference' }).catch(noop);
-                }
-                releaseAfter = job ?? handle.peek();
-            }
-            throw err;
-        }
-        finally {
-            const release = () => {
-                releaseModel(pool, name);
-            };
-            if (releaseAfter) {
-                void releaseAfter.then(release, release).finally(releaseWork).catch(noop);
-            }
-            else {
-                try {
-                    release();
-                }
-                finally {
-                    releaseWork();
-                }
-            }
+        if (!this._plugins.ctx.knowledge) {
+            throw new Error(KNOWLEDGE_PLUGIN_MISSING);
         }
+        return this._plugins.ctx.knowledge;
+    }
+    async knowledgeUpsert(artifact) {
+        return (await this._knowledgeService()).upsert(artifact);
+    }
+    async knowledgeRemove(artifactId) {
+        return (await this._knowledgeService()).remove(artifactId);
+    }
+    async knowledgeSearch(query) {
+        return (await this._knowledgeService()).search(query);
+    }
+    async knowledgeStatus() {
+        return (await this._knowledgeService()).status();
     }
     transcribe(context) {
-        return this._busy(() => this._transcribe(context));
+        return this._residency.busy(() => this._transcribe(context));
     }
     async _transcribe({ model, audio, signal }) {
-        return this._voiceJob(this._transcriptionModels, { category: 'transcription', model, signal }, async (sdk, id) => {
-            const pcm = await pcmForTranscription(audio);
-            if (signal?.aborted) {
-                throw new AbortedError();
-            }
-            if (pcm && pcm.length >= TRANSCRIBE_STREAM_MIN_BYTES) {
-                return transcribeStreaming(sdk, pcm, { modelId: id, signal });
-            }
-            return transcribeOnce(sdk, id, pcm ? buildWavBuffer(pcm) : audio);
+        const speech = await this._speechService();
+        return speech.transcribe({
+            model: model || defaultVoiceModel('transcription'),
+            audio,
+            signal
         });
     }
     detectLanguage(context) {
         return detectLanguage(context);
     }
     speak(context) {
-        return this._busy(() => this._speak(context));
+        return this._residency.busy(() => this._speak(context));
     }
     async _speak({ model, text, signal }) {
-        const samples = await this._voiceJob(this._ttsModels, { category: 'tts', model, signal }, (sdk, id) => speakOnce(sdk, id, text));
-        return { audio: packSamples(samples), sampleRate: SUPERTONIC_SAMPLE_RATE };
+        const speech = await this._speechService();
+        return speech.speak({ model: model || (await this._defaultTts(speech)), text, signal });
     }
     speakStream(context) {
-        return this._busyStream(() => this._speakStream(context));
+        return this._residency.busyStream(() => this._speakStream(context));
     }
     async *_speakStream({ model, text, signal }) {
-        if (!this.opened)
-            await this.ready();
-        if (this.suspended)
-            throw new Error('harness is suspended');
-        const name = residentSrc(model || (await this._defaultVoiceSrc('tts')), 'tts');
-        this._assertNotClosing();
-        const pool = this._ttsModels;
-        const chunks = pushQueue();
-        const releaseWork = this._enterWork();
-        let handle;
-        try {
-            handle = pool.open(name, name);
-        }
-        catch (error) {
-            releaseWork();
-            throw error;
-        }
-        let sdk = null;
-        let modelId = null;
-        const cancel = () => {
-            if (sdk && modelId) {
-                void sdk.cancel({ modelId, operation: 'inference' }).catch(noop);
-            }
-        };
-        signal?.addEventListener('abort', cancel, { once: true });
-        const job = this._voiceLane(async () => {
-            try {
-                modelId = (await handle.load()).modelId;
-                sdk = (await this._sdk.loadVoice());
-                this._assertNotClosing();
-                if (signal?.aborted) {
-                    return;
-                }
-                for await (const chunk of speakStreamOnce(sdk, modelId, text)) {
-                    chunks.push(chunk);
-                }
-            }
-            finally {
-                chunks.end();
-            }
-        });
-        let settled = false;
-        try {
-            yield* chunks;
-            await job;
-            settled = true;
-        }
-        finally {
-            signal?.removeEventListener('abort', cancel);
-            if (!settled) {
-                cancel();
-            }
-            void job
-                .catch(noop)
-                .finally(() => {
-                try {
-                    releaseModel(pool, name);
-                }
-                finally {
-                    releaseWork();
-                }
-            })
-                .catch(noop);
-        }
+        const speech = await this._speechService();
+        yield* speech.speakStream({ model: model || (await this._defaultTts(speech)), text, signal });
+    }
+    async _defaultTts(speech) {
+        const profile = await this.capability().then((capability) => capability.capabilityProfile, () => null);
+        return speech.defaultModel(profile);
     }
     async list(options = {}) {
         if (!this.opened)
             await this.ready();
-        const releaseWork = this._enterWork();
+        const releaseWork = this._lifecycle.enterWork();
         try {
             const sdk = await this._sdk.load();
-            this._assertNotClosing();
+            this._lifecycle.assertNotClosing();
             const rows = await listModels(sdk, options, {
-                cache: this._modelStatus,
+                cache: this._residency.status,
                 projectionFor: (name) => this._projectionFor(name)
             });
-            const loaded = this._settledModels();
-            const loading = this._loadingModels();
+            const loaded = this._residency.settled();
+            const loading = this._residency.loading();
             const custom = await customModelRows(options, { modelsDir: this._modelsDir, loaded });
-            return mergeCustomRows(rows, custom).map((row) => ({
-                ...row,
-                isLoading: loading.has(row.name)
-            }));
+            const merged = mergeCustomRows(rows, custom);
+            const fits = await this._residency.rowFits(merged);
+            return merged.map((row) => {
+                const fit = row.isLoaded || loaded.has(row.name) ? undefined : fits.get(row.registryPath);
+                return {
+                    ...row,
+                    isLoading: loading.has(row.name),
+                    fit: fit?.verdict,
+                    fitBasis: fit?.basis,
+                    fitEvidence: fit?.evidence
+                };
+            });
         }
         finally {
             releaseWork();
@@ -1472,12 +638,12 @@ export class Harness extends ReadyResource {
     async deleteModel(name) {
         if (!this.opened)
             await this.ready();
-        const releaseWork = this._enterWork();
+        const releaseWork = this._lifecycle.enterWork();
         try {
             const sdk = await this._sdk.load();
-            this._assertNotClosing();
+            this._lifecycle.assertNotClosing();
             const result = await deleteModelFiles(sdk, name, { modelsDir: this._modelsDir });
-            invalidateModelStatusCache(this._modelStatus);
+            this._residency.invalidateStatus();
             return summarizeDelete(result);
         }
         finally {
@@ -1487,10 +653,10 @@ export class Harness extends ReadyResource {
     async clearKvCache() {
         if (!this.opened)
             await this.ready();
-        const releaseWork = this._enterWork();
+        const releaseWork = this._lifecycle.enterWork();
         try {
             return await deleteAllKvCaches(() => {
-                this._assertNotClosing();
+                this._lifecycle.assertNotClosing();
                 return this._sdk.load();
             });
         }
@@ -1501,10 +667,10 @@ export class Harness extends ReadyResource {
     async deleteKvCache(kvCacheKey) {
         if (!this.opened)
             await this.ready();
-        const releaseWork = this._enterWork();
+        const releaseWork = this._lifecycle.enterWork();
         try {
             return await deleteKvCacheKey(() => {
-                this._assertNotClosing();
+                this._lifecycle.assertNotClosing();
                 return this._sdk.load();
             }, kvCacheKey);
         }
@@ -1518,7 +684,7 @@ export class Harness extends ReadyResource {
     async capability() {
         if (!this.opened)
             await this.ready();
-        this._assertNotClosing();
+        this._lifecycle.assertNotClosing();
         if (this._capability) {
             return this._capability;
         }
@@ -1560,211 +726,25 @@ export class Harness extends ReadyResource {
         return this._capabilityInflight;
     }
     warmModel(context) {
-        return this._busy(() => this._warmModel(context));
-    }
-    async _warmModel({ model, agent, signal }) {
-        if (!this.opened)
-            await this.ready();
-        this._assertNotClosing();
-        if (this.suspended) {
-            return;
-        }
-        const target = this._residency(model, agent);
-        hlog('warm model', { model, resident: isResident(target.pool, target.key) });
-        await this._loadAndRelease(target, signal, async () => {
-            if (target.pool !== this._models || isResident(target.pool, target.key)) {
-                return true;
-            }
-            const roomed = await this._makeRoomForCompletion(model, {
-                ctxSize: target.ctxSize,
-                signal,
-                deadlineMs: WARM_ROOM_WAIT_MS
-            });
-            if (roomed) {
-                await this._unloadIdleGenerators();
-            }
-            return roomed;
-        });
+        return this._residency.busy(() => this._residency.warm(context));
     }
     loadModel(context) {
-        return this._busy(() => this._loadModel(context));
-    }
-    async _loadModel({ model, agent, signal }) {
-        if (!this.opened)
-            await this.ready();
-        if (this.suspended) {
-            throw new Error('harness is suspended');
-        }
-        const target = this._residency(model, agent);
-        const resident = isResident(target.pool, target.key);
-        hlog('load model', { model, resident });
-        if (target.pool !== this._models) {
-            await this._loadAndRelease(target, signal);
-            return { loaded: true };
-        }
-        if (!resident) {
-            if (!(await this._fits(model, target.ctxSize))) {
-                return { loaded: false, reason: 'memory' };
-            }
-            await evictIdleWhere(this._models, (key) => modelOf(key) === model && !this._replying.includes(key));
-            await this._unloadIdleGenerators();
-        }
-        this._pinned.add(target.key);
-        try {
-            await this._loadAndRelease(target, signal);
-        }
-        catch (err) {
-            this._pinned.delete(target.key);
-            throw err;
-        }
-        return { loaded: true };
+        return this._residency.busy(() => this._residency.load(context));
     }
     unloadModel(context) {
-        return this._busy(() => this._unloadModel(context));
-    }
-    async _unloadModel({ model }) {
-        if (!this.opened)
-            await this.ready();
-        const target = this._residency(model);
-        const name = modelOf(target.key);
-        const unloaded = await evictModel(target.pool, name, { deadlineMs: UNLOAD_LEASE_WAIT_MS });
-        hlog('unload model', { model, unloaded });
-        if (unloaded) {
-            for (const key of this._pinned) {
-                if (modelOf(key) === name) {
-                    this._pinned.delete(key);
-                }
-            }
-        }
-        return { unloaded };
-    }
-    async _loadAndRelease({ pool, key, open }, signal, prepare = async () => true) {
-        const lease = await this._acquireModelLease({ pool, key, open, signal, prepare });
-        lease?.release();
-    }
-    async _unloadIdleGenerators() {
-        await this._imageRuntime?.unloadIdle().catch(noop);
-        await this._musicRuntime?.unloadIdle().catch(noop);
-    }
-    async _fits(model, ctxSize) {
-        const asset = curatedModelAsset(model, 'llm');
-        if (!asset) {
-            return true;
-        }
-        const assessed = await this._assessFit({
-            sha256Checksum: asset.sha256Checksum,
-            name: asset.name,
-            contextTokens: ctxSize || defaultContextSize(asset)
-        }).catch((err) => {
-            hlog('fit estimate failed', { model, err: errorMessage(err) });
-            return null;
-        });
-        return assessed?.fit !== 'likely-too-large';
-    }
-    async _yieldPins(model, ctxSize) {
-        for (const key of this._pinned) {
-            if (leaseCount(this._models, key) > 0 || this._replying.includes(key)) {
-                continue;
-            }
-            if (await this._fits(model, ctxSize))
-                return;
-            this._pinned.delete(key);
-            await evictModelWithin(this._models, key, { deadlineMs: WEDGED_EVICT_WAIT_MS });
-        }
-    }
-    _residency(model, agent) {
-        const addon = modelAddonOf(model);
-        if (addon === 'llm') {
-            const loadOpts = this._completionLoadOptions(model, agent);
-            const key = modelKey(model, loadOpts);
-            return {
-                pool: this._models,
-                key,
-                ctxSize: loadOpts.ctxSize,
-                open: () => this._models.open(key, model, loadOpts)
-            };
-        }
-        if (addon === 'embeddings') {
-            const key = this._embedFaults.key(residentSrc(model, addon));
-            return { pool: this._embedModels, key, open: () => this._embedModels.open(key, model) };
-        }
-        if (addon === 'tts' || addon === 'parakeet') {
-            const pool = addon === 'tts' ? this._ttsModels : this._transcriptionModels;
-            const key = residentSrc(model, addon);
-            return { pool, key, open: () => pool.open(key, key) };
-        }
-        throw new Error(`${model} loads for each generation and is not kept in memory`);
-    }
-    _completionLoadOptions(model, agent) {
-        return resolveLoadOptions({
-            ctxSize: agent?.ctxSize ?? undefined,
-            kvCacheK: agent?.kvCacheK ?? undefined,
-            kvCacheV: agent?.kvCacheV ?? undefined,
-            projectionModel: this._projectionFor(model)
-        }, this._deviceConfig());
-    }
-    async _acquireModelLease({ pool, key, open, signal, prepare }) {
-        const releaseWork = this._enterWork();
-        let pendingLoad = null;
-        let opened = false;
-        let released = false;
-        const release = () => {
-            if (released) {
-                return;
-            }
-            released = true;
-            try {
-                if (opened) {
-                    releaseModel(pool, key);
-                }
-            }
-            finally {
-                releaseWork();
-            }
-        };
-        try {
-            if (!(await prepare())) {
-                release();
-                return null;
-            }
-            if (signal?.aborted) {
-                throw new AbortedError();
-            }
-            if (this.suspended || this._runtimeDraining) {
-                throw new Error('harness is suspended');
-            }
-            this._assertNotClosing();
-            if (this._runtimeUnloadFailed) {
-                throw new Error('Runtime unload failed; close the harness before loading models again');
-            }
-            const handle = open();
-            opened = true;
-            const loading = handle.load();
-            pendingLoad = loading;
-            const loaded = await raceAbort(loading, signal);
-            return { modelId: loaded.modelId, release };
-        }
-        catch (error) {
-            if (pendingLoad) {
-                void pendingLoad.then(release, release).catch(noop);
-            }
-            else {
-                release();
-            }
-            throw error;
-        }
+        return this._residency.busy(() => this._residency.unload(context));
     }
     invoke(context) {
-        return this._busyStream(() => this._invoke(context));
+        return this._residency.busyStream(() => this._invoke(context));
     }
     async *_invoke({ capability, args, enhance, agent, attach, fetchAttachment, progress, signal }) {
         if (!this.opened)
             await this.ready();
         if (this.suspended) {
-            this._assertNotClosing();
+            this._lifecycle.assertNotClosing();
             return yield { type: 'aborted' };
         }
-        const releaseWork = this._enterWork();
+        const releaseWork = this._lifecycle.enterWork();
         hlog('invoke start', { capability, enhance });
         try {
             yield* invoke({
@@ -1772,7 +752,7 @@ export class Harness extends ReadyResource {
                 args,
                 enhance,
                 enhancer: this._residentEnhancer(),
-                tools: [...this._tools, ...this._capabilityTools],
+                tools: [...this._tools, ...this._capabilities],
                 ctx: {
                     image: imageSettingsFrom(agent),
                     attach,
@@ -1788,56 +768,65 @@ export class Harness extends ReadyResource {
         }
     }
     completion(context) {
-        this._assertNotClosing();
-        if (this._runtimeDraining) {
+        if (!context.agents) {
+            return this._completion(context);
+        }
+        if (context.boot || context.onStep) {
+            throw new TypeError('A run that follows handoffs cannot take boot or onStep; run it over the wire with a HostRunLog');
+        }
+        return Agent.follow({ completion: (hop) => this._completion(hop) }, { ...context, goal: undefined });
+    }
+    _completion(context) {
+        this._lifecycle.assertNotClosing();
+        if (this._lifecycle.draining) {
             throw new Error('harness is suspended');
         }
-        if (this._runtimeUnloadFailed) {
+        if (this._lifecycle.unloadFailed) {
             throw new Error('Runtime unload failed; close the harness before loading models again');
         }
-        const tracked = trackCompletion((signal) => this._busyStream(() => this._runCompletion({ ...context, signal })), context.signal, (run) => {
-            this._completionRuns.delete(run);
-            this._notifyEffectDrain();
-        });
-        const { iterator, run } = tracked;
-        this._completionRuns.add(run);
-        return iterator;
+        return this._lifecycle.trackCompletion((signal) => this._residency.busyStream(() => this._runCompletion({ ...context, signal })), context.signal);
     }
     async *_runCompletion(request) {
         if (!this.opened)
             await this.ready();
-        this._assertNotClosing();
-        if (this.suspended || this._runtimeDraining) {
+        this._lifecycle.assertNotClosing();
+        if (this.suspended || this._lifecycle.draining) {
             yield { type: 'aborted' };
             return;
         }
         const { boot, onStep, hostAppendTimeoutMs, requestDigestKey, ...provided } = request;
         let modelId = request.model ?? '';
         let key = null;
+        const releasePlugins = await this._plugins.hold(request.parentRunId !== undefined);
+        const detached = [];
         try {
             const runtime = async (run) => {
                 modelId = run.model ?? run.modelId;
                 const runContext = { ...run, model: run.model ?? run.modelId };
-                const lease = await this._completionRuntime(runContext);
+                const lease = await this._residency.completionRuntime(runContext);
                 if (!key) {
-                    this._replying.push(lease.key);
+                    this._residency.reply(lease.key);
                 }
                 key = lease.key;
-                return lease;
+                return { ...lease, services: this._plugins.ctx };
             };
             const args = { ...provided, lockOwner: this };
-            for await (const event of completion(runtime, args, {
+            for await (const event of CompletionEngine.run(runtime, args, {
+                hooks: this._hooks,
                 boot,
                 onStep,
                 hostAppendTimeoutMs,
                 requestDigestKey,
                 resumeRequest: provided,
-                onDetached: (pending, runId) => this._trackDetachedRun(pending, runId)
+                onDetached: (pending, runId) => {
+                    detached.push(pending);
+                    this._lifecycle.trackDetachedRun(pending, runId);
+                }
             })) {
                 yield event;
             }
             if (key) {
-                this._modelFaults.delete(modelId);
+                this._residency.clearFaults(modelId);
             }
         }
         catch (error) {
@@ -1846,15 +835,15 @@ export class Harness extends ReadyResource {
         finally {
             if (key) {
                 hlog('completion end', { model: modelId });
-                this._replying.splice(this._replying.indexOf(key), 1);
-                void this._imageRuntime?.unloadIdle().catch(noop);
-                void this._musicRuntime?.unloadIdle().catch(noop);
+                this._residency.replied(key);
+                void this._plugins.unloadIdle();
             }
+            void Promise.allSettled(detached).then(releasePlugins);
         }
     }
     async *_completionFailed(err, model, key) {
-        if (err instanceof AbortedError || this.suspended || this._runtimeDraining) {
-            hlog('completion aborted', { model, suspended: this.suspended || this._runtimeDraining });
+        if (err instanceof AbortedError || this.suspended || this._lifecycle.draining) {
+            hlog('completion aborted', { model, suspended: this.suspended || this._lifecycle.draining });
             yield { type: 'aborted' };
             return;
         }
@@ -1862,7 +851,7 @@ export class Harness extends ReadyResource {
         const name = err instanceof Error ? err.name : undefined;
         hlog('completion failed', { model, ...resolutionDetail(err), err: message });
         if (key && isSdkModelWedgedError(err)) {
-            const wedged = await this._evictWedgedModel(model, key);
+            const wedged = await this._residency.evictWedged(model, key);
             yield completionErrorEvent(wedged.message, name, err);
             if (wedged.fatal) {
                 process.exit(1);
@@ -1872,18 +861,9 @@ export class Harness extends ReadyResource {
             yield completionErrorEvent(message, name, err);
         }
     }
-    async _completionRuntime(request) {
-        const releaseWork = this._enterWork();
-        try {
-            return await prepareCompletionRuntime(this, request);
-        }
-        finally {
-            releaseWork();
-        }
-    }
     _residentEnhancer() {
         return async (prompt, signal) => {
-            const lease = await leaseResidentModel(this._models, (model) => !isTranslationModel(model));
+            const lease = await leaseResidentModel(this._residency.pool, (model) => !this._residency.borrowed(model));
             if (!lease) {
                 return null;
             }
@@ -1904,69 +884,6 @@ export class Harness extends ReadyResource {
             }
         };
     }
-    async _makeRoomForCompletion(model, { ctxSize, signal, deadlineMs = MODEL_ROOM_WAIT_MS } = {}) {
-        const roomed = await awaitModelCapacity(this._models, {
-            cap: this._completionModelCap,
-            deadlineMs,
-            signal,
-            evictable: (key) => !this._pinned.has(key) || modelOf(key) === model
-        });
-        if (!roomed) {
-            hlog('model room wait gave up', {
-                cap: this._completionModelCap,
-                loaded: loadedModels(this._models).length
-            });
-        }
-        await this._yieldPins(model, ctxSize);
-        return roomed;
-    }
-    async _evictWedgedModel(model, key) {
-        const faults = (this._modelFaults.get(model) ?? 0) + 1;
-        this._modelFaults.set(model, faults);
-        const leased = leaseCount(this._models, key) > 0;
-        const evicted = leased
-            ? false
-            : await evictModelWithin(this._models, key, { deadlineMs: WEDGED_EVICT_WAIT_MS });
-        hlog('wedged model evicted', { model, faults, evicted, leased });
-        if (leased) {
-            this._evictAfterLeases(model, key);
-        }
-        if (!evicted && !leased) {
-            return {
-                message: `${model} is stuck in device memory — restarting the model runtime`,
-                fatal: true
-            };
-        }
-        return {
-            message: faults > 1
-                ? `${model} keeps failing during inference on this device — it may need more memory than is available`
-                : `${model} failed during inference and was unloaded — try again`,
-            fatal: false
-        };
-    }
-    _evictAfterLeases(model, key) {
-        void evictModelWithin(this._models, key, { deadlineMs: WEDGED_EVICT_LEASED_MS })
-            .then((evicted) => hlog('wedged model evicted after leases', { model, evicted }))
-            .catch(noop);
-    }
-    async _busy(run) {
-        await this._idle.enter();
-        try {
-            return await run();
-        }
-        finally {
-            this._idle.exit();
-        }
-    }
-    async *_busyStream(run) {
-        await this._idle.enter();
-        try {
-            yield* run();
-        }
-        finally {
-            this._idle.exit();
-        }
-    }
 }
 function completionErrorEvent(message, name, error) {
     const event = { type: 'error', message, ...completionErrorDetails(error) };