dsh-harbor-evolution 0.7.2 → 0.7.3

package/lib/dashboard.js

@@ -1,10 +1,12 @@
 import { access, constants, lstat, readdir, readFile, stat } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
 import path from 'node:path'
 
 import { resolveWithin } from './evolution.js'
 
 const SUMMARY_NAME = 'evaluation-summary.json'
-const MAX_JOBS = 50
+const DEFAULT_JOB_PAGE_SIZE = 20
+const MAX_JOB_PAGE_SIZE = 100
 const MAX_JSON_BYTES = 2 * 1024 * 1024
 const MAX_SOURCE_BYTES = 128 * 1024
 const MAX_PREVIEW_BYTES = 512 * 1024
@@ -12,6 +14,11 @@ const MAX_TRIAL_LIMIT = 100
 const jsonCache = new Map()
 const SENSITIVE_KEY = /authorization|cookie|token|api[_-]?key|secret|password|request[_-]?headers/i
 const SENSITIVE_SOURCE_VALUE = /(authorization|cookie|token|api[_-]?key|secret|password)\s*[:=]\s*([^\s,;]+)/gi
+const WORKSPACE_SKIP_DIRECTORIES = new Set([
+  '.cache', '.git', '.harbor', '.next', '.venv', '__pycache__',
+  'build', 'candidates', 'coverage', 'datasets', 'dist', 'jobs', 'node_modules', 'public', 'vendor', 'venv',
+])
+const MAX_WORKSPACE_DEPTH = 5
 
 function safeSegment(value, label) {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(String(value ?? ''))) throw new Error(`${label} is invalid`)
@@ -193,19 +200,96 @@ async function readJob(jobsDir, entry, details) {
   }
 }
 
-async function listJobs(jobsDir) {
+async function listJobs(jobsDir, { offset = 0, limit = DEFAULT_JOB_PAGE_SIZE } = {}) {
   let entries
   try {
     entries = await readdir(jobsDir, { withFileTypes: true })
   } catch (error) {
-    if (error.code === 'ENOENT') return []
+    if (error.code === 'ENOENT') return { items: [], total: 0, offset, limit, hasMore: false }
     throw error
   }
   const directories = entries.filter(entry => entry.isDirectory() && !entry.isSymbolicLink())
   const recent = await Promise.all(directories.map(async entry => ({ entry, details: await stat(path.join(jobsDir, entry.name)) })))
   recent.sort((left, right) => right.details.mtimeMs - left.details.mtimeMs)
-  const jobs = await Promise.all(recent.map(({ entry, details }) => readJob(jobsDir, entry, details)))
-  return jobs.filter(Boolean).slice(0, MAX_JOBS)
+  const page = recent.slice(offset, offset + limit)
+  const jobs = await Promise.all(page.map(({ entry, details }) => readJob(jobsDir, entry, details)))
+  return { items: jobs.filter(Boolean), total: recent.length, offset, limit, hasMore: offset + limit < recent.length }
+}
+
+function relativePath(root, value) {
+  return path.relative(root, value).split(path.sep).join('/') || '.'
+}
+
+function workspaceIdentity(projectRoot, workspaceRoot, jobsDir, preferred) {
+  const digest = createHash('sha256').update(`${projectRoot}\0${workspaceRoot}\0${jobsDir}`).digest('hex').slice(0, 12)
+  const label = String(preferred || path.basename(workspaceRoot) || 'root').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'root'
+  return `${label}-${digest}`
+}
+
+async function regularFile(pathname) {
+  try {
+    const details = await lstat(pathname)
+    return details.isFile() && !details.isSymbolicLink()
+  } catch (error) {
+    if (error.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+/** Discover root and namespaced Harbor workspaces without interpreting YAML. */
+export async function discoverWorkspaceConfigs(config) {
+  const projectRoot = path.resolve(config.projectRoot)
+  const found = []
+  async function visit(directory, depth) {
+    const harborDirectory = path.join(directory, '.harbor')
+    const descriptorPath = path.join(harborDirectory, 'workspace.json')
+    const stackPath = path.join(harborDirectory, 'evaluation-stack.yml')
+    const descriptor = await readJson(descriptorPath)
+    if (descriptor?.schema_version === 1 && descriptor.jobs && descriptor.stack) {
+      const jobs = relativePath(projectRoot, resolveWithin(projectRoot, path.resolve(directory, descriptor.jobs), 'workspace.jobs'))
+      const stack = relativePath(projectRoot, resolveWithin(projectRoot, path.resolve(directory, descriptor.stack), 'workspace.stack'))
+      const workspaceRoot = relativePath(projectRoot, directory)
+      found.push({
+        ...config,
+        jobsDir: jobs,
+        stackPath: stack,
+        workspaceRoot,
+        workspaceLabel: descriptor.workspace_id ?? workspaceRoot,
+        workspaceId: workspaceIdentity(projectRoot, directory, jobs, descriptor.workspace_id),
+      })
+    } else if (await regularFile(stackPath)) {
+      const workspaceRoot = relativePath(projectRoot, directory)
+      const jobs = relativePath(projectRoot, path.join(directory, 'jobs'))
+      found.push({
+        ...config,
+        jobsDir: jobs,
+        stackPath: relativePath(projectRoot, stackPath),
+        workspaceRoot,
+        workspaceLabel: workspaceRoot,
+        workspaceId: workspaceIdentity(projectRoot, directory, jobs, workspaceRoot),
+      })
+    }
+    if (depth >= MAX_WORKSPACE_DEPTH) return
+    let entries
+    try { entries = await readdir(directory, { withFileTypes: true }) } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'EACCES') return
+      throw error
+    }
+    await Promise.all(entries
+      .filter(entry => entry.isDirectory() && !entry.isSymbolicLink() && !WORKSPACE_SKIP_DIRECTORIES.has(entry.name))
+      .map(entry => visit(path.join(directory, entry.name), depth + 1)))
+  }
+  await visit(projectRoot, 0)
+  if (!found.some(item => item.workspaceRoot === '.')) {
+    found.unshift({
+      ...config,
+      stackPath: '.harbor/evaluation-stack.yml',
+      workspaceRoot: '.',
+      workspaceLabel: path.basename(projectRoot) || 'root',
+      workspaceId: workspaceIdentity(projectRoot, projectRoot, config.jobsDir, path.basename(projectRoot)),
+    })
+  }
+  return found.sort((left, right) => left.workspaceRoot.localeCompare(right.workspaceRoot))
 }
 
 function jobsDirectory(config) {
@@ -216,32 +300,39 @@ function jobDirectory(config, job) {
   return path.join(jobsDirectory(config), safeSegment(job, 'job'))
 }
 
-export async function readDashboardSnapshot(config, metadata = {}) {
+export async function readDashboardSnapshot(config, metadata = {}, args = {}) {
   const projectRoot = path.resolve(config.projectRoot)
   const jobsDir = jobsDirectory(config)
-  const [jobs, projectRootCheck, jobsDirCheck, harborCheck, harborDshCheck, stackCheck] = await Promise.all([
-    listJobs(jobsDir),
+  const offset = Math.max(0, Number.parseInt(args.offset ?? 0, 10) || 0)
+  const limit = Math.min(MAX_JOB_PAGE_SIZE, Math.max(1, Number.parseInt(args.limit ?? DEFAULT_JOB_PAGE_SIZE, 10) || DEFAULT_JOB_PAGE_SIZE))
+  const [jobPage, projectRootCheck, jobsDirCheck, harborCheck, harborDshCheck, stackCheck] = await Promise.all([
+    listJobs(jobsDir, { offset, limit }),
     directoryCheck(projectRoot),
     directoryCheck(jobsDir, { optional: true }),
     executableCheck(config.harborBin),
     executableCheck(config.harborDshBin),
-    fileCheck(path.join(projectRoot, '.harbor', 'evaluation-stack.yml')),
+    fileCheck(resolveWithin(projectRoot, config.stackPath ?? '.harbor/evaluation-stack.yml', 'stackPath')),
   ])
+  const jobs = jobPage.items
   const counts = jobs.reduce((result, job) => ({ ...result, [job.status]: (result[job.status] ?? 0) + 1 }), {})
   const latestMetric = jobs.find(job => job.primaryMetric)?.primaryMetric
   return {
     schemaVersion: 3,
     generatedAt: new Date().toISOString(),
     pluginVersion: metadata.pluginVersion ?? 'development',
-    config: { jobsDir: config.jobsDir, dshVersion: config.dshVersion, agentImportPath: config.agentImportPath, pluginImportPath: config.pluginImportPath },
+    workspace: { id: config.workspaceId, label: config.workspaceLabel, root: config.workspaceRoot ?? '.', stackPath: config.stackPath },
+    workspaces: metadata.workspaces ?? [],
+    config: { projectRoot, projectRootSource: metadata.projectRootSource ?? 'configured', jobsDir: config.jobsDir, runtimePolicy: config.runtimePolicy ?? 'follow-latest', agentImportPath: config.agentImportPath, pluginImportPath: config.pluginImportPath },
     checks: { projectRoot: projectRootCheck, jobsDir: jobsDirCheck, harbor: harborCheck, harborDsh: harborDshCheck, evaluationStack: stackCheck },
     overview: {
-      totalJobs: jobs.length,
+      totalJobs: jobPage.total,
+      visibleJobs: jobs.length,
       completedJobs: (counts.completed ?? 0) + (counts.partial ?? 0) + (counts.attention ?? 0),
       activeJobs: (counts.pending ?? 0) + (counts.running ?? 0),
       failedJobs: counts.failed ?? 0,
       latestMetric,
     },
+    jobPagination: { offset: jobPage.offset, limit: jobPage.limit, total: jobPage.total, hasMore: jobPage.hasMore },
     jobs,
   }
 }
@@ -252,6 +343,7 @@ const DETAIL_ARTIFACTS = {
   dataset: 'dataset-manifest.json',
   datasetPreview: 'dataset-preview.json',
   stack: 'evaluation-stack-manifest.json',
+  stackSources: 'evaluation-stack-sources.json',
   context: 'evaluation-context.json',
   contract: 'evaluation-contract.json',
   doctor: 'architecture-doctor.json',
@@ -268,13 +360,13 @@ function schemaIssue(key, value) {
   if (value?.__readError) return value.__readError
   if (!isObject(value)) return 'artifact must be an object'
   const versions = {
-    summary: [2, 3], candidate: [1], dataset: [1], datasetPreview: [1], stack: [1], context: [1, 2], contract: [1],
+    summary: [2, 3], candidate: [1], dataset: [1], datasetPreview: [1], stack: [1], stackSources: [1], context: [1, 2], contract: [1],
     doctor: [1], population: [1, 2], lifecycle: [1], registry: [1], diagnosis: [1], optimization: [1, 2], promotion: [2],
   }[key]
   if (versions && !versions.includes(value.schema_version)) return `schema_version must be one of ${versions.join(', ')}`
   const required = {
     summary: ['job', 'metrics'], candidate: ['candidate_id', 'version', 'digest'], dataset: ['dataset_id', 'version', 'source_digest', 'tasks'], datasetPreview: ['dataset_id', 'version', 'source_digest', 'tasks'],
-    stack: ['stack_id', 'version', 'digest', 'components', 'judge'], context: ['digest'], contract: ['contract_id', 'version', 'primary_metric', 'metrics'],
+    stack: ['stack_id', 'version', 'digest', 'components', 'judge'], stackSources: ['stack_digest', 'components'], context: ['digest'], contract: ['contract_id', 'version', 'primary_metric', 'metrics'],
     doctor: ['promotion_ready', 'findings'], population: ['population_size', 'groups', 'metrics'], lifecycle: ['dataset_total', 'trials'],
     registry: ['artifacts'], diagnosis: ['diagnoses'], optimization: ['hypotheses'], promotion: ['decision', 'reasons', 'policy_digest'],
   }[key] ?? []
@@ -574,11 +666,22 @@ export async function readJobProgress(config, args) {
 
 export async function readMetaEvaluation(config, args = {}) {
   const evaluationRoot = resolveWithin(config.projectRoot, args.evaluationRoot ?? '.', 'evaluationRoot')
-  const groundTruth = await readJson(path.join(evaluationRoot, '.harbor', 'ground-truth.json'), { maxText: 64_000 })
-  const report = await readJson(path.join(evaluationRoot, '.harbor', 'meta-evaluation-report.json'), { maxText: 64_000 })
+  const index = await readJson(path.join(evaluationRoot, '.harbor', 'meta-artifacts.json'))
+  const registered = index?.schema_version === 1 ? index.artifacts ?? {} : {}
+  const groundTruthPath = resolveWithin(evaluationRoot, registered.ground_truth ?? '.harbor/ground-truth.json', 'groundTruthPath')
+  const reportPath = resolveWithin(evaluationRoot, registered.meta_evaluation_report ?? '.harbor/meta-evaluation-report.json', 'metaEvaluationReportPath')
+  const groundTruth = await readJson(groundTruthPath, { maxText: 64_000 })
+  const report = await readJson(reportPath, { maxText: 64_000 })
   const availableGroundTruth = groundTruth && !groundTruth.__readError
   const availableReport = report && !report.__readError
   const cases = availableGroundTruth && Array.isArray(groundTruth.cases) ? groundTruth.cases : []
+  const disagreementOffset = Math.max(0, Number.parseInt(args.offset ?? 0, 10) || 0)
+  const disagreementLimit = Math.min(100, Math.max(1, Number.parseInt(args.limit ?? 20, 10) || 20))
+  const disagreements = availableReport && Array.isArray(report.disagreements) ? report.disagreements : []
+  const pagedReport = availableReport ? {
+    ...report,
+    disagreements: disagreements.slice(disagreementOffset, disagreementOffset + disagreementLimit),
+  } : undefined
   return {
     schemaVersion: 1,
     evaluationRoot: path.relative(config.projectRoot, evaluationRoot) || '.',
@@ -590,9 +693,16 @@ export async function readMetaEvaluation(config, args = {}) {
       criteria: groundTruth.criteria ?? [],
       caseCount: cases.length,
       badcaseCount: cases.filter(item => item?.badcase).length,
-      path: path.relative(config.projectRoot, path.join(evaluationRoot, '.harbor', 'ground-truth.json')),
+      path: path.relative(config.projectRoot, groundTruthPath),
     } : undefined,
-    report: availableReport ? report : undefined,
+    report: pagedReport,
+    artifactIndex: index?.schema_version === 1 ? path.relative(config.projectRoot, path.join(evaluationRoot, '.harbor', 'meta-artifacts.json')) : undefined,
+    disagreementPagination: {
+      offset: disagreementOffset,
+      limit: disagreementLimit,
+      total: disagreements.length,
+      hasMore: disagreementOffset + disagreementLimit < disagreements.length,
+    },
     workflow: {
       candidate: 'Evaluator / Rubric / Judge identity',
       dataset: 'Fixed artifacts plus independent Ground Truth',
@@ -668,16 +778,27 @@ export async function readComparison(config, args) {
 export async function readEvaluatorGovernance(config, args) {
   const job = safeSegment(args.job, 'job')
   const directory = jobDirectory(config, job)
-  const [stack, contract, context] = await Promise.all([
+  const [stack, sources, contract, context] = await Promise.all([
     readJson(path.join(directory, 'evaluation-stack-manifest.json')),
+    readJson(path.join(directory, 'evaluation-stack-sources.json'), { maxText: MAX_SOURCE_BYTES }),
     readJson(path.join(directory, 'evaluation-contract.json')),
     readJson(path.join(directory, 'evaluation-context.json')),
   ])
   if (!stack || stack.__readError) throw new Error('Evaluation Stack is unavailable')
+  const historicalSources = sources?.schema_version === 1 && sources.stack_digest === stack.digest
+    ? sources
+    : undefined
   const components = {}
   for (const [role, component] of Object.entries(stack.components ?? {})) {
     const entry = component?.entry
-    const source = entry ? await readSafeText(resolveWithin(config.projectRoot, entry, `${role}.entry`), config.projectRoot) : { error: 'entry unavailable' }
+    const snapshot = historicalSources?.components?.[role]
+    const snapshotFile = snapshot?.files?.find(item => item.path === entry && item.text)
+      ?? snapshot?.files?.find(item => item.text)
+    const source = snapshotFile
+      ? { ...snapshotFile, source: 'job-snapshot', readOnly: true }
+      : entry
+        ? { ...(await readSafeText(resolveWithin(config.projectRoot, entry, `${role}.entry`), config.projectRoot)), source: 'historical-live-fallback', readOnly: true }
+        : { error: 'entry unavailable', source: 'unavailable', readOnly: true }
     components[role] = { ...component, source }
   }
   let comparison
@@ -697,7 +818,7 @@ export async function readEvaluatorGovernance(config, args) {
     }
   }
   return {
-    schemaVersion: 1, job, stackIdentity: { id: stack.stack_id, version: stack.version, digest: stack.digest },
+    schemaVersion: 1, job, stackIdentity: { id: stack.stack_id, version: stack.version, digest: stack.digest, comparisonDigest: stack.comparison_digest },
     judge: stack.judge, contract, contextDigest: context?.digest, components, comparison,
     editingPolicy: {
       browserWriteEnabled: false,

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,
   })
 }
 
@@ -80,7 +113,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 +124,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 +171,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 +244,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 +287,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 +340,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,

package/lib/model-runtime.js

@@ -74,7 +74,25 @@ export class CandidateModelRuntime {
     this.config = config
   }
 
-  async resolve(args = {}) {
+  async currentBinding() {
+    const inherited = this.ctx.agentDefaultModel.currentSelection()
+    const binding = await this.resolve({
+      candidateProvider: inherited.provider,
+      candidateModel: inherited.model,
+      candidateReasoningEffort: inherited.reasoningEffort,
+    })
+    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) {
     const explicitProvider = nonBlank(args.candidateProvider)
     const explicitModel = nonBlank(args.candidateModel)
     if (Boolean(explicitProvider) !== Boolean(explicitModel)) {
@@ -86,14 +104,37 @@ export class CandidateModelRuntime {
       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 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