@ran-sh/dsh-crew 1.1.1 → 1.2.0-rc.5

package/src/config-readiness.mjs

@@ -1,145 +1,211 @@
-import { buildReadinessMatrix, READINESS_REASON_CODES } from './readiness-matrix.mjs';
-import { PRODUCTION_EXECUTION_PLANE, PRODUCTION_PROFILE, PRODUCTION_LISTEN_PORT } from './runtime-identity.mjs';
+import { buildReadinessMatrix, READINESS_REASON_CODES } from './readiness-matrix.mjs';
+import { PRODUCTION_EXECUTION_PLANE, PRODUCTION_PROFILE, PRODUCTION_LISTEN_PORT } from './runtime-identity.mjs';
 
-function warningCodes(catalogBody) {
+function warningCodes(catalogBody) {
   const hints = Array.isArray(catalogBody?.health?.hints) ? catalogBody.health.hints : [];
   return [...new Set(hints
     .filter((hint) => hint?.level === 'warning' && typeof hint?.code === 'string' && hint.code.trim())
     .map((hint) => hint.code.trim()))];
-}
-
-function verifiedHubJob(job) {
-  const context = job?.execution_context;
-  return job?.status === 'done'
-    && job?.task_status === 'success'
-    && job?.delivery_complete === true
-    && job?.workspace_evidence_ok === true
-    && context?.execution_plane === PRODUCTION_EXECUTION_PLANE
-    && context?.profile === PRODUCTION_PROFILE
-    && Number(context?.listen_port) === PRODUCTION_LISTEN_PORT
-    && typeof context?.runtime_id === 'string'
-    && context.runtime_id.trim().length > 0;
-}
-
-function structurallyConsistentProviderInventory(body) {
-  if (!body || typeof body !== 'object' || body.ok === false || !Array.isArray(body.records)) return false;
-  return body.records.every((record) => {
-    if (!record || typeof record.id !== 'string' || record.id.trim() === '') return false;
-    if (!['present', 'absent'].includes(record.desired_state)) return false;
-    if (!record.lifecycle || typeof record.lifecycle !== 'object' || Array.isArray(record.lifecycle)) return false;
-    for (const field of ['installed', 'configured', 'enabled', 'catalogued']) {
-      if (typeof record.lifecycle[field] !== 'boolean') return false;
-    }
-    if (record.desired_state === 'absent' && record.lifecycle.enabled === true) return false;
-    return true;
-  });
-}
-
-export function buildHubExecutionRows(hubJobs = []) {
-  const jobs = Array.isArray(hubJobs) ? hubJobs : [];
-  const workerPassed = jobs.some((job) => job?.role === 'worker' && verifiedHubJob(job));
-  const workerPrimaryPassed = jobs.some((job) => job?.role === 'worker'
-    && verifiedHubJob(job)
-    && Number(job?.attempt ?? job?.selection_trace?.logical_attempt ?? 0) === 0);
-  const workerEscalationPassed = jobs.some((job) => job?.role === 'worker'
-    && verifiedHubJob(job)
-    && (Number(job?.attempt ?? job?.selection_trace?.logical_attempt ?? 0) > 0));
-  const reviewerPassed = jobs.some((job) => job?.role === 'reviewer'
-    && verifiedHubJob(job)
-    && job?.review_verdict === 'approve');
-  return [
-    workerPassed
-      ? { id: 'model_execution', status: 'PASS', reason_code: 'REAL_EXECUTION_PASSED', evidence_source: 'hub-jobs' }
-      : { id: 'model_execution', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
-    workerPrimaryPassed
-      ? { id: 'worker_primary_callable', status: 'PASS', reason_code: 'WORKER_PRIMARY_CALLABLE', evidence_source: 'hub-jobs' }
-      : { id: 'worker_primary_callable', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
-    workerEscalationPassed
-      ? { id: 'worker_escalation_callable', status: 'PASS', reason_code: 'WORKER_ESCALATION_CALLABLE', evidence_source: 'hub-jobs' }
-      : { id: 'worker_escalation_callable', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
-    reviewerPassed
-      ? { id: 'reviewer_primary_callable', status: 'PASS', reason_code: 'REVIEWER_PRIMARY_CALLABLE', evidence_source: 'hub-jobs' }
-      : { id: 'reviewer_primary_callable', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
-    { id: 'provider_lifecycle_consistent', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
-    reviewerPassed
-      ? { id: 'reviewer_pipeline', status: 'PASS', reason_code: 'REAL_REVIEW_PASSED', evidence_source: 'hub-jobs' }
-      : { id: 'reviewer_pipeline', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
-  ];
-}
+}
+
+function verifiedHubJob(job) {
+  const context = job?.execution_context;
+  return job?.status === 'done'
+    && job?.task_status === 'success'
+    && job?.delivery_complete === true
+    && job?.workspace_evidence_ok === true
+    && context?.execution_plane === PRODUCTION_EXECUTION_PLANE
+    && context?.profile === PRODUCTION_PROFILE
+    && Number(context?.listen_port) === PRODUCTION_LISTEN_PORT
+    && typeof context?.runtime_id === 'string'
+    && context.runtime_id.trim().length > 0;
+}
+
+function hasBlockingProviderRecovery(body, currentSelections) {
+  if (!Object.hasOwn(body, 'recovery_transactions')) return false;
+  if (!Array.isArray(body.recovery_transactions)) return true;
+  const selectedProviders = new Set(Object.values(currentSelections ?? {})
+    .filter((selection) => selection?.ok === true && typeof selection.provider === 'string')
+    .map((selection) => selection.provider));
+  return body.recovery_transactions.some((transaction) => transaction?.unresolved === true
+    || typeof transaction?.provider_id !== 'string'
+    || selectedProviders.has(transaction.provider_id));
+}
+
+function structurallyConsistentProviderInventory(body, currentSelections) {
+  if (!body || typeof body !== 'object' || body.ok === false || !Array.isArray(body.records)) return false;
+  if ('lifecycle_evidence' in body && body.lifecycle_evidence?.ok !== true) return false;
+  if ('declaration_evidence' in body && body.declaration_evidence?.ok !== true) return false;
+  if ('default_evidence' in body && body.default_evidence?.ok !== true) return false;
+  if (hasBlockingProviderRecovery(body, currentSelections)) return false;
+  return body.records.every((record) => {
+    if (!record || typeof record.id !== 'string' || record.id.trim() === '') return false;
+    if (!['present', 'absent'].includes(record.desired_state)) return false;
+    if (!record.lifecycle || typeof record.lifecycle !== 'object' || Array.isArray(record.lifecycle)) return false;
+    for (const field of ['installed', 'configured', 'enabled', 'catalogued']) {
+      if (typeof record.lifecycle[field] !== 'boolean') return false;
+    }
+    if (record.desired_state === 'absent' && record.lifecycle.enabled === true) return false;
+    return true;
+  });
+}
+
+function matchesCurrentRoute(job, currentSelections, role) {
+  if (!currentSelections) return true;
+  const selectionKey = role === 'worker'
+    && Number(job?.attempt ?? job?.selection_trace?.logical_attempt ?? 0) > 0
+    && Object.hasOwn(currentSelections, 'worker_escalation')
+    ? 'worker_escalation'
+    : role;
+  if (!Object.hasOwn(currentSelections, selectionKey)) return true;
+  const selected = currentSelections[selectionKey];
+  return selected?.ok === true
+    && job?.provider === selected.provider
+    && job?.model === selected.model;
+}
+
+function safeDetailCode(value, fallback) {
+  return typeof value === 'string' && /^[A-Z][A-Z0-9_]{0,127}$/u.test(value) ? value : fallback;
+}
+
+function currentRouteHealthEvidence({ role, currentSelections, providerHealthChecked, providerHealthBody } = {}) {
+  if (!currentSelections || !Object.hasOwn(currentSelections, role)) return null;
+  const selected = currentSelections[role];
+  if (selected?.ok === false) {
+    return {
+      status: 'FAIL',
+      reason_code: 'PROVIDER_ROUTE_UNCALLABLE',
+      evidence_source: 'model-routing',
+      detail_code: safeDetailCode(selected.code, 'MODEL_ROUTE_UNAVAILABLE'),
+    };
+  }
+  if (!selected?.provider || !selected?.model || providerHealthChecked !== true) return null;
+  if (providerHealthBody?.ok === false) {
+    return { status: 'FAIL', reason_code: 'PROVIDER_HEALTH_UNAVAILABLE', evidence_source: 'provider-health' };
+  }
+  const health = Array.isArray(providerHealthBody?.health) ? providerHealthBody.health : [];
+  const observation = health.find((entry) => entry?.provider === selected.provider
+    && entry?.model === selected.model
+    && entry?.fresh === true);
+  if (!observation || observation.state === 'unprobed') return null;
+  if (observation.state === 'callable') {
+    return { status: 'PASS', reason_code: 'PROVIDER_ROUTE_CALLABLE', evidence_source: 'provider-health' };
+  }
+  const stateCode = String(observation.state ?? '').toUpperCase().replaceAll('-', '_');
+  return {
+    status: 'FAIL',
+    reason_code: 'PROVIDER_ROUTE_UNCALLABLE',
+    evidence_source: 'provider-health',
+    detail_code: safeDetailCode(observation.reason_code, safeDetailCode(stateCode, 'PROVIDER_UNCALLABLE')),
+  };
+}
+
+export function buildHubExecutionRows(hubJobs = [], { currentSelections = null } = {}) {
+  const jobs = Array.isArray(hubJobs) ? hubJobs : [];
+  const workerPassed = jobs.some((job) => job?.role === 'worker' && matchesCurrentRoute(job, currentSelections, 'worker') && verifiedHubJob(job));
+  const workerPrimaryPassed = jobs.some((job) => job?.role === 'worker'
+    && matchesCurrentRoute(job, currentSelections, 'worker')
+    && verifiedHubJob(job)
+    && Number(job?.attempt ?? job?.selection_trace?.logical_attempt ?? 0) === 0);
+  const workerEscalationPassed = jobs.some((job) => job?.role === 'worker'
+    && matchesCurrentRoute(job, currentSelections, 'worker')
+    && verifiedHubJob(job)
+    && (Number(job?.attempt ?? job?.selection_trace?.logical_attempt ?? 0) > 0));
+  const reviewerPassed = jobs.some((job) => job?.role === 'reviewer'
+    && matchesCurrentRoute(job, currentSelections, 'reviewer')
+    && verifiedHubJob(job)
+    && job?.review_verdict === 'approve');
+  return [
+    workerPassed
+      ? { id: 'model_execution', status: 'PASS', reason_code: 'REAL_EXECUTION_PASSED', evidence_source: 'hub-jobs' }
+      : { id: 'model_execution', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
+    workerPrimaryPassed
+      ? { id: 'worker_primary_callable', status: 'PASS', reason_code: 'WORKER_PRIMARY_CALLABLE', evidence_source: 'hub-jobs' }
+      : { id: 'worker_primary_callable', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
+    workerEscalationPassed
+      ? { id: 'worker_escalation_callable', status: 'PASS', reason_code: 'WORKER_ESCALATION_CALLABLE', evidence_source: 'hub-jobs' }
+      : { id: 'worker_escalation_callable', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
+    reviewerPassed
+      ? { id: 'reviewer_primary_callable', status: 'PASS', reason_code: 'REVIEWER_PRIMARY_CALLABLE', evidence_source: 'hub-jobs' }
+      : { id: 'reviewer_primary_callable', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
+    { id: 'provider_lifecycle_consistent', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
+    reviewerPassed
+      ? { id: 'reviewer_pipeline', status: 'PASS', reason_code: 'REAL_REVIEW_PASSED', evidence_source: 'hub-jobs' }
+      : { id: 'reviewer_pipeline', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE', evidence_source: 'none' },
+  ];
+}
 
 /**
  * Enrich the conservative runtime matrix with evidence the config report has
  * already collected. This function performs no I/O and never reads provider
  * configuration, credentials, quotas, pricing, or hidden catalog expectations.
  */
-export function buildConfigReadinessMatrix({
-  platform = process.platform,
-  hubCompatibility = null,
-  workerProviderMode = null,
-  providerCatalogChecked = false,
-  providerCatalogBody = null,
-  providerInventoryChecked = false,
-  providerInventoryBody = null,
-  providerHealthChecked = false,
-  providerHealthBody = null,
-  hubJobsChecked = false,
-  hubJobsBody = null,
-} = {}) {
+export function buildConfigReadinessMatrix({
+  platform = process.platform,
+  hubCompatibility = null,
+  workerProviderMode = null,
+  providerCatalogChecked = false,
+  providerCatalogBody = null,
+  providerInventoryChecked = false,
+  providerInventoryBody = null,
+  providerHealthChecked = false,
+  providerHealthBody = null,
+  hubJobsChecked = false,
+  hubJobsBody = null,
+  currentSelections = null,
+} = {}) {
   const warnings = warningCodes(providerCatalogBody);
   const catalogResponseOk = !!providerCatalogBody
     && typeof providerCatalogBody === 'object'
     && providerCatalogBody.ok !== false;
   const catalogOk = providerCatalogChecked && catalogResponseOk && warnings.length === 0;
 
-  const evidence = {};
-  const hubJobs = hubCompatibility?.compatible === true
-    && hubJobsChecked
-    && hubJobsBody?.ok !== false
-    && Array.isArray(hubJobsBody?.jobs)
-    ? hubJobsBody.jobs
-    : [];
-  for (const row of buildHubExecutionRows(hubJobs)) {
-    if (row.status === 'PASS') {
-      evidence[row.id] = {
-        status: row.status,
-        reason_code: row.reason_code,
-        evidence_source: row.evidence_source,
-      };
-    }
-  }
-  if (
+  const evidence = {};
+  const hubJobs = hubCompatibility?.compatible === true
+    && hubJobsChecked
+    && hubJobsBody?.ok !== false
+    && Array.isArray(hubJobsBody?.jobs)
+    ? hubJobsBody.jobs
+    : [];
+  for (const row of buildHubExecutionRows(hubJobs, { currentSelections })) {
+    if (row.status === 'PASS') {
+      evidence[row.id] = {
+        status: row.status,
+        reason_code: row.reason_code,
+        evidence_source: row.evidence_source,
+      };
+    }
+  }
+  if (
     workerProviderMode !== 'deepseek-official'
     && hubCompatibility?.compatible === true
     && providerCatalogChecked
     && catalogResponseOk
     && warnings.length > 0
-  ) {
+  ) {
     evidence.provider_catalog = {
       status: 'FAIL',
       reason_code: READINESS_REASON_CODES.PROVIDER_CATALOG_HEALTH_WARNING,
       evidence_source: 'harness-catalog',
     };
-  }
-
-  if (providerInventoryChecked) {
-    evidence.provider_lifecycle_consistent = structurallyConsistentProviderInventory(providerInventoryBody)
-      ? { status: 'PASS', reason_code: READINESS_REASON_CODES.PROVIDER_LIFECYCLE_CONSISTENT, evidence_source: 'provider-inventory' }
-      : {
-          status: 'FAIL',
-          reason_code: providerInventoryBody?.ok === false
-            ? READINESS_REASON_CODES.PROVIDER_INVENTORY_UNAVAILABLE
-            : READINESS_REASON_CODES.PROVIDER_LIFECYCLE_INCONSISTENT,
-          evidence_source: 'provider-inventory',
-        };
-  }
-
-  if (providerHealthChecked && providerHealthBody?.ok === false) {
-    evidence.provider_health = {
-      status: 'FAIL',
-      reason_code: 'PROVIDER_HEALTH_UNAVAILABLE',
-      evidence_source: 'provider-health',
-    };
-  }
+  }
+
+  if (providerInventoryChecked) {
+    evidence.provider_lifecycle_consistent = structurallyConsistentProviderInventory(providerInventoryBody, currentSelections)
+      ? { status: 'PASS', reason_code: READINESS_REASON_CODES.PROVIDER_LIFECYCLE_CONSISTENT, evidence_source: 'provider-inventory' }
+      : {
+          status: 'FAIL',
+          reason_code: providerInventoryBody?.ok === false
+            ? READINESS_REASON_CODES.PROVIDER_INVENTORY_UNAVAILABLE
+            : READINESS_REASON_CODES.PROVIDER_LIFECYCLE_INCONSISTENT,
+          evidence_source: 'provider-inventory',
+        };
+  }
+
+  for (const [role, rowId] of [['worker', 'provider_health'], ['reviewer', 'reviewer_health']]) {
+    const healthEvidence = currentRouteHealthEvidence({ role, currentSelections, providerHealthChecked, providerHealthBody });
+    if (healthEvidence) evidence[rowId] = healthEvidence;
+  }
 
   const matrix = buildReadinessMatrix({
     platform,

package/src/extension-contract.mjs

@@ -2,7 +2,9 @@
 // describes only DSH Crew and deliberately never advertises itself as a top-
 // level Executor or control plane.
 
-export const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
+import { validateModelCallabilityV2 } from './model-callability-contract.mjs';
+
+export const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
 
 function row(matrix, id) {
   return Array.isArray(matrix?.rows) ? matrix.rows.find((entry) => entry?.id === id) : undefined;
@@ -34,40 +36,56 @@ function readinessFromRow(entry, { pass = 'READY', notRun = 'DEGRADED' } = {}) {
   return component('UNAVAILABLE', entry.reason_code ?? 'CHECK_FAILED');
 }
 
-export function buildExtensionContract({ config = {}, readinessMatrix = {}, readinessSnapshot = null, workspace = null, profiles = null, runtime = null } = {}) {
-  const matrix = readinessSnapshot?.readiness_matrix ?? readinessMatrix;
+function modelReadinessFromSnapshot(readinessSnapshot, matrix, runtime, expectedEnabledRoles, now = Date.now()) {
+  const callability = readinessSnapshot?.model_callability;
+  const providerHealthEvidence = row(matrix, 'provider_health');
+  const catalogEvidence = row(matrix, 'provider_catalog');
+  if (callability && typeof callability === 'object') {
+    const validation = validateModelCallabilityV2({
+      projection: callability,
+      runtime,
+      expectedEnabledRoles,
+      expectedSelections: { worker: readinessSnapshot?.worker?.selected ?? null, reviewer: readinessSnapshot?.reviewer?.selected ?? null },
+      now,
+    });
+    if (validation.ok && validation.state === 'CALLABLE') return component('READY', 'CURRENT_MODEL_CALLABLE', { captured_at: callability.captured_at, expires_at: callability.expires_at, runtime_id: callability.current_runtime_id });
+    if (validation.ok && validation.state === 'NOT_CALLABLE') return component('UNAVAILABLE', callability.roles.worker?.state === 'NOT_CALLABLE' ? callability.roles.worker.reason_code : callability.roles.reviewer.reason_code ?? 'CURRENT_MODEL_NOT_CALLABLE');
+    if (validation.ok && validation.state === 'STALE') return component('DEGRADED', 'MODEL_EVIDENCE_STALE');
+    return component('DEGRADED', validation.reason_code ?? 'MODEL_CALLABILITY_UNKNOWN');
+  }
+  if (providerHealthEvidence?.status === 'FAIL') return readinessFromRow(providerHealthEvidence);
+  if (catalogEvidence?.status === 'FAIL') return readinessFromRow(catalogEvidence);
+  if (providerHealthEvidence || catalogEvidence) return component('DEGRADED', 'MODEL_CALLABILITY_NOT_PROJECTED');
+  return component('UNAVAILABLE', 'MODEL_CALLABILITY_NOT_PROJECTED');
+}
+
+export function buildExtensionContract({ config = {}, readinessMatrix = {}, readinessSnapshot = null, workspace = null, profiles = null, runtime = null } = {}) {
+  const matrix = readinessSnapshot?.readiness_matrix ?? readinessMatrix;
   const workerEnabled = config.subagents_enabled !== false && config.worker_state !== 'disabled';
   const reviewerEnabled = config.subagents_enabled !== false && config.review_state !== 'disabled';
-  const realModelEvidence = ['worker_primary_callable', 'model_execution', 'worker_escalation_callable', 'deepseek_flash', 'deepseek_pro']
-    .map((id) => row(matrix, id))
-    .find((entry) => entry?.status === 'PASS');
-  const catalogEvidence = row(matrix, 'provider_catalog');
-  const lifecycleEvidence = row(matrix, 'provider_lifecycle_consistent');
-  const modelReadiness = catalogEvidence?.status === 'FAIL'
-    ? readinessFromRow(catalogEvidence)
-    : realModelEvidence
-      ? component('READY', realModelEvidence.reason_code ?? 'MODEL_EXECUTION_PASSED')
-      : catalogEvidence?.status === 'PASS' || catalogEvidence?.status === 'SKIP'
-        ? component('DEGRADED', 'MODEL_CATALOG_ONLY')
-        : component('UNAVAILABLE', catalogEvidence?.reason_code ?? 'NO_EVIDENCE');
-  const components = {
-    harness: readinessFromRow(row(matrix, 'hub_compatibility')),
-    provider_lifecycle: lifecycleEvidence
-      ? readinessFromRow(lifecycleEvidence, { notRun: 'DEGRADED' })
-      : component('DEGRADED', 'PROVIDER_LIFECYCLE_NOT_CHECKED'),
-    model: modelReadiness,
+  const reviewerHealthEvidence = row(matrix, 'reviewer_health');
+  const lifecycleEvidence = row(matrix, 'provider_lifecycle_consistent');
+  const modelReadiness = modelReadinessFromSnapshot(readinessSnapshot, matrix, runtime, { worker: workerEnabled, reviewer: reviewerEnabled });
+  const components = {
+    harness: readinessFromRow(row(matrix, 'hub_compatibility')),
+    provider_lifecycle: lifecycleEvidence
+      ? readinessFromRow(lifecycleEvidence, { notRun: 'DEGRADED' })
+      : component('DEGRADED', 'PROVIDER_LIFECYCLE_NOT_CHECKED'),
+    model: modelReadiness,
     workspace: workspaceComponent(workspace),
     reviewer: reviewerEnabled
-      ? readinessFromRow(row(matrix, 'reviewer_pipeline'))
-      : component('DEGRADED', 'REVIEWER_DISABLED'),
+      ? reviewerHealthEvidence?.status === 'FAIL'
+        ? readinessFromRow(reviewerHealthEvidence)
+        : readinessFromRow(row(matrix, 'reviewer_pipeline'))
+      : component('NOT_APPLICABLE', 'REVIEWER_DISABLED'),
   };
-  const states = Object.values(components).map((entry) => entry.status);
+  const states = Object.entries(components).filter(([key]) => key !== 'reviewer' || reviewerEnabled).map(([, entry]) => entry.status);
   const readiness = states.includes('UNAVAILABLE') ? 'UNAVAILABLE' : states.includes('DEGRADED') ? 'DEGRADED' : 'READY';
   return {
     schema_version: EXTENSION_CONTRACT_SCHEMA_VERSION,
     kind: 'dsh-crew-extension',
-    runtime: runtime ?? null,
-    ...(readinessSnapshot ? { readiness_snapshot: readinessSnapshot } : {}),
+    runtime: runtime ?? null,
+    ...(readinessSnapshot ? { readiness_snapshot: readinessSnapshot } : {}),
     capabilities: {
       'deepseek.worker': workerEnabled,
       'deepseek.reviewer': reviewerEnabled,

package/src/history/admission-gate.mjs

@@ -0,0 +1,51 @@
+/**
+ * Crew-profile-only runtime adapter. Fence the public agent creation entry,
+ * including creations still awaiting publication in the official agent list.
+ * Callers must persist their maintenance marker BEFORE asking idle().
+ * No original agent is cancelled or disposed by this adapter.
+ */
+const installed = new WeakSet();
+const guarded = Symbol.for('dsh-crew.history.admission');
+function method(object, name) {
+  for (let current = object; current; current = Object.getPrototypeOf(current)) {
+    const descriptor = Object.getOwnPropertyDescriptor(current, name);
+    if (descriptor) return descriptor.value;
+  }
+}
+
+export function installHistoryAdmissionGate(agents, isMaintenancePending) {
+  if (typeof agents?.create !== 'function' || typeof agents?.list !== 'function'
+    || typeof isMaintenancePending !== 'function') throw new Error('HISTORY_ADMISSION_UNAVAILABLE');
+  if (installed.has(agents)) throw new Error('HISTORY_ADMISSION_ALREADY_INSTALLED');
+  const entries = ['create', 'resume'].filter(name => typeof method(agents, name) === 'function')
+    .map(name => ({ name, original: method(agents, name), wrapper: null }));
+  if (!entries.some(entry => entry.name === 'create')) throw new Error('HISTORY_ADMISSION_UNAVAILABLE');
+  if (entries.some(entry => entry.original[guarded])) throw new Error('HISTORY_ADMISSION_ALREADY_INSTALLED');
+  let creating = 0;
+  for (const entry of entries) {
+    entry.wrapper = async function(...args) {
+      if (isMaintenancePending()) throw new Error('HISTORY_MAINTENANCE_PENDING');
+      creating += 1;
+      try { return await entry.original.apply(this, args); }
+      finally { creating -= 1; }
+    };
+    entry.wrapper[guarded] = true;
+    agents[entry.name] = entry.wrapper;
+  }
+  installed.add(agents);
+  return {
+    idle() {
+      // Cordis returns fresh traceable callable proxies; compare descriptors,
+      // not the per-access wrapper returned by agents.create/resume.
+      if (entries.some(entry => method(agents, entry.name) !== entry.wrapper)) return false;
+      try {
+        const live = agents.list();
+        return Array.isArray(live) && creating === 0 && live.length === 0;
+      } catch { return false; }
+    },
+    dispose() {
+      for (const entry of entries) if (method(agents, entry.name) === entry.wrapper) agents[entry.name] = entry.original;
+      installed.delete(agents);
+    },
+  };
+}