@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/src/host/native-keepalive.ts

@@ -0,0 +1,292 @@
+import { randomUUID } from 'node:crypto'
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { createUserMessage, isAgentLoopRequest } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { Role, TaskId } from '../contracts.js'
+import { digestOf } from '../digest.js'
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+import type { SessionBinding } from './bindings.js'
+import type { CacheMode } from './cache-defaults.js'
+import { cacheHit } from './cache-policy.js'
+import { NativeAuxiliaryRequests } from './native-auxiliary.js'
+import { nativeRequestAgent } from './native-request.js'
+import { FUSION_SOURCE_KIND } from '../message-source.js'
+
+/** R19 recovered schedule. */
+export const KEEPALIVE_INTERVAL_MS = 285_000
+/**
+ * The line appended after the copied prefix. maxTokens: 1 is not enough on its own: the ChatGPT Codex route
+ * rejects an output cap and pi-ai omits it, so a ping that said "continue" made the Lead think and call tools
+ * (live log: median 463 output tokens, all ending in tool calls). Measured 2026-10-01 on gpt-6-astra (Codex):
+ * "Reply OK" answered "OK" in 5 output tokens, 0 reasoning, no tool calls, 16/16 with tools still offered,
+ * full cache hit; "continue" called tools 8/8 and a bare "OK" read as approval and produced a plan.
+ * Tool choice and reasoning effort cannot change here: effort is part of OpenAI's cache key (effort "low"
+ * missed the cache entirely) and DSH requests carry no tool_choice.
+ */
+export const KEEPALIVE_PROMPT = 'Reply OK'
+export const KEEPALIVE_ATTEMPTS = 11
+export interface KeepaliveClock {
+  now(): number
+  schedule(callback: () => void, delayMs: number): () => void
+}
+const systemClock: KeepaliveClock = {
+  now: () => performance.now(),
+  schedule: (callback, delay) => {
+    const timer = setTimeout(callback, delay)
+    timer.unref()
+    return () => clearTimeout(timer)
+  },
+}
+type Owner = { binding: SessionBinding; role: Role }
+interface Callbacks {
+  owner(agent: Agent): Owner | undefined
+  allowed(agent: Agent, owner: Owner): boolean
+  failed(agent: Agent, reason: string): void
+  /** Per-model mode and interval (user setting, learned, defaults); absent: the pair profile and a fixed interval. */
+  policy?(owner: Owner, provider: string, model: string): { mode: CacheMode; intervalMs: number }
+  /** Evidence for learning and the settings page: a request after a wait, or a ping. */
+  observe?(owner: Owner, provider: string, model: string, sample: { gapSeconds: number; ping: boolean; hit: boolean; cacheRead: number; input: number; output?: number }): void
+}
+export interface KeepaliveRecord {
+  schemaVersion: 1
+  id: string
+  taskId: TaskId
+  sessionId: string
+  role: Role
+  profileDigest: string
+  inputDigest: string
+  createdAt: string
+  updatedAt: string
+  state: 'generating' | 'scheduled' | 'inflight' | 'stopped'
+  attempts: number
+  successes: number
+  stopReason?: string
+}
+interface Series {
+  agent: Agent
+  owner: Owner
+  input: GenerateOptions
+  started: number
+  controller: AbortController
+  record: KeepaliveRecord
+  revision: number
+  cancelTimer?: () => void
+  detachSourceAbort?: () => void
+  intervalMs: number
+}
+
+/** Retains only plugin-owned requests in memory; never replays timers on restart. */
+/** Explicit per-role choice; unset is automatic for the Lead (armed only on observed cache reads), off for the Worker. */
+export function keepalivePolicy(binding: SessionBinding, role: Role): boolean | 'auto' {
+  return binding.profile.cacheKeepalive?.[role] ?? (role === 'lead' ? 'auto' : false)
+}
+
+export class NativeCacheKeepalive {
+  readonly #series = new Map<string, Series>()
+  /** Start time of each agent's previous model request (real or ping): the wait before the next one. */
+  readonly #lastStart = new Map<string, number>()
+  readonly #pending = new Map<Promise<void>, { sessionId: string; taskId: TaskId }>()
+  readonly #dispose: (() => void)[] = []
+  #closed = false
+  constructor(readonly ctx: Context, readonly store: SqliteFusionStore,
+    readonly auxiliary: NativeAuxiliaryRequests, readonly callbacks: Callbacks,
+    readonly clock: KeepaliveClock = systemClock) {}
+
+  #active(row: Series): boolean {
+    if (this.#closed || this.#series.get(row.agent.id) !== row || row.controller.signal.aborted
+      || this.ctx.agents.get(row.agent.id) !== row.agent) return false
+    const current = this.callbacks.owner(row.agent)
+    return Boolean(current?.binding.selected && current.binding.taskId === row.owner.binding.taskId
+      && current.binding.profile.digest === row.owner.binding.profile.digest && current.role === row.owner.role
+      && this.#policy(current, row.input.provider, row.input.model).mode !== 'off' && this.callbacks.allowed(row.agent, current))
+  }
+
+  #policy(owner: Owner, provider: string, model: string): { mode: CacheMode; intervalMs: number } {
+    if (this.callbacks.policy) return this.callbacks.policy(owner, provider, model)
+    const legacy = keepalivePolicy(owner.binding, owner.role)
+    return { mode: legacy === true ? 'on' : legacy === false ? 'off' : 'auto', intervalMs: KEEPALIVE_INTERVAL_MS }
+  }
+
+  #invalidate(row: Series): void {
+    if (this.#series.get(row.agent.id) === row) this.#series.delete(row.agent.id)
+    row.cancelTimer?.(); row.cancelTimer = undefined
+    row.detachSourceAbort?.(); row.detachSourceAbort = undefined
+    row.controller.abort()
+  }
+
+  #persist(row: Series): boolean {
+    row.record.updatedAt = new Date().toISOString()
+    try {
+      row.revision = this.store.writeDocument(`keepalive:${row.record.taskId}:${row.record.id}`, row.revision, row.record)
+      return true
+    } catch (error) {
+      this.#invalidate(row)
+      this.callbacks.failed(row.agent, `Cache keepalive tracking failed: ${String(error)}`)
+      return false
+    }
+  }
+
+  #stop(row: Series, reason: string): void {
+    this.#invalidate(row)
+    if (row.record.state === 'stopped') return
+    row.record.state = 'stopped'; row.record.stopReason = reason
+    this.#persist(row)
+  }
+
+  stopSession(sessionId: string, reason: string): Promise<void> {
+    const row = this.#series.get(sessionId)
+    if (row) this.#stop(row, reason)
+    return Promise.all([...this.#pending].filter(([, item]) => item.sessionId === sessionId).map(([pending]) => pending)).then(() => undefined)
+  }
+
+  stopTask(taskId: TaskId, reason: string): Promise<void> {
+    for (const row of this.#series.values()) if (row.record.taskId === taskId) this.#stop(row, reason)
+    return Promise.all([...this.#pending].filter(([, item]) => item.taskId === taskId).map(([pending]) => pending)).then(() => undefined)
+  }
+
+  /** Called again after asynchronous context measurement, before spend admission. */
+  assertRequest(agent: Agent, request: GenerateOptions): void {
+    const extra = this.auxiliary.get(request)
+    if (!extra) return
+    const row = this.#series.get(agent.id)
+    if (!row || row.record.id !== extra.seriesId || row.record.attempts !== extra.iteration
+      || row.record.taskId !== extra.taskId || row.record.sessionId !== extra.sessionId
+      || row.record.profileDigest !== extra.profileDigest || row.record.role !== extra.role || !this.#active(row)) {
+      throw new Error('Cache keepalive generation is no longer active')
+    }
+    request.signal?.throwIfAborted()
+  }
+
+  #arm(row: Series, deadline: number): void {
+    if (!this.#active(row)) { this.#stop(row, 'inactive'); return }
+    row.record.state = 'scheduled'
+    if (!this.#persist(row)) return
+    row.cancelTimer = this.clock.schedule(() => {
+      row.cancelTimer = undefined
+      const pending = Promise.resolve().then(() => this.#ping(row)).finally(() => { this.#pending.delete(pending) })
+      this.#pending.set(pending, { sessionId: row.agent.id, taskId: row.record.taskId })
+    }, Math.max(0, deadline - this.clock.now()))
+  }
+
+  async #ping(row: Series): Promise<void> {
+    try {
+      if (!this.#active(row)) { this.#stop(row, 'inactive'); return }
+      const nextDeadline = this.clock.now() + row.intervalMs
+      row.record.attempts++; row.record.state = 'inflight'
+      if (!this.#persist(row)) return
+      const request: GenerateOptions = { ...structuredClone(row.input), maxTokens: 1, signal: row.controller.signal,
+        messages: [...structuredClone(row.input.messages), createUserMessage({ content: [{ type: 'text', text: KEEPALIVE_PROMPT }],
+          source: { kind: FUSION_SOURCE_KIND } })] }
+      this.auxiliary.tag(request, { purpose: 'cache-keepalive', taskId: row.record.taskId, sessionId: row.agent.id,
+        profileDigest: row.owner.binding.profile.digest, role: row.owner.role, seriesId: row.record.id, iteration: row.record.attempts })
+      let success = false
+      // Drain only: returned text, reasoning and tool calls never enter a Session
+      // or execute. Public llm/stream still applies context, spend and usage hooks.
+      for await (const chunk of this.ctx.llm.stream(request)) {
+        if (chunk.type === 'finish') success = ['stop', 'max-tokens', 'tool-calls'].includes(chunk.reason.kind)
+      }
+      if (success) row.record.successes++
+      if (row.controller.signal.aborted || this.#series.get(row.agent.id) !== row) { this.#persist(row); return }
+      if (!success) { this.#stop(row, 'request-failed'); return }
+      if (row.record.attempts >= KEEPALIVE_ATTEMPTS) { this.#stop(row, 'attempt-limit'); return }
+      this.#arm(row, nextDeadline)
+    } catch {
+      this.#stop(row, row.controller.signal.aborted ? 'cancelled' : 'request-failed')
+    }
+  }
+
+  install(): void {
+    const manager = this
+    // Evidence for the settings page and the interval rule: how long each agent waited and whether its
+    // prefix was still cached. Pings count too (they refresh the cache the next request relies on).
+    this.#dispose.push(this.ctx.on('llm/stream', async function* (request, next): AsyncIterable<StreamChunk> {
+      const agent = nativeRequestAgent(manager.ctx, request), owner = agent && manager.callbacks.owner(agent)
+      const extra = manager.auxiliary.get(request), ping = extra?.purpose === 'cache-keepalive'
+      if (!agent || !owner || !manager.callbacks.observe || (extra && !ping) || (!ping && (!isAgentLoopRequest(request) || request.purpose !== undefined))) {
+        yield* next(); return
+      }
+      const started = manager.clock.now(), previous = manager.#lastStart.get(agent.id)
+      manager.#lastStart.set(agent.id, started)
+      let usage: { inputTokens?: number; cacheReadTokens?: number; outputTokens?: number } | undefined
+      for await (const chunk of next()) {
+        if (chunk.type === 'usage') usage = chunk.usage
+        yield chunk
+      }
+      if (!usage || previous === undefined) return
+      const cacheRead = usage.cacheReadTokens ?? 0, input = usage.inputTokens ?? 0
+      try {
+        manager.callbacks.observe(owner, request.provider, request.model,
+          { gapSeconds: (started - previous) / 1000, ping, hit: cacheHit(cacheRead, input), cacheRead, input, output: usage.outputTokens ?? 0 })
+      } catch { /* evidence is advisory; never fail a model request over it */ }
+    }))
+    // Replacement invalidates the previous loop even if the next input is
+    // rejected locally. An in-flight ping drains before a new request enters.
+    this.#dispose.push(this.ctx.on('llm/stream', async function* (request, next) {
+      if (!manager.auxiliary.get(request) && (isAgentLoopRequest(request) || request.purpose === 'compaction')) {
+        const agent = nativeRequestAgent(manager.ctx, request)
+        if (agent) await manager.stopSession(agent.id, request.purpose === 'compaction' ? 'compaction' : 'new-generation')
+      }
+      yield* next()
+    }, { prepend: true }))
+    // This observer is inside admission. Only actual admitted AgentLoop input
+    // can establish a new prefix; unrelated one-shot calls cannot start timers.
+    this.#dispose.push(this.ctx.on('llm/stream', async function* (request, next): AsyncIterable<StreamChunk> {
+      const agent = nativeRequestAgent(manager.ctx, request), owner = agent && manager.callbacks.owner(agent)
+      // Explicit per-role choice wins. Unset means automatic for the Lead: it waits minutes for the Sidekick,
+      // and an expired prefix is resent uncached at the frontier price (round 4: 69% cache hits against 94%
+      // alone). Automatic arming requires this route to have reported cache reads, so a route without prompt
+      // caching never pays for pings.
+      const policy = owner ? manager.#policy(owner, request.provider, request.model) : undefined
+      if (!agent || !owner || !policy || policy.mode === 'off' || manager.auxiliary.get(request)
+        || !isAgentLoopRequest(request) || request.purpose !== undefined || manager.#closed) { yield* next(); return }
+      // Copy only public fields: no AgentLoop brand, source signal or mutable
+      // session history. Adapters may normalize their own copy downstream.
+      const input: GenerateOptions = structuredClone({ provider: request.provider, model: request.model,
+        messages: request.messages, tools: request.tools, system: request.system, temperature: request.temperature,
+        reasoningEffort: request.reasoningEffort, stop: request.stop, sessionId: request.sessionId })
+      const row: Series = { agent, owner, input, started: manager.clock.now(), controller: new AbortController(), revision: 0, intervalMs: policy.intervalMs,
+        record: { schemaVersion: 1, id: randomUUID(), taskId: owner.binding.taskId, sessionId: agent.id, role: owner.role,
+          profileDigest: owner.binding.profile.digest, inputDigest: digestOf(input), createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(), state: 'generating', attempts: 0, successes: 0 } }
+      manager.#series.set(agent.id, row)
+      if (request.signal) {
+        const abort = () => { void manager.stopSession(agent.id, 'native-cancel') }
+        request.signal.addEventListener('abort', abort, { once: true })
+        row.detachSourceAbort = () => request.signal!.removeEventListener('abort', abort)
+      }
+      if (!manager.#persist(row)) throw new Error('Cache keepalive request tracking failed')
+      let success = false, cached = policy.mode === 'on'
+      try {
+        for await (const chunk of next()) {
+          if (chunk.type === 'finish') success = ['stop', 'max-tokens', 'tool-calls'].includes(chunk.reason.kind)
+          if (chunk.type === 'usage' && (chunk.usage.cacheReadTokens ?? 0) > 0) cached = true
+          yield chunk
+        }
+      } finally {
+        if (success && cached && !request.signal?.aborted && manager.#series.get(agent.id) === row) manager.#arm(row, row.started + row.intervalMs)
+        else manager.#stop(row, cached ? 'generation-stopped' : 'no-cache-evidence')
+      }
+    }))
+    this.#dispose.push(this.ctx.on('session/event', (session, event) => {
+      if (event.type === 'compaction/start') void this.stopSession(session.id, 'compaction')
+      if (event.type !== 'turn/end') return
+      const row = this.#series.get(session.id)
+      if (row && (event.data.reason.kind !== 'completed' || row.owner.role === 'worker' || !this.#active(row))) {
+        void this.stopSession(session.id, 'agent-stopping')
+      }
+    }))
+    this.#dispose.push(this.ctx.on('agent/status', ({ status }) => {
+      if (status !== 'idle') return
+      for (const row of this.#series.values()) if (!this.#active(row)) void this.stopSession(row.agent.id, 'agent-idle')
+    }))
+    this.#dispose.push(this.ctx.on('agent/disposed', ({ agent }) => { this.#lastStart.delete(agent.id); void this.stopSession(agent.id, 'agent-disposed') }))
+  }
+
+  async close(): Promise<void> {
+    this.#closed = true
+    for (const row of this.#series.values()) this.#stop(row, 'runtime-closing')
+    await Promise.all(this.#pending.keys())
+    for (const dispose of this.#dispose.reverse()) dispose()
+  }
+}

package/src/host/native-model-control.ts

@@ -0,0 +1,298 @@
+import { bi } from '../bilingual.js'
+import { digestOf } from '../digest.js'
+import { randomUUID } from 'node:crypto'
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { LlmFailure, UserMessage } from '@deepseek-ai/dsh-llm'
+import type { PhysicalRoute, Role } from '../contracts.js'
+import type { SqliteFusionStore } from '../task/sqlite-store.js'
+import { BindingRepository, type SessionBinding } from './bindings.js'
+import { adaptiveWorkflow, enforcedWorkflow } from './native-workflow.js'
+import { isShellTool } from './shell.js'
+import { unsettledContinuationError } from './worker-terminal.js'
+import { FUSION_SOURCE_KIND } from '../message-source.js'
+
+const LEAD_RECOVERABLE = ['WORKFLOW_INCOMPLETE', 'NO_PROGRESS', 'UNKNOWN']
+const LEAD_RECOVERIES = 2
+
+export interface ModelControl {
+  schemaVersion: 1
+  sessionId: string
+  profileDigest: string
+  epoch: number
+  recoveryEpoch?: number
+  /** Lead-cleared recoverable Worker waits for the current task (bounded). */
+  leadRecoveries?: { taskId: string; count: number }
+  routes: Record<Role, PhysicalRoute>
+  waits: Partial<Record<Role, { taskId: string; code: string; at: string; retryNotBefore?: string; quotaResetAt: null }>>
+  operation?: { id: string; taskId: string; state: 'prepared' | 'dispatching' | 'delivered' | 'failed'; message?: UserMessage; error?: string }
+  schedule?: { id: string; taskId: string; epoch: number; dueAt: string; userSeq: number; state: 'scheduled' | 'cancelled' | 'fired' | 'failed'; reason?: string }
+}
+export interface ControlView extends ModelControl { revision: number }
+export function readModelControl(store: SqliteFusionStore, binding: SessionBinding): ControlView | undefined {
+  if (binding.profile.interactionMode !== 'model-like') return undefined
+  const row = store.readDocument(`model-control:${binding.sessionId}`)
+  if (!row) return { schemaVersion: 1, revision: 0, sessionId: binding.sessionId, profileDigest: binding.profile.digest,
+    epoch: 0, routes: { lead: binding.profile.lead, worker: binding.profile.worker }, waits: {} }
+  const value = row.value as ModelControl
+  if (value.schemaVersion !== 1 || value.sessionId !== binding.sessionId || value.profileDigest !== binding.profile.digest
+    || !Number.isSafeInteger(value.epoch) || value.epoch < 0 || !value.routes?.lead || !value.routes.worker || !value.waits) {
+    throw new Error('Fusion model control requires reconciliation')
+  }
+  return { ...value, revision: row.revision }
+}
+
+interface Callbacks {
+  owner(agent: Agent): { binding: SessionBinding; role: Role } | undefined
+  resolve(sessionId: string): Promise<Agent>
+  pause(agent: Agent): Promise<void>
+  resume(agent: Agent): Promise<void>
+  settled(binding: SessionBinding): boolean
+  stopAuxiliary(binding: SessionBinding): void
+}
+
+/** Durable local controls. No provider polling, synthetic user identity, or silent routing fallback. */
+export class NativeModelControl {
+  readonly #bindings: BindingRepository
+  readonly #locks = new Set<string>()
+  readonly #pending = new Set<Promise<void>>()
+  readonly #timers = new Map<string, ReturnType<typeof setTimeout>>()
+  readonly #dispose: (() => void)[] = []
+  #closed = false
+  constructor(readonly ctx: Context, readonly store: SqliteFusionStore, readonly callbacks: Callbacks) {
+    this.#bindings = new BindingRepository(store)
+    this.#dispose.push(ctx.on('agent/request-error', async (payload, next) => {
+      const owner = callbacks.owner(payload.agent)
+      if (owner?.binding.profile.interactionMode !== 'model-like') return next()
+      const quota = ['QUOTA', 'QUOTA_EXHAUSTED', 'INSUFFICIENT_QUOTA', 'USAGE_LIMIT_REACHED'].includes(payload.failure.code)
+      if (!quota) {
+        const action = await next()
+        if (!action && !payload.signal.aborted) this.failure(owner.binding, owner.role, payload.failure)
+        return action
+      }
+      this.failure(owner.binding, owner.role, payload.failure)
+      payload.agent.cancel({ kind: 'hook', reason: 'Fusion provider quota requires local continuation' }, { keepInbox: true })
+      return undefined
+    }, { prepend: true }))
+    this.#dispose.push(ctx.on('session/event', (session, event) => {
+      const user = event.type === 'user/message' ? !event.data.source || event.data.source.kind === 'user'
+        : event.type === 'agent/inbox/spliced' && event.data.inserted.some(message => !message.source || message.source.kind === 'user')
+      if (!user) return
+      const binding = this.#bindings.read(session.id)?.binding
+      if (!binding?.selected || binding.profile.interactionMode !== 'model-like') return
+      let view = readModelControl(store, binding)!
+      if (view.schedule?.state === 'scheduled' && event.seq > view.schedule.userSeq) this.cancel(binding, bi('新的用户消息已取消定时继续', 'A new user message cancelled the scheduled continuation'))
+      view = readModelControl(store, binding)!
+      if (adaptiveWorkflow(binding) && Object.values(view.waits).some(wait => wait?.taskId === binding.taskId
+        && ['NO_PROGRESS', 'WORKFLOW_INCOMPLETE'].includes(wait.code))) {
+        this.write({ ...view, recoveryEpoch: (view.recoveryEpoch ?? 0) + 1,
+          waits: Object.fromEntries(Object.entries(view.waits).filter(([, wait]) => wait?.taskId !== binding.taskId
+            || !['NO_PROGRESS', 'WORKFLOW_INCOMPLETE'].includes(wait.code))) })
+      }
+    }))
+    this.#dispose.push(ctx.on('tools/result', (exec, result) => {
+      const owner = exec.agent && callbacks.owner(exec.agent)
+      if (owner?.binding.profile.interactionMode !== 'model-like') return undefined
+      if (enforcedWorkflow(owner.binding)) return undefined
+      const id = `progress:${owner.binding.taskId}:${exec.agent!.id}`, row = store.readDocument(id)
+      const prior = row?.value as { fingerprint?: string; count?: number } | undefined
+      const shell = isShellTool(exec.name) && !result.isError ? result.value as { exitCode?: unknown; stdout?: unknown; stderr?: unknown } : undefined
+      const failedShell = typeof shell?.exitCode === 'number' && shell.exitCode !== 0
+      const fingerprint = result.isError || failedShell ? digestOf({ name: exec.name, args: exec.arguments,
+        outcome: failedShell ? { exitCode: shell!.exitCode, stdout: shell!.stdout, stderr: shell!.stderr } : result.content }) : undefined
+      const count = fingerprint && fingerprint === prior?.fingerprint ? (prior.count ?? 0) + 1 : fingerprint ? 1 : 0
+      store.writeDocument(id, row?.revision ?? 0, { fingerprint, count })
+      if (count >= 3) this.failure(owner.binding, owner.role, { code: 'NO_PROGRESS', message: 'Three unchanged failed tool attempts; a changed approach is required' })
+      return undefined
+    }))
+    for (const binding of this.#bindings.selected()) this.arm(binding)
+  }
+  reset(binding: SessionBinding) {
+    if (binding.profile.interactionMode !== 'model-like') return
+    const id = `model-control:${binding.sessionId}`, row = this.store.readDocument(id)
+    this.store.writeDocument(id, row?.revision ?? 0, { schemaVersion: 1, sessionId: binding.sessionId,
+      profileDigest: binding.profile.digest, epoch: 0, routes: { lead: binding.profile.lead, worker: binding.profile.worker }, waits: {} })
+  }
+  write(view: ControlView) {
+    const { revision, ...value } = view
+    return this.store.writeDocument(`model-control:${view.sessionId}`, revision, value)
+  }
+  route(binding: SessionBinding, role: Role): PhysicalRoute { return readModelControl(this.store, binding)?.routes[role] ?? binding.profile[role] }
+  waiting(binding: SessionBinding, role: Role) {
+    const wait = readModelControl(this.store, binding)?.waits[role]
+    return wait?.taskId === binding.taskId ? wait : undefined
+  }
+  /**
+   * Clear a role wait the Lead can resolve itself by sending a new instruction: a missing report or
+   * transition (WORKFLOW_INCOMPLETE), a repeated unchanged result (NO_PROGRESS) or an unclassified
+   * error (UNKNOWN). At most LEAD_RECOVERIES per task; quota and credential stops are never cleared here.
+   */
+  leadRecover(binding: SessionBinding, role: Role): boolean {
+    const view = readModelControl(this.store, binding)
+    const wait = view?.waits[role]
+    if (!view || !wait || wait.taskId !== binding.taskId || !LEAD_RECOVERABLE.includes(wait.code)) return false
+    const used = view.leadRecoveries?.taskId === binding.taskId ? view.leadRecoveries.count : 0
+    if (used >= LEAD_RECOVERIES) return false
+    const { [role]: _cleared, ...waits } = view.waits
+    this.write({ ...view, waits, recoveryEpoch: (view.recoveryEpoch ?? 0) + 1, leadRecoveries: { taskId: binding.taskId, count: used + 1 } })
+    return true
+  }
+  /** The role stalled again after the Lead already redirected it LEAD_RECOVERIES times this task. */
+  recoveriesExhausted(binding: SessionBinding, role: Role): boolean {
+    const view = readModelControl(this.store, binding), wait = view?.waits[role]
+    if (!view || !wait || wait.taskId !== binding.taskId || !LEAD_RECOVERABLE.includes(wait.code)) return false
+    return (view.leadRecoveries?.taskId === binding.taskId ? view.leadRecoveries.count : 0) >= LEAD_RECOVERIES
+  }
+  blocked(binding: SessionBinding, role: Role): string | undefined {
+    const view = readModelControl(this.store, binding)
+    if (view?.operation && ['prepared', 'dispatching'].includes(view.operation.state)) return 'Fusion continuation is pending local delivery confirmation'
+    return view?.waits[role]?.taskId === binding.taskId ? `${role} is paused (${view.waits[role]!.code}); use local Fusion controls to continue` : undefined
+  }
+  reconcileDelivery(agent: Agent, binding: SessionBinding, evidenceId: string) {
+    const view = readModelControl(this.store, binding), operation = view?.operation
+    if (!view || !operation || !['prepared', 'dispatching'].includes(operation.state)) return
+    const delivered = operation.message && agent.session.snapshotEvents().some(event => event.type === 'agent/inbox/spliced'
+      && event.data.inserted.some(message => message.id === operation.message!.id))
+    this.write({ ...view, operation: { ...operation, state: delivered ? 'delivered' : 'failed',
+      error: `Delivery inspected; evidence ${evidenceId}. No automatic replay.` } })
+  }
+  failure(binding: SessionBinding, role: Role, failure: LlmFailure) {
+    const view = readModelControl(this.store, binding)!
+    const ms = failure.providerRetryAfterMs
+    this.write({ ...view, waits: { ...view.waits, [role]: { taskId: binding.taskId, code: failure.code,
+      at: new Date().toISOString(), quotaResetAt: null,
+      ...(ms !== undefined && Number.isFinite(ms) && ms >= 0 && ms < 8.64e15 - Date.now()
+        ? { retryNotBefore: new Date(Date.now() + ms).toISOString() } : {}) } },
+      ...(view.schedule ? { schedule: { ...view.schedule, state: 'cancelled', reason: bi('模型仍不可用；不会重复自动请求', 'The model is still unavailable; no further automatic request') } } : {}) })
+    this.callbacks.stopAuxiliary(binding)
+    this.clearTimer(binding.sessionId)
+  }
+  private require(sessionId: string, taskId: string, revision: number) {
+    const saved = this.#bindings.read(sessionId)
+    if (!saved?.binding.selected || saved.binding.taskId !== taskId) throw new Error(bi('任务已变化，请刷新状态', 'The task changed; refresh the status'))
+    const view = readModelControl(this.store, saved.binding)
+    if (!view || view.revision !== revision) throw new Error(bi('恢复状态已变化，请刷新后重试', 'The recovery state changed; refresh and retry'))
+    if (this.store.load(saved.binding.taskId)?.control.mode === 'completed') throw new Error(bi('任务已经完成', 'The task is already finished'))
+    return { binding: saved.binding, view, bindingRevision: saved.revision }
+  }
+  private userSeq(agent: Agent) { return agent.session.snapshotEvents().findLast(event => event.type === 'user/message'
+    && (!event.data.source || event.data.source.kind === 'user') || event.type === 'agent/inbox/spliced'
+    && event.data.inserted.some(message => !message.source || message.source.kind === 'user'))?.seq ?? 0 }
+  cancel(binding: SessionBinding, reason = bi('已取消定时继续', 'Scheduled continuation cancelled')) {
+    const view = readModelControl(this.store, binding)
+    if (view?.schedule?.state === 'scheduled') this.write({ ...view, schedule: { ...view.schedule, state: 'cancelled', reason } })
+    this.clearTimer(binding.sessionId)
+  }
+  async schedule(sessionId: string, taskId: string, revision: number, dueAt: string) {
+    const time = Date.parse(dueAt)
+    if (!Number.isFinite(time) || time <= Date.now()) throw new Error(bi('请选择未来的继续时间', 'Choose a time in the future'))
+    const { binding } = this.require(sessionId, taskId, revision)
+    const agent = await this.callbacks.resolve(sessionId)
+    const { view } = this.require(sessionId, taskId, revision)
+    if (agent.status !== 'idle' || !this.callbacks.settled(binding)) throw new Error(bi('等待当前操作停止并核对结果后再设置定时继续', 'Wait for the current operation to stop and check it before scheduling'))
+    if (view.operation && ['prepared', 'dispatching'].includes(view.operation.state)) throw new Error(bi('请先检查上次继续操作的投递结果', 'Check the delivery of the last continuation first'))
+    if (!Object.values(view.waits).some(wait => wait?.taskId === taskId)) throw new Error(bi('只有等待模型恢复的任务可以定时继续', 'Only a task waiting for its model can be scheduled'))
+    this.write({ ...view, schedule: { id: randomUUID(), taskId, epoch: view.epoch, dueAt: new Date(time).toISOString(),
+      userSeq: this.userSeq(agent), state: 'scheduled' } })
+    this.arm(binding)
+  }
+  continue(sessionId: string, taskId: string, revision: number, change?: { role: Role; route: PhysicalRoute }, scheduledId?: string): Promise<void> {
+    if (this.#closed) return Promise.reject(new Error('Fusion runtime is closing'))
+    const pending = this.runContinue(sessionId, taskId, revision, change, scheduledId)
+    this.#pending.add(pending)
+    void pending.finally(() => this.#pending.delete(pending)).catch(() => undefined)
+    return pending
+  }
+  private async runContinue(sessionId: string, taskId: string, revision: number, change?: { role: Role; route: PhysicalRoute }, scheduledId?: string) {
+    if (this.#locks.has(sessionId)) throw new Error(bi('当前会话正在恢复，请稍候', 'This conversation is recovering; please wait'))
+    this.#locks.add(sessionId)
+    try {
+      const initial = this.require(sessionId, taskId, revision)
+      const agent = await this.callbacks.resolve(sessionId)
+      const userSeq = this.userSeq(agent)
+      let { view, binding } = this.require(sessionId, taskId, revision)
+      if (view.operation && ['prepared', 'dispatching'].includes(view.operation.state)) {
+        const messageId = view.operation.message?.id
+        const delivered = messageId && agent.session.snapshotEvents().some(event => event.type === 'agent/inbox/spliced'
+          && event.data.inserted.some(message => message.id === messageId))
+        if (delivered) { this.write({ ...view, operation: { ...view.operation, state: 'delivered' } }); return }
+        throw new Error(bi('上次继续操作的投递结果未知；请检查会话，不会自动重复发送', 'Delivery of the last continuation is unknown; check the conversation. Nothing is resent automatically'))
+      }
+      if (scheduledId && (view.schedule?.id !== scheduledId || view.schedule.state !== 'scheduled'
+        || view.schedule.epoch !== view.epoch || view.schedule.userSeq !== userSeq || agent.status !== 'idle')) {
+        this.cancel(binding, bi('任务状态已变化，定时继续已取消', 'The task changed; the scheduled continuation was cancelled')); return
+      }
+      // Native pause drains both agents and native effects before committing a route.
+      await this.callbacks.pause(agent)
+      const current = this.#bindings.read(sessionId)
+      if (current?.revision !== initial.bindingRevision || this.userSeq(agent) !== userSeq) throw new Error(bi('暂停期间任务或用户消息已变化，请刷新', 'The task or messages changed while paused; refresh'))
+      ;({ view, binding } = this.require(sessionId, taskId, revision))
+      if (!this.callbacks.settled(binding)) {
+        const text = unsettledContinuationError(Boolean(change))
+        throw new Error(bi(text.zh, text.en))
+      }
+      const operation = { id: randomUUID(), taskId, state: 'prepared' as const }
+      const message = createUserMessage({ content: [{ type: 'text', text: `Continue the existing Fusion task ${taskId} from its saved state. Read fusion_read_state if needed. Preserve accepted constraints and inspect uncertain effects before replay. Local continuation operation: ${operation.id}.` }],
+        source: { kind: FUSION_SOURCE_KIND, form: 'notice', summary: bi('用户通过 Fusion 控件继续当前任务', 'The user continued the task from the Fusion controls') } })
+      view = { ...view, epoch: view.epoch + (change ? 1 : 0), recoveryEpoch: (view.recoveryEpoch ?? 0) + 1,
+        routes: change ? { ...view.routes, [change.role]: change.route } : view.routes,
+        waits: change ? Object.fromEntries(Object.entries(view.waits).filter(([role]) => role !== change.role)) : {}, operation: { ...operation, message },
+        ...(view.schedule ? { schedule: { ...view.schedule, state: scheduledId ? 'fired' : 'cancelled' } } : {}) }
+      view.revision = this.write(view)
+      for (const id of this.store.listDocumentIds(`progress:${taskId}:`)) {
+        const row = this.store.readDocument(id)!
+        this.store.writeDocument(id, row.revision, { count: 0 })
+      }
+      for (const id of this.store.listDocumentIds(`workflow-progress:${taskId}:`)) {
+        const row = this.store.readDocument(id)!
+        this.store.writeDocument(id, row.revision, { schemaVersion: 1, milestone: '', recent: [] })
+      }
+      this.clearTimer(sessionId)
+      try {
+        await this.callbacks.resume(agent)
+        if (this.#closed || this.userSeq(agent) !== userSeq) throw new Error(bi('恢复期间出现新消息或插件已退出', 'A new message arrived or the plugin exited during recovery'))
+        view = { ...view, operation: { ...view.operation!, state: 'dispatching' } }
+        view.revision = this.write(view)
+        agent.send(message, 'next-turn', true)
+        const delivered = agent.session.snapshotEvents().some(event => event.type === 'agent/inbox/spliced'
+          && event.data.inserted.some(item => item.id === message.id))
+        if (!delivered) throw new Error(bi('继续消息未获得原生收件箱确认；不会自动重发', 'The native inbox did not confirm the continuation; it is not resent automatically'))
+        this.write({ ...view, operation: { ...view.operation!, state: 'delivered' } })
+      } catch (error) {
+        if (view.operation?.state === 'prepared') this.write({ ...view, operation: { ...view.operation, state: 'failed', error: String(error) } })
+        throw error
+      }
+    } finally { this.#locks.delete(sessionId) }
+  }
+  private clearTimer(sessionId: string) { clearTimeout(this.#timers.get(sessionId)); this.#timers.delete(sessionId) }
+  private arm(binding: SessionBinding) {
+    this.clearTimer(binding.sessionId)
+    if (this.#closed || binding.profile.interactionMode !== 'model-like') return
+    const view = readModelControl(this.store, binding)!, schedule = view.schedule
+    if (schedule?.state !== 'scheduled') return
+    const delay = Math.max(0, Date.parse(schedule.dueAt) - Date.now())
+    const timer = setTimeout(() => {
+      this.#timers.delete(binding.sessionId)
+      const current = this.#bindings.read(binding.sessionId)?.binding
+      if (!current?.selected || current.taskId !== schedule.taskId || this.store.load(current.taskId)?.control.mode === 'completed') {
+        if (current?.selected && current.profile.interactionMode === 'model-like') this.cancel(current, bi('任务已结束或切换', 'The task ended or changed'))
+        return
+      }
+      if (delay > 60_000) { this.arm(current); return }
+      const fresh = readModelControl(this.store, current)!
+      void this.continue(current.sessionId, current.taskId, fresh.revision, undefined, schedule.id).catch(error => {
+        const latest = readModelControl(this.store, current)!
+        if (latest.schedule?.id === schedule.id && latest.schedule.state === 'scheduled') this.write({ ...latest,
+          schedule: { ...latest.schedule, state: 'failed', reason: String(error) } })
+      })
+    }, Math.min(delay, 60_000))
+    timer.unref(); this.#timers.set(binding.sessionId, timer)
+  }
+  async close() {
+    this.#closed = true
+    for (const id of this.#timers.keys()) this.clearTimer(id)
+    this.#dispose.forEach(dispose => dispose())
+    await Promise.allSettled(this.#pending)
+  }
+}