agentworkshop 0.7.66 → 0.7.71

package/server/services/workshop/optimization/run.repo.ts

@@ -0,0 +1,158 @@
+/**
+ * OptimizationRun / Candidate / Recommendation / Outcome 仓储(不可变运行台账)。
+ */
+/* eslint-disable @stylistic/max-statements-per-line, @stylistic/member-delimiter-style */
+import type { DatabaseSync } from 'node:sqlite'
+import { getAmlRuntime } from '../aml/runtime'
+import type { ProblemIR, Recommendation, RecommendationStatus, SolveCandidate, SolveResult } from './contracts'
+import { recommendationLabel } from './contracts'
+
+export interface RunRow {
+  id: string
+  bindingId: string
+  bindingRevision: number
+  profileId: string
+  profileVersion: number
+  problemIrHash: string
+  status: string
+  independentCost: number | null
+  startedAt: string
+  finishedAt: string | null
+  problemIrJson: string
+  diagnosticsJson: string
+}
+
+const RUN_COLS = `id, binding_id AS bindingId, binding_revision AS bindingRevision, profile_id AS profileId,
+  profile_version AS profileVersion, problem_ir_hash AS problemIrHash, status, independent_cost AS independentCost,
+  started_at AS startedAt, finished_at AS finishedAt, problem_ir_json AS problemIrJson, diagnostics_json AS diagnosticsJson`
+
+export function createRunRepo(db: DatabaseSync) {
+  return {
+    insertRun(input: { id: string, bindingId: string, bindingRevision: number, profileId: string, profileVersion: number, ir: ProblemIR, context: unknown, startedAt: string }): void {
+      db.prepare(`INSERT INTO optimizer_runs
+        (id, binding_id, binding_revision, profile_id, profile_version, problem_ir_hash, context_snapshot_json,
+         problem_ir_json, status, diagnostics_json, started_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'running', '{}', ?)`)
+        .run(input.id, input.bindingId, input.bindingRevision, input.profileId, input.profileVersion,
+          input.ir.hash, JSON.stringify(input.context ?? {}), JSON.stringify(input.ir), input.startedAt)
+    },
+
+    finishRun(id: string, result: SolveResult): void {
+      db.prepare(`UPDATE optimizer_runs SET status = ?, diagnostics_json = ?, independent_cost = ?, finished_at = ? WHERE id = ? AND status = 'running'`)
+        .run(result.status, JSON.stringify(result.diagnostics ?? {}), result.independentCost, new Date().toISOString(), id)
+    },
+
+    getRun(id: string): RunRow | undefined {
+      return db.prepare(`SELECT ${RUN_COLS} FROM optimizer_runs WHERE id = ?`).get(id) as unknown as RunRow | undefined
+    },
+
+    listRuns(filter: { bindingId?: string, limit?: number } = {}): RunRow[] {
+      const where = filter.bindingId ? 'WHERE binding_id = ?' : ''
+      const args: unknown[] = filter.bindingId ? [filter.bindingId, filter.limit ?? 50] : [filter.limit ?? 50]
+      return db.prepare(`SELECT ${RUN_COLS} FROM optimizer_runs ${where} ORDER BY started_at DESC LIMIT ?`).all(...(args as never[])) as unknown as RunRow[]
+    },
+
+    insertCandidates(runId: string, candidates: SolveCandidate[], modelId?: string): string[] {
+      const ids: string[] = []
+      for (const candidate of candidates) {
+        const id = `oc-${runId.slice(3)}-${candidate.seq}`
+        ids.push(id)
+        db.prepare(`INSERT INTO optimizer_candidates
+          (id, run_id, seq, controls_json, predicted_json, cost, constraints_json, verified, verify_report_json, model_id)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+          .run(id, runId, candidate.seq, JSON.stringify(candidate.controls), JSON.stringify(candidate.predicted),
+            candidate.cost, JSON.stringify(candidate.constraints), candidate.feasible ? 1 : 0, JSON.stringify({ feasible: candidate.feasible }), modelId ?? '')
+      }
+      return ids
+    },
+
+    getCandidate(id: string): { id: string, runId: string, seq: number, controls: number[][], predicted: number[][], cost: number | null, constraints: unknown[], verified: number } | undefined {
+      const r = db.prepare('SELECT id, run_id AS runId, seq, controls_json AS controls, predicted_json AS predicted, cost, constraints_json AS constraints, verified FROM optimizer_candidates WHERE id = ?').get(id) as Record<string, unknown> | undefined
+      if (!r) return undefined
+      return {
+        id: String(r.id),
+        runId: String(r.runId),
+        seq: Number(r.seq),
+        controls: JSON.parse(String(r.controls)) as number[][],
+        predicted: JSON.parse(String(r.predicted)) as number[][],
+        cost: r.cost == null ? null : Number(r.cost),
+        constraints: JSON.parse(String(r.constraints)) as unknown[],
+        verified: Number(r.verified ?? 0),
+      }
+    },
+
+    listCandidates(runId: string): Array<{ id: string, seq: number, cost: number | null }> {
+      return db.prepare('SELECT id, seq, cost FROM optimizer_candidates WHERE run_id = ? ORDER BY seq ASC').all(runId) as Array<{ id: string, seq: number, cost: number | null }>
+    },
+
+    insertRecommendation(input: {
+      id: string, runId: string, candidateId: string, problemIrHash: string, modelArtifactHash: string
+      evidenceSource: 'simulation' | 'real' | 'unassessed', uqEvidence: Record<string, unknown> | null
+      status: RecommendationStatus, validUntil: string
+    }): Recommendation {
+      const now = new Date().toISOString()
+      const label = recommendationLabel(input.status)
+      db.prepare(`INSERT INTO optimizer_recommendations
+        (id, run_id, candidate_id, problem_ir_hash, model_artifact_hash, evidence_source, uq_evidence_json,
+         status, status_label, legacy, valid_until, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, '', ?, ?)`)
+        .run(input.id, input.runId, input.candidateId, input.problemIrHash, input.modelArtifactHash,
+          input.evidenceSource, input.uqEvidence ? JSON.stringify(input.uqEvidence) : null,
+          input.status, label, input.validUntil, now)
+      return this.getRecommendation(input.id)!
+    },
+
+    getRecommendation(id: string): Recommendation | undefined {
+      const r = db.prepare(`SELECT id, run_id AS runId, candidate_id AS candidateId, problem_ir_hash AS problemIrHash,
+        model_artifact_hash AS modelArtifactHash, evidence_source AS evidenceSource, uq_evidence_json AS uqEvidenceJson,
+        status, status_label AS statusLabel, valid_until AS validUntil, created_at AS createdAt
+        FROM optimizer_recommendations WHERE id = ?`).get(id) as Record<string, unknown> | undefined
+      if (!r) return undefined
+      return {
+        id: String(r.id), runId: String(r.runId), candidateId: String(r.candidateId),
+        problemIrHash: String(r.problemIrHash), modelArtifactHash: String(r.modelArtifactHash),
+        evidenceSource: String(r.evidenceSource) as Recommendation['evidenceSource'],
+        uqEvidence: r.uqEvidenceJson ? JSON.parse(String(r.uqEvidenceJson)) as Record<string, unknown> : null,
+        status: String(r.status) as RecommendationStatus, statusLabel: String(r.statusLabel || recommendationLabel(String(r.status) as RecommendationStatus)),
+        validUntil: String(r.validUntil), createdAt: String(r.createdAt),
+      }
+    },
+
+    latestRecommendationForRun(runId: string): Recommendation | undefined {
+      const r = db.prepare('SELECT id FROM optimizer_recommendations WHERE run_id = ? ORDER BY created_at DESC LIMIT 1').get(runId) as { id: string } | undefined
+      return r ? this.getRecommendation(r.id) : undefined
+    },
+
+    /** 失效:工况/配方/权限/revison 变化 → 旧建议 expired(不删除,保留审计)。 */
+    expireWhere(filter: { bindingId?: string, runId?: string, problemIrHash?: string }): number {
+      const where: string[] = ['status != \'expired\'']
+      const args: unknown[] = []
+      if (filter.runId) { where.push('run_id = ?'); args.push(filter.runId) }
+      if (filter.problemIrHash) { where.push('problem_ir_hash = ?'); args.push(filter.problemIrHash) }
+      if (filter.bindingId) { where.push('run_id IN (SELECT id FROM optimizer_runs WHERE binding_id = ?)'); args.push(filter.bindingId) }
+      const r = db.prepare(`UPDATE optimizer_recommendations SET status = 'expired', status_label = ? WHERE ${where.join(' AND ')}`)
+        .run(recommendationLabel('expired'), ...(args as never[]))
+      return Number(r.changes)
+    },
+
+    insertOutcome(input: { id: string, recommendationId: string, appliedAt: string | null, observed: Record<string, unknown>, delta: Record<string, unknown>, verdict: string }): void {
+      db.prepare(`INSERT INTO optimizer_outcomes (id, recommendation_id, applied_at, observed_json, delta_json, verdict, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)`)
+        .run(input.id, input.recommendationId, input.appliedAt, JSON.stringify(input.observed), JSON.stringify(input.delta), input.verdict, new Date().toISOString())
+    },
+
+    listOutcomes(recommendationId: string): Array<{ id: string, verdict: string, delta: Record<string, unknown>, appliedAt: string | null }> {
+      return (db.prepare('SELECT id, verdict, delta_json AS delta, applied_at AS appliedAt FROM optimizer_outcomes WHERE recommendation_id = ? ORDER BY created_at ASC').all(recommendationId) as Array<{ id: string, verdict: string, delta: string, appliedAt: string | null }>)
+        .map(r => ({ id: r.id, verdict: r.verdict, delta: JSON.parse(r.delta) as Record<string, unknown>, appliedAt: r.appliedAt }))
+    },
+  }
+}
+
+export type RunRepo = ReturnType<typeof createRunRepo>
+
+const g = globalThis as typeof globalThis & { __optimizerRunRepo?: RunRepo }
+
+export function getRunRepo(): RunRepo {
+  g.__optimizerRunRepo ??= createRunRepo(getAmlRuntime().db)
+  return g.__optimizerRunRepo
+}

package/server/services/workshop/optimization/templates.ts

@@ -0,0 +1,3 @@
+/** 问题模板常量(与 Twin Registry 的 ObjectiveAdapter ref 同名)。 */
+export const LINEAR_MPC_TEMPLATE = 'linear_mpc_quadratic@1' as const
+export const STEADY_RESPONSE_TEMPLATE = 'steady_response@1' as const

package/server/services/workshop/optimization/uq-evidence.ts

@@ -0,0 +1,144 @@
+/**
+ * UQ 证据(D2/D3/D4/D5)——工件级、块级 conformal,唯一证据源。
+ *
+ * 统计量 = h 步 rollout 残差在块内最大值(逐 CV,模型单位);h = 训练时 ds.P(static 固定 1)。
+ * 校准段(val)定 qhat,检验段(test)实测 coverage —— 两段不相交。
+ * 两种模式:
+ *   - split_conformal:nValBlocks≥9 ∧ nValRuns≥2,分位数 ⌈(n+1)(1−α)⌉/n(α=0.1)
+ *   - empirical_max:2≤nValBlocks≤8,qhat = max(val)×1.25(预注册安全系数),coverage 必须 =1
+ * emit 条件:nUniqueTestSteps≥120 ∧ nTestRuns≥2;不足不发证(fail-closed)。
+ * verified 门限(D3):coverage ≥ max(0.8, 0.9−3√(0.09/nTestRuns));empirical_max → 1.0。
+ */
+import { amlUqFreshDays } from '../settings'
+
+export interface ArtifactUq {
+  method: 'split_conformal' | 'empirical_max'
+  qhatPerCv: number[]
+  coverageTest: number
+  alpha: number
+  horizon: number
+  nValBlocks: number
+  nValRuns: number
+  nValUniqueSteps: number
+  nTestBlocks: number
+  nTestRuns: number
+  nUniqueTestSteps: number
+  safetyFactor?: number
+  calibratedAt: string
+}
+
+export interface BlockUqInput {
+  /** val 段逐块逐 CV 的 max|h 步残差|(模型单位) */
+  valScoresPerCv: Array<number[]>
+  testScoresPerCv: Array<number[]>
+  nValRuns: number
+  nTestRuns: number
+  nUniqueTestSteps: number
+  horizon: number
+  alpha?: number
+  calibratedAt?: string
+}
+
+/** ⌈(n+1)(1−α)⌉ 阶统计量(split conformal;rank 超界时取 max) */
+function conformalQuantile(scores: number[], alpha: number): number {
+  const n = scores.length
+  if (!n) return Number.POSITIVE_INFINITY
+  const rank = Math.min(n, Math.ceil((n + 1) * (1 - alpha)))
+  const sorted = [...scores].sort((a, b) => a - b)
+  return sorted[rank - 1] ?? sorted[n - 1] ?? Number.POSITIVE_INFINITY
+}
+
+export function computeBlockUq(input: BlockUqInput): { uq: ArtifactUq | null, reason: string } {
+  const alpha = input.alpha ?? 0.1
+  const nValBlocks = input.valScoresPerCv.length
+  const nTestBlocks = input.testScoresPerCv.length
+  // emit 条件(D2):样本量不足不发 uq → 维持 unverified(fail-closed)
+  if (input.nUniqueTestSteps < 120 || input.nTestRuns < 2 || nTestBlocks < 1) {
+    return { uq: null, reason: `样本量不足(nUniqueTestSteps=${input.nUniqueTestSteps}<120 或 nTestRuns=${input.nTestRuns}<2);不发 UQ 证据` }
+  }
+  if (nValBlocks < 2 || input.nValRuns < 1) {
+    return { uq: null, reason: `校准块不足(nValBlocks=${nValBlocks}<2);不发 UQ 证据` }
+  }
+  const cvCount = input.valScoresPerCv[0]?.length ?? 0
+  if (!cvCount) return { uq: null, reason: '无 CV 校准分数' }
+
+  const useConformal = nValBlocks >= 9 && input.nValRuns >= 2
+  const qhatPerCv: number[] = []
+  for (let j = 0; j < cvCount; j++) {
+    const valScores = input.valScoresPerCv.map(r => r[j] ?? Number.POSITIVE_INFINITY).filter(Number.isFinite)
+    if (valScores.length !== nValBlocks) return { uq: null, reason: `CV ${j} 校准分数含非有限值;不发 UQ 证据` }
+    qhatPerCv.push(useConformal ? conformalQuantile(valScores, alpha) : Math.max(...valScores) * 1.25)
+  }
+  // test 段实测 coverage(逐 CV 命中块数/测试块数;门取 min_j)
+  let minCoverage = 1
+  for (let j = 0; j < cvCount; j++) {
+    const testScores = input.testScoresPerCv.map(r => r[j] ?? Number.POSITIVE_INFINITY)
+    const hits = testScores.filter(s => Number.isFinite(s) && s <= (qhatPerCv[j] ?? Number.POSITIVE_INFINITY)).length
+    minCoverage = Math.min(minCoverage, nTestBlocks ? hits / nTestBlocks : 0)
+  }
+  return {
+    uq: {
+      method: useConformal ? 'split_conformal' : 'empirical_max',
+      qhatPerCv: qhatPerCv.map(q => Number(q.toFixed(9))),
+      coverageTest: Number(minCoverage.toFixed(6)),
+      alpha,
+      horizon: input.horizon,
+      nValBlocks,
+      nValRuns: input.nValRuns,
+      nValUniqueSteps: 0,
+      nTestBlocks,
+      nTestRuns: input.nTestRuns,
+      nUniqueTestSteps: input.nUniqueTestSteps,
+      ...(useConformal ? {} : { safetyFactor: 1.25 }),
+      calibratedAt: input.calibratedAt ?? new Date().toISOString(),
+    },
+    reason: useConformal ? 'split_conformal' : 'empirical_max(经验界,非 conformal)',
+  }
+}
+
+/** D3 verified 门限:0.8 硬底(裸公式在小样本塌缩到 0.264);empirical_max 必须 1.0 */
+export function coverageThreshold(uq: Pick<ArtifactUq, 'method' | 'nTestRuns'>): number {
+  if (uq.method === 'empirical_max') return 1.0
+  const n = Math.max(1, uq.nTestRuns)
+  return Math.max(0.8, 0.9 - 3 * Math.sqrt(0.09 / n))
+}
+
+/** D4 inputDistance = MV+CV 双偏移(σ 取工件 norm;σ≈0 → ∞;列数不符 → null,不伪造) */
+export function inputDistance(input: {
+  currentU: Array<number | undefined>
+  currentY: Array<number | undefined>
+  normU: { mean: number[], std: number[] }
+  normY: { mean: number[], std: number[] }
+}): number | null {
+  const dev = (values: Array<number | undefined>, norm: { mean: number[], std: number[] }): number | null => {
+    if (values.length !== norm.std.length || values.length !== norm.mean.length) return null
+    let max = 0
+    for (let i = 0; i < values.length; i++) {
+      const v = values[i]
+      if (v === undefined || !Number.isFinite(v)) return null
+      const sigma = Math.abs(norm.std[i] ?? 0)
+      if (sigma < 1e-9) return Number.POSITIVE_INFINITY
+      max = Math.max(max, Math.abs((v - (norm.mean[i] ?? 0)) / sigma))
+    }
+    return max
+  }
+  const du = dev(input.currentU, input.normU)
+  if (du === null) return null
+  const dy = dev(input.currentY, input.normY)
+  if (dy === null) return null
+  return Math.max(du, dy)
+}
+
+/** UQ 保鲜(D2):calibratedAt 超过 aml.uq.freshDays → 过期 */
+export function isUqFresh(uq: Pick<ArtifactUq, 'calibratedAt'>, now = Date.now()): boolean {
+  const t = Date.parse(uq.calibratedAt)
+  if (!Number.isFinite(t)) return false
+  return now - t <= amlUqFreshDays() * 86_400_000
+}
+
+/** 建议 UQ 证据快照(进 recommendation 行;含 artifactHash 锚,杜绝双证据路径) */
+export interface RecommendationUqEvidence extends ArtifactUq {
+  artifactHash: string
+  calibrationFresh: boolean
+  inputDistance: number | null
+}

package/server/services/workshop/optimization/worker-client.ts

@@ -0,0 +1,358 @@
+/**
+ * Optimizer Python Worker 客户端(G3.1 / B.9.3)。
+ *
+ *  - 有界进程池(默认 1,范围 1–4),每进程同时 1 个 solve;
+ *  - NDJSON(stdin/stdout),请求 ID、硬超时、协作取消 + 必要时杀独占进程;
+ *  - Worker 崩溃:在途请求标 interrupted(不自动重放),指数退避补位;
+ *  - 复用 AML 共享 .venv(不建第二套环境),线程预算显式注入,不继承 secrets。
+ */
+/* eslint-disable @stylistic/max-statements-per-line */
+import { existsSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ChildProcess } from 'node:child_process'
+import { createInterface } from 'node:readline'
+import { AppError } from '../../../utils/errors'
+import { getAmlRuntime } from '../aml/runtime'
+import { ensureVenv, jobEnv, platformPythonDir } from '../aml/python-runtime'
+import { acquireEnvReadLease } from '../aml/env-lease'
+import { killHarnessProcess } from '../agents/harness-process'
+import { spawnLineProcess } from '../agents/adapters/line-spawn'
+import { optimizerSolverSettings } from '../settings'
+import { createLogger } from '../logger'
+import type { ProblemIR, SolverEventFrame, SolverRequestFrame, SolverResponseFrame } from './contracts'
+
+const log = createLogger('optimizer.worker')
+const PROTOCOL_VERSION = 1
+const KILL_CONFIRM_MS = 5000
+
+export function optimizerPythonDir(): string {
+  const candidates = [
+    process.env.AW_OPTIMIZER_PYHOME,
+    join(process.cwd(), 'server/services/workshop/optimization/python'),
+    join(process.cwd(), '.output/.AgentWorkShop/optimizer-python'),
+  ].filter((p): p is string => Boolean(p))
+  for (const candidate of candidates) {
+    if (existsSync(join(candidate, 'worker.py'))) return candidate
+  }
+  return join(process.cwd(), 'server/services/workshop/optimization/python')
+}
+
+/** 求解进程环境:jobEnv 白名单 + 线程预算;不继承 process.env。 */
+export function solverEnv(amlRoot: string, pythonDir: string, threads: number): Record<string, string> {
+  const rt = getAmlRuntime()
+  const solverDir = join(amlRoot, 'runtime', 'solver')
+  mkdirSync(solverDir, { recursive: true })
+  const env = jobEnv(rt, solverDir)
+  env.PYTHONPATH = [pythonDir, platformPythonDir()].join(process.platform === 'win32' ? ';' : ':')
+  const n = String(Math.max(1, Math.min(threads, 16)))
+  env.OMP_NUM_THREADS = n
+  env.OPENBLAS_NUM_THREADS = n
+  env.MKL_NUM_THREADS = n
+  env.NUMEXPR_NUM_THREADS = n
+  env.PYTHONHASHSEED = '0'
+  return env
+}
+
+export interface WorkerClientOptions {
+  poolSize: number
+  requestTimeoutMs: number
+  threads: number
+}
+
+interface Pending {
+  reqId: string
+  resolve: (value: unknown) => void
+  reject: (error: Error) => void
+  timer: NodeJS.Timeout
+}
+
+class WorkerProc {
+  child: ChildProcess | null = null
+  ready = false
+  retiring = false
+  inFlight: string | null = null
+  pending = new Map<string, Pending>()
+  pid = 0
+  /** ready 帧原样保留(协议版本/pid 可核验;测试与排障共用) */
+  readyFrame: SolverEventFrame | null = null
+
+  constructor(readonly index: number) {}
+
+  async ensureSpawned(pythonPath: string, pythonDir: string, threads: number): Promise<void> {
+    if (this.retiring) throw new AppError(503, 'WORKER_RETIRING', 'Solver Worker 正在退出')
+    if (this.child && this.ready) return
+    if (this.child) return
+    const rt = getAmlRuntime()
+    const env = solverEnv(rt.root, pythonDir, threads)
+    const child = spawnLineProcess(pythonPath, [join(pythonDir, 'worker.py')], { cwd: pythonDir, env, cleanEnv: true })
+    this.child = child
+    this.pid = child.pid ?? 0
+    const rl = createInterface({ input: child.stdout! })
+    rl.on('line', line => this.onLine(line))
+    child.stderr?.on('data', (chunk: Buffer) => {
+      const text = chunk.toString('utf8').trimEnd()
+      if (text) log.info(`[worker ${this.index}] ${text.slice(-400)}`)
+    })
+    child.once('exit', (code, signal) => this.onExit(code, signal))
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new AppError(503, 'WORKER_START_TIMEOUT', 'Solver Worker 启动超时(未收到 ready 帧)')), 20_000)
+      const check = setInterval(() => {
+        if (this.ready) { clearInterval(check); clearTimeout(timer); resolve() }
+      }, 25)
+      child.once('exit', () => { clearInterval(check); clearTimeout(timer); reject(new AppError(503, 'WORKER_EXITED', `Solver Worker 启动即退出(pid=${this.pid})`)) })
+    })
+  }
+
+  private onLine(line: string): void {
+    let frame: Record<string, unknown>
+    try {
+      frame = JSON.parse(line) as Record<string, unknown>
+    }
+    catch {
+      log.warn(`[worker ${this.index}] 非协议 stdout 行被忽略:${line.slice(0, 200)}`)
+      return
+    }
+    if (frame.type === 'ready') {
+      const readyFrame = frame as unknown as SolverEventFrame
+      const diagPid = Number((readyFrame.diag as { pid?: number } | undefined)?.pid ?? 0)
+      if (readyFrame.protocolVersion !== PROTOCOL_VERSION || !Number.isInteger(diagPid) || diagPid <= 0) {
+        log.error(`[worker ${this.index}] ready 帧非法(protocolVersion=${String(readyFrame.protocolVersion)} pid=${String(diagPid)});终止该进程`)
+        this.retiring = true
+        if (this.pid) killHarnessProcess(this.pid)
+        return
+      }
+      this.readyFrame = readyFrame
+      this.ready = true
+      return
+    }
+    if (frame.type === 'heartbeat' || frame.type === 'log') {
+      if (frame.type === 'log') log.info(`[worker ${this.index}] ${String(frame.message ?? '')}`)
+      return
+    }
+    const reqId = String(frame.reqId ?? '')
+    const pending = this.pending.get(reqId)
+    if (!pending) return
+    clearTimeout(pending.timer)
+    this.pending.delete(reqId)
+    this.inFlight = null
+    pending.resolve(frame)
+  }
+
+  private onExit(code: number | null, signal: NodeJS.Signals | null): void {
+    if (this.inFlight != null) this.retiring = true
+    this.ready = false
+    this.child = null
+    this.pid = 0
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer)
+      pending.reject(new AppError(503, 'WORKER_INTERRUPTED', `Solver Worker 退出(code=${code} signal=${signal});在途请求标 interrupted`))
+    }
+    this.pending.clear()
+    this.inFlight = null
+  }
+
+  async send(frame: SolverRequestFrame, timeoutMs: number): Promise<unknown> {
+    if (!this.child || this.retiring) throw new AppError(503, 'WORKER_NOT_READY', 'Solver Worker 未启动或正在退出')
+    const reqId = frame.reqId
+    return await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        // 必须在清空请求前封存,否则并发排队请求会复用即将被终止的旧进程。
+        this.retiring = true
+        this.pending.delete(reqId)
+        this.inFlight = null
+        void this.cancel(reqId)
+        reject(new AppError(504, 'SOLVE_TIMEOUT', `求解超时(${timeoutMs}ms);已请求取消`))
+      }, timeoutMs)
+      this.pending.set(reqId, { reqId, resolve, reject, timer })
+      this.inFlight = reqId
+      this.child!.stdin!.write(`${JSON.stringify(frame)}\n`)
+    })
+  }
+
+  async cancel(reqId: string): Promise<void> {
+    if (!this.child) return
+    this.child.stdin?.write(`${JSON.stringify({ protocolVersion: PROTOCOL_VERSION, reqId: `cancel-${reqId}`, op: 'cancel', payload: { reqId } })}\n`)
+  }
+}
+
+export class SolverWorkerPool {
+  private readonly workers: WorkerProc[]
+  private pythonPath: string | null = null
+  private readonly pythonDir = optimizerPythonDir()
+  private consecutiveFailures = 0
+  private degraded = false
+  private nextAttemptAt = 0
+  private readonly options: WorkerClientOptions
+
+  constructor(options?: Partial<WorkerClientOptions>) {
+    const defaults = workerOptionsFromSettings()
+    this.options = { ...defaults, ...options }
+    this.workers = Array.from({ length: Math.max(1, Math.min(this.options.poolSize, 4)) }, (_, index) => new WorkerProc(index))
+  }
+
+  get size(): number { return this.workers.length }
+
+  /** 在跑 Worker 的 pid(排障/验收:崩溃恢复与进程退出确认) */
+  workerPids(): number[] {
+    return this.workers.map(w => w.pid).filter(pid => pid > 0)
+  }
+
+  stats(): { size: number, ready: number, busy: number, degraded: boolean, pythonPath: string | null } {
+    return {
+      size: this.workers.length,
+      ready: this.workers.filter(w => w.ready && !w.retiring).length,
+      busy: this.workers.filter(w => w.inFlight != null || w.retiring).length,
+      degraded: this.degraded,
+      pythonPath: this.pythonPath,
+    }
+  }
+
+  async ensureReady(): Promise<string> {
+    if (this.pythonPath) return this.pythonPath
+    const rt = getAmlRuntime()
+    this.pythonPath = await ensureVenv(rt)
+    return this.pythonPath
+  }
+
+  /** 能力探针:缺依赖返回 ENV_MISSING_DEP(不要等请求崩)。 */
+  async probe(): Promise<{ ok: boolean, osqp: boolean, scipy: boolean, pythonPath: string }> {
+    const pythonPath = await this.ensureReady()
+    // 固定脚本文件(不使用 -c 内联代码,零拼接);子进程统一走 line-spawn 包装
+    const child = spawnLineProcess(pythonPath, [join(this.pythonDir, 'probe.py')], {
+      cwd: this.pythonDir, env: solverEnv(getAmlRuntime().root, this.pythonDir, this.options.threads), cleanEnv: true,
+    })
+    const chunks: string[] = []
+    child.stdout?.on('data', (chunk: Buffer) => chunks.push(chunk.toString('utf8')))
+    const code = await new Promise<number>((resolve) => {
+      const timer = setTimeout(() => {
+        if (child.pid) killHarnessProcess(child.pid)
+        resolve(-1)
+      }, 30_000)
+      child.once('exit', (exitCode) => { clearTimeout(timer); resolve(exitCode ?? -1) })
+    })
+    let parsed: { osqp?: string | null, scipy?: string | null } = {}
+    try { parsed = JSON.parse(chunks.join('').trim() || '{}') as typeof parsed }
+    catch { /* 保持空 */ }
+    return { ok: code === 0, osqp: Boolean(parsed.osqp), scipy: Boolean(parsed.scipy), pythonPath }
+  }
+
+  async solve(ir: ProblemIR, opts: { timeoutMs?: number, requestId?: string } = {}): Promise<{ result: unknown, workerPid: number, elapsedMs: number }> {
+    if (this.degraded) throw new AppError(503, 'SOLVER_UNAVAILABLE', 'Solver Worker 池已降级(连续崩溃);检查 optimizer_capabilities 并重启实例')
+    if (Date.now() < this.nextAttemptAt) throw new AppError(503, 'SOLVER_RESTARTING', 'Solver Worker 正在退避重启,请稍后重试')
+    const probe = await this.probe()
+    if (!probe.ok) throw new AppError(503, 'ENV_MISSING_DEP', '求解环境缺少 osqp/scipy;请重建 AML 环境(requirements 已锁定 osqp)')
+    const lease = acquireEnvReadLease('optimizer-solver')
+    const started = Date.now()
+    try {
+      const slot = await this.acquireSlot()
+      const reqId = opts.requestId ?? `solve-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`
+      const timeoutMs = opts.timeoutMs ?? this.options.requestTimeoutMs
+      try {
+        await slot.ensureSpawned(probe.pythonPath, this.pythonDir, this.options.threads)
+      }
+      catch (err) {
+        // 预占失败必须释放,否则该槽位永久 busy
+        slot.inFlight = null
+        await this.retire(slot)
+        throw err
+      }
+      const frame: SolverRequestFrame = {
+        protocolVersion: PROTOCOL_VERSION, reqId, op: 'solve',
+        payload: { problemIr: ir }, deadlineMs: timeoutMs,
+      }
+      try {
+        const response = await slot.send(frame, timeoutMs) as SolverResponseFrame
+        this.consecutiveFailures = 0
+        if (!response.ok) {
+          const error = response.error ?? { code: 'SOLVER_ERROR', message: 'unknown' }
+          throw new AppError(422, error.code, error.message)
+        }
+        return { result: response.result, workerPid: slot.pid, elapsedMs: Date.now() - started }
+      }
+      catch (err) {
+        const code = err instanceof AppError ? err.code : ''
+        if (code === 'SOLVE_TIMEOUT' || code === 'WORKER_INTERRUPTED') {
+          // 超时/崩溃:独占进程直接终止(单任务进程,安全兜底),确认退出后从池移除
+          await this.retire(slot)
+          this.consecutiveFailures++
+          if (this.consecutiveFailures >= 3) {
+            this.degraded = true
+            log.error('[optimizer-worker] 连续 3 次失败,池降级为不可用')
+          }
+          else {
+            this.nextAttemptAt = Date.now() + Math.min(4000, 1000 * 2 ** (this.consecutiveFailures - 1))
+          }
+        }
+        throw err
+      }
+    }
+    finally {
+      lease.release()
+    }
+  }
+
+  async cancel(reqId: string): Promise<void> {
+    for (const worker of this.workers) {
+      if (worker.inFlight === reqId) await worker.cancel(reqId)
+    }
+  }
+
+  /** 确认旧进程已退出才回收;超时则强杀进程树(Windows /T /F)。 */
+  private async retire(worker: WorkerProc): Promise<void> {
+    worker.retiring = true
+    const child = worker.child
+    if (!child) { worker.retiring = false; return }
+    const exited = new Promise<boolean>((resolve) => {
+      const timer = setTimeout(() => resolve(false), KILL_CONFIRM_MS)
+      child.once('exit', () => { clearTimeout(timer); worker.retiring = false; resolve(true) })
+    })
+    if (worker.pid) killHarnessProcess(worker.pid)
+    const confirmed = await exited
+    if (!confirmed) {
+      log.error(`[optimizer-worker] pid=${worker.pid} 5s 内未确认退出(KILL_CONFIRM=WORKER_KILL_FAILED),隔离该进程`)
+      // 保留封存槽位;仅当该进程真正退出后允许补位,不能静默缩小池容量。
+    }
+  }
+
+  private async acquireSlot(): Promise<WorkerProc> {
+    for (let attempt = 0; attempt < 600; attempt++) {
+      const free = this.workers.find(w => w.inFlight == null && !w.retiring)
+      if (free) {
+        // 预占:从 acquire 到 send 之间有 await(ensureSpawned),不预占会被并发请求
+        // 拿到同一进程并触发 SOLVER_BUSY。
+        free.inFlight = `reserved-${Date.now().toString(36)}-${attempt}`
+        return free
+      }
+      await new Promise(resolve => setTimeout(resolve, 50))
+    }
+    throw new AppError(429, 'SOLVER_QUEUE_FULL', 'Solver 进程池持续繁忙;请降低并发或扩大池上限')
+  }
+
+  async shutdown(): Promise<void> {
+    for (const worker of this.workers) {
+      if (worker.pid) killHarnessProcess(worker.pid)
+      worker.child = null
+    }
+    this.workers.length = 0
+  }
+}
+
+function workerOptionsFromSettings(): WorkerClientOptions {
+  const s = optimizerSolverSettings()
+  return { poolSize: s.poolSize, requestTimeoutMs: s.requestTimeoutMs, threads: s.threads }
+}
+
+const g = globalThis as typeof globalThis & { __optimizerWorkerPool?: SolverWorkerPool }
+
+export function getSolverWorkerPool(): SolverWorkerPool {
+  g.__optimizerWorkerPool ??= new SolverWorkerPool()
+  return g.__optimizerWorkerPool
+}
+
+/** 环境重建前由 env-manager 调用:先停 Worker(Windows rmSync 才能成功)。 */
+export function shutdownSolverWorkers(): void {
+  const pool = g.__optimizerWorkerPool
+  if (!pool) return
+  void pool.shutdown()
+  g.__optimizerWorkerPool = undefined
+}