dsh-harbor-evolution 0.8.2 → 0.9.2

package/lib/diagnostic-observation.js

@@ -0,0 +1,175 @@
+import { constants } from 'node:fs'
+import { lstat, open, readFile, readlink } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { resolveWithin } from './evolution.js'
+
+const phases = new Set(['queued', 'preparing-environment', 'preparing-agent', 'loading-observation', 'running-agent', 'running-adapter', 'running-integration', 'rendering', 'evaluating', 'completed', 'completed-unscored', 'candidate-quality-failed', 'infrastructure-error', 'evaluation-error', 'cancelled'])
+const fail = () => { throw Object.assign(new Error('HARBOR_DIAGNOSTIC_OBSERVATION_UNSAFE: Diagnostic evidence is missing or unsafe.'), { code: 'HARBOR_DIAGNOSTIC_OBSERVATION_UNSAFE' }) }
+
+export async function pinDiagnosticEnvironment(runProcess, environment) {
+  const env = { ...environment }
+  let endpoint = env.DOCKER_HOST
+  if (env.DOCKER_CONTEXT || !endpoint) {
+    let context = env.DOCKER_CONTEXT
+    if (!context) {
+      const selected = await runProcess('docker', ['context', 'show'], { env, timeoutMs: 5000, maxOutputBytes: 1024 })
+      if (selected.code !== 0) fail()
+      context = selected.stdout.trim()
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,100}$/.test(context)) fail()
+    const resolved = await runProcess('docker', ['context', 'inspect', context, '--format', '{{.Endpoints.docker.Host}}'], { env, timeoutMs: 5000, maxOutputBytes: 4096 })
+    if (resolved.code !== 0) fail()
+    endpoint = resolved.stdout.trim()
+  }
+  if (!/^unix:\/\/\/[^\r\n\0]{1,4000}$/.test(endpoint)) throw Object.assign(new Error('HARBOR_DIAGNOSTIC_RUNTIME_UNSUPPORTED: Bounded diagnostics currently require a local Docker Unix socket. Remote/TLS contexts are not enabled because immutable transport and cleanup ownership cannot yet be proven; no run was started.'), { code: 'HARBOR_DIAGNOSTIC_RUNTIME_UNSUPPORTED' })
+  // Pin the endpoint, not merely its mutable context name. No TLS credentials
+  // are copied and editing Docker's context definition cannot redirect a run.
+  env.DOCKER_HOST = endpoint
+  delete env.DOCKER_CONTEXT
+  delete env.DOCKER_TLS
+  delete env.DOCKER_TLS_VERIFY
+  delete env.DOCKER_CERT_PATH
+  return env
+}
+
+export async function readDiagnosticRuntimeIdentity({ runProcess, platform = process.platform, env }) {
+  let machine, processDomain = ''
+  if (platform === 'darwin') {
+    const response = await runProcess('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], { env, timeoutMs: 5000, maxOutputBytes: 64 * 1024 })
+    if (response.code !== 0) fail()
+    machine = response.stdout.match(/"IOPlatformUUID"\s*=\s*"([a-f0-9-]{36})"/i)?.[1] ?? ''
+  } else if (platform === 'linux') {
+    const info = await lstat('/etc/machine-id')
+    if (!info.isFile() || info.size > 1024) fail()
+    machine = (await readFile('/etc/machine-id', 'utf8')).trim()
+    const namespace = await readlink('/proc/self/ns/pid')
+    const boot = (await readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim()
+    if (!/^pid:\[[0-9]+\]$/.test(namespace) || !/^[a-f0-9-]{36}$/.test(boot)) fail()
+    processDomain = `:${namespace}:${boot}`
+  } else fail()
+  if (!/^[a-f0-9-]{16,64}$/i.test(machine)) fail()
+  const docker = await runProcess('docker', ['info', '--format', '{{.ID}}'], { env, timeoutMs: 10_000, maxOutputBytes: 1024 })
+  if (docker.code !== 0 || !/^[A-Za-z0-9:_.-]{8,200}$/.test(docker.stdout.trim())) fail()
+  const digest = value => `sha256:${createHash('sha256').update(value).digest('hex')}`
+  // Do not persist device IDs, daemon endpoints, context names or credentials.
+  return { hostIdentity: digest(`${platform}:${machine.toLowerCase()}${processDomain}`), dockerIdentity: digest(docker.stdout.trim()) }
+}
+
+async function artifact(root, target) {
+  const file = resolveWithin(root, target, 'diagnostic observation')
+  let cursor = root
+  for (const part of path.relative(root, file).split(path.sep)) {
+    cursor = path.join(cursor, part)
+    if ((await lstat(cursor)).isSymbolicLink()) fail()
+  }
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const info = await handle.stat()
+    if (!info.isFile() || info.size > 512 * 1024) fail()
+    return JSON.parse(await handle.readFile('utf8'))
+  } finally { await handle.close() }
+}
+
+async function evidence(config, operation, root, { tolerateLifecycleError = false } = {}) {
+  if (!/^hop_[A-Za-z0-9_-]{1,100}$/.test(operation.operationId ?? '')) fail()
+  const jobName = `diagnostic-${operation.operationId.slice(4)}`
+  const directory = resolveWithin(root, path.join(config.jobsDir ?? 'jobs', jobName), 'diagnostic Job')
+  const provenance = await artifact(root, path.join(directory, 'diagnostic-provenance.json'))
+  if (provenance?.protocol !== 'harbor-diagnostic-provenance/v1' || provenance.operationId !== operation.operationId || provenance.promotionEligible !== false || !Array.isArray(provenance.selection) || provenance.selection.length < 1 || provenance.selection.length > 12) fail()
+  const resultRef = { verified: true, jobName, ...(operation.target?.workspace ? { workspace: operation.target.workspace } : {}), partial: operation.status !== 'COMPLETED' }
+  let lifecycle, observationWarning
+  try {
+    lifecycle = await artifact(root, path.join(directory, 'trial-lifecycle.json'))
+    if (lifecycle.schema_version !== 1 || lifecycle.job !== jobName || lifecycle.dataset_total !== provenance.selection.length || !Array.isArray(lifecycle.trials) || lifecycle.trials.length !== provenance.selection.length || lifecycle.trials.some(trial => !phases.has(trial.phase) || typeof trial.terminal !== 'boolean' || !Number.isSafeInteger(trial.dataset_order) || trial.dataset_order < 0 || trial.dataset_order >= provenance.selection.length) || new Set(lifecycle.trials.map(trial => trial.dataset_order)).size !== provenance.selection.length) fail()
+  } catch (cause) {
+    if (cause.code !== 'ENOENT' && !tolerateLifecycleError) throw cause
+    lifecycle = undefined
+    if (cause.code !== 'ENOENT') observationWarning = 'HARBOR_DIAGNOSTIC_OBSERVATION_UNSAFE'
+  }
+  return { resultRef, lifecycle, total: provenance.selection.length, ...(observationWarning ? { observationWarning } : {}) }
+}
+
+/** Bounded local artifact reads only. Missing evidence is not manufactured progress. */
+export async function observeDiagnostic(config, operation, { root }) {
+  try {
+    const { resultRef, lifecycle, total, observationWarning } = await evidence(config, operation, root, { tolerateLifecycleError: true })
+    if (!lifecycle) return { resultRef, ...(observationWarning ? { observationWarning } : {}) }
+    const counts = {}
+    for (const trial of lifecycle.trials) counts[trial.phase] = (counts[trial.phase] ?? 0) + 1
+    return { resultRef, progress: { source: 'harbor-lifecycle', total, completed: lifecycle.trials.filter(trial => trial.terminal).length, counts, ...(typeof lifecycle.updated_at === 'string' && Number.isFinite(Date.parse(lifecycle.updated_at)) ? { updatedAt: lifecycle.updated_at } : {}) } }
+  } catch (cause) {
+    return cause.code === 'ENOENT' ? {} : { observationWarning: 'HARBOR_DIAGNOSTIC_OBSERVATION_UNSAFE' }
+  }
+}
+
+function probeGroup(pid) {
+  try { process.kill(-pid, 0); return 'running' }
+  catch (cause) { if (cause.code !== 'ESRCH') return 'unknown' }
+  // A reused live PID is deliberately a blocker, never a process to signal.
+  try { process.kill(pid, 0); return 'running' }
+  catch (cause) { return cause.code === 'ESRCH' ? 'stopped' : 'unknown' }
+}
+
+const composeName = name => {
+  const lowered = name.toLowerCase()
+  return (/^[a-z0-9]/.test(lowered) ? lowered : `0${lowered}`).replace(/[^a-z0-9_-]/g, '-')
+}
+
+/** Read-only reconciliation. It does not kill processes or remove Docker resources. */
+export async function inspectDiagnostic(config, operation, { root, runProcess, processProbe = probeGroup, platform = process.platform }) {
+  const blockers = []
+  const checkpoint = operation.events?.find(event => event.result?.process)?.result.process
+  let processState = 'unknown'
+  let runtimeMatches = false
+  let environment
+  if (/^sha256:[a-f0-9]{64}$/.test(checkpoint?.hostIdentity ?? '') && /^sha256:[a-f0-9]{64}$/.test(checkpoint?.dockerIdentity ?? '') && checkpoint.platform === platform && checkpoint.dockerTransport === 'pinned-local-unix/v1') {
+    try {
+      environment = await pinDiagnosticEnvironment(runProcess, process.env)
+      const current = await readDiagnosticRuntimeIdentity({ runProcess, platform, env: environment })
+      runtimeMatches = current.hostIdentity === checkpoint.hostIdentity && current.dockerIdentity === checkpoint.dockerIdentity
+    } catch {}
+  }
+  if (!runtimeMatches) blockers.push({ code: 'DIAGNOSTIC_RUNTIME_IDENTITY_UNVERIFIED', message: 'The recorded Host machine and Docker daemon cannot be matched. Restore the original runtime/context and inspect again; a different empty daemon is not proof of cleanup.' })
+  if (runtimeMatches && Number.isSafeInteger(checkpoint?.pid) && checkpoint.pid > 1 && checkpoint.groupId === checkpoint.pid && ['darwin', 'linux'].includes(checkpoint.platform)) {
+    try { processState = await processProbe(checkpoint.pid) } catch {}
+    if (!['stopped', 'running', 'unknown'].includes(processState)) processState = 'unknown'
+  }
+  const processInfo = { state: processState, ...(checkpoint?.pid ? { pid: checkpoint.pid, groupId: checkpoint.groupId } : {}) }
+  if (processState !== 'stopped') blockers.push({ code: processState === 'running' ? 'DIAGNOSTIC_PROCESS_PRESENT' : 'DIAGNOSTIC_PROCESS_OWNERSHIP_UNKNOWN', message: processState === 'running' ? 'The recorded process or process group still exists. Stop the original Host-owned run and inspect again; no signal was sent.' : 'A trustworthy stopped-process checkpoint is unavailable. An administrator must reconcile the original runner; no resources or lock were changed.' })
+  let resources = { state: 'unknown', items: [] }, resultRef
+  try {
+    const value = await evidence(config, operation, root)
+    resultRef = value.resultRef
+    if (!runtimeMatches) fail()
+    if (!value.lifecycle) fail()
+    const names = value.lifecycle.trials.map(trial => trial.trial_name).filter(Boolean)
+    // A separate-verifier name is truncated to 63 characters by Harbor. For
+    // longer Trial names that can truncate the ownership prefix itself, so
+    // refuse to infer cleanup instead of missing those resources.
+    if (names.some(name => typeof name !== 'string' || !/^[A-Za-z0-9_.-]{1,50}$/.test(name)) || value.lifecycle.trials.some(trial => trial.phase !== 'queued' && !trial.trial_name)) fail()
+    // Harbor 0.21's POSIX Docker adapter binds every environment and separate
+    // verifier project to `<trial_name>__…`. Trial-start is journaled before
+    // environment launch. We read labels only, never environment variables.
+    const prefixes = names.map(name => `${composeName(name)}__`)
+    const items = []
+    for (const kind of ['container', 'network', 'volume']) {
+      const args = [kind, 'ls', ...(kind === 'container' ? ['--all'] : []), '--filter', 'label=com.docker.compose.project', '--format', '{{.ID}}\t{{.Label "com.docker.compose.project"}}']
+      if (kind === 'volume') args[args.length - 1] = '{{.Name}}\t{{.Label "com.docker.compose.project"}}'
+      const response = await runProcess('docker', args, { cwd: root, env: environment, timeoutMs: 10_000, maxOutputBytes: 128 * 1024 })
+      if (response.code !== 0 || typeof response.stdout !== 'string') fail()
+      for (const line of response.stdout.split('\n').filter(Boolean)) {
+        const [id, project, extra] = line.split('\t')
+        if (extra !== undefined || !/^[a-zA-Z0-9_.-]{1,200}$/.test(id ?? '') || !/^[a-z0-9_-]{1,220}$/.test(project ?? '')) fail()
+        if (prefixes.some(prefix => project.startsWith(prefix))) items.push({ kind, id, project })
+      }
+    }
+    const finalIdentity = await readDiagnosticRuntimeIdentity({ runProcess, platform, env: environment })
+    if (finalIdentity.hostIdentity !== checkpoint.hostIdentity || finalIdentity.dockerIdentity !== checkpoint.dockerIdentity) fail()
+    resources = { state: items.length ? 'remaining' : 'clean', items: items.sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`)), checkedProjects: prefixes, boundary: 'Owned Compose containers, networks and volumes only; shared image/build caches are retained.' }
+    if (items.length) blockers.push({ code: 'DIAGNOSTIC_RESOURCES_REMAIN', message: 'The listed Compose resources remain. Have the workspace administrator inspect these exact resources, then check again. This action never deletes resources.' })
+  } catch {
+    blockers.push({ code: 'DIAGNOSTIC_RESOURCES_UNKNOWN', message: 'Job provenance/lifecycle or Docker inspection is unavailable. Restore access and inspect again; an empty or unreadable response is not proof of cleanup.' })
+  }
+  return { process: processInfo, resources, ...(resultRef ? { resultRef } : {}), blockers, canRecover: processState === 'stopped' && resources.state === 'clean' }
+}

package/lib/diagnostic-runner.js

@@ -0,0 +1,206 @@
+import { lstat, open, realpath } from 'node:fs/promises'
+import { constants } from 'node:fs'
+import path from 'node:path'
+import { runBoundedProcess } from './bounded-process.js'
+import { buildEvaluationRunReceipt, redactDiagnostic, resolveWithin } from './evolution.js'
+import { inspectDiagnostic, observeDiagnostic, pinDiagnosticEnvironment, readDiagnosticRuntimeIdentity } from './diagnostic-observation.js'
+
+export const DIAGNOSTIC_LIMITS = Object.freeze({ maxTrials: 12, concurrency: 2, attempts: 1, maxRetries: 0, wallTimeoutMs: 900_000, maxModelRequests: 96, maxResponseBytes: 1_048_576 })
+const AGENT = 'harbor_dsh_evolution.agent:DshCandidateAgent'
+const PLUGIN = 'harbor_dsh_evolution.diagnostic_plugin:BoundedDiagnosticPlugin'
+const PLAN_PROTOCOL = 'harbor-bounded-diagnostic-plan/v1'
+const OPERATION_ID = /^hop_[A-Za-z0-9_-]{1,100}$/
+
+function failure(code, message) { return Object.assign(new Error(`${code}: ${message}`), { code }) }
+function aborted(signal) { if (signal?.aborted) throw failure('HARBOR_PROCESS_ABORTED', 'Diagnostic cancelled before launch.') }
+function bindingIdentity(binding) {
+  return Object.fromEntries(['provider', 'model', 'transport', 'protocol', 'reasoning_effort'].filter(key => binding?.[key] !== undefined).map(key => [key, binding[key]]))
+}
+function hasLockedRuntime(runtime) {
+  const safeSourcePath = value => typeof value === 'string' && value.length <= 1024 && value.trim() === value && !/[\\:\x00-\x1f\x7f]/.test(value) && !value.split('/').some(part => ['', '.', '..', 'node_modules', '.harbor-runtime', '.git'].includes(part))
+  return runtime?.kind === 'deepseek-harness' && runtime.policy === 'candidate-locked' && runtime.transport === 'acp'
+    && runtime.descriptor === 'candidate-runtime.json' && runtime.lockfile === 'package-lock.json'
+    && safeSourcePath(runtime.entrypoint) && /\.(?:js|mjs|cjs)$/.test(runtime.entrypoint)
+    && safeSourcePath(runtime.config_path) && typeof runtime.agent_entry_id === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(runtime.agent_entry_id)
+    && typeof runtime.node_version === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(runtime.node_version) && Number(runtime.node_version.split('.')[0]) >= 22
+    && ['descriptor_digest', 'entrypoint_digest', 'lockfile_digest'].every(key => /^sha256:[a-f0-9]{64}$/.test(runtime[key] ?? ''))
+}
+function assertPlan(plan) {
+  if (plan?.protocol !== PLAN_PROTOCOL || !/^sha256:[a-f0-9]{64}$/.test(plan.planDigest ?? '') || plan.mode !== 'diagnostic' || plan.promotionEligible !== false || !Array.isArray(plan.selection) || !plan.selection.length || plan.selection.length > DIAGNOSTIC_LIMITS.maxTrials || Object.entries(DIAGNOSTIC_LIMITS).some(([key, value]) => plan.limits?.[key] !== value)) {
+    throw failure('HARBOR_DIAGNOSTIC_PLAN_INVALID', 'The installed adapter did not produce the bounded diagnostic contract.')
+  }
+  if (!hasLockedRuntime(plan.identities?.candidate?.runtime)) {
+    throw failure('HARBOR_DIAGNOSTIC_RUNTIME_ADAPTER_UNSUPPORTED', 'Update the Python Adapter and review a new plan; it has not verified a locked Candidate-owned ACP runtime. No Job was started.')
+  }
+}
+function safeProcessError(error) {
+  const code = /^HARBOR_[A-Z_]+$/.test(error?.code ?? '') ? error.code : 'HARBOR_DIAGNOSTIC_EXECUTION_FAILED'
+  return failure(code, redactDiagnostic(error?.message ?? 'Diagnostic execution failed.').slice(0, 600))
+}
+
+async function safeJsonArtifact(root, file, maxBytes = 4 * 1024 * 1024) {
+  const target = resolveWithin(root, file, 'diagnostic artifact')
+  const relative = path.relative(root, target)
+  let cursor = root
+  for (const part of relative.split(path.sep)) {
+    cursor = path.join(cursor, part)
+    if ((await lstat(cursor)).isSymbolicLink()) throw failure('HARBOR_DIAGNOSTIC_ARTIFACT_INVALID', 'Diagnostic artifacts must not traverse symlinks.')
+  }
+  const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const stats = await handle.stat()
+    if (!stats.isFile() || stats.size > maxBytes) throw failure('HARBOR_DIAGNOSTIC_ARTIFACT_INVALID', 'Diagnostic artifacts exceeded the bounded regular-file contract.')
+    return JSON.parse(await handle.readFile('utf8'))
+  } finally { await handle.close() }
+}
+
+/** Fixed CLI adapter. Authorization, idempotency and persistent Operation state belong to the Host controller. */
+export class DiagnosticRunner {
+  constructor(config, modelRuntime, { runProcess = runBoundedProcess, platform = process.platform, processProbe } = {}) {
+    this.config = config
+    this.modelRuntime = modelRuntime
+    this.runProcess = runProcess
+    this.platform = platform
+    this.processProbe = processProbe
+  }
+
+  async observe(operation, { owner } = {}) {
+    return observeDiagnostic(this.config, operation, { root: await this._root(owner) })
+  }
+
+  async inspect(operation, { owner } = {}) {
+    return inspectDiagnostic(this.config, operation, { root: await this._root(owner), runProcess: this.runProcess, processProbe: this.processProbe, platform: this.platform })
+  }
+
+  async _root(owner) {
+    if (!owner?.sessionId || !owner.projectRoot) throw failure('HARBOR_DIAGNOSTIC_OWNER_REQUIRED', 'A current Session project is required.')
+    const root = await realpath(owner.projectRoot)
+    if (root !== await realpath(this.config.projectRoot)) throw failure('HARBOR_DIAGNOSTIC_SOURCE_DENIED', 'The diagnostic runner belongs to a different project.')
+    if (this.platform === 'win32') throw failure('HARBOR_DIAGNOSTIC_RUNTIME_UNSUPPORTED', 'This runner requires POSIX process-group cancellation; Windows execution is not enabled.')
+    return root
+  }
+
+  _environment() { return { ...process.env, HARBOR_TELEMETRY: '0', ...(this.config.pythonPath ? { PYTHONPATH: this.config.pythonPath } : {}) } }
+
+  async _json(args, root, { input, signal, timeoutMs = 30_000 } = {}) {
+    let result
+    try {
+      result = await this.runProcess(this.config.harborDshBin, args, { cwd: root, env: this._environment(), timeoutMs, signal, allowedExitCodes: [0, 2], maxOutputBytes: 4 * 1024 * 1024, ...(input ? { input: JSON.stringify(input) } : {}) })
+    } catch (error) { throw safeProcessError(error) }
+    let value
+    try { value = JSON.parse(result.stdout) } catch { throw failure('HARBOR_DIAGNOSTIC_ADAPTER_UNAVAILABLE', 'Update the Python Adapter; its bounded diagnostic response is missing or invalid.') }
+    if (value?.error) {
+      const message = redactDiagnostic(value.error).slice(0, 600)
+      throw failure(message.match(/^(HARBOR_[A-Z_]+):/)?.[1] ?? 'HARBOR_DIAGNOSTIC_SOURCE_INVALID', message)
+    }
+    return value
+  }
+
+  async _binding(plan) {
+    if (!this.modelRuntime?.resolve || !this.modelRuntime?.openLease) throw failure('HARBOR_DIAGNOSTIC_MODEL_UNAVAILABLE', 'The Host model broker is not connected.')
+    const pinned = plan.candidateModelBinding
+    const binding = await this.modelRuntime.resolve({}, pinned, { ignoreConfigured: true })
+    if (JSON.stringify(bindingIdentity(binding)) !== JSON.stringify(bindingIdentity(pinned))) throw failure('HARBOR_DIAGNOSTIC_MODEL_CHANGED', 'The recorded Candidate model cannot be resolved exactly.')
+    return binding
+  }
+
+  async prepare({ owner, sourceJobDir, trialIds, signal }) {
+    const root = await this._root(owner)
+    const source = resolveWithin(root, sourceJobDir, 'source Job')
+    const plan = await this._json(['diagnostic-subset', 'plan'], root, { input: { projectRoot: root, sourceJobDir: source, trialIds }, signal })
+    assertPlan(plan)
+    const binding = await this._binding(plan)
+    if (typeof this.modelRuntime.assertLeaseLimits !== 'function') throw failure('HARBOR_DIAGNOSTIC_MODEL_LIMIT_UNSUPPORTED', 'The Host broker cannot prove the requested model budget; update the runtime before running.')
+    const budget = await this.modelRuntime.assertLeaseLimits(binding, { maxRequests: DIAGNOSTIC_LIMITS.maxModelRequests, maxResponseBytes: DIAGNOSTIC_LIMITS.maxResponseBytes })
+    if (!Number.isSafeInteger(budget?.maxRequests) || budget.maxRequests < 1 || budget.maxRequests > DIAGNOSTIC_LIMITS.maxModelRequests || !Number.isSafeInteger(budget?.maxResponseBytes) || budget.maxResponseBytes < 1 || budget.maxResponseBytes > DIAGNOSTIC_LIMITS.maxResponseBytes) throw failure('HARBOR_DIAGNOSTIC_MODEL_LIMIT_UNSUPPORTED', 'The Host broker returned an invalid effective budget.')
+    const runtime = await this._json(['docker-check'], root, { signal })
+    if (runtime?.valid !== true) {
+      const codes = (runtime?.findings ?? []).filter(item => item.level === 'error').map(item => String(item.code)).filter(code => /^DOCKER_[A-Z_]+$/.test(code))
+      throw failure('HARBOR_DIAGNOSTIC_RUNTIME_BLOCKED', `Docker is not ready (${codes.join(', ') || 'DOCKER_UNAVAILABLE'}). Fix the runtime and check parameters again; no Job was started.`)
+    }
+    // This is a read-only capability check. Unsupported remote/TLS transports
+    // must be visible in preflight, not discovered after user confirmation.
+    await pinDiagnosticEnvironment(this.runProcess, this._environment())
+    try {
+      const version = await this.runProcess(this.config.harborBin, ['--version'], { cwd: root, env: this._environment(), timeoutMs: 10_000, signal, maxOutputBytes: 4096 })
+      if (!/\b0\.21\.\d+(?:\b|[-+])/.test(version.stdout)) throw failure('HARBOR_DIAGNOSTIC_RUNTIME_UNSUPPORTED', 'The bounded runner requires the installed Harbor 0.21 adapter contract.')
+    } catch (error) { throw safeProcessError(error) }
+    return { ...plan, effectiveLimits: { ...plan.limits, maxModelRequests: budget.maxRequests, maxResponseBytes: budget.maxResponseBytes } }
+  }
+
+  async execute(plan, { owner, operationId, signal, onSpawn, onUsage } = {}) {
+    if (!OPERATION_ID.test(operationId ?? '')) throw failure('HARBOR_DIAGNOSTIC_OPERATION_INVALID', 'A stable Host Operation ID is required.')
+    assertPlan(plan)
+    aborted(signal)
+    const root = await this._root(owner)
+    const trialIds = plan.selection.map(item => item.trialId)
+    const fresh = await this.prepare({ owner, sourceJobDir: plan.sourceJob, trialIds, signal })
+    if (fresh.planDigest !== plan.planDigest) throw failure('HARBOR_DIAGNOSTIC_REVISION_CONFLICT', 'Inputs changed since preflight. Review a new preview; no Job was started.')
+    if (plan.effectiveLimits && JSON.stringify(plan.effectiveLimits) !== JSON.stringify(fresh.effectiveLimits)) throw failure('HARBOR_DIAGNOSTIC_REVISION_CONFLICT', 'The effective diagnostic budget changed. Review a new preview; no Job was started.')
+    const binding = await this._binding(fresh)
+    const jobName = `diagnostic-${operationId.slice(4)}`
+    if (jobName.length > 100) throw failure('HARBOR_DIAGNOSTIC_OPERATION_INVALID', 'The Operation ID exceeds the fixed Job-name bound.')
+    const jobs = resolveWithin(root, this.config.jobsDir ?? 'jobs', 'jobs directory')
+    let cursor = root
+    for (const part of path.relative(root, jobs).split(path.sep).filter(Boolean)) {
+      cursor = path.join(cursor, part)
+      try { if ((await lstat(cursor)).isSymbolicLink()) throw failure('HARBOR_DIAGNOSTIC_SOURCE_DENIED', 'The Job output directory must not traverse symlinks.') }
+      catch (error) { if (error.code !== 'ENOENT') throw error }
+    }
+    const jobDir = path.join(jobs, jobName)
+    try { await lstat(jobDir); throw failure('HARBOR_DIAGNOSTIC_ALREADY_STARTED', 'This Operation already has a Job; it cannot be launched again.') }
+    catch (error) { if (error.code !== 'ENOENT') throw error }
+    aborted(signal)
+    const materialized = await this._json(['diagnostic-subset', 'materialize'], root, { input: { projectRoot: root, sourceJobDir: plan.sourceJob, trialIds, expectedPlanDigest: plan.planDigest, operationId }, signal, timeoutMs: 60_000 })
+    assertPlan(materialized)
+    const candidate = resolveWithin(root, materialized.candidatePath, 'Candidate')
+    const dataset = resolveWithin(root, materialized.datasetPath, 'diagnostic Dataset')
+    const stack = resolveWithin(root, materialized.stackPath, 'Evaluation Stack')
+    const identity = materialized.identities.candidate
+    const args = [
+      'run', '-p', dataset, '-a', AGENT,
+      '--ak', `candidate_path=${candidate}`, '--ak', `candidate_version=${identity.version}`, '--ak', `candidate_digest=${identity.digest}`,
+      '--ak', `candidate_model_provider=${binding.provider}`, '--ak', `candidate_model=${binding.model}`,
+      '--job-name', jobName, '--jobs-dir', jobs, '-n', String(DIAGNOSTIC_LIMITS.concurrency), '-k', '1', '--max-retries', '0', '-e', 'docker', '--delete',
+      '--plugin', PLUGIN, '--plugin-kwarg', `candidate_manifest=${path.join(candidate, 'candidate-manifest.json')}`,
+      '--plugin-kwarg', `dataset_path=${dataset}`, '--plugin-kwarg', `stack_path=${stack}`, '--plugin-kwarg', `project_root=${root}`, '--plugin-kwarg', 'mode=diagnostic',
+      '--plugin-kwarg', `candidate_model_provider=${binding.provider}`, '--plugin-kwarg', `candidate_model=${binding.model}`,
+      '--plugin-kwarg', `candidate_model_transport=${binding.transport}`, '--plugin-kwarg', `candidate_model_protocol=${binding.protocol}`,
+      '--plugin-kwarg', `expected_dataset_digest=${materialized.datasetIdentity.source_digest}`, '--plugin-kwarg', `expected_stack_digest=${materialized.identities.stack.digest}`,
+      '--plugin-kwarg', `operation_id=${operationId}`, '--plugin-kwarg', `source_plan_digest=${materialized.planDigest}`,
+    ]
+    if (binding.reasoning_effort !== undefined) args.push('--ak', `candidate_reasoning_effort=${binding.reasoning_effort}`, '--plugin-kwarg', `candidate_reasoning_effort=${binding.reasoning_effort}`)
+    aborted(signal)
+    const environment = await pinDiagnosticEnvironment(this.runProcess, this._environment())
+    const runtimeIdentity = await readDiagnosticRuntimeIdentity({ runProcess: this.runProcess, platform: this.platform, env: environment })
+    aborted(signal)
+    const lease = await this.modelRuntime.openLease(binding, { candidateDigest: identity.digest, jobName, maxRequests: fresh.effectiveLimits.maxModelRequests, maxResponseBytes: fresh.effectiveLimits.maxResponseBytes })
+    let processStarted = false
+    // A lightweight in-memory counter is sampled by the controller; unlike
+    // lifecycle evidence, request usage cannot be reconstructed after restart.
+    onUsage?.(() => lease.usage?.())
+    const executionError = error => {
+      const safe = safeProcessError(error)
+      if (processStarted) Object.assign(safe, { cleanupRequired: true, jobName, diagnosticOnly: true })
+      return safe
+    }
+    try {
+      const result = await this.runProcess(this.config.harborBin, args, {
+        cwd: root, env: { ...environment, 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 },
+        timeoutMs: DIAGNOSTIC_LIMITS.wallTimeoutMs, maxOutputBytes: 2 * 1024 * 1024, killGraceMs: 30_000, signal,
+        onSpawn: pid => { processStarted = true; return onSpawn?.(pid, { job: jobName, dataset: materialized.datasetIdentity, operationId, process: { pid, groupId: pid, platform: this.platform, dockerTransport: 'pinned-local-unix/v1', ...runtimeIdentity } }) },
+      })
+      const summary = await safeJsonArtifact(root, path.join(jobDir, 'evaluation-summary.json'))
+      const context = await safeJsonArtifact(root, path.join(jobDir, 'evaluation-context.json'))
+      const count = plan.selection.length
+      if (summary?.schema_version !== 3 || summary.job !== jobName || summary.mode !== 'diagnostic' || summary.n_trials !== count || summary.n_discovered_trials !== count || summary.artifact_validation?.valid !== true || context.mode !== 'diagnostic' || context.candidate?.digest !== identity.digest || context.dataset?.source_digest !== materialized.datasetIdentity.source_digest || context.evaluation_stack?.digest !== materialized.identities.stack.digest || summary.evaluation_context?.full_digest !== context.full_digest) {
+        throw failure('HARBOR_DIAGNOSTIC_ARTIFACT_INVALID', 'The Job process ended without complete, identity-matching diagnostic artifacts. Inspect the Job; it is not a successful evaluation.')
+      }
+      return { ...buildEvaluationRunReceipt({ jobName, mode: 'diagnostic', summary, processCode: result.code }), schema: 'harbor-diagnostic-operation-result/v1', operationId, jobName, productionImpact: 'none', promotionEligible: false, sourceJob: path.basename(plan.sourceJob), selectionCount: count, freshBaselineRequired: true, limits: fresh.effectiveLimits }
+    } catch (error) { throw executionError(error) }
+    finally {
+      try { await lease.close() }
+      catch (error) { throw executionError(error) }
+    }
+  }
+}

package/lib/evaluator-saves.js

@@ -0,0 +1,129 @@
+import { constants } from 'node:fs'
+import { access, lstat, mkdir, open, rename, unlink } from 'node:fs/promises'
+import { createHash, randomUUID } from 'node:crypto'
+import path from 'node:path'
+
+const SCHEMA = 'harbor-evaluator-save/v1'
+const IDENTITY = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,99}$/
+const DIGEST = /^(?:sha256:)?[a-f0-9]{64}$/i
+const MAX_RECORD_BYTES = 16 * 1024
+const fail = () => { throw new Error('HARBOR_EVALUATOR_SAVE_HISTORY_UNAVAILABLE: Saved-version history could not be safely read or recorded.') }
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex')
+
+function relativeFile(value) {
+  if (typeof value !== 'string' || !value || value.length > 1024 || /[\u0000-\u001f\u007f\\]/.test(value) || value.startsWith('/') || /^[a-z][a-z\d+.-]*:/i.test(value) || value.split('/').some(part => !part || part === '.' || part === '..')) fail()
+  return value
+}
+
+function identity(value) { if (typeof value !== 'string' || !IDENTITY.test(value)) fail(); return value }
+
+function scopeFor(args) {
+  const scope = { sessionId: args.sessionId, workspace: args.workspace, job: args.job }
+  // Workspace IDs may begin with a dot (the project-root workspace label).
+  // These opaque strings are hashed, never interpolated into a file path.
+  if (Object.values(scope).some(value => typeof value !== 'string' || !value || value.length > 512 || /[\u0000-\u001f\u007f]/.test(value))) fail()
+  return scope
+}
+
+export function evaluatorSourceIdentity(governance) {
+  const evaluator = governance?.components?.evaluator
+  return { stack: governance?.stackIdentity, evaluator: { id: evaluator?.id, version: evaluator?.version, digest: evaluator?.digest, entry: evaluator?.entry }, contextDigest: governance?.contextDigest }
+}
+
+// The journal stores identities only, never browser-supplied receipts, source
+// text, credentials, or evaluation claims. Live source is re-read by the Host.
+function receiptIdentity(receipt) {
+  const evaluator = receipt?.evaluator
+  const stack = receipt?.stack
+  if (typeof evaluator?.digest !== 'string' || !DIGEST.test(evaluator.digest)) fail()
+  return {
+    stack: { id: identity(stack?.id), version: identity(stack?.version), path: relativeFile(stack?.path) },
+    evaluator: { evaluator_id: identity(evaluator?.evaluator_id), version: identity(evaluator?.version), descriptor_path: relativeFile(evaluator?.descriptor_path), digest: evaluator.digest },
+    requires_fresh_baseline: true, automatic_evaluation: false, automatic_gate: false,
+  }
+}
+
+async function directory(root, create) {
+  let current = path.resolve(root)
+  for (const segment of ['.harbor', 'workbench-evaluator-saves']) {
+    current = path.join(current, segment)
+    if (create) await mkdir(current, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error })
+    const details = await lstat(current)
+    if (!details.isDirectory() || details.isSymbolicLink()) fail()
+  }
+  return current
+}
+
+async function stackDigest(config, relative) {
+  const segments = relativeFile(relative).split('/')
+  let file = path.resolve(config.projectRoot)
+  for (const segment of segments) {
+    file = path.join(file, segment)
+    if ((await lstat(file)).isSymbolicLink()) fail()
+  }
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const details = await handle.stat()
+    if (!details.isFile() || details.size > 1024 * 1024) fail()
+    return `sha256:${createHash('sha256').update(await handle.readFile()).digest('hex')}`
+  } finally { await handle.close() }
+}
+
+// Check journal access before mutating the evaluator. A later disk failure must
+// still be reported as a *saved* version with recovery unavailable, not a failed
+// save which invites the user to repeat a successful source mutation.
+export async function prepareEvaluatorSaveHistory(config, args) {
+  const scope = scopeFor(args)
+  const destination = await directory(config.projectRoot, true)
+  await access(destination, constants.W_OK)
+  return { scope, destination }
+}
+
+export async function recordEvaluatorSave(config, args, governance, receipt) {
+  if (receipt?.requires_fresh_baseline !== true || receipt?.automatic_evaluation !== false || receipt?.automatic_gate !== false) fail()
+  const { scope, destination } = await prepareEvaluatorSaveHistory(config, args)
+  const value = receiptIdentity(receipt)
+  const record = { schema: SCHEMA, scope, sourceDigest: hash(evaluatorSourceIdentity(governance)), stackDigest: await stackDigest(config, value.stack.path), savedAt: new Date().toISOString(), receipt: value }
+  const temporary = path.join(destination, `.save-${randomUUID()}.tmp`)
+  let handle
+  try {
+    handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600)
+    await handle.writeFile(JSON.stringify(record))
+    await handle.sync()
+    await handle.close(); handle = undefined
+    await rename(temporary, path.join(destination, `${hash(scope)}.json`))
+  } finally {
+    await handle?.close()
+    await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error })
+  }
+  return { ...receipt, continuation: { verification: 'VERIFIED', savedAt: record.savedAt, durable: true } }
+}
+
+export async function readEvaluatorSave(config, args, governance, current, inspect) {
+  const scope = scopeFor(args)
+  let handle
+  let record
+  try {
+    const destination = await directory(config.projectRoot, false)
+    handle = await open(path.join(destination, `${hash(scope)}.json`), constants.O_RDONLY | constants.O_NOFOLLOW)
+    const details = await handle.stat()
+    if (!details.isFile() || details.size > MAX_RECORD_BYTES) fail()
+    record = JSON.parse(await handle.readFile('utf8'))
+  } catch (error) { if (error.code === 'ENOENT') return undefined; throw error }
+  finally { await handle?.close() }
+  if (record.schema !== SCHEMA || hash(record.scope) !== hash(scope) || record.sourceDigest !== hash(evaluatorSourceIdentity(governance)) || typeof record.stackDigest !== 'string' || !DIGEST.test(record.stackDigest) || typeof record.savedAt !== 'string' || !Number.isFinite(Date.parse(record.savedAt))) fail()
+  const receipt = receiptIdentity(record.receipt)
+  // A saved explicit Stack path can differ from the Job's default discovery
+  // path. Resolve only the validated recorded path through the Host inspector.
+  if (inspect && current?.stack?.path !== receipt.stack.path) {
+    try { current = await inspect(receipt.stack.path) } catch { current = undefined }
+  }
+  let verified = false
+  let available = Boolean(current)
+  try { verified = hash(receiptIdentity(current)) === hash(receipt) && await stackDigest(config, receipt.stack.path) === record.stackDigest } catch { available = false }
+  return {
+    ...receipt,
+    ...(verified ? { evaluator: { ...receipt.evaluator, editable_files: current.evaluator.editable_files } } : {}),
+    continuation: { verification: verified ? 'VERIFIED' : available ? 'DRIFTED' : 'UNAVAILABLE', savedAt: record.savedAt, durable: true, recovered: true },
+  }
+}