@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/src/host/native-context.ts

@@ -0,0 +1,204 @@
+import { randomUUID } from 'node:crypto'
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction'
+import { createUserMessage, isAgentLoopRequest, LlmError } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/dsh-token-meter'
+import type {} from '@deepseek-ai/dsh-agent-preset-registry'
+import type { PhysicalRoute, Role, TokenMeasurement } from '../contracts.js'
+import { inputBudget, safetyTokens } from '../context/guard.js'
+import { digestOf } from '../digest.js'
+import { FUSION_CONTEXT_BUDGET } from '../errors.js'
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+import type { SessionBinding } from './bindings.js'
+import { FUSION_SOURCE_KIND, isFusionSourceKind } from '../message-source.js'
+import { nativeRequestAgent } from './native-request.js'
+import { FUSION_TASK_CONTEXT, type NativeTaskContext } from './native-task-context.js'
+import type { NativeAuxiliaryRequests } from './native-auxiliary.js'
+import { routeNativeCompaction } from './native-compaction.js'
+
+type Owner = { binding: SessionBinding; role: Role }
+interface ContextCheck {
+  route: PhysicalRoute
+  measurement: TokenMeasurement
+  budget: number
+  purpose: GenerateOptions['purpose'] | 'conversation' | 'cache-keepalive'
+  logRevision: number
+  nativeBaseline: string
+  minimumRetainedInputTokens: number
+}
+interface RejectedRequest extends ContextCheck { owner: Owner; recordId: string }
+
+/** Optional summary routing, then final admission and the Host's single compaction owner. */
+export class NativeContextGuard {
+  readonly #rejected = new WeakMap<Agent, RejectedRequest>()
+  constructor(readonly ctx: Context, readonly store: SqliteFusionStore,
+    readonly owner: (agent: Agent) => Owner | undefined,
+    readonly blocked: (owner: Owner, reason: string) => void,
+    readonly taskContext?: NativeTaskContext,
+    readonly auxiliary?: NativeAuxiliaryRequests,
+    readonly route?: (binding: SessionBinding, role: Role) => PhysicalRoute) {}
+
+  async measure(agent: Agent, owner: Owner, request: GenerateOptions): Promise<ContextCheck> {
+    const meter = this.ctx.get('tokenMeter')
+    if (!meter) throw new Error('Fusion requires the native tokenMeter service')
+    const separateCompactor = request.purpose === 'compaction' && owner.binding.profile.compactor
+    const route = separateCompactor ? separateCompactor.route : owner.binding.profile[owner.role]
+    const policy = owner.binding.profile.context[owner.role]
+    if (request.provider !== route.provider || request.model !== route.model) {
+      throw new Error('Fusion request must use its frozen role or compactor model')
+    }
+    const logged = isAgentLoopRequest(request) ? agent.session.requestContext() : undefined
+    const capacity = logged?.provider === request.provider && logged.model === request.model
+      ? logged.contextWindow : (await this.ctx.llm.resolveModelInfo(request.provider, request.model, request.signal)).context?.contextWindow
+    if (!Number.isSafeInteger(capacity) || Number(capacity) <= 0) throw new Error('The configured model does not disclose a usable context window')
+    const contextWindow = Number(capacity), output = request.maxTokens
+    if (!Number.isSafeInteger(output) || Number(output) <= 0) throw new Error('Fusion requires an explicit output token reservation')
+    const { messages, tools, signal: _signal, sessionId: _sessionId, purpose: _purpose, system, ...config } = request
+    const replay = meter.measure(agent.session, { config, ...(tools?.length ? { tools } : {}) })
+    // The actual one-shot envelope can include a summary directive or tools not
+    // on the current surface. Charge it too. JSON tool schemas use the public
+    // message estimator with extra framing, rather than a private meter import.
+    const text = (value: string) => meter.estimateMessage(createUserMessage({ content: [{ type: 'text', text: value }],
+      source: { kind: FUSION_SOURCE_KIND } }))
+    const fixed = (system ? text(system) : 0) + (tools?.length ? text(JSON.stringify(tools)) : 0)
+    const actual = messages.reduce((total, message) => total + meter.estimateMessage(message.id ? message : createUserMessage({ content: message.content, source: { kind: FUSION_SOURCE_KIND } })), 0) + fixed
+    const pinned = messages.flatMap(message => isFusionSourceKind(message.source?.kind)
+      && message.source.form === 'snapshot' ? message.source.sections.filter(section => section.name === FUSION_TASK_CONTEXT) : []).at(-1)
+    // A summary cannot shrink the required current task snapshot, system prompt
+    // or tool schemas. Reject an impossible restore before charging a summary.
+    const minimumRetainedInputTokens = fixed + (pinned ? text(pinned.text) : 0)
+    // Replay includes cached history once, including any native usage anchor.
+    // New surface deltas remain heuristic even when that anchor is measured.
+    const measurement: TokenMeasurement = {
+      // A separately routed summary reads only its selected region. The role's
+      // full-history usage anchor cannot price this different model's request.
+      inputTokens: this.auxiliary?.get(request) || separateCompactor ? actual : Math.max(replay.totalTokens, actual), reservedOutputTokens: Number(output), contextWindow,
+      safetyTokens: safetyTokens(contextWindow, policy, 'heuristic'), quality: 'heuristic',
+      requestDigest: digestOf({ ...config, messages, tools, system, purpose: request.purpose }),
+    }
+    // A summary repairs the role's soft target and must be allowed to read a
+    // larger prefix; it is still subject to the physical window and spend cap.
+    const effectivePolicy = request.purpose === 'compaction' ? { ...policy, targetInputTokens: contextWindow } : policy
+    return { route, measurement, budget: inputBudget(effectivePolicy, contextWindow, Number(output), 'heuristic'),
+      purpose: this.auxiliary?.get(request)?.purpose ?? request.purpose ?? 'conversation', logRevision: replay.logRevision,
+      nativeBaseline: replay.baseline.kind, minimumRetainedInputTokens }
+  }
+
+  install(admit: (agent: Agent, owner: Owner, request: GenerateOptions) => void,
+    ready: (agent: Agent, request: GenerateOptions) => void): () => void {
+    const guard = this
+    const disposeStream = this.ctx.on('llm/stream', async function* (request, next): AsyncIterable<StreamChunk> {
+      const agent = nativeRequestAgent(guard.ctx, request), owner = agent && guard.owner(agent)
+      if (!agent || !owner) { yield* next(); return }
+      const auxiliary = guard.auxiliary?.get(request)
+      ready(agent, request)
+      if (owner.binding.profile.interactionMode === 'model-like') {
+        // The native compactor and actual physical adapter own window/defaults.
+        // Keep request/effect admission, without inventing a second output cap.
+        routeNativeCompaction(request, owner.binding.profile, guard.route?.(owner.binding, owner.role))
+        admit(agent, owner, request)
+        yield* next()
+        return
+      }
+      let check: ContextCheck
+      try {
+        routeNativeCompaction(request, owner.binding.profile)
+        check = await guard.measure(agent, owner, request)
+      }
+      catch (error) {
+        const reason = `Fusion 上下文检查失败：${error instanceof Error ? error.message : String(error)}`
+        if (!auxiliary && request.purpose !== 'session-title') guard.blocked(owner, reason)
+        yield { type: 'finish', reason: { kind: 'error', failure: new LlmError(reason, 'FUSION_CONTEXT_UNAVAILABLE').failure } }
+        return
+      }
+      request.signal?.throwIfAborted()
+      const accepted = check.measurement.inputTokens <= check.budget
+      const recordId = `context-request:${owner.binding.taskId}:${randomUUID()}`
+      guard.store.writeDocument(recordId, 0, { schemaVersion: 1, sessionId: agent.id, role: owner.role,
+        taskId: owner.binding.taskId, checkedAt: new Date().toISOString(), admitted: accepted, ...check })
+      if (!accepted) {
+        const reason = `Fusion 上下文 ${check.measurement.inputTokens} 超过本轮预算 ${check.budget}（估算）`
+        if (isAgentLoopRequest(request) && request.purpose === undefined) guard.#rejected.set(agent, { owner, recordId, ...check })
+        else if (!auxiliary && request.purpose !== 'session-title') guard.blocked(owner, reason)
+        yield { type: 'finish', reason: { kind: 'error', failure: new LlmError(reason, FUSION_CONTEXT_BUDGET).failure } }
+        return
+      }
+      if (isAgentLoopRequest(request) && request.purpose === undefined) guard.#rejected.delete(agent)
+      // Run spend reservation only after context admission; rejected local
+      // attempts are neither upstream calls nor consumed call allowances.
+      ready(agent, request)
+      admit(agent, owner, request)
+      yield* next()
+    }, { prepend: true })
+    const disposeRecovery = this.ctx.on('agent/request-error', async ({ agent, turn, step, failure, signal }, next) => {
+      const rejected = this.#rejected.get(agent)
+      if (failure.code !== FUSION_CONTEXT_BUDGET || !rejected) return next()
+      this.#rejected.delete(agent)
+      const { owner } = rejected
+      const key = `context-recovery:${owner.binding.taskId}:${agent.id}:${turn}:${step}`
+      const saved = this.store.readDocument(key)
+      const prior = saved?.value as { attempts: number; priorInput: number } | undefined
+      const attempts = prior?.attempts ?? 0
+      const stop = (reason: string) => {
+        const current = this.store.readDocument(key)
+        const used = (current?.value as { attempts?: number } | undefined)?.attempts ?? attempts
+        this.store.writeDocument(key, current?.revision ?? 0,
+          { ...(current?.value as Record<string, unknown> | undefined), schemaVersion: 1, attempts: used,
+            priorInput: rejected.measurement.inputTokens, state: 'blocked', reason, request: rejected.recordId })
+        this.blocked(owner, reason)
+        return undefined
+      }
+      if (signal.aborted) return stop('上下文压缩已中断；Fusion 已暂停并保留原始记录')
+      if (rejected.minimumRetainedInputTokens > rejected.budget) return stop('Fusion 必须保留的任务内容已超过本轮上下文预算；请缩短最新交接或调整模型配置，原始记录已保留')
+      if (attempts >= 2 || prior && rejected.measurement.inputTokens >= prior.priorInput) return stop('上下文压缩没有继续缩小；Fusion 已暂停，保留原始记录')
+      // Web presets deliberately isolate this service. The public preset
+      // addressor selects this Agent's existing owner without mounting another.
+      const compaction = this.ctx.get('agentPresets')?.serviceFor(agent, 'compaction')
+        ?? agent.ctx.get('compaction') ?? this.ctx.get('compaction')
+      const meter = this.ctx.get('tokenMeter')
+      if (!compaction || !meter) return stop('DSH 未提供上下文压缩服务；Fusion 已暂停')
+      const measurement = meter.measure(agent.session)
+      const nodes = measurement.nodes
+      const first = nodes.findIndex(node => agent.session.eventAt(node.seq)?.type !== 'system/message')
+      // Keep the newest balanced unit and a bounded recent tail. Selection is
+      // by surface position, never numeric seq order after a replacement.
+      const policy = owner.binding.profile.context[owner.role]
+      const keepTokens = Math.max(0, Math.floor(rejected.budget * policy.compactToFraction)
+        - Math.max(0, measurement.totalTokens - measurement.surfaceTokens) - policy.reserveOutputTokens)
+      let keep = nodes.length - 1
+      while (keep > first && !toolPairingBalancedBefore(agent.session, nodes[keep]!.seq)) keep--
+      let retained = nodes.slice(Math.max(0, keep)).reduce((sum, node) => sum + node.tokens, 0)
+      for (let index = keep - 1; index > first; index--) {
+        retained += nodes[index]!.tokens
+        if (retained > keepTokens) break
+        if (toolPairingBalancedBefore(agent.session, nodes[index]!.seq)) keep = index
+      }
+      if (first < 0 || keep <= first) return stop('当前输入没有可安全压缩的历史；请缩短输入或调整 Fusion 模型配置')
+      this.store.writeDocument(key, saved?.revision ?? 0, { schemaVersion: 1, attempts: attempts + 1,
+        priorInput: rejected.measurement.inputTokens, state: 'started', request: rejected.recordId })
+      try {
+        const checkpoint = this.taskContext?.prepareCompaction(agent, owner.binding, owner.role,
+          nodes.slice(first, keep).map(node => node.seq))
+        const result = await compaction.compactRegion(nodes[first]!.seq, nodes[keep - 1]!.seq, agent, signal)
+        signal.throwIfAborted()
+        if (checkpoint) this.taskContext!.restoreCompaction(agent, owner.binding, owner.role, checkpoint, result.compactionId)
+        const after = meter.measure(agent.session).totalTokens
+        this.store.writeDocument(key, this.store.readDocument(key)!.revision, { schemaVersion: 1, attempts: attempts + 1,
+          priorInput: rejected.measurement.inputTokens, state: 'compacted', compactionId: result.compactionId,
+          beforeTokens: rejected.measurement.inputTokens, beforeNativeTokens: measurement.totalTokens,
+          afterTokens: after, request: rejected.recordId, ...(checkpoint ? { checkpoint } : {}) })
+        // A provider usage anchor can be below the actual one-shot envelope.
+        // Compare against the admitted measurement, then check the complete
+        // frozen retry again. A still-rejected nonshrinking retry stops above.
+        if (after >= rejected.measurement.inputTokens) return stop('DSH 压缩后上下文没有缩小；Fusion 已暂停')
+        return { kind: 'retry' }
+      } catch (error) {
+        if (signal.aborted) return stop('上下文压缩已中断；Fusion 已暂停并保留原始记录')
+        return stop(`DSH 上下文压缩失败；Fusion 已暂停：${error instanceof Error ? error.message : String(error)}`)
+      }
+    }, { prepend: true })
+    return () => { disposeRecovery(); disposeStream() }
+  }
+}

package/src/host/native-effects.ts

@@ -0,0 +1,260 @@
+import { randomUUID } from 'node:crypto'
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import { JobId } from '@deepseek-ai/dsh-jobs'
+import type { JobView } from '@deepseek-ai/dsh-jobs'
+import type { ArtifactRef, Role, TaskId } from '../contracts.js'
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+import type { SessionBinding } from './bindings.js'
+import { isShellTool } from './shell.js'
+
+interface EffectRecord {
+  schemaVersion: 1
+  taskId: TaskId
+  agentId: string
+  role: Role
+  callId: string
+  rootCallId: string
+  toolName: string
+  processId: number
+  startedAt: string
+  state: 'dispatch-started' | 'returned' | 'outcome-unknown' | 'inspected'
+  arguments: ArtifactRef
+  endedAt?: string
+  nativeIsError?: boolean
+  inspectionEvidence?: string
+  quiescenceBasis?: 'explicit-user-inspection'
+  nativeJob?: { id: string; startedAt: number; deadlineAt: number | null; status: JobView['status']; detail?: string }
+}
+
+/** Public native dispatch journal; it never wraps a provider or invents a PID. */
+export class NativeEffects {
+  readonly #live = new Map<symbol, TaskId>()
+  readonly #waiters = new Map<symbol, Agent>()
+  readonly #jobs = new Map<string, { id: string; row: EffectRecord; agent: Agent; timer: ReturnType<typeof setTimeout> | undefined }>()
+  readonly #registry: Context['jobs'] | undefined
+  constructor(readonly ctx: Context, readonly store: SqliteFusionStore, readonly callbacks: {
+    owner(agent: Agent): { binding: SessionBinding; role: Role } | undefined
+    track(exec: Readonly<ToolExecution>): boolean
+    failed(agent: Agent, error: unknown): void
+    backgroundMaxMs?(exec: Readonly<ToolExecution>, binding: SessionBinding): number | null
+  }) { this.#registry = ctx.get('jobs') }
+
+  install(): () => void {
+    const offJobs = this.#registry?.events.subscribe({ owners: 'all' }, event => {
+      if (event.type !== 'settled') return
+      const snapshot = event.job
+      const live = this.#jobs.get(snapshot.id)
+      if (live && snapshot.owner === live.agent.id) this.#settled(live, snapshot)
+    })
+    const offTools = this.ctx.on('tools/execute', async (exec, next) => {
+      const owner = exec.agent && this.callbacks.owner(exec.agent)
+      if (owner && exec.name === 'job_output') {
+        this.#waiters.set(exec.token, exec.agent!)
+        try { return await next() } finally { this.#waiters.delete(exec.token) }
+      }
+      if (!owner || !this.callbacks.track(exec)) return next()
+      const taskId = owner.binding.taskId, id = `native-effect:${taskId}:${randomUUID()}`
+      let row: EffectRecord
+      try {
+        row = { schemaVersion: 1, taskId, agentId: exec.agent!.id, role: owner.role,
+          callId: exec.callId, rootCallId: exec.rootCallId, toolName: exec.name, processId: process.pid,
+          startedAt: new Date().toISOString(), state: 'dispatch-started',
+          arguments: this.store.putArtifact(taskId, Buffer.from(JSON.stringify({ tool: exec.name, arguments: exec.arguments })), 'application/vnd.dsh-fusion.native-effect+json') }
+        this.store.writeDocument(id, 0, row)
+      } catch (error) { this.callbacks.failed(exec.agent!, error); throw error }
+      this.#live.set(exec.token, taskId)
+      try {
+        const result = await next()
+        const value = !result.isError && result.value
+        // A shell call keeps a live native job when it asked for background OR its foreground run was
+        // promoted (rc.2 returns kind:'promoted' + jobId on a foreground timeout, even with
+        // run_in_background=false). Either way the job must own the write lease until it settles.
+        const resultJob = (!result.isError ? value : null) as { kind?: unknown; jobId?: unknown } | null
+        const jobKind = resultJob?.kind
+        const keepsLiveJob = isShellTool(exec.name) && !result.isError
+          && ((exec.arguments as { run_in_background?: unknown }).run_in_background === true
+            || jobKind === 'background' || jobKind === 'promoted')
+        if (keepsLiveJob) {
+          // kind=promoted/background is a live job claim: verify the identity, never record it as
+          // returned — a missing jobId would release the write lease while the command still runs.
+          if ((jobKind !== 'background' && jobKind !== 'promoted') || typeof resultJob?.jobId !== 'string') {
+            throw new Error(`Native ${exec.name} returned a live job without an authoritative jobId`)
+          }
+          const snapshot = this.#registry!.get(JobId(resultJob.jobId), exec.agent?.id)
+          if (snapshot.kind !== exec.name || snapshot.owner !== exec.agent!.id) throw new Error('Native job ownership mismatch')
+          const maximum = this.callbacks.backgroundMaxMs ? this.callbacks.backgroundMaxMs(exec, owner.binding) : 60_000
+          const requested = (exec.arguments as { timeoutMs?: unknown }).timeoutMs
+          const timeout = typeof requested === 'number' && Number.isFinite(requested) && requested > 0
+            ? Math.min(requested, maximum ?? Infinity) : maximum
+          if (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0)) throw new Error('Background command deadline is unavailable')
+          row = { ...row, nativeJob: { id: snapshot.id, startedAt: snapshot.startedAt,
+            deadlineAt: timeout === null ? null : Date.now() + Math.ceil(timeout), status: snapshot.status } }
+          const timer = timeout === null ? undefined : setTimeout(() => {
+            try {
+              this.#assertJob(row, this.#registry!.get(snapshot.id, exec.agent?.id))
+              this.#registry!.kill(snapshot.id, exec.agent?.id, 'Fusion command deadline elapsed')
+            } catch (error) {
+              const live = this.#jobs.get(snapshot.id)
+              if (live) this.#uncertain(live, error)
+              else this.callbacks.failed(exec.agent!, error)
+            }
+          }, timeout)
+          timer?.unref()
+          const live = { id, row, agent: exec.agent!, timer }
+          this.#jobs.set(snapshot.id, live)
+          this.store.writeDocument(id, 1, row)
+          if (snapshot.status !== 'running' && snapshot.status !== 'stopping') this.#settled(live, snapshot)
+          return result
+        }
+        // This means the native tool promise returned, not that its mutation
+        // was correct, or that a post-crash provider range was inspected.
+        this.store.writeDocument(id, 1, { ...row, state: 'returned', endedAt: new Date().toISOString(), nativeIsError: Boolean(result.isError) })
+        return result
+      } catch (error) {
+        // A start may have succeeded before durable job identity could be saved.
+        // Cancel only this exact native job, never replay the command.
+        if (row.nativeJob && this.#jobs.has(row.nativeJob.id)) {
+          try { this.#registry!.kill(JobId(row.nativeJob.id), exec.agent?.id, 'Fusion job tracking failed') }
+          catch (stopError) { this.callbacks.failed(exec.agent!, stopError) }
+        }
+        try {
+          this.store.writeDocument(id, this.store.readDocument(id)!.revision,
+            { ...row, state: 'outcome-unknown', endedAt: new Date().toISOString() })
+        } catch (recordingError) { this.callbacks.failed(exec.agent!, recordingError) }
+        this.callbacks.failed(exec.agent!, error)
+        throw error
+      } finally { this.#live.delete(exec.token) }
+    }, { prepend: true })
+    return () => {
+      offTools(); offJobs?.()
+      for (const live of this.#jobs.values()) clearTimeout(live.timer)
+    }
+  }
+
+  #settled(live: { id: string; row: EffectRecord; agent: Agent; timer: ReturnType<typeof setTimeout> | undefined }, snapshot: JobView): void {
+    try {
+      this.#assertJob(live.row, snapshot)
+      if (snapshot.status === 'running' || snapshot.status === 'stopping') return
+      const row = this.store.readDocument(live.id)!
+      this.store.writeDocument(live.id, row.revision, { ...live.row,
+        nativeJob: { ...live.row.nativeJob!, status: snapshot.status, ...(snapshot.detail ? { detail: snapshot.detail } : {}) },
+        state: snapshot.status === 'failed' ? 'outcome-unknown' : 'returned', endedAt: new Date().toISOString() })
+      // Failed registry records can result from a throwing producer cancel;
+      // unlike completed/killed bash, that does not prove process quiescence.
+      if (snapshot.status === 'failed') this.callbacks.failed(live.agent, new Error('Native job failed without proven process quiescence'))
+    } catch (error) { this.callbacks.failed(live.agent, error) }
+    finally { clearTimeout(live.timer); this.#jobs.delete(snapshot.id) }
+  }
+
+  #assertJob(row: EffectRecord, snapshot: JobView): void {
+    if (!row.nativeJob || row.processId !== process.pid || snapshot.id !== row.nativeJob.id
+      || snapshot.kind !== row.toolName || snapshot.owner !== row.agentId || snapshot.startedAt !== row.nativeJob.startedAt) {
+      throw new Error('Native job identity changed; inspect rather than adopting or replaying it')
+    }
+  }
+
+  #uncertain(live: { id: string; row: EffectRecord; agent: Agent; timer: ReturnType<typeof setTimeout> | undefined }, error: unknown): void {
+    clearTimeout(live.timer)
+    this.#jobs.delete(live.row.nativeJob!.id)
+    try {
+      const row = this.store.readDocument(live.id)!
+      this.store.writeDocument(live.id, row.revision, { ...live.row, state: 'outcome-unknown' })
+    } catch (recordingError) { this.callbacks.failed(live.agent, recordingError) }
+    this.callbacks.failed(live.agent, error)
+  }
+
+  backgroundProblem(exec: Readonly<ToolExecution>): string | undefined {
+    if (!this.#registry || !exec.agent || !this.ctx.tools.get('job_output', exec.agent?.id) || !this.ctx.tools.get('job_kill', exec.agent?.id)) {
+      return 'Background commands require the native jobs runtime and visible job_output/job_kill tools'
+    }
+    return undefined
+  }
+
+  jobProblem(exec: Readonly<ToolExecution>, taskId: TaskId): string | undefined {
+    const id = (exec.arguments as { job_id?: unknown }).job_id
+    if (typeof id !== 'string' || !exec.agent || !this.#registry) return 'Native job identity is required'
+    const record = this.store.listDocumentIds(`native-effect:${taskId}:`).map(key => this.store.readDocument(key)!.value as EffectRecord)
+      .find(row => row.nativeJob?.id === id && row.agentId === exec.agent!.id && row.taskId === taskId)
+    if (!record) return 'Only native jobs recorded for this Agent and current Fusion task may be accessed'
+    try { this.#assertJob(record, this.#registry.get(JobId(id), exec.agent?.id)) }
+    catch (error) { return String(error) }
+    return undefined
+  }
+
+  waitingForJob(agent: Agent): boolean { return [...this.#waiters.values()].includes(agent) }
+
+  /**
+   * Whether a tool call this process is running belongs to this task, or a
+   * native job it started there is still unsettled. This is the in-process half
+   * of the deletion guard: a durable row alone cannot tell a live call from the
+   * residue of an interrupted one, because both look like `dispatch-started`.
+   */
+  live(taskId: TaskId): boolean {
+    return [...this.#live.values()].includes(taskId)
+      || [...this.#jobs.values()].some(job => job.row.taskId === taskId)
+  }
+
+  onlyBackgroundPending(taskId: TaskId): boolean {
+    const pending = this.pending(taskId)
+    return pending.length > 0 && pending.every(({ id, record }) => record.state === 'dispatch-started'
+      && record.nativeJob && this.#jobs.get(record.nativeJob.id)?.id === id)
+  }
+
+  async stopJobs(taskId: TaskId): Promise<void> {
+    for (const live of [...this.#jobs.values()].filter(job => job.row.taskId === taskId)) {
+      try {
+        const id = JobId(live.row.nativeJob!.id)
+        this.#assertJob(live.row, this.#registry!.get(id, live.agent.id))
+        this.#registry!.kill(id, live.agent.id, 'Fusion task is stopping')
+        const done = await this.#registry!.wait(id, 10_000, live.agent.id)
+        if (done.status === 'running' || done.status === 'stopping' || done.status === 'failed') {
+          throw new Error('Native job did not prove process quiescence; keep the writer and inspect')
+        }
+        if (this.#jobs.has(id)) this.#settled(live, done)
+      } catch (error) { this.#uncertain(live, error); throw error }
+    }
+  }
+
+  pending(taskId: TaskId): readonly { id: string; record: EffectRecord }[] {
+    return this.store.listDocumentIds(`native-effect:${taskId}:`).flatMap(id => {
+      const record = this.store.readDocument(id)!.value as EffectRecord
+      if (record.schemaVersion !== 1 || record.taskId !== taskId || !record.agentId || !record.toolName
+        || !Number.isSafeInteger(record.processId) || record.processId <= 0
+        || !['dispatch-started', 'returned', 'outcome-unknown', 'inspected'].includes(record.state)) {
+        throw new Error('Native effect journal requires migration or inspection')
+      }
+      if (record.nativeJob && (typeof record.nativeJob.id !== 'string'
+        || !Number.isSafeInteger(record.nativeJob.startedAt) || record.nativeJob.deadlineAt !== null && !Number.isSafeInteger(record.nativeJob.deadlineAt))) {
+        throw new Error('Native job journal requires migration or inspection')
+      }
+      return record.state === 'dispatch-started' || record.state === 'outcome-unknown' ? [{ id, record }] : []
+    })
+  }
+
+  assertInspection(taskId: TaskId, effectsStopped: boolean): void {
+    const pending = this.pending(taskId)
+    if (!pending.length) return
+    if ([...this.#live.values()].includes(taskId) || [...this.#jobs.values()].some(job => job.row.taskId === taskId)) {
+      throw new Error('Native tool execution is still live; stop and settle it before recovery')
+    }
+    if (!effectsStopped) {
+      throw new Error(`有 ${pending.length} 项原生操作在中断时未收尾。Host 退出不代表命令及子进程已停止。请先检查并停止这些操作，再使用 /fusion recover --effects-stopped <检查记录>。`)
+    }
+    for (const { record } of pending) {
+      if (record.processId === process.pid) continue
+      try { process.kill(record.processId, 0); throw new Error('The recorded effect owner is still live; settle it before recovery') }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error }
+    }
+  }
+
+  inspected(taskId: TaskId, evidence: string, effectsStopped: boolean): void {
+    this.assertInspection(taskId, effectsStopped)
+    if (!evidence) throw new Error('Effect inspection evidence is required')
+    for (const { id, record } of this.pending(taskId)) {
+      this.store.writeDocument(id, this.store.readDocument(id)!.revision, { ...record,
+        state: 'inspected', inspectionEvidence: evidence, quiescenceBasis: 'explicit-user-inspection' })
+    }
+  }
+}

package/src/host/native-evidence.ts

@@ -0,0 +1,31 @@
+import type { ArtifactRef, TaskId, ToolEvidence } from '../contracts.js'
+import { digestOf } from '../digest.js'
+import type { PlannedReceipt } from '../evidence/receipts.js'
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+import type { FrozenCheck } from './native-checks.js'
+
+/** Coverage uses logical receipt IDs; ordinary evidence uses content digests. */
+export function readNativeEvidence(store: SqliteFusionStore, taskId: TaskId, id: string): Uint8Array {
+  if (!id.startsWith('receipt:')) return store.readArtifact(taskId, id)
+  const match = /^receipt:(fusion-check-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/.exec(id)
+  if (!match) throw new Error('Invalid native check receipt id')
+  // Never search another task's documents, even when the caller knows its ID.
+  const document = store.readDocument(`check-invocation:${taskId}:${match[1]}`)
+  const record = document?.value as { check?: FrozenCheck; receipt?: PlannedReceipt; evidence?: ToolEvidence } | undefined
+  const { check, receipt, evidence } = record ?? {}
+  if (!check?.plan || !check.definition || !receipt?.evidence || !evidence
+    || receipt.id !== id || check.plan.taskId !== taskId || evidence.taskId !== taskId
+    || evidence.nativeToolCallId !== match[1] || evidence.operationId !== match[1]
+    || receipt.planDigest !== digestOf(check.plan) || digestOf(receipt.evidence) !== digestOf(evidence)
+    || evidence.argvDigest !== check.plan.argvDigest || evidence.cwdDigest !== check.plan.cwdDigest) {
+    throw new Error('Native check receipt unavailable or invalid for this task')
+  }
+  const refs: ArtifactRef[] = [evidence.stdout, evidence.stderr]
+  if (refs.some(ref => !ref || ref.ownerTaskId !== taskId || String(ref.id) !== ref.digest
+    || !Number.isSafeInteger(ref.bytes) || ref.bytes < 0)) throw new Error('Invalid check output ownership or reference')
+  const contents = store.readArtifacts(taskId, refs.map(ref => ref.id))
+  if (contents.some((bytes, index) => bytes.byteLength !== refs[index]!.bytes)) throw new Error('Invalid check output length')
+  // Reading a failed or old check is allowed. Only the existing review gate can
+  // decide whether it proves acceptance of the current candidate.
+  return Buffer.from(JSON.stringify({ kind: 'check-receipt', check, receipt }))
+}

package/src/host/native-exploration.ts

@@ -0,0 +1,114 @@
+import { lstatSync, readFileSync } from 'node:fs'
+import type { ExplorationReport, ExplorationSource, WorkOrder } from '../contracts.js'
+import { sha256Hex } from '../digest.js'
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+import { changedPaths, workspacePath } from './workspace.js'
+import type { WorkspaceSnapshot } from './workspace.js'
+
+interface PreparedSource { source: ExplorationSource; text: string; digest: string }
+
+function formatChanged(paths: readonly string[]): string {
+  const shown = paths.slice(0, 12)
+  if (!shown.length) return '(snapshot id changed with no listed path delta)'
+  return `${shown.join(', ')}${paths.length > shown.length ? ` (+${paths.length - shown.length} more)` : ''}`
+}
+
+/** Read cited ranges against the frozen baseline. Nothing is stored until every range is valid. */
+function prepareSources(baseline: WorkspaceSnapshot, sources: readonly ExplorationSource[]): PreparedSource[] {
+  if (sources.length > 12) throw new Error('A completed exploration requires 1–12 source ranges')
+  let total = 0
+  return sources.map(source => {
+    const path = workspacePath(baseline.root, source.path)
+    const entry = baseline.entries.find(item => item.path === source.path && item.kind === 'file')
+    if (!entry) throw new Error('Exploration sources must be files in the frozen workspace manifest')
+    if (!Number.isSafeInteger(source.startLine) || !Number.isSafeInteger(source.endLine)
+      || source.startLine < 1 || source.endLine < source.startLine || source.endLine - source.startLine >= 80) {
+      throw new Error('Exploration source ranges require 1–80 lines each')
+    }
+    let stat
+    try { stat = lstatSync(path) }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw new Error('Exploration source is missing')
+      throw error
+    }
+    // A FIFO or socket is not source text. Reject it before readFileSync, which would block on a pipe.
+    if (!stat.isFile()) throw new Error(`Unsupported source file type: ${source.path}`)
+    const bytes = readFileSync(path)
+    if (sha256Hex(bytes) !== entry.digest) throw new Error('Exploration source changed during capture')
+    const content = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+    if (content.includes('\0')) throw new Error('Exploration sources must be text files')
+    const lines = content.split('\n')
+    if (source.endLine > lines.length) throw new Error('Exploration source range exceeds the file')
+    const text = lines.slice(source.startLine - 1, source.endLine).join('\n')
+    total += Buffer.byteLength(text, 'utf8')
+    if (total > 24_000) throw new Error('Exploration excerpts exceed 24000 bytes; select narrower ranges')
+    return { source, text, digest: entry.digest }
+  })
+}
+
+function storeSources(store: SqliteFusionStore, taskId: WorkOrder['taskId'], prepared: readonly PreparedSource[]): ExplorationReport['sources'] {
+  return prepared.map(item => ({ ...item.source, fileDigest: item.digest,
+    excerpt: store.putArtifact(taskId, Buffer.from(item.text), 'text/plain') }))
+}
+
+/**
+ * Source-backed handoff. Completed reports are checked against the files they cite,
+ * not against every other file in a non-git root. blocked and needs-decision reports
+ * are always recorded, with drift or a failed whole-tree snapshot named, and are not acceptance.
+ *
+ * `current` is omitted when snapshotting the tree threw. The failure is stored on a
+ * non-completed report. A completed report ignores that unrelated failure and still
+ * stands or falls on the cited files alone.
+ */
+export function captureExploration(store: SqliteFusionStore, order: WorkOrder, baseline: WorkspaceSnapshot, current: WorkspaceSnapshot | undefined,
+  submitted: Pick<ExplorationReport, 'summary' | 'status' | 'unresolved'>, sources: readonly ExplorationSource[], snapshotFailure?: string): ExplorationReport {
+  if (order.mode !== 'explore' || baseline.id !== order.baseSnapshot || (current !== undefined && baseline.root !== current.root)) {
+    throw new Error('Exploration capture requires the frozen explore baseline')
+  }
+  if (current === undefined && !snapshotFailure) throw new Error('Exploration capture requires a current snapshot or a recorded snapshot failure')
+  const drifted = current !== undefined && baseline.id !== current.id
+  const changed = drifted && current ? changedPaths(baseline, current) : []
+  const driftDetail = drifted && current
+    ? `Exploration workspace changed since frozen baseline ${baseline.id}; current snapshot ${current.id}; changed paths: ${formatChanged(changed)}. This is not acceptance. A completed report can cite only files that still match the baseline; blocked or needs-decision records this drift.`
+    : undefined
+  const snapshotDetail = current === undefined
+    ? `Workspace snapshot failed: ${snapshotFailure}. Frozen baseline ${baseline.id}. This is not acceptance. The report is recorded so the blocker is not dropped; a completed report can cite only files that still match that baseline.`
+    : undefined
+  if (submitted.status !== 'completed') {
+    const problems = [driftDetail, snapshotDetail].filter((item): item is string => item !== undefined)
+    let prepared: PreparedSource[] = []
+    if (sources.length) {
+      try { prepared = prepareSources(baseline, sources) }
+      catch (error) { problems.push(error instanceof Error ? error.message : String(error)) }
+    }
+    return { schemaVersion: 1, workOrderId: order.id, revision: order.revision, summary: submitted.summary,
+      status: submitted.status, unresolved: [...submitted.unresolved, ...problems], snapshot: baseline.id,
+      sources: storeSources(store, order.taskId, prepared) }
+  }
+  if (!sources.length || sources.length > 12) throw new Error('A completed exploration requires 1–12 source ranges')
+  if (drifted && current) {
+    const cited = new Set(sources.map(source => source.path))
+    const citedChanged = changed.filter(path => cited.has(path))
+    if (citedChanged.length) {
+      throw new Error(`Cited exploration evidence changed: ${citedChanged.join(', ')}. Frozen baseline ${baseline.id}; current snapshot ${current.id}. Submit status "blocked" or "needs-decision" to record this drift; a completed report cannot cite files that no longer match the frozen baseline.`)
+    }
+  }
+  const prepared = prepareSources(baseline, sources)
+  return { schemaVersion: 1, workOrderId: order.id, revision: order.revision, ...submitted,
+    snapshot: baseline.id, sources: storeSources(store, order.taskId, prepared) }
+}
+
+/** Path of the first cited file whose bytes no longer match the captured digest, if any. */
+export function citedEvidenceChanged(root: string, baseline: WorkspaceSnapshot, report: Pick<ExplorationReport, 'sources'>): string | undefined {
+  for (const source of report.sources) {
+    const entry = baseline.entries.find(item => item.path === source.path && item.kind === 'file')
+    if (!entry || entry.digest !== source.fileDigest) return source.path
+    try {
+      const path = workspacePath(root, source.path)
+      if (!lstatSync(path).isFile()) return source.path
+      const bytes = readFileSync(path)
+      if (sha256Hex(bytes) !== source.fileDigest) return source.path
+    } catch { return source.path }
+  }
+  return undefined
+}