dsh-harbor-evolution 0.7.2 → 0.8.0

package/lib/evolution.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 
 import { MANIFEST_NAME, snapshotCandidate } from './candidate.js'
@@ -8,17 +8,50 @@ export function resolveWithin(root, value, label) {
   const base = path.resolve(root)
   const resolved = path.resolve(base, value)
   if (resolved !== base && !resolved.startsWith(`${base}${path.sep}`)) {
-    throw new Error(`${label} must stay under projectRoot`)
+    throw new Error(
+      `PATH_OUTSIDE_PROJECT_ROOT: ${label} must stay under projectRoot.\n` +
+      `projectRoot: ${base}\n` +
+      `${label}: ${value}\n` +
+      'Recommended fix: use a path inside the current Agent session directory, or open the intended project as the session working directory. The Web Workbench projectRoot can be switched and reloaded in Harbor settings.',
+    )
   }
   return resolved
 }
 
+const META_ARTIFACT_INDEX = '.harbor/meta-artifacts.json'
+
+function inferEvaluationRoot(projectRoot, artifactPath, explicitRoot) {
+  if (explicitRoot) return resolveWithin(projectRoot, explicitRoot, 'evaluationRoot')
+  const relative = path.relative(projectRoot, artifactPath)
+  const parts = relative.split(path.sep)
+  const marker = parts.lastIndexOf('.harbor')
+  return marker >= 0 ? path.resolve(projectRoot, ...parts.slice(0, marker)) : path.resolve(projectRoot)
+}
+
+async function recordMetaArtifact(config, artifactPath, key, explicitRoot) {
+  const evaluationRoot = inferEvaluationRoot(config.projectRoot, artifactPath, explicitRoot)
+  const registeredArtifact = resolveWithin(evaluationRoot, artifactPath, key)
+  const indexPath = resolveWithin(evaluationRoot, META_ARTIFACT_INDEX, 'metaArtifactIndex')
+  let current = { schema_version: 1, artifacts: {} }
+  try {
+    const parsed = JSON.parse(await readFile(indexPath, 'utf8'))
+    if (parsed?.schema_version === 1 && parsed.artifacts && typeof parsed.artifacts === 'object') current = parsed
+  } catch (error) {
+    if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error
+  }
+  current.artifacts[key] = path.relative(evaluationRoot, registeredArtifact).split(path.sep).join('/')
+  await mkdir(path.dirname(indexPath), { recursive: true })
+  const temporary = `${indexPath}.${process.pid}.tmp`
+  await writeFile(temporary, `${JSON.stringify(current, null, 2)}\n`, 'utf8')
+  await rename(temporary, indexPath)
+  return path.relative(config.projectRoot, indexPath).split(path.sep).join('/')
+}
+
 export async function snapshot(config, args) {
   const candidateDir = resolveWithin(config.projectRoot, args.candidatePath, 'candidatePath')
   return snapshotCandidate(candidateDir, {
     candidateId: args.candidateId,
     version: args.version,
-    runtimeVersion: config.dshVersion,
   })
 }
 
@@ -33,6 +66,73 @@ export function makeJobName(manifest, now = new Date()) {
   return `${identity}-${suffix}`
 }
 
+export function makeHistoricalJobName(batch, now = new Date()) {
+  const timestamp = now.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/[-:]/g, '')
+  const digest = String(batch?.digest ?? '').replace(/^sha256:/, '').slice(0, 8) || 'historical'
+  return `dsh-session-history-${timestamp}-${digest}`
+}
+
+const HISTORICAL_COVERAGE_KEYS = [
+  'scored_trials',
+  'unscored_trials',
+  'total_trials',
+  'trial_rate',
+  'criterion_scored',
+  'criterion_total',
+  'criterion_rate',
+]
+
+function historicalCoverageMatches(summaryCoverage, completionCoverage) {
+  if (!summaryCoverage || !completionCoverage) return false
+  return HISTORICAL_COVERAGE_KEYS.every(key => (
+    typeof summaryCoverage[key] === 'number'
+    && summaryCoverage[key] === completionCoverage[key]
+  ))
+}
+
+/**
+ * Harbor 0.21 treats Job-plugin finalization failures as warnings, so a zero
+ * process exit is not proof that Historical artifacts completed. Validate the
+ * fresh plugin-owned sentinel and its core Summary cross-links fail-closed.
+ */
+export function assertHistoricalCompletion(summary, completion, {
+  jobName,
+  batchDigest,
+  batchId,
+  recordCount,
+}) {
+  const summaryValid = (
+    summary?.schema_version === 4
+    && summary?.job === jobName
+    && summary?.job_kind === 'historical-generation-evaluation'
+    && summary?.mode === 'diagnostic'
+    && summary?.execution_mode === 'observe-existing'
+    && summary?.evaluation_target?.digest === batchDigest
+    && summary?.evaluation_target?.batch_id === batchId
+    && summary?.evaluation_target?.record_count === recordCount
+    && summary?.n_trials === recordCount
+    && summary?.coverage?.total_trials === recordCount
+    && summary?.artifact_validation?.valid === true
+    && summary?.candidate === undefined
+  )
+  if (!summaryValid) {
+    throw new Error('HISTORICAL_JOB_IDENTITY_INVALID: the Summary is not a validated, Candidate-free Historical Generation Evaluation for this Batch')
+  }
+  const completionValid = (
+    completion?.schema_version === 1
+    && completion?.job_kind === 'historical-generation-evaluation'
+    && completion?.status === 'completed'
+    && completion?.valid === true
+    && completion?.job === jobName
+    && completion?.summary_path === 'evaluation-summary.json'
+    && completion?.artifact_registry_path === 'artifact-registry.json'
+    && historicalCoverageMatches(summary.coverage, completion.coverage)
+  )
+  if (!completionValid) {
+    throw new Error('HISTORICAL_JOB_ARTIFACT_VALIDATION_FAILED: the completion sentinel is missing, stale, or inconsistent with the validated Summary')
+  }
+}
+
 async function cliJson(config, args, { allowedExitCodes = [0], input } = {}) {
   let result
   try {
@@ -80,7 +180,7 @@ export async function updateEvaluator(config, args) {
 
 export async function initializeGroundTruth(config, args) {
   const output = resolveWithin(config.projectRoot, args.outputPath ?? '.harbor/ground-truth.json', 'outputPath')
-  return cliJson(config, [
+  const result = await cliJson(config, [
     'ground-truth', 'init',
     '--project-root', config.projectRoot,
     '--output', output,
@@ -91,19 +191,25 @@ export async function initializeGroundTruth(config, args) {
     '--provenance', String(args.provenance ?? ''),
     '--criteria', String(args.criteria ?? ''),
   ])
+  result.artifact_index = await recordMetaArtifact(config, output, 'ground_truth', args.evaluationRoot)
+  return result
 }
 
 export async function runMetaEvaluation(config, args) {
   const groundTruth = resolveWithin(config.projectRoot, args.groundTruthPath ?? '.harbor/ground-truth.json', 'groundTruthPath')
   const observations = resolveWithin(config.projectRoot, args.observationsPath, 'observationsPath')
   const output = resolveWithin(config.projectRoot, args.outputPath ?? '.harbor/meta-evaluation-report.json', 'outputPath')
-  return cliJson(config, [
+  const result = await cliJson(config, [
     'meta-evaluate',
     '--project-root', config.projectRoot,
     '--ground-truth', groundTruth,
     '--observations', observations,
     '--output', output,
   ])
+  const evaluationRoot = args.evaluationRoot
+    ?? inferEvaluationRoot(config.projectRoot, groundTruth)
+  result.artifact_index = await recordMetaArtifact(config, output, 'meta_evaluation_report', evaluationRoot)
+  return result
 }
 
 function strictInputs(config, args) {
@@ -132,6 +238,63 @@ function candidateModelCliArgs(binding) {
   ]
 }
 
+export function redactDiagnostic(value) {
+  return String(value ?? '')
+    .replace(/(authorization\s*[:=]\s*(?:bearer\s+)?)[^\s,'"}]+/gi, '$1[redacted]')
+    .replace(/(bearer\s+)[A-Za-z0-9._~+\/-]+/gi, '$1[redacted]')
+    .replace(/((?:api[_-]?key|token|secret|password)\s*[:=]\s*)[^\s,'"}]+/gi, '$1[redacted]')
+}
+
+export function classifyHarborFailure(value) {
+  const text = String(value ?? '')
+  const suggestions = []
+  if (/AgentSetupTimeoutError|agent setup.{0,30}time(?:d out|out)/i.test(text)) {
+    suggestions.push({ code: 'AGENT_SETUP_TIMEOUT', action: 'Use a base image with Python, curl, Node.js, npm, and ACP/DSH dependencies already installed; then rerun Doctor.' })
+  }
+  if (/evaluation-result\.json is missing/i.test(text)) {
+    suggestions.push({ code: 'EVALUATOR_RESULT_MISSING', action: 'Update tests/test.sh or its evaluator script to write /logs/verifier/evaluation-result.json using evaluation-result/v1.' })
+  }
+  if (/Either datasets or tasks must be provided|HARBOR_RUNTIME_NO_TASKS/i.test(text)) {
+    suggestions.push({ code: 'DATASET_NOT_RESOLVED', action: 'Make the Dataset root contain immediate Task subdirectories with schema_version = "1.4", [task] name = "org/name", instruction.md, environment/, and tests/test.sh.' })
+  }
+  if (/docker-credential-|credential helper/i.test(text)) {
+    suggestions.push({ code: 'DOCKER_CREDENTIAL_HELPER', action: 'Repair the configured Docker credential helper or use a verified image already present in the local Docker daemon.' })
+  }
+  if (/Cannot connect to the Docker daemon|DOCKER_DAEMON_UNAVAILABLE/i.test(text)) {
+    suggestions.push({ code: 'DOCKER_DAEMON_UNAVAILABLE', action: 'Start Docker and confirm `docker version` can reach the server.' })
+  }
+  if (!suggestions.length) {
+    suggestions.push({ code: 'INSPECT_JOB_LOG', action: 'Review the stderr/job.log excerpt below, fix the first causal error, rerun Doctor, then retry the Job.' })
+  }
+  return suggestions
+}
+
+async function optionalTail(pathname, maxChars = 6000) {
+  try {
+    const value = await readFile(pathname, 'utf8')
+    return value.slice(-maxChars)
+  } catch {
+    return ''
+  }
+}
+
+export async function explainHarborFailure(error, jobDir) {
+  const stderr = error?.result?.stderr ?? ''
+  const stdout = error?.result?.stdout ?? ''
+  const logCandidates = ['job.log', 'harbor.log']
+  const logParts = (await Promise.all(logCandidates.map(name => optionalTail(path.join(jobDir, name)))))
+    .filter(Boolean)
+  const detail = redactDiagnostic([stderr.slice(-8000), ...logParts, stdout.slice(-2000)].filter(Boolean).join('\n'))
+  const suggestions = classifyHarborFailure(detail || error?.message)
+  const lines = [
+    `HARBOR_JOB_FAILED: Harbor exited with code ${error?.result?.code ?? 'unknown'}.`,
+    `jobPath: ${jobDir}`,
+    ...suggestions.map(item => `nextStep[${item.code}]: ${item.action}`),
+  ]
+  if (detail.trim()) lines.push('diagnosticTail:', detail.trim())
+  return new Error(lines.join('\n'))
+}
+
 export async function validateDataset(config, args) {
   const dataset = resolveWithin(config.projectRoot, args.datasetPath, 'datasetPath')
   return cliJson(config, ['dataset', 'validate', dataset, '--project-root', config.projectRoot], { allowedExitCodes: [0, 2] })
@@ -148,12 +311,23 @@ export async function initializeProject(config, args) {
     '--judge-provider', args.judgeProvider, '--judge-model', args.judgeModel, '--judge-version', args.judgeVersion,
     '--policy-id', args.policyId, '--policy-version', args.policyVersion,
     '--min-improvement', String(args.minImprovement),
+    '--workspace-subdir', String(args.workspaceSubdir ?? '.'),
+  ])
+}
+
+export async function initializeQuickDiagnostic(config, args) {
+  return cliJson(config, [
+    'quick', 'diagnostic',
+    '--project-root', config.projectRoot,
+    '--query', String(args.query ?? ''),
+    '--rubric', String(args.rubric ?? ''),
+    '--workspace-subdir', String(args.workspaceSubdir ?? 'harbor-diagnostic'),
   ])
 }
 
 export async function runDoctor(config, args) {
   const inputs = strictInputs(config, { ...args, mode: args.mode ?? 'diagnostic' })
-  const command = ['doctor', '--architecture', '--project-root', inputs.projectRoot, '--stack', inputs.stack, '--dataset', inputs.dataset]
+  const command = ['doctor', '--architecture', '--runtime', '--project-root', inputs.projectRoot, '--stack', inputs.stack, '--dataset', inputs.dataset]
   if (args.candidatePath) command.push('--candidate', inputs.candidate)
   if (inputs.policy) command.push('--policy', inputs.policy)
   return cliJson(config, command, { allowedExitCodes: [0, 2] })
@@ -180,9 +354,16 @@ export async function runEvaluation(config, args, modelRuntime) {
   const inputs = strictInputs(config, args)
   const datasetValidation = await validateDataset(config, args)
   if (!datasetValidation.valid) {
-    throw new Error(`Dataset validation failed: ${datasetValidation.findings.map(item => item.code).join(', ')}`)
+    throw new Error(
+      `Dataset validation failed under projectRoot ${inputs.projectRoot}:\n` +
+      datasetValidation.findings.map(item => `${item.code}: ${item.message}`).join('\n'),
+    )
   }
   const doctor = await runDoctor(config, args)
+  const runtimeBlockers = doctor.findings.filter(item => item.level === 'error' && item.code.startsWith('DOCKER_'))
+  if (runtimeBlockers.length) {
+    throw new Error(`Runtime Doctor blocked Harbor Job:\n${runtimeBlockers.map(item => `${item.code}: ${item.message}`).join('\n')}`)
+  }
   if (inputs.mode === 'promotion-eligible' && !doctor.promotion_ready) {
     throw new Error(`Architecture Doctor blocked promotion-eligible Job: ${doctor.findings.filter(item => item.level === 'error').map(item => item.code).join(', ')}`)
   }
@@ -226,20 +407,25 @@ export async function runEvaluation(config, args, modelRuntime) {
     jobName,
   })
   try {
-    const processResult = await runProcess(config.harborBin, harborArgs, {
-      cwd: config.projectRoot,
-      timeoutMs: config.timeoutMs,
-      env: {
-        ...process.env,
-        ...(config.pythonPath ? { PYTHONPATH: config.pythonPath } : {}),
-        HSE_MODEL_GATEWAY_URL: lease.endpoint,
-        HSE_MODEL_GATEWAY_TOKEN: lease.token,
-        HSE_MODEL_GATEWAY_PROVIDER: lease.candidateProvider,
-        HSE_MODEL_GATEWAY_INFO: JSON.stringify(lease.modelInfo),
-        HSE_MODEL_GATEWAY_PROTOCOL: lease.protocol,
-      },
-    })
     const jobDir = path.join(inputs.jobs, jobName)
+    let processResult
+    try {
+      processResult = await runProcess(config.harborBin, harborArgs, {
+        cwd: config.projectRoot,
+        timeoutMs: config.timeoutMs,
+        env: {
+          ...process.env,
+          ...(config.pythonPath ? { PYTHONPATH: config.pythonPath } : {}),
+          HSE_MODEL_GATEWAY_URL: lease.endpoint,
+          HSE_MODEL_GATEWAY_TOKEN: lease.token,
+          HSE_MODEL_GATEWAY_PROVIDER: lease.candidateProvider,
+          HSE_MODEL_GATEWAY_INFO: JSON.stringify(lease.modelInfo),
+          HSE_MODEL_GATEWAY_PROTOCOL: lease.protocol,
+        },
+      })
+    } catch (error) {
+      throw await explainHarborFailure(error, jobDir)
+    }
     const summary = JSON.parse(await readFile(path.join(jobDir, 'evaluation-summary.json'), 'utf8'))
     return {
       manifest,
@@ -255,6 +441,128 @@ export async function runEvaluation(config, args, modelRuntime) {
   }
 }
 
+/**
+ * Materialize an immutable Historical Generation Batch before Harbor creates
+ * its Job, then run a deterministic Observation Adapter. This path never
+ * snapshots or executes a Candidate.
+ */
+export async function runHistoricalEvaluation(config, args, modelRuntime) {
+  const projectRoot = path.resolve(config.projectRoot)
+  const batchPath = resolveWithin(projectRoot, args.batchPath, 'batchPath')
+  const batchDir = resolveWithin(projectRoot, args.batchDir ?? path.dirname(batchPath), 'batchDir')
+  const output = resolveWithin(projectRoot, path.join(batchDir, 'dataset'), 'historicalDataset')
+  if (!args.judgeBinding?.provider || !args.judgeBinding?.model) {
+    throw new Error('Historical Judge model binding is required before materialization')
+  }
+  const materialized = await cliJson(config, [
+    'historical', 'materialize',
+    '--project-root', projectRoot,
+    '--batch', batchPath,
+    '--output', output,
+    '--judge-provider', args.judgeBinding.provider,
+    '--judge-model', args.judgeBinding.model,
+    ...(args.judgeBinding.reasoning_effort === undefined
+      ? []
+      : ['--judge-reasoning-effort', args.judgeBinding.reasoning_effort]),
+  ])
+  const dataset = resolveWithin(projectRoot, materialized.dataset_path ?? output, 'historicalDataset')
+  const stack = resolveWithin(projectRoot, materialized.stack_path, 'historicalStack')
+  const batch = JSON.parse(await readFile(batchPath, 'utf8'))
+  const jobs = resolveWithin(projectRoot, config.jobsDir, 'jobsDir')
+  const jobName = args.jobName ?? makeHistoricalJobName(batch)
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(jobName)) {
+    throw new Error('jobName contains unsupported characters')
+  }
+  const agentImportPath = config.historicalAgentImportPath
+    ?? 'harbor_dsh_evolution.session_agent:SessionObservationAgent'
+  const pluginImportPath = config.historicalPluginImportPath
+    ?? 'dsh-historical-evaluation'
+  const harborArgs = [
+    'run', '-y', '-p', dataset,
+    '-a', agentImportPath,
+    '--job-name', jobName,
+    '--jobs-dir', jobs,
+    '--plugin', pluginImportPath,
+    '--plugin-kwarg', `batch_path=${batchPath}`,
+    '--plugin-kwarg', `dataset_path=${dataset}`,
+    '--plugin-kwarg', `stack_path=${stack}`,
+    '--plugin-kwarg', `project_root=${projectRoot}`,
+    '--plugin-kwarg', 'mode=diagnostic',
+  ]
+  const lease = await modelRuntime.openLease(args.judgeBinding, {
+    candidateDigest: batch.digest,
+    jobName,
+  })
+  const jobDir = path.join(jobs, jobName)
+  try {
+    let processResult
+    try {
+      processResult = await runProcess(config.harborBin, harborArgs, {
+        cwd: projectRoot,
+        timeoutMs: config.timeoutMs,
+        env: {
+          ...process.env,
+          ...(config.pythonPath ? { PYTHONPATH: config.pythonPath } : {}),
+          HSE_JUDGE_GATEWAY_URL: lease.endpoint,
+          HSE_JUDGE_GATEWAY_TOKEN: lease.token,
+          HSE_JUDGE_GATEWAY_PROVIDER: lease.candidateProvider,
+          HSE_JUDGE_GATEWAY_INFO: JSON.stringify({
+            protocol: lease.protocol,
+            candidate_digest: batch.digest,
+            job: jobName,
+            binding: {
+              provider: args.judgeBinding.provider,
+              model: args.judgeBinding.model,
+              ...(args.judgeBinding.reasoning_effort === undefined
+                ? {}
+                : { reasoning_effort: args.judgeBinding.reasoning_effort }),
+            },
+            model_info: lease.modelInfo,
+          }),
+          HSE_JUDGE_GATEWAY_PROTOCOL: lease.protocol,
+        },
+      })
+    } catch (error) {
+      throw await explainHarborFailure(error, jobDir)
+    }
+    let summary
+    let completion
+    try {
+      summary = JSON.parse(await readFile(path.join(jobDir, 'evaluation-summary.json'), 'utf8'))
+      completion = JSON.parse(await readFile(path.join(jobDir, 'historical-evaluation-complete.json'), 'utf8'))
+    } catch (error) {
+      throw new Error(
+        `HISTORICAL_JOB_INCOMPLETE: Harbor exited successfully but the Historical plugin did not write its summary/completion sentinel (${error.message})`,
+      )
+    }
+    assertHistoricalCompletion(summary, completion, {
+      jobName,
+      batchDigest: batch.digest,
+      batchId: batch.batch_id,
+      recordCount: Array.isArray(batch.records) ? batch.records.length : undefined,
+    })
+    return {
+      judgeModelBinding: {
+        provider: args.judgeBinding.provider,
+        model: args.judgeBinding.model,
+        ...(args.judgeBinding.reasoning_effort === undefined
+          ? {}
+          : { reasoning_effort: args.judgeBinding.reasoning_effort }),
+      },
+      job: path.relative(projectRoot, jobDir).split(path.sep).join('/'),
+      summary,
+      completion,
+      materialized: {
+        dataset: path.relative(projectRoot, dataset).split(path.sep).join('/'),
+        stack: path.relative(projectRoot, stack).split(path.sep).join('/'),
+      },
+      process: { code: processResult.code },
+    }
+  } finally {
+    await lease.close()
+  }
+}
+
 export async function readEvaluation(config, args) {
   const jobDir = resolveWithin(config.projectRoot, args.jobPath, 'jobPath')
   return JSON.parse(await readFile(path.join(jobDir, 'evaluation-summary.json'), 'utf8'))

package/lib/model-runtime.js

@@ -74,26 +74,71 @@ export class CandidateModelRuntime {
     this.config = config
   }
 
-  async resolve(args = {}) {
+  async resolveCurrent() {
+    const inherited = this.ctx.agentDefaultModel.currentSelection()
+    return this.resolve({
+      candidateProvider: inherited.provider,
+      candidateModel: inherited.model,
+      candidateReasoningEffort: inherited.reasoningEffort,
+    }, undefined, { ignoreConfigured: true })
+  }
+
+  async currentBinding() {
+    const binding = await this.resolveCurrent()
+    return {
+      schema_version: 1,
+      source: 'skill-agent-default',
+      provider: binding.provider,
+      model: binding.model,
+      ...(binding.reasoning_effort === undefined
+        ? {}
+        : { reasoning_effort: binding.reasoning_effort }),
+    }
+  }
+
+  async resolve(args = {}, pinnedBinding, { ignoreConfigured = false } = {}) {
     const explicitProvider = nonBlank(args.candidateProvider)
     const explicitModel = nonBlank(args.candidateModel)
     if (Boolean(explicitProvider) !== Boolean(explicitModel)) {
       throw new Error('candidateProvider and candidateModel must be supplied together')
     }
-    const configuredProvider = nonBlank(this.config.candidateProvider)
-    const configuredModel = nonBlank(this.config.candidateModel)
+    const configuredProvider = ignoreConfigured ? undefined : nonBlank(this.config.candidateProvider)
+    const configuredModel = ignoreConfigured ? undefined : nonBlank(this.config.candidateModel)
     if (Boolean(configuredProvider) !== Boolean(configuredModel)) {
       throw new Error('Harbor candidateProvider and candidateModel configuration must be supplied together')
     }
 
+    const pinnedProvider = nonBlank(pinnedBinding?.provider)
+    const pinnedModel = nonBlank(pinnedBinding?.model)
+    if (Boolean(pinnedProvider) !== Boolean(pinnedModel)) {
+      throw new Error('Candidate model-binding.json requires provider and model')
+    }
+    const pinnedReasoning = nonBlank(pinnedBinding?.reasoning_effort)
+    if (pinnedProvider && explicitProvider && (
+      explicitProvider !== pinnedProvider
+      || explicitModel !== pinnedModel
+      || (nonBlank(args.candidateReasoningEffort) ?? undefined) !== pinnedReasoning
+    )) {
+      throw new Error('CANDIDATE_MODEL_BINDING_CONFLICT: explicit Job model arguments do not match model-binding.json; create a new Candidate for a different model identity')
+    }
+    if (pinnedProvider && configuredProvider && (
+      configuredProvider !== pinnedProvider
+      || configuredModel !== pinnedModel
+      || (nonBlank(this.config.candidateReasoningEffort) ?? undefined) !== pinnedReasoning
+    )) {
+      throw new Error('CANDIDATE_MODEL_BINDING_CONFLICT: Plugin model configuration does not match model-binding.json; create a new Candidate or remove the global override')
+    }
+
     const inherited = this.ctx.agentDefaultModel.currentSelection()
-    const provider = explicitProvider ?? configuredProvider ?? inherited.provider
-    const model = explicitModel ?? configuredModel ?? inherited.model
+    const provider = pinnedProvider ?? explicitProvider ?? configuredProvider ?? inherited.provider
+    const model = pinnedModel ?? explicitModel ?? configuredModel ?? inherited.model
     const explicitReasoning = nonBlank(args.candidateReasoningEffort)
-    const configuredReasoning = nonBlank(this.config.candidateReasoningEffort)
+    const configuredReasoning = ignoreConfigured ? undefined : nonBlank(this.config.candidateReasoningEffort)
     const canInheritReasoning = provider === inherited.provider && model === inherited.model
-    const reasoningEffort = explicitReasoning ?? configuredReasoning
-      ?? (canInheritReasoning ? inherited.reasoningEffort : undefined)
+    const reasoningEffort = pinnedProvider
+      ? pinnedReasoning
+      : explicitReasoning ?? configuredReasoning
+        ?? (canInheritReasoning ? inherited.reasoningEffort : undefined)
 
     if (!this.ctx.llm.listProviders().some(item => item.id === provider)) {
       throw new Error(`Candidate model provider "${provider}" is not registered in DeepSeek Harness`)

package/lib/runtime-identity.js

@@ -0,0 +1,7 @@
+import { readFileSync } from 'node:fs'
+
+const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+
+export const DSH_RUNTIME_VERSION = packageJson.harborEvolution.dshRuntimeVersion
+export const CANDIDATE_ACP_PACKAGE = packageJson.harborEvolution.candidateAcpPackage
+export const RUNTIME_POLICY = packageJson.harborEvolution.runtimePolicy