dsh-model-groups 0.3.4 → 0.3.5

package/src/auto-patch.js

@@ -4,6 +4,7 @@ import os from 'node:os';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { planPatches, applyPlan, sha256 } from '../scripts/native-patches.mjs';
+import { restorationPending } from './maintenance.js';
 
 export function findDshRoot(entry = process.argv[1]) {
   if (!entry) throw new Error('无法确定 DSH 进程入口。');
@@ -26,6 +27,7 @@ export function findDshRoot(entry = process.argv[1]) {
 }
 
 export function autoPatch(root, home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh')) {
+  if (restorationPending(root, home)) return { state: 'restore-pending', changed: 0, runtimeVerified: false };
   const plans = planPatches(root, 'apply');
   const pending = plans.some(plan => plan.source !== plan.result);
   if (!pending) return { state: 'disk-ready', changed: 0, runtimeVerified: false };
@@ -35,6 +37,7 @@ export function autoPatch(root, home = process.env.DSH_HOME || path.join(os.home
   try { fs.mkdirSync(lock, { mode: 0o700 }); }
   catch { throw new Error('补丁安装已被锁定；可能有另一进程正在安装。确认没有安装任务后再处理锁目录，勿并发重试。'); }
   try {
+    if (restorationPending(root, home)) return { state: 'restore-pending', changed: 0, runtimeVerified: false };
     const changed = applyPlan(planPatches(root, 'apply'), path.join(storage, 'backups'));
     if (!planPatches(root, 'check').every(plan => plan.state === 'patched')) throw new Error('自动补丁复查失败。');
     return { state: changed ? 'restart-required' : 'disk-ready', changed, runtimeVerified: false };

package/src/client.js

@@ -5,6 +5,10 @@ const inject = ['slots', 'modelDirectories', 'sessions', 'locale', 'remote', 're
 export function apply(ctx) {
   installModelSelectStyles();
   installModelGroupsStyles();
+  installSettingsPageStyles();
+  ctx.slots.inject('settings.section', () => ctx.slots.register({
+    name: 'settings.section', id: 'dsh-model-groups', order: 35, label: '模型分组',
+  }, ModelGroupsSettingsPage));
   const providersForm = ctx.configForms?.get('llm-pi-ai');
   let statusDisposed = false;
   let statusNotice;
@@ -14,11 +18,11 @@ export function apply(ctx) {
       if (statusDisposed || (!status.restartRequired && !status.failed)) return;
       statusNotice = document.createElement('div');
       statusNotice.dataset.plugin = 'dsh-model-groups';
-      statusNotice.setAttribute('role', 'alertdialog');
-      statusNotice.style.cssText = 'position:fixed;inset:0;z-index:2147483647;background:var(--dsw-alias-bg-base,#fff);color:var(--dsw-alias-label-primary,#222);display:grid;place-items:center;padding:24px;box-sizing:border-box;';
+      statusNotice.setAttribute('role', 'status');
+      statusNotice.style.cssText = 'position:fixed;bottom:16px;right:16px;max-width:min(360px,80vw);z-index:1000;background:var(--dsw-alias-bg-base,#fff);color:var(--dsw-alias-label-primary,#222);padding:12px;border:1px solid currentColor;border-radius:8px;box-sizing:border-box;pointer-events:none;';
       statusNotice.textContent = status.failed
-        ? '多密钥自动补丁未完成。请回到 App 对话查看引擎日志或运行安装诊断，勿强制覆盖。当前网页暂不可用于编辑模型配置。'
-        : '多密钥补丁已自动安装。请先保存其他页面的草稿，再到 App 重启原引擎并刷新此网页。当前网页暂停操作，避免新旧模块混用。';
+        ? '多密钥自动补丁未完成。请回到 App 对话查看引擎日志或运行安装诊断，勿强制覆盖。请暂勿编辑模型配置；可到「设置 → 模型分组」检查并安全恢复。'
+        : '多密钥补丁已自动安装。请先保存其他页面的草稿，再到 App 重启原引擎并刷新此网页。请暂勿编辑模型配置，避免新旧模块混用；维护入口仍可使用。';
       document.body.appendChild(statusNotice);
     }).catch(() => {});
   ctx.on('dispose', () => { statusDisposed = true; statusNotice?.remove(); });

package/src/index.js

@@ -1,29 +1,37 @@
-import { findDshRoot, autoPatch } from './auto-patch.js';
+import os from 'node:os';
+import path from 'node:path';
+import { findDshRoot } from './auto-patch.js';
+import { createMaintenance, maintenanceHandler } from './maintenance.js';
+import { createHostInspection } from './maintenance-host.js';
 
-// Explicit patch distribution: installation/loading validates and updates the
-// known DSH disk files. It never forces module reload, restart or config changes.
+// Neither disposal nor ordinary package removal restores patches: HMR and updates
+// also dispose plugins. Only the explicitly confirmed maintenance transaction does.
 export function apply(ctx) {
   const key = Symbol.for('dsh-model-groups.patch-state');
   const state = globalThis[key] ??= { restartRequired: false, error: null };
-  ctx.inject(['webserver'], child => {
-    child.effect(() => child.webserver.register({
-      kind: 'exact', path: '/dsh-model-groups/status',
-      handler(req, res) {
-        res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
-        res.end(JSON.stringify({ restartRequired: state.restartRequired, failed: state.error !== null }));
-      },
-    }));
-  });
+  const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+  let root;
   try {
-    const result = autoPatch(findDshRoot());
-    if (result.state === 'restart-required') {
-      state.restartRequired = true;
-      ctx.logger.warn(`多密钥兼容补丁已自动安装（${result.changed} 项）。请保存草稿，在 App 重启原引擎并刷新原网页；当前进程尚未验证生效。`);
-    } else {
-      ctx.logger.info('多密钥磁盘补丁已就绪。若本次进程尚未在打补丁后重启，请重启原引擎并刷新网页。');
-    }
-  } catch (error) {
-    state.error = error.message;
-    ctx.logger.error(`多密钥自动安装未完成：${error.message}。未强制覆盖未知文件，请运行安装诊断；不要把模型分组出现视为多密钥已就绪。`);
+    root = findDshRoot();
+    state.error = null;
+    state.restartRequired = false;
+    ctx.logger.info('多密钥补丁由设置页手动管理；插件启动不会修改宿主文件。');
+  } catch {
+    state.error = 'patch-validation-failed';
+    ctx.logger.error('多密钥安装校验失败，未强制覆盖未知文件。请查看维护页。');
   }
+  ctx.inject(['webServer', 'connection', 'pluginManager'], child => {
+    const inspect = root ? createHostInspection(child, root, home) : async () => ({ blockers: [{ code: 'HOST_UNKNOWN', message: '无法验证当前宿主安装，禁止恢复。' }], fingerprint: '' });
+    const controller = root ? createMaintenance({ root, home, inspect, manager: child.pluginManager }) : {
+      snapshot: async () => ({ phase: 'failed', restartRequired: false, patches: [], blockers: (await inspect()).blockers, canRestore: false, canRestoreOnly: false, canApply: false, token: null }),
+      restore: async () => { throw { code: 'HOST_UNKNOWN', message: '无法验证当前宿主安装。' }; },
+    };
+    child.effect(() => child.webServer.register({ kind: 'exact', path: '/dsh-model-groups/maintenance', handler: maintenanceHandler(controller, child.connection) }));
+    child.effect(() => child.webServer.register({ kind: 'exact', path: '/dsh-model-groups/status', handler(req, res) {
+      const admission = child.connection.admit(req);
+      if (!admission?.peer || admission.peer.principal?.kind !== 'owner') { res.writeHead(admission?.rejection || 403); res.end(); return; }
+      res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+      res.end(JSON.stringify({ restartRequired: state.restartRequired, failed: state.error !== null }));
+    } }));
+  });
 }

package/src/maintenance-fallback.js

@@ -0,0 +1,160 @@
+import { randomBytes } from 'node:crypto';
+
+const alias = value => typeof value === 'string' && value.startsWith('@dsh-key/');
+const validId = value => typeof value === 'string' && value.length > 0 && value.length <= 512;
+const selection = value => {
+  if (!value || !validId(value.provider) || !validId(value.model) ||
+      (value.reasoningEffort !== undefined && !validId(value.reasoningEffort))) throw new Error('INVALID_SELECTION');
+  return { provider: value.provider, model: value.model,
+    ...(value.reasoningEffort === undefined ? {} : { reasoningEffort: value.reasoningEffort }) };
+};
+const equal = (a, b) => !!a && !!b && a.provider === b.provider && a.model === b.model && a.reasoningEffort === b.reasoningEffort;
+const fail = code => Object.assign(new Error(code), { code });
+const clone = value => JSON.parse(JSON.stringify(value));
+const unsupported = () => [
+  { code: 'COLD_SESSIONS_UNSUPPORTED', message: 'Cold sessions cannot be safely changed by this adapter.' },
+  { code: 'HISTORICAL_REFERENCES_UNSUPPORTED', message: 'Historical request headers and replay/fork references are not rewritten.' },
+  { code: 'OTHER_REFERENCES_UNSUPPORTED', message: 'Agent options, subagent descriptors, presets, other profiles and processes are not migrated.' },
+];
+
+/** Verified installed service spellings. Descriptive only: this module imports no host code. */
+export const FALLBACK_HOST_APIS = Object.freeze({
+  live: 'ctx.agents.get(sessionId); agent.model.current(); agent.model.select(selection)',
+  durability: 'await ctx.sessions.flush(agent.session); await ctx.sessionQuery.readSession(sessionId)',
+  defaults: 'ctx.agentDefaultModel.currentSelection(); ctx.agentDefaultModel.remembersLastSelection(); await ctx.agentDefaultModel.saveSelection(next, { ifCurrent: previous })',
+  catalog: 'session.modelCatalog() uses ctx.llm.listProviders/listModels/resolveModelInfo; NOT called here because discovery may perform network I/O',
+  limitation: 'No host session-selection CAS or cross-service transaction exists; synchronous local check+select is not a process-wide maintenance lock.',
+});
+
+/**
+ * UNWIRED, local-only injected adapter. No discovery, inference, credential access, file
+ * writes, cold-agent creation, automatic default update or native patch operations.
+ *
+ * `catalog` is a detached ALREADY OBTAINED ordinary catalog: { groups: [{ id, models:
+ * [{ id, reasoning?: { efforts: [{id}] } }] }] }. `ordinaryProviders` is an explicit
+ * allowlist verified by the future caller from local configuration: the catalog alone
+ * cannot establish that a provider has no multi-key routing. Never derive it by merely
+ * excluding alias IDs. No provider discovery or settings/secret reads occur here.
+ *
+ * Inject formal services `agents`, `sessions`, `defaultModel`, and optional
+ * `readPersistedSelection(id)` (read-only; return the effective current selection).
+ * The future reader must fold model/selection and request/header events, not old
+ * request headers alone. `sessions.flush` must return true (a durability listener).
+ *
+ * Session CAS is a synchronous identity + full selection + seq + idle check immediately
+ * followed by the synchronous AgentModel.select. No await is permitted between them.
+ * This is same-process CAS only; it does NOT lock out a later prompt or other process.
+ * Defaults use the host's lock-held ifCurrent CAS and reject fixed-default mode.
+ * Each ticket changes exactly ONE explicitly chosen target. Partial failures are
+ * reported, never rolled back or represented as successful migration/removal safety.
+ */
+export function createFallbackSelection({ catalog, ordinaryProviders = [], agents, sessions,
+  defaultModel, readPersistedSelection, now = Date.now, token = () => randomBytes(24).toString('hex'), ttlMs = 120000 } = {}) {
+  const allowed = new Set(ordinaryProviders);
+  const choices = [];
+  for (const group of catalog?.groups ?? []) {
+    if (!validId(group.id) || alias(group.id) || !allowed.has(group.id)) continue;
+    for (const model of group.models ?? []) {
+      if (!validId(model.id) || alias(model.id)) continue;
+      const efforts = (model.reasoning?.efforts ?? []).map(effort => effort.id).filter(validId);
+      if (choices.some(item => item.provider === group.id && item.model === model.id)) throw fail('AMBIGUOUS_CATALOG');
+      choices.push({ provider: group.id, model: model.id, efforts });
+    }
+  }
+  const tickets = new Map();
+  let busy = false;
+  const choice = input => {
+    const next = selection(input);
+    if (Object.keys(input).some(key => !['provider', 'model', 'reasoningEffort'].includes(key))) throw fail('INVALID_SELECTION');
+    const item = choices.find(item => item.provider === next.provider && item.model === next.model);
+    if (!item || alias(next.provider) || alias(next.model) ||
+        (next.reasoningEffort !== undefined && !item.efforts.includes(next.reasoningEffort))) throw fail('NOT_ORDINARY_CATALOG_SELECTION');
+    return next;
+  };
+  const readLive = id => {
+    const agent = agents?.get?.(id);
+    if (!agent || agent.id !== id || !agent.session || typeof agent.model?.current !== 'function' || typeof agent.model?.select !== 'function') throw fail('LIVE_SESSION_UNSUPPORTED');
+    if (agent.status !== 'idle' || (agent.phase && agent.phase.kind !== 'idle')) throw fail('SESSION_BUSY');
+    if (!Number.isSafeInteger(agent.session.seq) || agent.session.seq < 0) throw fail('SESSION_REVISION_UNAVAILABLE');
+    return { agent, session: agent.session, seq: agent.session.seq, current: selection(agent.model.current()) };
+  };
+  const readDefault = () => {
+    if (typeof defaultModel?.currentSelection !== 'function' || typeof defaultModel?.remembersLastSelection !== 'function' || typeof defaultModel?.saveSelection !== 'function') throw fail('DEFAULT_API_UNAVAILABLE');
+    if (defaultModel.remembersLastSelection() !== true) throw fail('FIXED_DEFAULT_UNSUPPORTED');
+    return selection(defaultModel.currentSelection());
+  };
+  function preview({ target, next } = {}) {
+    const blockers = [];
+    let selected, previous, observation, cleanTarget;
+    try {
+      selected = choice(next);
+      if (target?.kind === 'session' && validId(target.sessionId) && Object.keys(target).every(key => ['kind', 'sessionId'].includes(key))) {
+        cleanTarget = { kind: 'session', sessionId: target.sessionId };
+        if (typeof sessions?.flush !== 'function' || typeof readPersistedSelection !== 'function') throw fail('DURABILITY_VERIFICATION_UNAVAILABLE');
+        observation = readLive(target.sessionId);
+        previous = observation.current;
+      } else if (target?.kind === 'default' && Object.keys(target).length === 1) {
+        cleanTarget = { kind: 'default' };
+        previous = readDefault();
+      } else throw fail('TARGET_UNSUPPORTED');
+      if (!alias(previous.model) && !alias(previous.provider)) throw fail('NOT_ALIAS_SELECTION');
+    } catch (error) { blockers.push({ code: error.code || 'INVALID_SELECTION' }); }
+    let ticket = null;
+    if (!blockers.length) {
+      // Bound memory and invalidate expired confirmations without exposing observations.
+      for (const [key, value] of tickets) if (value.expires <= now()) tickets.delete(key);
+      if (tickets.size >= 128) tickets.delete(tickets.keys().next().value);
+      ticket = token();
+      if (typeof ticket !== 'string' || !ticket || tickets.has(ticket)) throw fail('TOKEN_UNAVAILABLE');
+      tickets.set(ticket, { target: cleanTarget, next: selected, previous, observation, expires: now() + ttlMs });
+    }
+    return { canApply: blockers.length === 0 && !busy, token: ticket,
+      target: cleanTarget ? { ...cleanTarget } : null, previous: previous ? { ...previous } : null, next: selected ? { ...selected } : null,
+      blockers, removalBlockers: unsupported(), safeToRemovePatches: false,
+      scope: 'one-current-selection-only', catalogFreshness: 'caller-supplied-snapshot' };
+  }
+  async function apply(input) {
+    if (busy) throw fail('BUSY');
+    const ticket = tickets.get(input?.token);
+    if (!ticket || ticket.expires <= now() || input?.confirmation !== 'CONFIRM FALLBACK SELECTION' ||
+        Object.keys(input).some(key => !['token', 'confirmation'].includes(key))) throw fail('CONFIRMATION_REQUIRED');
+    tickets.delete(input.token);
+    busy = true;
+    let changed = false;
+    try {
+      if (ticket.target.kind === 'session') {
+        const live = readLive(ticket.target.sessionId);
+        const old = ticket.observation;
+        if (live.agent !== old.agent || live.session !== old.session || live.seq !== old.seq || !equal(live.current, ticket.previous)) throw fail('STATE_CHANGED');
+        // The only live write: synchronous check+select with no intervening await.
+        changed = true; // A throwing host operation may already have appended.
+        const result = live.agent.model.select({ ...ticket.next });
+        if (result && typeof result.then === 'function') throw fail('ASYNC_SELECTION_UNSUPPORTED');
+        if (await sessions.flush(live.session) !== true) throw fail('DURABILITY_UNCONFIRMED');
+        const persisted = selection(await readPersistedSelection(ticket.target.sessionId));
+        const after = readLive(ticket.target.sessionId);
+        if (after.agent !== live.agent || after.session !== live.session || !equal(after.current, ticket.next) || !equal(persisted, ticket.next)) throw fail('POSTCHECK_FAILED');
+      } else {
+        if (!equal(readDefault(), ticket.previous)) throw fail('STATE_CHANGED');
+        const receipt = await defaultModel.saveSelection({ ...ticket.next }, { ifCurrent: { ...ticket.previous } });
+        if (receipt?.status !== 'saved') throw fail('DEFAULT_CAS_REJECTED');
+        changed = true;
+        if (!equal(readDefault(), ticket.next)) throw fail('POSTCHECK_FAILED');
+      }
+      return { status: 'applied', target: clone(ticket.target), selected: { ...ticket.next },
+        safeToRemovePatches: false, removalBlockers: unsupported() };
+    } catch (error) {
+      // Host errors can include secrets: do not propagate messages or causes.
+      return { status: changed ? 'changed-unverified' : 'not-applied', code: knownCode(error),
+        mayHaveChanged: changed || ticket.target.kind === 'default', safeToRemovePatches: false,
+        removalBlockers: unsupported() };
+    } finally { busy = false; }
+  }
+  return { preview, apply, catalog: () => choices.map(({ provider, model, efforts }) => ({ provider, model, efforts: [...efforts] })) };
+}
+
+function knownCode(error) {
+  return ['LIVE_SESSION_UNSUPPORTED', 'SESSION_BUSY', 'SESSION_REVISION_UNAVAILABLE', 'STATE_CHANGED',
+    'FIXED_DEFAULT_UNSUPPORTED', 'DEFAULT_API_UNAVAILABLE', 'DEFAULT_CAS_REJECTED', 'ASYNC_SELECTION_UNSUPPORTED',
+    'DURABILITY_UNCONFIRMED', 'POSTCHECK_FAILED'].includes(error?.code) ? error.code : 'OPERATION_FAILED';
+}

package/src/maintenance-host.js

@@ -0,0 +1,250 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+const digest = value => crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const messages = {
+  inspection_unknown: '宿主依赖未完整验证。',
+  config_inspection_failed: '配置依赖未完整验证。',
+  default_inspection_failed: '默认模型依赖未完整验证。',
+  session_service_missing: '会话查询服务不可用，会话依赖未完整验证。',
+  session_inspection_failed: '部分会话依赖未完整验证。',
+  agent_inspection_failed: '部分智能体依赖未完整验证。',
+  activity_unverified: '部分任务活动状态未验证，请确认任务已结束。',
+  process_inspection_failed: '引擎进程活动状态未完整验证。',
+  profile_unknown: '部分配置组合依赖未完整验证。',
+  cross_profile_bundle: '其他配置仍安装或选择本插件，卸载后可能受影响。',
+  alias_dependency: '观察到多密钥模型路由，卸载后相关路由可能不可用。',
+  key_config_dependency: '观察到多密钥配置，维护不会自动删除这些配置。',
+  expression_unknown: '配置含动态表达式，无法证明不存在依赖。',
+  active_turns: '存在正在运行或维护中的任务，请先等待任务结束。',
+  other_process: '发现其他引擎进程，无法验证它们的活动状态。',
+};
+
+// These scalar configuration fields cannot supply a plugin, model route or key
+// collection. Unknown fields/roots remain conservative. Never infer safety from
+// expression text, plugin enablement, or a name/id that might itself be dynamic.
+const nonRouteScalars = new Set([
+  'apiKey', 'apiKeyEnv', 'baseURL', 'baseUrl', 'endpoint', 'timeout', 'timeoutMs',
+  'maxRetries', 'temperature', 'topP', 'maxTokens', 'contextWindow',
+  'enabled', 'disabled', 'label', 'description', 'locale', 'language', 'port', 'host',
+]);
+
+/** Pure scanner: never evaluates expressions or returns inspected values. */
+export function dependencySignals(value) {
+  const result = { alias: 0, keys: 0, expression: 0 };
+  const seen = new WeakSet();
+  const routeCollections = new Set(['providers', 'profiles', 'keyEntries', 'models', 'modelOverrides', 'allowedModels', 'plugins']);
+  const walk = (input, safeScalar = false, field, parentField) => {
+    if (typeof input === 'string') { if (input.startsWith('@dsh-key/')) result.alias++; return; }
+    if (!input || typeof input !== 'object') return;
+    if (Object.hasOwn(input, '__jsExpr')) {
+      if (!safeScalar) result.expression++;
+      return;
+    }
+    if (seen.has(input)) { result.expression++; return; }
+    seen.add(input);
+    if (!Array.isArray(input)) {
+      if (input.multiKey === true || (input.keyEntries && typeof input.keyEntries === 'object' && Object.keys(input.keyEntries).length)) result.keys++;
+      if (Object.hasOwn(input, 'multiKey') && typeof input.multiKey !== 'boolean' && !input.multiKey?.__jsExpr) result.expression++;
+      if (Object.hasOwn(input, 'keyEntries') && (!input.keyEntries || typeof input.keyEntries !== 'object' || Array.isArray(input.keyEntries))) result.expression++;
+    }
+    // Safety applies only to the immediate scalar slot, never a whole subtree.
+    const configFields = field === undefined || field === 'config' || ['value', 'base', 'user'].includes(field) || routeCollections.has(parentField);
+    for (const [key, child] of Object.entries(input)) walk(child,
+      configFields && !Array.isArray(input) && !routeCollections.has(field) && nonRouteScalars.has(key), key, field);
+    seen.delete(input);
+  };
+  walk(value);
+  return result;
+}
+
+// Fingerprints never serialize arbitrary host objects, credentials or expression text.
+// Unknown shapes remain an explicit inspection signal, not an assertion of safety.
+function routeProjection(value, ancestors = new WeakSet()) {
+  if (value === undefined || value === null) return value;
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'object' || ancestors.has(value)) throw new Error('Invalid route projection');
+  if (Object.hasOwn(value, '__jsExpr')) return { __jsExpr: true };
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) return value.map(item => routeProjection(item, ancestors));
+    const result = {};
+    for (const key of ['provider', 'model', 'reasoningEffort', 'agentProvider', 'agentModel', 'allowedModels']) {
+      if (!Object.hasOwn(value, key)) continue;
+      const child = value[key];
+      if (key === 'allowedModels') {
+        if (!Array.isArray(child)) throw new Error('Invalid route policy');
+      } else if (child != null && typeof child !== 'string' && !(typeof child === 'object' && Object.hasOwn(child, '__jsExpr'))) {
+        throw new Error('Invalid route scalar');
+      }
+      result[key] = routeProjection(child, ancestors);
+    }
+    return result;
+  } finally { ancestors.delete(value); }
+}
+
+/** Fold explicit routes only; message bodies and Session objects are never projected. */
+export function sessionDependencies(events) {
+  if (!Array.isArray(events)) throw new Error('Invalid session observation');
+  let lastUsed, pending;
+  const sameSelection = (a, b) => a && b && a.provider === b.provider && a.model === b.model && a.reasoningEffort === b.reasoningEffort;
+  const durable = [];
+  let openTurns = 0;
+  for (const event of events) {
+    if (!event || typeof event.type !== 'string') throw new Error('Invalid event observation');
+    if (event.type === 'model/selection') {
+      if (!event.data || typeof event.data.model !== 'string') throw new Error('Invalid selection observation');
+      pending = routeProjection(event.data);
+    }
+    if (event.type === 'request/header') {
+      const header = event.data?.header, route = header?.config;
+      if (!route || typeof route.provider !== 'string' || typeof route.model !== 'string') throw new Error('Invalid route observation');
+      lastUsed = routeProjection({ provider: route.provider, model: route.model,
+        reasoningEffort: header.adapterDefaults?.reasoningEffort === true ? undefined : route.reasoningEffort });
+      durable.push(lastUsed);
+      if (sameSelection(pending, lastUsed)) pending = undefined;
+    }
+    if (event.type === 'subagent/descriptor') {
+      if (typeof event.data?.agentModel !== 'string') throw new Error('Invalid descriptor observation');
+      durable.push(routeProjection({ provider: event.data.agentProvider, model: event.data.agentModel }));
+    }
+    if (event.type === 'subagent/model-selection-policy') {
+      if (!Array.isArray(event.data?.allowedModels)) throw new Error('Invalid policy observation');
+      durable.push(routeProjection(event.data.allowedModels));
+    }
+    if (event.type === 'turn/start') openTurns++;
+    if (event.type === 'turn/end') openTurns = Math.max(0, openTurns - 1);
+  }
+  return { routes: [pending ?? lastUsed, ...durable], openTurns };
+}
+
+/** Read-only inspection bounded to the supplied home and installation. No global-install claim. */
+export function createHostInspection(ctx, root, home) {
+  return async function inspect() {
+    const counts = new Map(), observations = new Set(), dependencies = new Set();
+    const block = (code, count = 1) => counts.set(code, (counts.get(code) || 0) + count);
+    const observe = value => {
+      const signals = dependencySignals(value), routes = [], seen = new WeakSet();
+      const collect = input => {
+        if (!input || typeof input !== 'object' || seen.has(input)) return;
+        seen.add(input);
+        if (Object.hasOwn(input, '__jsExpr')) return;
+        if (['provider', 'model', 'agentProvider', 'agentModel', 'allowedModels'].some(key => Object.hasOwn(input, key))) routes.push(routeProjection(input));
+        for (const child of Object.values(input)) collect(child);
+      };
+      collect(value);
+      const observation = digest([signals.alias > 0, signals.keys > 0, signals.expression > 0, routes]);
+      if (dependencies.has(observation)) return;
+      dependencies.add(observation);
+      observations.add(observation);
+      if (signals.alias) block('alias_dependency');
+      if (signals.keys) block('key_config_dependency');
+      if (signals.expression) block('expression_unknown');
+    };
+    try {
+      const require = createRequire(path.join(root, 'package.json'));
+      const boot = await import(pathToFileURL(require.resolve('@deepseek-ai/dsh-app-boot')).href);
+      const profile = ctx.profileContext;
+      if (!profile || !Array.isArray(profile.overlays) || fs.realpathSync(profile.home) !== fs.realpathSync(home)) throw new Error('Unknown launch scope');
+      const profilesRoot = path.join(home, boot.PROFILES_DIR);
+      const directories = fs.readdirSync(profilesRoot, { withFileTypes: true });
+      let currentFound = false;
+      for (const entry of directories.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory()) { block('profile_unknown'); continue; }
+        const dir = path.join(profilesRoot, entry.name);
+        const current = fs.realpathSync(dir) === fs.realpathSync(profile.dir);
+        currentFound ||= current;
+        try {
+          const manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+          observations.add(digest([entry.name, Object.hasOwn(manifest.dependencies || {}, 'dsh-model-groups'), manifest.dsh?.profile?.bundles?.includes('dsh-model-groups') === true]));
+          if (!current && (Object.hasOwn(manifest.dependencies || {}, 'dsh-model-groups') || manifest.dsh?.profile?.bundles?.includes('dsh-model-groups'))) block('cross_profile_bundle');
+          const loaded = boot.loadProfileDirectory('dsh', dir, profile.installAnchor, { readOnly: true });
+          if (loaded.skippedBundles.length) block('profile_unknown', loaded.skippedBundles.length);
+          const context = { ...profile, dir, patchPath: loaded.patchPath, home, overlays: current ? profile.overlays : [] };
+          const patches = boot.readProfilePatches('dsh', context, loaded);
+          // Scan raw layers too: disabled rows and overridden residual config must not disappear.
+          observe(patches);
+          // Raw layers retain disabled/overridden residues without composing or evaluating them.
+        } catch { block('profile_unknown'); }
+      }
+      if (!currentFound) block('profile_unknown');
+    } catch { block('profile_unknown'); }
+    try {
+      for (const { entry, inherited, override } of ctx.configEditor.configuration()) observe({
+        plugin: entry.options.name, config: entry.options.config, base: inherited, user: override,
+      });
+    } catch { block('config_inspection_failed'); }
+    try { observe(routeProjection(ctx.agentDefaultModel.currentSelection())); }
+    catch { block('default_inspection_failed'); }
+    // Do not call settings.describe: it evaluates expressions a second time.
+    try {
+      if (typeof ctx.sessionQuery?.listSessions !== 'function' || typeof ctx.sessionQuery?.readSession !== 'function') {
+        block('session_service_missing'); block('activity_unverified');
+      } else {
+        const sessions = await ctx.sessionQuery.listSessions();
+        if (!Array.isArray(sessions)) throw new Error('Invalid session list');
+        for (const record of sessions) {
+          try {
+            const id = record?.header?.id;
+            if (typeof id !== 'string' || !id) throw new Error('Invalid session identity');
+            observations.add(digest(['session', id, record.live === true]));
+            const loaded = await ctx.sessionQuery.readSession(id);
+            if (loaded.session?.id !== id) throw new Error('Invalid session snapshot identity');
+            if (!Array.isArray(loaded.events)) throw new Error('Invalid session events');
+            // Activity survives malformed route observations in this same snapshot.
+            let openTurns = 0;
+            for (const event of loaded.events) {
+              if (event?.type === 'turn/start') openTurns++;
+              if (event?.type === 'turn/end') openTurns = Math.max(0, openTurns - 1);
+            }
+            observations.add(digest(['activity', id, openTurns]));
+            if (record.live === true && openTurns) block('active_turns');
+            const state = sessionDependencies(loaded.events);
+            observe(state.routes);
+            observations.add(digest(['session', id, state.routes]));
+            // Historical unfinished turns are dependency observations, never activity locks.
+            if (typeof record.live !== 'boolean') block('activity_unverified');
+          } catch { block('session_inspection_failed'); block('activity_unverified'); }
+        }
+      }
+    } catch { block('session_inspection_failed'); block('activity_unverified'); }
+    try {
+      for (const agent of ctx.agents.list()) {
+        // Inspect activity independently: a broken model service must not hide a live agent.
+        try {
+          const status = agent.status, phase = agent.phase?.kind;
+          observations.add(digest(['agent', typeof agent.id === 'string' ? agent.id : null,
+            typeof status === 'string' ? status : null, typeof phase === 'string' ? phase : null]));
+          // Host status is idle/running; maintenance is an idle-status exclusive phase.
+          if (status === 'running' || phase === 'maintenance') block('active_turns');
+          else if (status !== 'idle' || (agent.phase && phase !== 'idle')) block('activity_unverified');
+        } catch { block('activity_unverified'); }
+        try { observe(routeProjection(agent.options)); observe(routeProjection(agent.model.current())); }
+        catch { block('agent_inspection_failed'); }
+      }
+    } catch { block('agent_inspection_failed'); block('activity_unverified'); }
+    // Bounded process observation: no credentials/configuration files are opened.
+    // A second Node DSH process is unknown, not presumed inactive. This is not a cross-home lock.
+    try {
+      for (const entry of fs.readdirSync('/proc', { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^\d+$/.test(entry.name) || Number(entry.name) === process.pid) continue;
+        let command;
+        try { command = fs.readFileSync(`/proc/${entry.name}/cmdline`, 'utf8').split('\0'); }
+        catch (error) { if (error.code === 'ENOENT' || error.code === 'ESRCH') continue; throw error; }
+        if (/(?:^|\/)node(?:js)?$/.test(command[0] || '') && command.slice(1).some(arg => {
+          if (!path.isAbsolute(arg)) return /^(?:dsh|@deepseek-ai\/dsh)(?:\/|$)/.test(arg);
+          const relative = path.relative(root, arg);
+          return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)
+            && /(?:^|\/)dsh(?:\/|$)|@deepseek-ai\/dsh/.test(arg);
+        })) {
+          block('other_process'); observations.add(digest(entry.name));
+        }
+      }
+    } catch { block('process_inspection_failed'); }
+    const blockers = [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([code, count]) => ({ code, message: messages[code], count }));
+    return { blockers, fingerprint: digest([[...observations].sort(), blockers]) };
+  };
+}