dsh-harbor-evolution 0.8.2 → 0.9.2

package/lib/evolution.js

@@ -2,6 +2,8 @@ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 
 import { MANIFEST_NAME, snapshotCandidate } from './candidate.js'
+import { loadCandidateRuntime } from './candidate-runtime.js'
+import { redactCredentialText, redactLocalPaths, redactOpaqueSecretText } from './credential-redaction.js'
 import { runProcess } from './process.js'
 
 export function resolveWithin(root, value, label) {
@@ -145,7 +147,8 @@ async function cliJson(config, args, { allowedExitCodes = [0], input } = {}) {
     })
   } catch (error) {
     const detail = error?.result?.stderr?.trim().split('\n').at(-1)?.replace(/^[A-Za-z]+Error:\s*/, '')
-    throw new Error(detail || error.message)
+    const sanitized = redactDiagnostic(detail || error.message).slice(0, 512)
+    throw new Error(sanitized || 'HARBOR_DSH_COMMAND_FAILED: harbor-dsh did not return a safe error detail')
   }
   try {
     return JSON.parse(result.stdout)
@@ -154,6 +157,15 @@ async function cliJson(config, args, { allowedExitCodes = [0], input } = {}) {
   }
 }
 
+export function historicalDockerBlockers(value) {
+  const findings = Array.isArray(value?.findings) ? value.findings : []
+  return findings.filter(item => (
+    item?.level === 'error'
+    && typeof item.code === 'string'
+    && item.code.startsWith('DOCKER_')
+  ))
+}
+
 export async function inspectEvaluator(config, args = {}) {
   const stack = resolveWithin(config.projectRoot, args.stackPath ?? '.harbor/evaluation-stack.yml', 'stackPath')
   return cliJson(config, [
@@ -239,10 +251,91 @@ 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]')
+  const credentials = redactCredentialText(String(value ?? ''), '[redacted]')
+  const opaque = redactOpaqueSecretText(credentials, kind => `[redacted ${kind}]`)
+  return redactLocalPaths(opaque)
+}
+
+const RUN_RECEIPT_TEXT_LIMIT = 256
+const RUN_SUMMARY_COUNT_FIELDS = [
+  'n_trials',
+  'n_valid_scores',
+  'n_invalid_scores',
+  'n_exceptions',
+  'n_unscored_trials',
+  'n_discovered_trials',
+]
+
+function boundedRunReceiptText(value, fallback = 'unknown') {
+  const sanitized = redactDiagnostic(value).replace(/[\r\n\t]+/g, ' ').trim()
+  return (sanitized || fallback).slice(0, RUN_RECEIPT_TEXT_LIMIT)
+}
+
+function safeNonNegativeInteger(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : undefined
+}
+
+function safeFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+function narrowRunSummary(summary, { historical = false } = {}) {
+  const receipt = {
+    artifact_ref: 'evaluation-summary.json',
+    artifact_validation: { valid: summary?.artifact_validation?.valid === true },
+  }
+  const schemaVersion = safeNonNegativeInteger(summary?.schema_version)
+  if (schemaVersion !== undefined) receipt.schema_version = schemaVersion
+  for (const key of RUN_SUMMARY_COUNT_FIELDS) {
+    const value = safeNonNegativeInteger(summary?.[key])
+    if (value !== undefined) receipt[key] = value
+  }
+  if (historical) {
+    const coverage = {}
+    for (const key of HISTORICAL_COVERAGE_KEYS) {
+      const value = safeFiniteNumber(summary?.coverage?.[key])
+      if (value !== undefined) coverage[key] = value
+    }
+    receipt.coverage = coverage
+  }
+  return receipt
+}
+
+/**
+ * A mutating tool receipt is intentionally not an artifact read path. Return
+ * only bounded scalar status plus a reference that can be opened through
+ * harbor_eval_result, where untrusted artifact content receives its dedicated
+ * allowlist/redaction policy.
+ */
+export function buildEvaluationRunReceipt({ jobName, mode, summary, processCode }) {
+  return {
+    schema_version: 1,
+    jobKind: 'candidate-evaluation',
+    mode: mode === 'promotion-eligible' ? 'promotion-eligible' : 'diagnostic',
+    status: 'completed',
+    job: boundedRunReceiptText(jobName),
+    summary: narrowRunSummary(summary),
+    process: { code: safeNonNegativeInteger(processCode) ?? null },
+  }
+}
+
+export function buildHistoricalRunReceipt({ jobName, summary, processCode }) {
+  return {
+    schema_version: 1,
+    jobKind: 'historical-generation-evaluation',
+    executionMode: 'observe-existing',
+    promotionEligible: false,
+    status: 'completed',
+    job: boundedRunReceiptText(jobName),
+    summary: narrowRunSummary(summary, { historical: true }),
+    completion: {
+      schema_version: 1,
+      status: 'completed',
+      valid: true,
+      artifact_ref: 'historical-evaluation-complete.json',
+    },
+    process: { code: safeNonNegativeInteger(processCode) ?? null },
+  }
 }
 
 export function classifyHarborFailure(value) {
@@ -288,7 +381,7 @@ export async function explainHarborFailure(error, jobDir) {
   const suggestions = classifyHarborFailure(detail || error?.message)
   const lines = [
     `HARBOR_JOB_FAILED: Harbor exited with code ${error?.result?.code ?? 'unknown'}.`,
-    `jobPath: ${jobDir}`,
+    'jobPath: [local path]',
     ...suggestions.map(item => `nextStep[${item.code}]: ${item.action}`),
   ]
   if (detail.trim()) lines.push('diagnosticTail:', detail.trim())
@@ -350,8 +443,11 @@ export async function previewContext(config, args) {
 }
 
 export async function runEvaluation(config, args, modelRuntime) {
-  const manifest = await snapshot(config, args)
   const inputs = strictInputs(config, args)
+  // Do not rely on a possibly older Python Doctor to enforce a contract that
+  // its agent may not understand. Legacy snapshots remain readable, not runnable.
+  await loadCandidateRuntime(inputs.candidate, { required: true })
+  const manifest = await snapshot(config, args)
   const datasetValidation = await validateDataset(config, args)
   if (!datasetValidation.valid) {
     throw new Error(
@@ -360,10 +456,13 @@ export async function runEvaluation(config, args, modelRuntime) {
     )
   }
   const doctor = await runDoctor(config, args)
-  const runtimeBlockers = doctor.findings.filter(item => item.level === 'error' && item.code.startsWith('DOCKER_'))
+  const runtimeBlockers = doctor.findings.filter(item => item.level === 'error' && (item.code.startsWith('DOCKER_') || item.code.startsWith('CANDIDATE_RUNTIME_')))
   if (runtimeBlockers.length) {
     throw new Error(`Runtime Doctor blocked Harbor Job:\n${runtimeBlockers.map(item => `${item.code}: ${item.message}`).join('\n')}`)
   }
+  if (!doctor.findings.some(item => item.level === 'info' && item.code === 'CANDIDATE_RUNTIME_VERIFIED')) {
+    throw new Error('CANDIDATE_RUNTIME_ADAPTER_UNSUPPORTED: update the Python Adapter; it has not verified the Candidate-owned local ACP runtime. No model lease or Harbor Job was started.')
+  }
   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(', ')}`)
   }
@@ -427,15 +526,12 @@ export async function runEvaluation(config, args, modelRuntime) {
       throw await explainHarborFailure(error, jobDir)
     }
     const summary = JSON.parse(await readFile(path.join(jobDir, 'evaluation-summary.json'), 'utf8'))
-    return {
-      manifest,
-      candidateModelBinding: args.candidateModelBinding,
-      job: path.relative(inputs.projectRoot, jobDir),
+    return buildEvaluationRunReceipt({
+      jobName,
+      mode: inputs.mode,
       summary,
-      doctor,
-      contextPreview: preview,
-      process: { code: processResult.code },
-    }
+      processCode: processResult.code,
+    })
   } finally {
     await lease.close()
   }
@@ -467,6 +563,16 @@ export async function runHistoricalEvaluation(config, args, modelRuntime) {
   ])
   const dataset = resolveWithin(projectRoot, materialized.dataset_path ?? output, 'historicalDataset')
   const stack = resolveWithin(projectRoot, materialized.stack_path, 'historicalStack')
+  // Fail fast on Docker runtime blockers (e.g. an unresolvable credential
+  // helper) before Harbor creates a Job whose Trials would all fail during
+  // environment setup and only report missing downstream artifacts.
+  const dockerCheck = await cliJson(config, ['docker-check'], { allowedExitCodes: [0, 2] })
+  const dockerBlockers = historicalDockerBlockers(dockerCheck)
+  if (dockerBlockers.length) {
+    throw new Error(
+      `HISTORICAL_DOCKER_PREFLIGHT_FAILED: Docker runtime preflight blocked the Historical Job:\n${dockerBlockers.map(item => `${item.code}: ${item.message}`).join('\n')}`,
+    )
+  }
   const batch = JSON.parse(await readFile(batchPath, 'utf8'))
   const jobs = resolveWithin(projectRoot, config.jobsDir, 'jobsDir')
   const jobName = args.jobName ?? makeHistoricalJobName(batch)
@@ -541,23 +647,11 @@ export async function runHistoricalEvaluation(config, args, modelRuntime) {
       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('/'),
+    return buildHistoricalRunReceipt({
+      jobName,
       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 },
-    }
+      processCode: processResult.code,
+    })
   } finally {
     await lease.close()
   }

package/lib/historical-run-lock.js

@@ -0,0 +1,102 @@
+import { realpathSync } from 'node:fs'
+import path from 'node:path'
+
+const LOCKED_MESSAGE = 'HISTORICAL_JOB_ALREADY_RUNNING: wait for the current Historical Session Job to finish'
+
+function lockError(code, message) {
+  const error = new Error(`${code}: ${message}`)
+  error.code = code
+  return error
+}
+
+function realpathIfPresent(value) {
+  try {
+    return realpathSync.native(value)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined
+    throw lockError('HISTORICAL_LOCK_SCOPE_INVALID', 'the Historical workspace path could not be resolved safely')
+  }
+}
+
+function realpathFromDeepestExistingAncestor(value) {
+  let current = path.resolve(value)
+  const missingSegments = []
+  while (true) {
+    const physical = realpathIfPresent(current)
+    if (physical) return path.resolve(physical, ...missingSegments)
+    const parent = path.dirname(current)
+    if (parent === current) {
+      throw lockError('HISTORICAL_LOCK_SCOPE_INVALID', 'the Historical workspace path has no resolvable ancestor')
+    }
+    missingSegments.unshift(path.basename(current))
+    current = parent
+  }
+}
+
+/**
+ * Resolve the write target used by Historical evaluation. The absolute Jobs
+ * directory, rather than a UI workspace label, is the collision boundary:
+ * nested project roots that point at the same directory must share a lock.
+ */
+export function historicalRunScope(config = {}) {
+  const projectRoot = String(config.projectRoot ?? '')
+  const jobsDir = String(config.jobsDir ?? 'jobs')
+  if (!projectRoot || !path.isAbsolute(projectRoot)) {
+    throw lockError('HISTORICAL_LOCK_SCOPE_INVALID', 'projectRoot must be an absolute path')
+  }
+  if (!jobsDir) {
+    throw lockError('HISTORICAL_LOCK_SCOPE_INVALID', 'jobsDir must be a non-empty path inside projectRoot')
+  }
+  const root = path.resolve(projectRoot)
+  const target = path.resolve(root, jobsDir)
+  const relative = path.relative(root, target)
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw lockError('HISTORICAL_LOCK_SCOPE_INVALID', 'jobsDir must stay inside projectRoot')
+  }
+  return realpathFromDeepestExistingAncestor(target)
+}
+
+/** Process-local, fail-closed lease registry for Historical Job writers. */
+export class HistoricalRunLock {
+  constructor() {
+    this.active = new Map()
+  }
+
+  acquire(config, owner = {}) {
+    const scope = historicalRunScope(config)
+    if (this.active.has(scope)) {
+      const error = new Error(LOCKED_MESSAGE)
+      error.code = 'HISTORICAL_JOB_ALREADY_RUNNING'
+      throw error
+    }
+
+    const token = Symbol('historical-run-lease')
+    this.active.set(scope, { token, owner: { ...owner } })
+    let released = false
+    return Object.freeze({
+      scope,
+      release: () => {
+        if (released) return false
+        released = true
+        const current = this.active.get(scope)
+        if (current?.token === token) this.active.delete(scope)
+        return true
+      },
+    })
+  }
+
+  async runExclusive(config, task, owner = {}) {
+    if (typeof task !== 'function') {
+      throw lockError('HISTORICAL_LOCK_TASK_INVALID', 'the protected operation must be a function')
+    }
+    const lease = this.acquire(config, owner)
+    try {
+      return await task()
+    } finally {
+      lease.release()
+    }
+  }
+}
+
+/** Shared across every Harbor plugin/controller instance in this Node process. */
+export const historicalRunLock = new HistoricalRunLock()

package/lib/historical-web.js

@@ -1,5 +1,8 @@
 import { randomUUID } from 'node:crypto'
 
+import { redactDiagnostic } from './evolution.js'
+import { historicalRunLock } from './historical-run-lock.js'
+
 const OPERATION_RETENTION_MS = 60 * 60 * 1000
 
 function timestamp(now) {
@@ -9,9 +12,7 @@ function timestamp(now) {
 
 function publicError(error) {
   const raw = error instanceof Error ? error.message : String(error)
-  const message = raw
-    .replace(/(?:\/[A-Za-z0-9._ -]+){2,}/g, '[local path]')
-    .replace(/[A-Za-z]:\\[^\s]+/g, '[local path]')
+  const message = redactDiagnostic(raw).slice(0, 512)
   const match = message.match(/^([A-Z][A-Z0-9_]+):\s*(.*)$/s)
   return {
     code: match?.[1] ?? 'HISTORICAL_JOB_FAILED',
@@ -44,6 +45,7 @@ export class HistoricalWebController {
     randomId = () => randomUUID(),
     schedule = callback => queueMicrotask(callback),
     operationRetentionMs = OPERATION_RETENTION_MS,
+    runLock = historicalRunLock,
   }) {
     this.service = service
     this.sessionDiagnostic = sessionDiagnostic
@@ -51,6 +53,7 @@ export class HistoricalWebController {
     this.randomId = randomId
     this.schedule = schedule
     this.operationRetentionMs = operationRetentionMs
+    this.runLock = runLock
     this.previews = new Map()
     this.operations = new Map()
     this.consumedPreviews = new Map()
@@ -71,19 +74,27 @@ export class HistoricalWebController {
     }
   }
 
-  _activeOperation(workspace) {
+  _activeWorkspaceOperation(workspace) {
     return [...this.operations.values()]
       .filter(item => item.workspace === workspace && ['queued', 'running'].includes(item.status))
       .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0]
   }
 
+  _activeOwnedOperation(workspace, ownerSessionId) {
+    return [...this.operations.values()]
+      .filter(item => item.workspace === workspace && item.ownerSessionId === ownerSessionId && ['queued', 'running'].includes(item.status))
+      .sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0]
+  }
+
   async preview(args = {}) {
     this._cleanup()
-    const resolved = await this.service.historicalWorkspace({ workspace: args.workspace })
+    const ownerSessionId = String(args.sessionId ?? '').trim()
+    if (!ownerSessionId) throw new Error('HISTORICAL_SESSION_REQUIRED: a live DSH Session is required')
+    const resolved = await this.service.historicalWorkspace({ workspace: args.workspace, sessionId: ownerSessionId })
     const previewId = this.randomId()
     const identity = {
       projectRoot: resolved.projectRoot,
-      ownerSessionId: `web-historical:${this.randomId()}`,
+      ownerSessionId: `web-historical:${ownerSessionId}:${this.randomId()}`,
     }
     const preview = await this.sessionDiagnostic.previewWithIdentity({
       limit: args.limit === undefined ? 10 : args.limit,
@@ -94,6 +105,7 @@ export class HistoricalWebController {
     this.previews.set(previewId, {
       previewId,
       workspace: resolved.workspace,
+      ownerSessionId,
       identity,
       config: resolved.config,
       selectionToken,
@@ -110,11 +122,14 @@ export class HistoricalWebController {
 
   async run(args = {}) {
     this._cleanup()
+    const ownerSessionId = String(args.sessionId ?? '').trim()
+    if (!ownerSessionId) throw new Error('HISTORICAL_SESSION_REQUIRED: a live DSH Session is required')
     const previewId = String(args.previewId ?? '')
     if (!previewId) throw new Error('HISTORICAL_PREVIEW_REQUIRED: preview the recent Sessions before confirming the Job')
     const existingOperationId = this.consumedPreviews.get(previewId)
     if (existingOperationId) {
       const existing = this.operations.get(existingOperationId)
+      if (existing?.ownerSessionId !== ownerSessionId) throw new Error('HISTORICAL_PREVIEW_SESSION_MISMATCH: the preview belongs to another DSH Session')
       if (args.workspace && existing?.workspace !== args.workspace) {
         throw new Error('HISTORICAL_PREVIEW_WORKSPACE_MISMATCH: the workspace changed; preview again')
       }
@@ -122,33 +137,47 @@ export class HistoricalWebController {
     }
     const preview = this.previews.get(previewId)
     if (!preview) throw new Error('HISTORICAL_PREVIEW_INVALID: this preview expired or was already discarded; preview again')
+    if (preview.ownerSessionId !== ownerSessionId) throw new Error('HISTORICAL_PREVIEW_SESSION_MISMATCH: the preview belongs to another DSH Session')
     if (args.workspace && preview.workspace !== args.workspace) {
       throw new Error('HISTORICAL_PREVIEW_WORKSPACE_MISMATCH: the workspace changed; preview again')
     }
-    const active = this._activeOperation(preview.workspace)
+    const active = this._activeWorkspaceOperation(preview.workspace)
     if (active) {
       throw new Error('HISTORICAL_JOB_ALREADY_RUNNING: wait for the current Historical Session Job to finish')
     }
+    const lease = this.runLock.acquire(preview.config, {
+      channel: 'web',
+      workspace: preview.workspace,
+    })
     const operationId = this.randomId()
     const createdAt = timestamp(this.now).toISOString()
     const operation = {
       operationId,
       workspace: preview.workspace,
+      ownerSessionId,
       status: 'queued',
       selectedCount: preview.selectedCount,
       createdAt,
     }
-    this.previews.delete(previewId)
-    this.operations.set(operationId, operation)
-    this.consumedPreviews.set(previewId, operationId)
-    this.schedule(() => { void this._execute(operation, preview) })
+    try {
+      this.previews.delete(previewId)
+      this.operations.set(operationId, operation)
+      this.consumedPreviews.set(previewId, operationId)
+      this.schedule(() => { void this._execute(operation, preview, lease) })
+    } catch (error) {
+      this.operations.delete(operationId)
+      this.consumedPreviews.delete(previewId)
+      this.previews.set(previewId, preview)
+      lease.release()
+      throw error
+    }
     return publicOperation(operation)
   }
 
-  async _execute(operation, preview) {
-    operation.status = 'running'
-    operation.startedAt = timestamp(this.now).toISOString()
+  async _execute(operation, preview, lease) {
     try {
+      operation.status = 'running'
+      operation.startedAt = timestamp(this.now).toISOString()
       const result = await this.sessionDiagnostic.runWithIdentity({
         selectionToken: preview.selectionToken,
       }, preview.identity, { config: preview.config })
@@ -159,22 +188,29 @@ export class HistoricalWebController {
       operation.status = 'failed'
       operation.error = publicError(error)
     } finally {
-      operation.finishedAt = timestamp(this.now).toISOString()
+      try {
+        operation.finishedAt = timestamp(this.now).toISOString()
+      } finally {
+        lease.release()
+      }
     }
   }
 
   operation(args = {}) {
     this._cleanup()
+    const ownerSessionId = String(args.sessionId ?? '').trim()
+    if (!ownerSessionId) throw new Error('HISTORICAL_SESSION_REQUIRED: a live DSH Session is required')
     const operationId = String(args.operationId ?? '')
     if (operationId) {
       const operation = this.operations.get(operationId)
       if (!operation) return { status: 'idle' }
+      if (operation.ownerSessionId !== ownerSessionId) throw new Error('HISTORICAL_OPERATION_SESSION_MISMATCH: the operation belongs to another DSH Session')
       if (args.workspace && operation.workspace !== args.workspace) {
         throw new Error('HISTORICAL_OPERATION_WORKSPACE_MISMATCH: the operation belongs to another workspace')
       }
       return publicOperation(operation)
     }
     if (!args.workspace) return { status: 'idle' }
-    return publicOperation(this._activeOperation(String(args.workspace)))
+    return publicOperation(this._activeOwnedOperation(String(args.workspace), ownerSessionId))
   }
 }

package/lib/interaction-objects.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto'
+
+export const LOCAL_OBJECT_KINDS = new Set(['hypothesis', 'gate-reason', 'metric', 'finding', 'attempt', 'exception', 'evaluator-source', 'trial-set'])
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]))
+  return value
+}
+
+export function localObjectDigest(value) {
+  return `sha256:${createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex')}`
+}
+
+/** Host-derived selectors. No paths or artifact prose enter message context. */
+export function interactionObjectCatalog(job, jobState, trialState, governance) {
+  const artifacts = jobState?.artifacts ?? {}
+  const entries = []
+  const add = (kind, stage, value, fields = {}) => {
+    if (value === undefined || value === null) return
+    const sourceDigest = localObjectDigest(value)
+    const id = `${kind}-${sourceDigest.slice(7, 31)}`
+    entries.push({ ref: { kind, id, job, stage, sourceDigest, ...fields }, value })
+  }
+  for (const value of (artifacts.optimization?.hypotheses ?? []).slice(0, 100)) add('hypothesis', 'optimizer', value)
+  for (const value of (artifacts.promotion?.reasons ?? []).slice(0, 100)) add('gate-reason', 'gate', value)
+  for (const [metric, value] of Object.entries(artifacts.summary?.metrics ?? {}).slice(0, 100)) {
+    if (typeof value === 'number' && Number.isFinite(value)) add('metric', 'reporter', { metric, value })
+  }
+  if (trialState) {
+    const trial = trialState.lifecycle?.id ?? trialState.trial
+    for (const value of (trialState.assessment?.findings ?? []).slice(0, 100)) add('finding', 'judge', value, { trial })
+    for (const reason of (trialState.assessment?.score?.invalid_reasons ?? trialState.lifecycle?.score?.invalid_reasons ?? []).slice(0, 100)) add('exception', 'judge', { reason, scoreValid: false }, { trial })
+    if (trialState.lifecycle?.exception) add('exception', 'judge', trialState.lifecycle.exception, { trial })
+    if (trialState.lifecycle) add('attempt', 'judge', trialState.lifecycle, { trial })
+  }
+  for (const role of ['evaluator', 'rubric']) {
+    const source = governance?.components?.[role]?.source
+    if (typeof source?.text === 'string' && !source.error) {
+      add('evaluator-source', 'judge', { role, text: source.text }, { sourceRole: role })
+    }
+  }
+  return entries
+}
+
+export function resolveCatalogSelection(ref, catalog) {
+  const entry = catalog.find(item => item.ref.job === ref.job && item.ref.kind === ref.kind && item.ref.id === ref.id && item.ref.sourceDigest === ref.sourceDigest && item.ref.trial === ref.trial)
+  if (!entry) throw new Error('HARBOR_CONTEXT_STALE_SELECTION: Selected artifact item has changed or is unavailable; select it again.')
+  if (ref.kind !== 'evaluator-source') return entry
+  if (ref.sourceRole !== entry.ref.sourceRole) throw new Error('HARBOR_CONTEXT_STALE_SELECTION: Source role does not match the selected artifact.')
+  const lines = entry.value.text.split('\n')
+  const start = ref.startLine ?? 1
+  const end = ref.endLine ?? Math.min(lines.length, 200)
+  if (start < 1 || end < start || end > lines.length || end - start >= 200) throw new Error('HARBOR_CONTEXT_INVALID: Select between 1 and 200 saved source lines.')
+  return { ref: { ...entry.ref, startLine: start, endLine: end }, value: { role: ref.sourceRole, startLine: start, endLine: end, text: lines.slice(start - 1, end).join('\n') } }
+}

package/lib/model-runtime.js

@@ -9,6 +9,14 @@ function nonBlank(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : undefined
 }
 
+function leaseLimit(value, fallback, label) {
+  const selected = value ?? fallback
+  if (!Number.isSafeInteger(selected) || selected < 1) {
+    throw Object.assign(new Error(`HARBOR_MODEL_LIMIT_INVALID: ${label} must be a positive integer.`), { code: 'HARBOR_MODEL_LIMIT_INVALID' })
+  }
+  return selected
+}
+
 function sameSecret(expected, actual) {
   const left = Buffer.from(expected)
   const right = Buffer.from(actual)
@@ -165,7 +173,27 @@ export class CandidateModelRuntime {
     }
   }
 
-  async openLease(binding, scope) {
+  /** Read-only budget validation, shared by Preflight and the execution boundary. */
+  async assertLeaseLimits(binding, scope = {}) {
+    const globalRequests = leaseLimit(this.config.modelBrokerMaxRequests, 1000, 'modelBrokerMaxRequests')
+    const maxRequests = Math.min(globalRequests, leaseLimit(scope.maxRequests, globalRequests, 'maxRequests'))
+    let maxResponseBytes
+    if (scope.maxResponseBytes !== undefined) {
+      const globalBytes = leaseLimit(this.config.modelBrokerMaxResponseBytes, 4 * 1024 * 1024, 'modelBrokerMaxResponseBytes')
+      maxResponseBytes = Math.min(globalBytes, leaseLimit(scope.maxResponseBytes, globalBytes, 'maxResponseBytes'))
+    }
+    if (scope.maxOutputTokens !== undefined) {
+      leaseLimit(scope.maxOutputTokens, undefined, 'maxOutputTokens')
+      // The current public DSH model metadata does not prove provider-wire
+      // enforcement. In particular its Codex adapter can ignore maxTokens.
+      // Do not silently treat an API option as an actual billing/token cap.
+      throw Object.assign(new Error('HARBOR_MODEL_OUTPUT_LIMIT_UNSUPPORTED: This Host does not expose verified provider output-token enforcement. Use explicit request, time and response-byte budgets; these are not token or billing limits.'), { code: 'HARBOR_MODEL_OUTPUT_LIMIT_UNSUPPORTED' })
+    }
+    return { maxRequests, ...(maxResponseBytes === undefined ? {} : { maxResponseBytes }) }
+  }
+
+  async openLease(binding, scope = {}) {
+    const limits = await this.assertLeaseLimits(binding, scope)
     const token = randomBytes(32).toString('base64url')
     const route = `/harbor-model-gateway/v1/${randomBytes(18).toString('base64url')}`
     const controllers = new Set()
@@ -180,6 +208,7 @@ export class CandidateModelRuntime {
           protocol: MODEL_GATEWAY_PROTOCOL,
           candidate_digest: scope.candidateDigest,
           job: scope.jobName,
+          limits,
           binding: {
             provider: binding.provider,
             model: binding.model,
@@ -192,7 +221,7 @@ export class CandidateModelRuntime {
         sendJson(response, 405, { error: 'method not allowed' })
         return
       }
-      if (requestCount >= this.config.modelBrokerMaxRequests) {
+      if (requestCount >= limits.maxRequests) {
         sendJson(response, 429, { error: 'model gateway request budget exhausted' })
         return
       }
@@ -209,8 +238,12 @@ export class CandidateModelRuntime {
           model: _model,
           reasoningEffort: _reasoningEffort,
           signal: _signal,
+          maxRequests: _maxRequests,
+          maxResponseBytes: _maxResponseBytes,
+          maxOutputTokens: _maxOutputTokens,
           ...requestOptions
         } = body
+        if (controller.signal.aborted) throw new Error('Candidate disconnected before model execution')
         response.writeHead(200, {
           'content-type': 'application/x-ndjson; charset=utf-8',
           'cache-control': 'no-store',
@@ -222,8 +255,17 @@ export class CandidateModelRuntime {
           ...(binding.reasoning_effort === undefined ? {} : { reasoningEffort: binding.reasoning_effort }),
           signal: controller.signal,
         })
+        let responseBytes = 0
         for await (const chunk of stream) {
-          if (!response.write(`${JSON.stringify(chunk)}\n`)) await once(response, 'drain')
+          const line = `${JSON.stringify(chunk)}\n`
+          responseBytes += Buffer.byteLength(line, 'utf8')
+          if (limits.maxResponseBytes !== undefined && responseBytes > limits.maxResponseBytes) {
+            const error = new Error('model gateway response byte budget exhausted; this is not a provider token or billing limit')
+            controller.abort(error)
+            // Never publish the overflowing chunk or a successful finish.
+            throw error
+          }
+          if (!response.write(line)) await once(response, 'drain', { signal: controller.signal })
         }
         response.end()
       } catch (error) {
@@ -248,6 +290,9 @@ export class CandidateModelRuntime {
       token,
       candidateProvider: CANDIDATE_GATEWAY_PROVIDER,
       modelInfo: binding.model_info,
+      limits: { ...limits },
+      // Host-only observation: no gateway URL, token or request content escapes.
+      usage: () => ({ modelRequests: requestCount, maxModelRequests: limits.maxRequests }),
       async close() {
         if (closed) return
         closed = true