@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/src/dsh-fusion.ts

@@ -0,0 +1,321 @@
+import { bi } from './bilingual.js'
+import { FusionError, TASK_BUSY, TASK_NOT_FOUND } from './errors.js'
+import { DeletionBlocked } from './task/deletion.js'
+import { backfillHistory, readHistory } from './host/history.js'
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { ModelModality } from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/dsh-api-session-controller'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-commands'
+import type {} from '@deepseek-ai/dsh-agent-default-model'
+import { FusionCatalogAdapter, FUSION_PROVIDER, FUSION_MODEL, installNativeFusionSelection } from './host/native-selection.js'
+import type { ResolvedProfile } from './profile/resolve.js'
+import { choiceFromProfile, modelProfileFromChoice, validatePairChoice, savedLeadRoute } from './host/settings.js'
+import { CachePolicy, cacheView } from './host/cache-policy.js'
+import { CACHE_DEFAULTS_CHECKED } from './host/cache-defaults.js'
+import { loadJsonObject, resolveProfile } from './profile/resolve.js'
+import { profileRoutes } from './profile/compactor.js'
+import { loadModelPromptBundle, loadPromptBundle } from './prompts.js'
+import { SqliteFusionStore } from './task/sqlite-store.js'
+import { BindingRepository, type SessionBinding } from './host/bindings.js'
+import { FusionCoordinator } from './host/coordinator.js'
+import { authorizeConfiguredPair, NativeRequestBudget } from './host/native-budget.js'
+import { json, readJson, trustedRequest } from './host/http.js'
+import { readFusionStatusAsync } from './host/status.js'
+import { readHistoricalFusionActivity } from './host/native-activity.js'
+import { nativeShellTool } from './host/shell.js'
+import { adoptLegacyStateDirectory } from './store-migration.js'
+import { FUSION_API_PATH, LEGACY_FUSION_API_PATH, LEGACY_PLUGIN_NAME, isFusionProvider } from './identity.js'
+
+export * from './index.js'
+
+export const name = 'dsh-fusion'
+export const inject = ['agents', 'sessions', 'llm', 'tools', 'subagents', 'systemPrompt', 'webServer', 'sessionController', 'sessionQuery', 'commands', 'agentDefaultModel', 'tokenMeter']
+export interface Config { profilePath?: string; authorizationPath?: string; databasePath?: string; workerTools?: string[] }
+const defaultWorkerTools = [nativeShellTool, 'read', 'write', 'edit', 'glob', 'grep', 'job_output', 'job_kill']
+// Schemastery otherwise normalizes an omitted array to [], bypassing ?? below.
+// An explicitly empty list must remain empty, so the default belongs in the schema.
+export const Config: z<Config> = z.object({ profilePath: z.string(), authorizationPath: z.string(), databasePath: z.string(),
+  workerTools: z.array(z.string()).default(defaultWorkerTools) })
+
+export async function apply(ctx: Context, config: Config = {}): Promise<void> {
+  const dshHome = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const database = config.databasePath || join(dshHome, 'plugins', name, 'state.sqlite')
+  if (!isAbsolute(database)) throw new Error('Fusion databasePath must be absolute')
+  // The plugin was called `dsh-model-fusion` before it was renamed. Its whole
+  // durable ledger — tasks, briefs, artifacts, cache settings — lives in that
+  // directory, so an installation upgrade must keep reading it rather than
+  // start an empty store beside it.
+  if (!config.databasePath) adoptLegacyStateDirectory(join(dshHome, 'plugins', LEGACY_PLUGIN_NAME), join(dshHome, 'plugins', name))
+  const store = new SqliteFusionStore(database), bindings = new BindingRepository(store)
+  const cachePolicy = new CachePolicy(store)
+  backfillHistory(store)
+  const budget = new NativeRequestBudget(store, config.authorizationPath)
+  let defaultProfile: ResolvedProfile | undefined
+  const physicalCatalog = async () => {
+    const catalog = await ctx.sessionController.modelCatalog()
+    return { ...catalog, groups: catalog.groups.filter(group => !isFusionProvider(group.id)) }
+  }
+  const configuredProfile = async (): Promise<ResolvedProfile> => {
+    defaultProfile = undefined
+    const saved = store.readDocument('settings:profile')
+    if (!saved && (!config.profilePath || !isAbsolute(config.profilePath))) throw new Error(bi('请先在设置的 Fusion 页面选择 Lead 和 Worker', 'Open Settings → Fusion and choose a Lead and a Sidekick first'))
+    const raw = saved?.value as Record<string, unknown> | undefined ?? loadJsonObject(config.profilePath!)
+    const catalog = await physicalCatalog()
+    const pair = validatePairChoice(raw, catalog)
+    const next = saved ? modelProfileFromChoice(pair) : raw
+    defaultProfile = resolveProfile(next, next.interactionMode === 'model-like' ? loadModelPromptBundle() : loadPromptBundle(), { authorizedRoutes: catalog.groups.flatMap(group =>
+      group.models.map(model => ({ provider: group.id, model: model.id }))) })
+    return defaultProfile
+  }
+  const needsBudget = (profile: ResolvedProfile['profile']) => Boolean(config.authorizationPath) || profile.interactionMode !== 'model-like'
+  let runtime: FusionCoordinator | undefined
+  const effectiveRoutes = (binding: SessionBinding) => profileRoutes({ ...binding.profile,
+    lead: runtime?.modelControl.route(binding, 'lead') ?? binding.profile.lead,
+    worker: runtime?.modelControl.route(binding, 'worker') ?? binding.profile.worker })
+  let creating: Promise<FusionCoordinator> | undefined
+  const getRuntime = (frozen?: ResolvedProfile): Promise<FusionCoordinator> => {
+    if (runtime) return Promise.resolve(runtime)
+    if (creating) return creating
+    creating = (async () => {
+      const profile = frozen ?? await configuredProfile()
+      runtime = new FusionCoordinator(ctx, store, { profile, workerTools: config.workerTools ?? defaultWorkerTools,
+        resumeAuthorization: binding => needsBudget(binding.profile) ? budget.check(effectiveRoutes(binding)).authorizationId : 'native-account',
+        authorizeRequest: (_agent, binding) => {
+          if (!needsBudget(binding.profile)) return
+          try { budget.check(effectiveRoutes(binding)) }
+          catch (error) {
+            const state = store.load(binding.taskId)
+            if (state?.control.mode === 'running' && !state.control.budgetBlocked) runtime?.append(binding.taskId, 'budget/blocked', { reason: String(error) })
+            throw error
+          }
+        },
+        reserveRequest: (request, binding) => {
+          if (!needsBudget(binding.profile)) return
+          try { budget.reserve({ provider: request.provider, model: request.model }, request.maxTokens ?? 0) }
+          catch (error) {
+            const state = store.load(binding.taskId)
+            if (state?.control.mode === 'running' && !state.control.budgetBlocked) runtime?.append(binding.taskId, 'budget/blocked', { reason: String(error) })
+            throw error
+          }
+        } })
+      return runtime
+    })().finally(() => { creating = undefined })
+    return creating
+  }
+  // The catalog entry admits what the configured Lead admits: the Lead is the
+  // only role that reads user content, while the Worker receives text work orders.
+  const leadInputModalities = async (): Promise<readonly ModelModality[] | undefined> => {
+    try {
+      const saved = store.readDocument('settings:profile')?.value
+      const lead = savedLeadRoute(saved)
+        ?? (config.profilePath && isAbsolute(config.profilePath) ? savedLeadRoute(loadJsonObject(config.profilePath)) : undefined)
+      if (!lead) return undefined
+      return (await ctx.llm.resolveModelInfo(lead.provider, lead.model)).inputModalities
+    } catch {
+      // An unresolvable Lead route (unregistered provider, retired model, broken
+      // profile file) cannot verify image support; the catalog entry stays text-only.
+      return undefined
+    }
+  }
+  ctx.effect(() => ctx.llm.registerAdapter([FUSION_PROVIDER], new FusionCatalogAdapter(leadInputModalities)))
+  ctx.effect(() => installNativeFusionSelection(ctx, {
+    coordinator: () => runtime, profile: () => defaultProfile,
+    selection: agent => {
+      const selection = agent.session.snapshotEvents().findLast(event => event.type === 'model/selection')
+      if (selection?.type === 'model/selection') return selection.data
+      if (bindings.read(agent.id)?.binding.selected) return { provider: FUSION_PROVIDER, model: FUSION_MODEL }
+      const header = agent.session.requestHeader()
+      return header ? { provider: header.config.provider, model: header.config.model } : ctx.agentDefaultModel.currentSelection()
+    },
+  }))
+  // Frozen bindings must be restored before another user request is allowed.
+  const restoreFailure = new Map<string, string>()
+  ctx.effect(() => ctx.on('agent/pre-step', async (payload, next) => {
+    const binding = bindings.read(payload.agent.id)?.binding
+    if (!binding?.selected) return next()
+    try { await getRuntime({ profile: binding.profile, prompts: binding.prompts }); if (restoreFailure.has(payload.agent.id)) restoreFailure.delete(payload.agent.id) }
+    catch (error) { restoreFailure.set(payload.agent.id, String(error)); return { kind: 'reject' } }
+    return next()
+  }, { prepend: true }))
+  const apiHandler: Parameters<Context['webServer']['register']>[0]['handler'] = async (req, res) => {
+    if (!trustedRequest(req)) return json(res, 403, { error: 'forbidden' })
+    try {
+      const url = new URL(req.url ?? '/', 'http://localhost')
+      if (req.method === 'GET') {
+        if (url.searchParams.get('view') === 'history') return json(res, 200, readHistory(store, url.searchParams.get('cursor') ?? ''))
+        if (url.searchParams.get('view') === 'activity') return json(res, 200, await readHistoricalFusionActivity(ctx, store,
+          url.searchParams.get('sessionId') ?? '', url.searchParams.get('callId') ?? '', Number(url.searchParams.get('after') ?? -1)))
+        if (url.searchParams.get('view') === 'status') {
+          const abort = new AbortController(), disconnected = () => abort.abort()
+          res.once('close', disconnected)
+          try {
+            const status = await readFusionStatusAsync(store, url.searchParams.get('sessionId') ?? '', abort.signal)
+            if (!res.destroyed) return json(res, 200, status)
+            return
+          } catch (error) { if (!abort.signal.aborted) throw error; return }
+          finally { res.off('close', disconnected) }
+        }
+        if (url.searchParams.get('view') === 'catalog') return json(res, 200, await ctx.sessionController.modelCatalog())
+        if (url.searchParams.get('view') === 'cache') {
+          let profile: ResolvedProfile | undefined
+          try { profile = await configuredProfile() } catch { profile = undefined }
+          return json(res, 200, { checked: CACHE_DEFAULTS_CHECKED, models: cacheView(cachePolicy,
+            profile ? { lead: profile.profile.lead, worker: profile.profile.worker } : undefined, profile?.profile.cacheKeepalive) })
+        }
+        if (url.searchParams.get('view') === 'settings') {
+          const saved = store.readDocument('settings:profile')
+          let profile: ResolvedProfile | undefined, reason: string | undefined, authorized = false
+          try {
+            profile = await configuredProfile()
+            if (needsBudget(profile.profile)) budget.check(profileRoutes(profile.profile)); authorized = true
+          } catch (error) { reason = error instanceof Error ? error.message : String(error) }
+          return json(res, 200, { revision: saved?.revision ?? 0, catalog: await physicalCatalog(),
+            pair: profile ? choiceFromProfile(profile.profile) : null,
+            authorized, reason, managedAuthorization: Boolean(config.authorizationPath), policy: profile?.profile.interactionMode ?? 'legacy', actualBilledUsd: null, apiEquivalentUsd: null })
+        }
+        const sessionId = url.searchParams.get('sessionId') ?? ''
+        const binding = sessionId && bindings.read(sessionId)?.binding
+        let available = false, reason: string | undefined
+        try {
+          const profile = binding && binding.selected ? { profile: binding.profile, prompts: binding.prompts } : await configuredProfile()
+          const controller = await getRuntime(profile)
+          controller.transport.assertAvailable()
+          if (needsBudget(profile.profile)) budget.check(profileRoutes(profile.profile))
+          available = true
+        } catch (error) { reason = error instanceof Error ? error.message : String(error) }
+        const state = binding && store.load(binding.taskId)
+        return json(res, 200, { selected: Boolean(binding && binding.selected), available, ...(reason ? { reason } : {}),
+          ...(state ? { task: { id: state.taskId, phase: state.phase, verification: state.verification, workerId: state.acceptedChild } } : {}) })
+      }
+      if (req.method === 'DELETE') {
+        const taskId = url.searchParams.get('taskId')
+        if (!taskId) return json(res, 400, { error: bi('缺少任务标识', 'Missing task id') })
+        try {
+          // The coordinator is the only authority that can see in-process Agents,
+          // tool calls and leases. It exists whenever this Host has served the plugin;
+          // without one, nothing in this process owns the task.
+          store.deleteTask(taskId, { liveReason: id => runtime?.liveWork(id) })
+          return json(res, 200, { ok: true, taskId })
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          // Decide on the stored code, not on message text: a translated message would silently become a 500.
+          if (error instanceof FusionError && error.code === TASK_NOT_FOUND) return json(res, 404, { error: message })
+          if (error instanceof FusionError && error.code === TASK_BUSY) {
+            const blocker = error instanceof DeletionBlocked ? error.blocker : undefined
+            const detail = error instanceof DeletionBlocked ? error.detail : undefined
+            return json(res, 409, { error: message, ...(blocker ? { blocker } : {}), ...(detail ? { detail } : {}) })
+          }
+          return json(res, 500, { error: message })
+        }
+      }
+      if (req.method !== 'POST') return json(res, 405, { error: 'method not allowed' })
+      const body = await readJson(req)
+      if (['continue', 'switch-role', 'schedule', 'cancel-schedule'].includes(String(body.action))) {
+        if (typeof body.sessionId !== 'string' || typeof body.taskId !== 'string' || !Number.isSafeInteger(body.revision)) throw new Error(bi('恢复参数无效', 'Invalid recovery parameters'))
+        const saved = bindings.read(body.sessionId)
+        if (!saved?.binding.selected || saved.binding.taskId !== body.taskId || saved.binding.profile.interactionMode !== 'model-like') throw new Error(bi('当前任务不支持此恢复操作', 'This task does not support that recovery action'))
+        const binding = saved.binding
+        const controller = await getRuntime({ profile: binding.profile, prompts: binding.prompts })
+        if (needsBudget(binding.profile)) budget.check(effectiveRoutes(binding))
+        if (body.action === 'cancel-schedule') {
+          const row = store.readDocument(`model-control:${body.sessionId}`)
+          if (row?.revision !== body.revision) throw new Error(bi('状态已变化，请刷新', 'The state changed; refresh'))
+          controller.modelControl.cancel(binding)
+        } else if (body.action === 'schedule') {
+          if (typeof body.dueAt !== 'string') throw new Error(bi('请选择继续时间', 'Choose when to continue'))
+          await controller.modelControl.schedule(body.sessionId, body.taskId, Number(body.revision), body.dueAt)
+        } else {
+          let change: { role: 'lead' | 'worker'; route: typeof binding.profile.lead } | undefined
+          if (body.action === 'switch-role') {
+            if (body.role !== 'lead' && body.role !== 'worker') throw new Error(bi('请选择要更换的角色', 'Choose the role to switch'))
+            const pair = validatePairChoice({ lead: body.route, worker: body.route }, await physicalCatalog())
+            change = { role: body.role, route: pair.lead }
+            if (needsBudget(binding.profile)) budget.check(profileRoutes({ ...binding.profile,
+              lead: controller.modelControl.route(binding, 'lead'), worker: controller.modelControl.route(binding, 'worker'), [change.role]: change.route }))
+          }
+          await controller.modelControl.continue(body.sessionId, body.taskId, Number(body.revision), change)
+        }
+        return json(res, 200, { ok: true })
+      }
+      if (body.action === 'cache-setting') {
+        if (typeof body.provider !== 'string' || typeof body.model !== 'string' || !body.provider || !body.model) throw new Error(bi('请选择模型', 'Choose a model'))
+        const setting = body.reset === true ? null : {
+          ...(body.mode === undefined || body.mode === null ? {} : { mode: body.mode as 'auto' | 'on' | 'off' }),
+          ...(body.intervalSeconds === undefined || body.intervalSeconds === null ? {} : { intervalSeconds: Number(body.intervalSeconds) }) }
+        cachePolicy.save(body.provider, body.model, setting)
+        return json(res, 200, { ok: true })
+      }
+      if (body.action === 'configure') {
+        if (!Number.isSafeInteger(body.revision) || Number(body.revision) < 0) throw new Error(bi('配置版本无效，请刷新后重试', 'Invalid settings revision; refresh and retry'))
+        const pair = validatePairChoice(body.pair, await physicalCatalog())
+        const revision = store.writeDocument('settings:profile', Number(body.revision), modelProfileFromChoice(pair))
+        const profile = await configuredProfile()
+        await getRuntime(profile)
+        return json(res, 200, { ok: true, revision })
+      }
+      if (body.action === 'authorize') {
+        if (config.authorizationPath) throw new Error(bi('运行额度由外部授权文件管理，不能在此覆盖', 'Run limits are managed by an external authorization file and cannot be overridden here'))
+        const saved = store.readDocument('settings:profile')
+        if (!saved || saved.revision !== body.revision) throw new Error(bi('模型组合已变化，请刷新后再启用额度', 'The pair changed; refresh before enabling limits'))
+        const profile = await configuredProfile()
+        if (store.readDocument('settings:profile')?.revision !== body.revision) throw new Error(bi('模型组合已变化，请刷新后再启用额度', 'The pair changed; refresh before enabling limits'))
+        const auth = authorizeConfiguredPair(store, profileRoutes(profile.profile), body.limits)
+        return json(res, 200, { ok: true, expiresAt: auth.expiresAt })
+      }
+      throw new Error(bi('请使用原模型菜单选择 Fusion 或切换普通模型', 'Use the model menu to select Fusion or another model'))
+    } catch (error) { return json(res, 409, { error: error instanceof Error ? error.message : String(error) }) }
+  }
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: FUSION_API_PATH, handler: apiHandler }))
+  // A tab still running the pre-rename bundle asks the old path until it is
+  // reloaded. Keep answering it from the same handler; nothing new uses it.
+  ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: LEGACY_FUSION_API_PATH, handler: apiHandler }))
+  ctx.effect(() => ctx.commands.register({ name: 'fusion', description: bi('Fusion 状态、暂停、恢复与退出（不调用模型）', 'Fusion status, pause, resume and exit (no model call)'),
+    input: { hint: bi('status | pause | resume | recover [--effects-stopped] <检查记录> | off', 'status | pause | resume | recover [--effects-stopped] <inspection note> | off') },
+    handler: async invocation => {
+      const [action = 'status', ...note] = invocation.rawInput.trim().split(/\s+/)
+      try {
+        const binding = bindings.read(invocation.agent.id)?.binding
+        if (!binding?.selected) return { kind: 'success', text: bi('当前会话未启用 Fusion。请在模型选择器中选择 Fusion · 自动。', 'Fusion is not selected in this conversation. Choose Fusion · auto in the model menu.') }
+        if (action === 'status' || action === '') {
+          const controller = await getRuntime({ profile: binding.profile, prompts: binding.prompts })
+          const state = store.load(binding.taskId)!
+          const unfinishedEffects = controller.effects.pending(binding.taskId).map(({ record }) => ({ role: record.role, tool: record.toolName }))
+          const usage = store.listDocumentIds(`usage:${state.taskId}:`).map(id => store.readDocument(id)!.value as { purpose?: string })
+          return { kind: 'success', text: JSON.stringify({ taskId: state.taskId, phase: state.phase, verification: state.verification,
+            control: state.control, workerId: state.acceptedChild, modelCalls: usage.length,
+            cacheKeepaliveCalls: usage.filter(row => row.purpose === 'cache-keepalive').length,
+            compactionCalls: usage.filter(row => row.purpose === 'compaction').length,
+            unfinishedEffects, ...(unfinishedEffects.length ? { recoveryHint: bi('请核对中断的工具操作，确认对应命令及子进程已停止；Host 退出不代表这些操作已结束。', 'Check the interrupted tool operations and confirm their commands and child processes stopped; a Host exit does not end them.') } : {}),
+            actualBilledUsd: null, apiEquivalentUsd: null }, null, 2) }
+        }
+        const controller = await getRuntime({ profile: binding.profile, prompts: binding.prompts })
+        if (action === 'pause') { controller.modelControl.cancel(binding); await controller.pause(invocation.agent) }
+        else if (action === 'resume') {
+          const authorizationId = needsBudget(binding.profile) ? budget.check(effectiveRoutes(binding)).authorizationId : 'native-account'
+          if (binding.profile.interactionMode === 'model-like') await controller.modelControl.continue(binding.sessionId, binding.taskId,
+            store.readDocument(`model-control:${binding.sessionId}`)?.revision ?? 0)
+          else await controller.resume(invocation.agent, authorizationId)
+        } else if (action === 'recover') await controller.reconcile(invocation.agent, { commandId: invocation.commandId,
+          effectsStopped: note[0] === '--effects-stopped', note: (note[0] === '--effects-stopped' ? note.slice(1) : note).join(' ') })
+        else if (action === 'off') {
+          await controller.clear(invocation.agent)
+          await ctx.sessionController.selectModel({ sessionId: SessionId(invocation.agent.id), ...binding.profile.lead })
+        }
+        else throw new Error(bi('使用 /fusion status、pause、resume、recover <检查记录> 或 off', 'Use /fusion status, pause, resume, recover <inspection note> or off'))
+        return { kind: 'success', text: action === 'resume' ? binding.profile.interactionMode === 'model-like' ? bi('已通过原生收件箱提交一次继续操作。', 'One continuation was submitted through the native inbox.') : bi('Fusion 已恢复。发送下一条消息继续当前任务。', 'Fusion resumed. Send a message to continue the task.') : bi(`Fusion ${action} 已完成。`, `Fusion ${action} done.`) }
+      } catch (error) { return { kind: 'error', text: error instanceof Error ? error.message : String(error) } }
+    } }))
+  ctx.effect(() => async () => { if (creating) await creating.catch(() => undefined); if (runtime) await runtime.close(); store.close() })
+  // Warm only configuration/scopes; initialization performs no inference.
+  try { await getRuntime(await configuredProfile()) }
+  catch {
+    const selected = bindings.selected()[0]
+    if (selected) await getRuntime({ profile: selected.profile, prompts: selected.prompts })
+  }
+  ctx.logger.info('[my-plugins/dsh-fusion] loaded')
+}

package/src/errors.ts

@@ -0,0 +1,34 @@
+export class FusionError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'FusionError'
+  }
+}
+
+export const FUSION_CONTEXT_BUDGET = 'FUSION_CONTEXT_BUDGET'
+export const REVISION_CONFLICT = 'REVISION_CONFLICT'
+export const REVISION_STALE = 'REVISION_STALE'
+export const EVENT_CONFLICT = 'EVENT_CONFLICT'
+export const FLUSH_FAILED = 'FLUSH_FAILED'
+export const CHECKSUM_MISMATCH = 'CHECKSUM_MISMATCH'
+export const LEASE_BUSY = 'LEASE_BUSY'
+export const LEASE_GENERATION = 'LEASE_GENERATION'
+export const PROFILE_UNAVAILABLE = 'PROFILE_UNAVAILABLE'
+export const SPEND_UNAUTHORIZED = 'SPEND_UNAUTHORIZED'
+export const APPROVAL_SCOPE = 'APPROVAL_SCOPE'
+export const OUTCOME_UNKNOWN = 'OUTCOME_UNKNOWN'
+export const NEEDS_REPAIR = 'NEEDS_REPAIR'
+export const USAGE_MERGE_CONFLICT = 'USAGE_MERGE_CONFLICT'
+export const USAGE_LEDGER_REQUIRED = 'USAGE_LEDGER_REQUIRED'
+export const CONTROL_BLOCKED = 'CONTROL_BLOCKED'
+export const REVIEW_RESULT_CONFLICT = 'REVIEW_RESULT_CONFLICT'
+export const REVIEW_TICKET_REQUIRED = 'REVIEW_TICKET_REQUIRED'
+export const WORK_ORDER_CONFLICT = 'WORK_ORDER_CONFLICT'
+export const STORE_MIGRATION_REQUIRED = 'STORE_MIGRATION_REQUIRED'
+/** No task carries this id (or it was already deleted). */
+export const TASK_NOT_FOUND = 'TASK_NOT_FOUND'
+/** Deleting it would strand a live Worker, lease or unfinished handoff. */
+export const TASK_BUSY = 'TASK_BUSY'

package/src/evidence/gate.ts

@@ -0,0 +1,290 @@
+import type {
+  AcceptanceCriterion,
+  Digest,
+  SnapshotId,
+  TaskId,
+  ToolEvidence,
+  VerificationLevel,
+  WorkOrder,
+  WorkerReport,
+} from '../contracts.js'
+import { sha256Hex } from '../digest.js'
+import {
+  artifactFingerprint,
+  assertPlannedCheck,
+  checkPlanDigest,
+  invocationHeader,
+  sameInvocationHeader,
+  type VerificationRegistry,
+} from './receipts.js'
+
+export interface EvidenceVerdict {
+  readonly verification: VerificationLevel
+  readonly reasons: readonly string[]
+}
+
+export type TrustedEvidenceRegistry =
+  | readonly ToolEvidence[]
+  | Readonly<Record<string, ToolEvidence>>
+  | ReadonlyMap<string, ToolEvidence>
+
+export interface RegisteredVerifier {
+  readonly id: string
+  readonly kind: AcceptanceCriterion['verificationKind']
+  readonly argvDigests?: readonly Digest[]
+}
+
+export interface EvaluateReportOptions {
+  readonly verifiers?: readonly RegisteredVerifier[]
+  readonly registry?: VerificationRegistry
+}
+
+export const DEFAULT_TEST_VERIFIERS: readonly RegisteredVerifier[] = [
+  { id: 'pytest', kind: 'test', argvDigests: [sha256Hex('python -m pytest')] },
+  { id: 'npm-test', kind: 'test', argvDigests: [sha256Hex('npm test')] },
+]
+
+interface EvidenceIndex {
+  readonly byId: ReadonlyMap<string, ToolEvidence>
+  readonly ambiguous: ReadonlySet<string>
+}
+
+function sameIdentity(left: ToolEvidence, right: ToolEvidence): boolean {
+  return left.operationId === right.operationId
+    && left.taskId === right.taskId
+    && left.nativeToolCallId === right.nativeToolCallId
+}
+
+function sameContent(left: ToolEvidence, right: ToolEvidence): boolean {
+  return sameIdentity(left, right)
+    && sameInvocationHeader(invocationHeader(left), invocationHeader(right))
+    && left.argvDigest === right.argvDigest
+    && left.cwdDigest === right.cwdDigest
+    && left.actor === right.actor
+    && left.state === right.state
+    && left.exitCode === right.exitCode
+    && left.inputSnapshot === right.inputSnapshot
+    && left.outputSnapshot === right.outputSnapshot
+    && left.endedAt === right.endedAt
+    && left.startedAt === right.startedAt
+    && artifactFingerprint(left.stdout) === artifactFingerprint(right.stdout)
+    && artifactFingerprint(left.stderr) === artifactFingerprint(right.stderr)
+    && (left.kind ?? 'tool') === (right.kind ?? 'tool')
+}
+
+function isLifecycleUpgrade(existing: ToolEvidence, incoming: ToolEvidence): boolean {
+  return sameIdentity(existing, incoming)
+    && sameInvocationHeader(invocationHeader(existing), invocationHeader(incoming))
+    && existing.state === 'started'
+    && incoming.state === 'completed'
+}
+
+function addAlias(byId: Map<string, ToolEvidence>, ambiguous: Set<string>, id: string, item: ToolEvidence): void {
+  const existing = byId.get(id)
+  if (!existing) {
+    byId.set(id, item)
+    return
+  }
+  if (sameContent(existing, item)) return
+  if (isLifecycleUpgrade(existing, item)) {
+    byId.set(id, item)
+    return
+  }
+  if (isLifecycleUpgrade(item, existing)) return
+  ambiguous.add(id)
+}
+
+function indexRegistry(registry: TrustedEvidenceRegistry): EvidenceIndex {
+  const byId = new Map<string, ToolEvidence>()
+  const ambiguous = new Set<string>()
+
+  const add = (item: ToolEvidence, explicitId?: string) => {
+    if (explicitId) addAlias(byId, ambiguous, explicitId, item)
+    addAlias(byId, ambiguous, item.operationId, item)
+    addAlias(byId, ambiguous, item.stdout.id, item)
+    addAlias(byId, ambiguous, item.stderr.id, item)
+  }
+
+  if (registry instanceof Map) {
+    for (const [id, item] of registry) add(item, id)
+  } else if (Array.isArray(registry)) {
+    for (const item of registry) add(item)
+  } else {
+    for (const [id, item] of Object.entries(registry)) add(item, id)
+  }
+
+  return { byId, ambiguous }
+}
+
+function eligibilityFailure(item: ToolEvidence, taskId: TaskId, currentSnapshot: SnapshotId): string | undefined {
+  if (item.taskId !== taskId) return `evidence ${item.operationId} belongs to task ${item.taskId}, not ${taskId}`
+  if (item.state !== 'completed') return `evidence ${item.operationId} is ${item.state}, not completed`
+  if (item.endedAt === null) return `evidence ${item.operationId} has no endedAt`
+  if (item.exitCode !== 0) return `evidence ${item.operationId} exited ${item.exitCode}`
+  if (item.inputSnapshot !== currentSnapshot) {
+    return `evidence ${item.operationId} input snapshot ${item.inputSnapshot} is not current ${currentSnapshot}`
+  }
+  if (item.outputSnapshot !== currentSnapshot) {
+    return `evidence ${item.operationId} output snapshot ${item.outputSnapshot ?? 'missing'} is not current ${currentSnapshot}`
+  }
+  return undefined
+}
+
+function plannedCheckFailure(
+  workOrder: WorkOrder,
+  criterion: AcceptanceCriterion,
+  evidenceId: string,
+  registry: VerificationRegistry | undefined,
+  actualSnapshot: SnapshotId,
+): string | undefined {
+  if (criterion.verificationKind === 'human' || criterion.verificationKind === 'review') return undefined
+  if (!registry || !criterion.planId || !criterion.planDigest) {
+    return `criterion ${criterion.id} has no frozen CheckPlan; allowedPaths are not a verification cwd`
+  }
+  const plan = registry.getPlan(criterion.planId)
+  if (!plan) return `criterion ${criterion.id} cites unknown plan ${criterion.planId}`
+  if (criterion.planDigest !== checkPlanDigest(plan)) {
+    return `criterion ${criterion.id} plan digest does not match the frozen work-order plan`
+  }
+  const receipt = registry.getReceipt(evidenceId)
+  if (!receipt) {
+    return `criterion ${criterion.id} cites legacy evidence ${evidenceId} without a planned receipt`
+  }
+  try {
+    assertPlannedCheck(workOrder, criterion.id, plan, receipt, actualSnapshot)
+    return undefined
+  } catch (error) {
+    return `criterion ${criterion.id}: ${(error as Error).message}`
+  }
+}
+
+function relevanceFailure(
+  criterion: AcceptanceCriterion,
+  record: ToolEvidence,
+  verifiers: readonly RegisteredVerifier[],
+): string | undefined {
+  const kind = record.kind ?? 'tool'
+  if (criterion.verificationKind === 'human') {
+    if (kind !== 'human-decision') {
+      return `human criterion ${criterion.id} cannot be fulfilled by a tool exit`
+    }
+    return undefined
+  }
+  if (criterion.verificationKind === 'review') {
+    if (kind !== 'review-accept') {
+      return `review criterion ${criterion.id} needs an accepting review record`
+    }
+    return undefined
+  }
+  const allowed = verifiers.filter(verifier => {
+    if (verifier.kind !== criterion.verificationKind) return false
+    if (criterion.verifierId && verifier.id !== criterion.verifierId) return false
+    return true
+  })
+  if (!allowed.some(verifier => verifier.argvDigests?.includes(record.argvDigest))) {
+    return `criterion ${criterion.id} evidence argv is not a registered ${criterion.verificationKind} verifier`
+  }
+  return undefined
+}
+
+/**
+ * Score only the current work order's mandatory criteria and the evidence those
+ * claims actually cite. Historical failures stay in the registry for audit.
+ * Authenticity and relevance are independent checks.
+ */
+export function evaluateReport(
+  workOrder: WorkOrder,
+  report: WorkerReport,
+  trustedRegistry: TrustedEvidenceRegistry,
+  currentSnapshot: SnapshotId,
+  options?: EvaluateReportOptions,
+): EvidenceVerdict {
+  const trust: string[] = []
+  if (report.workOrderId !== workOrder.id) {
+    trust.push(`report workOrderId ${report.workOrderId} does not match frozen work order ${workOrder.id}`)
+  }
+  if (report.revision !== workOrder.revision) {
+    trust.push(`report revision ${report.revision} does not match frozen work order revision ${workOrder.revision}`)
+  }
+  if (report.snapshot !== currentSnapshot) {
+    trust.push('snapshot drift: report snapshot is not the current workspace snapshot')
+  }
+
+  const acceptanceById = new Map(workOrder.acceptance.map(criterion => [criterion.id, criterion]))
+  const seenClaims = new Set<string>()
+  const index = indexRegistry(trustedRegistry)
+  const verifiers = options?.verifiers ?? DEFAULT_TEST_VERIFIERS
+  const satisfied = new Set<string>()
+
+  for (const claim of report.coverage) {
+    if (seenClaims.has(claim.criterionId)) {
+      trust.push(`duplicate criterion ${claim.criterionId}`)
+      continue
+    }
+    seenClaims.add(claim.criterionId)
+    if (!acceptanceById.has(claim.criterionId)) {
+      trust.push(`unknown criterion ${claim.criterionId}`)
+      continue
+    }
+    if (claim.state !== 'satisfied') continue
+    if (claim.evidenceIds.length === 0) {
+      trust.push(`criterion ${claim.criterionId} claimed satisfied without evidence`)
+      continue
+    }
+    const criterion = acceptanceById.get(claim.criterionId)!
+    const cited = new Set<string>()
+    let claimOk = true
+    for (const evidenceId of claim.evidenceIds) {
+      if (cited.has(evidenceId)) continue
+      cited.add(evidenceId)
+      if (index.ambiguous.has(evidenceId)) {
+        trust.push(`criterion ${claim.criterionId} cites ambiguous evidence id ${evidenceId}`)
+        claimOk = false
+        continue
+      }
+      if (criterion.verificationKind === 'test' || criterion.verificationKind === 'static-check') {
+        const planned = plannedCheckFailure(workOrder, criterion, evidenceId, options?.registry, currentSnapshot)
+        if (planned) {
+          trust.push(planned.startsWith('criterion ') ? planned : `criterion ${claim.criterionId}: ${planned}`)
+          claimOk = false
+        }
+        continue
+      }
+      const record = index.byId.get(evidenceId)
+      if (!record) {
+        trust.push(`criterion ${claim.criterionId} cites unknown evidence id ${evidenceId}`)
+        claimOk = false
+        continue
+      }
+      const why = eligibilityFailure(record, workOrder.taskId, currentSnapshot)
+        ?? relevanceFailure(criterion, record, verifiers)
+      if (why) {
+        trust.push(`criterion ${claim.criterionId}: ${why}`)
+        claimOk = false
+      }
+    }
+    if (claimOk) satisfied.add(claim.criterionId)
+  }
+
+  if (trust.length) {
+    return { verification: 'unverified', reasons: trust }
+  }
+
+  const coverage: string[] = []
+  if (report.status !== 'completed') {
+    coverage.push(`report status is ${report.status}`)
+  }
+  if (report.unresolved.length) {
+    coverage.push(`${report.unresolved.length} unresolved item(s) remain`)
+  }
+  for (const criterion of workOrder.acceptance) {
+    if (!criterion.mandatory) continue
+    if (!satisfied.has(criterion.id)) {
+      coverage.push(`mandatory criterion ${criterion.id} is not satisfied by current trusted evidence`)
+    }
+  }
+  if (coverage.length) {
+    return { verification: 'partial', reasons: coverage }
+  }
+  return { verification: 'verified', reasons: [] }
+}