@whaletalk/dsh-codex-collab 0.1.7 → 0.1.10

package/harness/session-observer.mjs

@@ -0,0 +1,217 @@
+/** Shared, bounded observation of session history. Never retain full message history. */
+import { assistantTextOf } from './session-target.mjs'
+const compact = (event) => {
+  const d = event.data || {}
+  const fields = {
+    'turn/start': ['turn'], 'turn/end': ['turn', 'reason'],
+    'tool/call': ['callId', 'turn', 'step'],
+    'approval/asked': ['id', 'toolName', 'callId'],
+    'approval/decided': ['id', 'outcome'],
+    'user/message': ['turn', 'source'], 'model/selection': [],
+  }[event.type]
+  if (!fields) return null
+  const data = {}
+  for (const key of fields) {
+    if (d[key] === undefined) continue
+    data[key] = key === 'source' ? { rpcId: d.source?.rpcId }
+      : key === 'reason' ? { kind: d.reason?.kind } : d[key]
+  }
+  return { seq: event.seq, type: event.type, data }
+}
+const replayEvent = (event) => {
+  if (event.type !== 'assistant/message') return compact(event) || { seq: event.seq, type: event.type, data: {} }
+  const text = assistantTextOf(event)
+  return { seq: event.seq, type: event.type, data: { turn: event.data?.turn, step: event.data?.step, message: { content: [{ type: 'text', text }] } } }
+}
+const weight = (event) => JSON.stringify(event).length * 2 + 128
+
+export const createSessionObservationHub = (options = {}) => {
+  const entries = new Map()
+  const counters = { reads: 0, observations: 0, events: 0, gaps: 0, failures: 0 }
+  const maxEvidence = options.maxEvidence ?? 32768
+  const now = options.now || Date.now
+  let closed = false
+  const maxTailBytes = options.maxTailBytes ?? 4 * 1024 * 1024
+  const retain = (e, event) => {
+    if (!e.listeners.size) return
+    const value = replayEvent(event), bytes = weight(value)
+    if (bytes > maxTailBytes) { e.tail = []; e.tailBytes = 0; return }
+    e.tail.push(value); e.tailBytes = (e.tailBytes || 0) + bytes
+    while (e.tail.length > 256 || e.tailBytes > maxTailBytes) e.tailBytes -= weight(e.tail.shift())
+  }
+  const query = () => typeof options.query === 'function' ? options.query() : options.query
+  const live = (id) => { try { return options.liveSession?.(id) } catch { return null } }
+  const entry = (id) => {
+    if (!entries.has(id) && entries.size >= 32) {
+      const idle = [...entries.values()].filter(e => !e.listeners.size && !e.inflight).sort((a,b) => a.touched - b.touched)[0]
+      if (idle) { idle.stream?.abort(); entries.delete(idle.id) }
+    }
+    let e = entries.get(id)
+    if (!e) { e = { id, cursor: -1, ready: false, evidence: [], overflow: false, tail: [], listeners: new Set(), buffered: [], reading: false, requested: 0, completed: 0, inflight: null, stream: null, connected: false, touched: now(), object: null }; if (!closed) entries.set(id, e) }
+    e.touched = now()
+    return e
+  }
+  const headMatches = (e) => {
+    const s = live(e.id)
+    return e.ready && s && s === e.object?.deref() && Number.isInteger(s.seq) && s.seq - 1 === e.cursor
+  }
+  const uncertain = (e) => { e.connected = false; for (const sub of e.listeners) sub.onUncertain?.() }
+  const deliver = (e, event) => {
+    for (const sub of [...e.listeners]) {
+      if (sub.signal?.aborted || event.seq <= sub.afterSeq) continue
+      sub.afterSeq = event.seq
+      sub.onEvent?.(event)
+    }
+  }
+  const accept = (e, event) => {
+    if (closed || !event || !Number.isInteger(event.seq)) return
+    if (e.reading || !e.ready) {
+      const value = replayEvent(event), bytes = weight(value)
+      if (e.buffered.length >= 1024 || (e.bufferBytes || 0) + bytes > maxTailBytes) {
+        e.buffered = []; e.bufferBytes = 0; e.bufferOverflow = true; uncertain(e); return
+      }
+      if (!e.bufferOverflow) { e.buffered.push(value); e.bufferBytes = (e.bufferBytes || 0) + bytes }
+      return
+    }
+    if (event.seq <= e.cursor) return
+    if (event.seq !== e.cursor + 1) { counters.gaps++; e.ready = false; uncertain(e); accept(e, event); return }
+    e.cursor = event.seq
+    counters.events++
+    const small = compact(event)
+    if (small) { e.evidence.push(small); if (e.evidence.length > maxEvidence) { e.evidence.shift(); e.overflow = true } }
+    retain(e, event)
+    deliver(e, event)
+  }
+  const off = options.ctx?.on?.('session/event', (session, event) => {
+    const id = session?.id ?? session?.header?.id
+    const e = entries.get(id)
+    if (!e || closed) return
+    if (e.object?.deref() && e.object.deref() !== session) { e.ready = false; e.cursor = -1; uncertain(e) }
+    e.object = new WeakRef(session)
+    accept(e, event)
+  }, { global: true })
+
+  const read = async (e) => {
+    const q = query()
+    if (!q) return null
+    let snapshot
+    try {
+      e.reading = true
+      const object = live(e.id)
+      if (typeof q.observeSession === 'function') { counters.observations++; snapshot = await q.observeSession(e.id, { projectionMode: 'none' }) }
+      else { counters.reads++; snapshot = await q.readSession(e.id) }
+      if (closed || !snapshot || !Array.isArray(snapshot.events)) return null
+      const events = snapshot.events
+      const cursor = Number.isInteger(snapshot.cursor) ? snapshot.cursor : (events.length ? events[events.length - 1].seq : -1)
+      if (!Number.isInteger(cursor)) return null
+      if (object && live(e.id) !== object) { uncertain(e); return null }
+      if (cursor < e.cursor) { uncertain(e); return null }
+      const previous = e.cursor
+      e.evidence = []; e.overflow = false
+      for (const event of events) {
+        const small = compact(event)
+        if (small) { e.evidence.push(small); if (e.evidence.length > maxEvidence) { e.evidence.shift(); e.overflow = true } }
+      }
+      e.cursor = cursor; e.ready = true; e.object = object ? new WeakRef(object) : e.object
+      // A cold observation is borrowed, immutable SDK history. Release its cache lease immediately.
+      e.tail = []; e.tailBytes = 0
+      for (let i = Math.max(0, events.length - 256); i < events.length; i++) retain(e, events[i])
+      for (const event of events) if (event.seq > previous) deliver(e, event)
+      return { events, cursor }
+    } catch { counters.failures++; e.failures = (e.failures || 0) + 1; e.retryAt = now() + Math.min(30000, 1000 * 2 ** Math.min(e.failures, 5)); uncertain(e); return null }
+    finally {
+      try { snapshot?.[Symbol.dispose]?.() } catch { /* release must not hide failure */ }
+      e.reading = false
+      const buffered = e.buffered; e.buffered = []; e.bufferBytes = 0
+      if (e.bufferOverflow) { e.bufferOverflow = false; e.ready = false; uncertain(e) }
+      buffered.sort((a,b) => a.seq - b.seq)
+      for (const event of buffered) accept(e, event)
+    }
+  }
+  const refreshEntry = async (e, fresh, force = false) => {
+    if (closed) return null
+    if (!fresh && !force && e.retryAt > now()) return null
+    if (!force && headMatches(e)) return { cursor: e.cursor, evidence: e.overflow ? null : e.evidence }
+    if (!force && !fresh && e.ready && e.connected) return { cursor: e.cursor, evidence: e.overflow ? null : e.evidence }
+    const ticket = ++e.requested
+    if (!e.inflight) {
+      e.inflight = (async () => {
+        let result = null
+        while (!closed && e.completed < e.requested) {
+          const through = e.requested
+          result = await read(e)
+          e.completed = through
+          if (!result) { e.ready = false; break }
+          e.failures = 0; e.retryAt = 0
+        }
+        return result
+      })().finally(() => { e.inflight = null })
+    }
+    const result = await e.inflight
+    // A query requested after an older read began needs a cut begun after its request.
+    if (!closed && result && e.completed < ticket) return refreshEntry(e, true)
+    return closed || !result || !e.ready ? null : { ...result, evidence: e.overflow ? null : e.evidence }
+  }
+  const startStream = (e) => {
+    if (e.stream || closed || headMatches(e)) return
+    const controller = new AbortController()
+    e.stream = controller
+    void (async () => {
+      try {
+        const service = typeof options.controller === 'function' ? options.controller() : options.controller
+        if (!service?.follow) return
+        for await (const frame of service.follow({ address: e.address || { kind: 'session', sessionId: e.id } }, controller.signal)) {
+          if (closed || controller.signal.aborted) break
+          if (frame.type === 'snapshot') {
+            // The follow tail has no resume cursor. A missing business interval is repaired by query.
+            const records = frame.records || []
+            for (const record of records) accept(e, record?.type === 'event' ? record.event : record)
+            if (!e.ready || (Number.isInteger(frame.cursor) && frame.cursor !== e.cursor)) await refreshEntry(e, true)
+            e.connected = e.ready
+          } else if (frame.type === 'event') { accept(e, frame.event); if (!e.ready) await refreshEntry(e, true) }
+        }
+      } catch { counters.failures++ }
+      finally { if (e.stream === controller) { e.stream = null; uncertain(e) } }
+    })()
+  }
+  const hub = {
+    async refresh(id, { fresh = false } = {}) { return refreshEntry(entry(id), fresh) },
+    async evidence(id, { fresh = true } = {}) { const e = entry(id); return await refreshEntry(e, fresh) && !e.overflow ? e.evidence : null },
+    async latestSelectionSeq(id) { const events = await hub.evidence(id); if (!events) return { ok: false }; return { ok: true, seq: events.findLast(e => e.type === 'model/selection')?.seq ?? null } },
+    async capture(id) { return readThrough(entry(id)) },
+    async since(id, afterSeq, { fresh = false } = {}) {
+      const e = entry(id)
+      const result = await refreshEntry(e, fresh)
+      if (!result) return null
+      if (e.listeners.size) startStream(e)
+      if (afterSeq >= e.cursor) return { events: [], cursor: e.cursor }
+      if (result.events) return { events: result.events.filter(x => x.seq > afterSeq), cursor: result.cursor }
+      if (e.tail.length && e.tail[0].seq <= afterSeq + 1) return { events: e.tail.filter(x => x.seq > afterSeq), cursor: e.cursor }
+      const snap = await readThrough(e)
+      return snap && { events: snap.events.filter(x => x.seq > afterSeq), cursor: snap.cursor }
+    },
+    subscribe(id, { afterSeq = -1, onEvent, onUncertain, signal, address } = {}) {
+      const e = entry(id), sub = { afterSeq, onEvent, onUncertain, signal }
+      if (closed || signal?.aborted) return () => {}
+      if (address) {
+        const normalized = address.kind === 'subagent'
+          ? { kind: 'subagent', parentSessionId: address.parentSessionId, childSessionId: address.childSessionId, mode: address.mode }
+          : { kind: 'session', sessionId: address.sessionId }
+        if (e.address && JSON.stringify(e.address) !== JSON.stringify(normalized)) { onUncertain?.(); return () => {} }
+        e.address = normalized
+      }
+      e.listeners.add(sub)
+      const release = () => { e.listeners.delete(sub); signal?.removeEventListener('abort', release); if (!e.listeners.size) { e.stream?.abort(); e.tail = []; e.tailBytes = 0 } }
+      signal?.addEventListener('abort', release, { once: true })
+      void hub.since(id, afterSeq).then(snap => { if (!snap || closed || !e.listeners.has(sub)) return; for (const event of snap.events) { if (event.seq > sub.afterSeq) { sub.afterSeq = event.seq; sub.onEvent?.(event) } }; startStream(e) })
+      return release
+    },
+    healthy(id) { const e = entries.get(id); return !!e && (headMatches(e) || (e.ready && e.connected)) },
+    prune() { for (const [id,e] of entries) if (!e.listeners.size && !e.inflight && now() - e.touched > 30000) { e.stream?.abort(); entries.delete(id) } },
+    status() { return { ...counters, sessions: entries.size, tailBytes: [...entries.values()].reduce((n,e) => n + (e.tailBytes || 0), 0), bufferedBytes: [...entries.values()].reduce((n,e) => n + (e.bufferBytes || 0), 0) } },
+    close() { closed = true; if (typeof off === 'function') off(); for (const e of entries.values()) { e.stream?.abort(); e.listeners.clear(); e.evidence = []; e.tail = []; e.buffered = [] }; entries.clear() },
+  }
+  // Force a full borrowed cut for legacy result extraction, still serialized with all other reads.
+  const readThrough = (e) => refreshEntry(e, true, true)
+  return hub
+}

package/harness/session-target.mjs

@@ -27,8 +27,45 @@ export const REASONS = {
   BAD_REQUEST: 'session-bad-request',
   GATEWAY_INTERNAL: 'session-gateway-internal',
   DISPATCH_FAILED: 'session-dispatch-failed',
+  /** 带来源的会话任务不能精确关联到单个请求回合：在执行前拒绝 steer。 */
+  ORIGIN_STEER_UNSUPPORTED: 'origin-steer-unsupported',
+  // ---- 投递控制（queue / steer）的稳定失败码 ----
+  /** steer 必须显式给出父任务（不允许按"最近/最老任务"推断）。 */
+  PARENT_REQUIRED: 'steer-parent-required',
+  /** 给的父任务不存在、不属于同一来源/会话/档案，或不是真实在执行的队列任务。 */
+  PARENT_INVALID: 'steer-parent-invalid',
+  /** 父任务已终态（不可能再插入）。 */
+  PARENT_TERMINAL: 'steer-parent-terminal',
+  /** 父任务还在排队（还没真正开始执行）——插入没有意义，执行前拒绝。 */
+  PARENT_QUEUED: 'steer-parent-queued',
+  /** 给了 expectedTurn 但与父任务当前真实 turn 不一致。 */
+  PARENT_TURN_MISMATCH: 'steer-turn-mismatch',
+  /** 无来源的 steer 会改动别人的在途任务：零投递拒绝。 */
+  ORIGIN_REQUIRED_FOR_STEER: 'steer-origin-required',
+  /** 旧无来源（不可精确关联）任务与新的来源绑定任务混在同一会话：拒绝这种不安全组合。 */
+  LEGACY_MIX_UNSAFE: 'legacy-mix-unsafe',
+  /** 回执已接收但没能观察到自己的 rpcId 落进父回合（不重发、不猜）。 */
+  RECEIPT_UNCONFIRMED: 'steer-receipt-unconfirmed',
+  /** 回执落进了**另一个**回合（官方异步 admission / wakingAfterAbort 改道）：如实报告偏离，绝不假成功。 */
+  RECEIPT_TURN_DEVIATED: 'steer-turn-deviated',
+  /** steer 预检时父任务的回合已经结束（官方日志证据）：执行前拒绝。 */
+  PARENT_TURN_CLOSED: 'steer-parent-turn-closed',
+  /** 模型路由：精确指定的 pair/model 不在已配置目录内，或同名跨 provider 歧义 → 派活前拒绝（不静默选错）。 */
+  MODEL_ROUTE_INVALID: 'model-route-invalid',
+  /** 模型路由已按"本任务"终态收口（候选耗尽/禁 fallback 终止等）：稳定 reason，客户端不重发、不冒充成功。 */
+  MODEL_ROUTE_EXHAUSTED: 'model-route-exhausted',
+  /** 子代理回合以失败 stopReason 结束（error/aborted/refusal/max-tokens…）：绝不 done。 */
+  SUBAGENT_TURN_FAILED: 'subagent-turn-failed',
+  /** 关联到了请求回合，但该回合以非 completed 结束（aborted/blocked/error/…）。 */
+  TURN_FAILED: 'session-turn-failed',
+  /** 没有任何证据能确认这个请求回合的结局（不猜、不重发）。 */
+  UNCONFIRMED: 'execution-state-unconfirmed',
 }
 
+/** `turn/end` 的 reason.kind 枚举（来自 driver/typert）：**只有 completed 算成功**。 */
+export const TURN_END_KINDS = ['completed', 'aborted', 'blocked', 'error', 'max-tokens', 'interrupted', 'forked']
+export const SUCCESS_TURN_END = 'completed'
+
 /** 候选列表回传给调用方时的上限，避免把整个会话库倒出去。 */
 export const MAX_CANDIDATES = 10
 
@@ -91,6 +128,235 @@ export const pickSessionResult = (streamed, extracted) => {
   return fromStream !== '' ? fromStream : '(无输出)'
 }
 
+/**
+ * 请求 → DSH turn 的关联器（纯函数群）。
+ *
+ * 依据（本机 controller 0.2.0-rc.2 的实测字段）：
+ *  - `prompt.requestId` 会被写进 `user/message` 的 `event.data.source.rpcId`——这是"这条用户消息属于
+ *    哪次请求"的**唯一可靠凭据**（我们用 taskId 当 requestId）；
+ *  - **`user/message.data.turn` 不存在**：turn 号只能靠按 seq 有序跟踪"已 turn/start 但还没 turn/end"
+ *    的回合得到，遇到 rpcId 匹配的 user/message 时把它归到**当时仍未闭合**的那个 turn；
+ *  - `assistant/message.data = {turn, step, message:{content:[...]}}`：只收自己那个 turn 的助手文本；
+ *  - `turn/end.data = {turn, reason:{kind,…}}`：这是本次请求结束的依据；**只有 completed 算成功**；
+ *  - `api-session/status` 只表示 agent 当前是否 running（连续跑 queued turn 时可能没有新的 running=true），
+ *    因此它**绝不能**当作某个请求完成的证明。
+ *
+ * 同一套规则被 live follow 帧、follow 开场 snapshot.records、以及轮询读日志共用；`seq` 去重保证
+ * 同一条事件被多条路径投递时也只算一次、不串文本。
+ */
+export const createRequestTracker = (requestId, floorSeq) => ({
+  floorSeq,
+  requestId: String(requestId),
+  /** 已 turn/start 但未 turn/end 的 turn 号（有序）。 */
+  openTurns: [],
+  /** 匹配到本请求的 turn 号（由 rpcId 匹配时那一刻的未闭合 turn 决定）。 */
+  turn: undefined,
+  sawRequest: false,
+  text: '',
+  /**
+   * **只记录"真正产生了效果"的事件 seq**（建立 turn 关联 / 追加自己 turn 的文字 / 收尾 / 记录 turn/start）。
+   * 当时因为"还不知道自己那个 turn"而无法使用的事件**不**标记——后续从完整日志回填时它们必须能被重新消费
+   * （否则快照缺前半段就会永久丢掉答案）。
+   */
+  usedSeqs: new Set(),
+  /**
+   * 绑定到自己的 turn **之前**看到的助手文本（seq 升序回填）。
+   * 不能丢（快照缺前半段时会永久丢答案），也不能在回读时按"到达顺序"追加（会倒序/重复）。
+   */
+  deferred: [],
+  /** 本请求的 user/message 所在 seq（回填助手文本的下界；未见到时保持 undefined）。 */
+  requestSeq: undefined,
+  end: undefined,
+  lastSeq: 0,
+})
+
+const dataOf = (event) => (event.data !== undefined && event.data !== null && typeof event.data === 'object' ? event.data : {})
+
+/**
+ * **官方日志的 fresh 证据**（第四轮 B/C/E）：只读事件序列，不看任何缓存状态。
+ *  - `openTurns(events)`：按出现顺序列出仍未结束的 turn（turn/start 入、对应 turn/end 出）。
+ *  - `currentOpenTurn(events)`：最后一个仍未结束的 turn（= 真实"当前开放回合"），没有则 null。
+ *  - `turnHasEnded(events, turn)`：该 turn 是否已经收到 turn/end。
+ *  - `findRequestEvidence(events, requestId)`：该 rpcId 的 user/message 落在哪个 turn（含 seq）。
+ */
+export const openTurnsOf = (events) => {
+  const open = []
+  if (!Array.isArray(events)) return open
+  for (const event of events) {
+    if (event === null || typeof event !== 'object') continue
+    const data = dataOf(event)
+    const turn = typeof data.turn === 'number' ? data.turn : undefined
+    if (event.type === 'turn/start' && turn !== undefined) { if (!open.includes(turn)) open.push(turn); continue }
+    if (event.type === 'turn/end' && turn !== undefined) {
+      const index = open.indexOf(turn)
+      if (index >= 0) open.splice(index, 1)
+    }
+  }
+  return open
+}
+
+export const currentOpenTurn = (events) => {
+  const open = openTurnsOf(events)
+  return open.length === 0 ? null : open[open.length - 1]
+}
+
+export const turnHasEnded = (events, turn) => {
+  if (!Array.isArray(events) || !Number.isInteger(turn)) return false
+  for (const event of events) {
+    if (event === null || typeof event !== 'object') continue
+    const data = dataOf(event)
+    if (event.type === 'turn/end' && data.turn === turn) return true
+  }
+  return false
+}
+
+/** 该 rpcId 的 user/message 在日志里的位置：`{seq, turn}`（turn = 它所在的那个开放回合；不明则 null）。 */
+export const findRequestEvidence = (events, requestId) => {
+  if (!Array.isArray(events) || typeof requestId !== 'string' || requestId === '') return null
+  const open = []
+  for (const event of events) {
+    if (event === null || typeof event !== 'object') continue
+    const data = dataOf(event)
+    const turn = typeof data.turn === 'number' ? data.turn : undefined
+    if (event.type === 'turn/start' && turn !== undefined) { if (!open.includes(turn)) open.push(turn); continue }
+    if (event.type === 'turn/end' && turn !== undefined) {
+      const index = open.indexOf(turn)
+      if (index >= 0) open.splice(index, 1)
+      continue
+    }
+    if (event.type !== 'user/message') continue
+    const source = data.source !== undefined && data.source !== null && typeof data.source === 'object' ? data.source : {}
+    if (source.rpcId !== requestId) continue
+    const enclosing = typeof data.turn === 'number' ? data.turn : (open.length > 0 ? open[open.length - 1] : null)
+    return { seq: typeof event.seq === 'number' ? event.seq : undefined, turn: enclosing }
+  }
+  return null
+}
+
+/**
+ * 一次性把"绑定前"的助手文本按 seq 升序补进 `text`（第四轮修正 E/D）：
+ *  - **批内/跨回放去重**：已经用过的 seq 绝不重复追加（同一缺前快照喂两遍不能变成 OWNOWN）；
+ *  - **按 turn 过滤**：明确属于别的 turn 的文本丢弃（不能把另一个回合的 FOREIGN 记到自己头上）；
+ *  - **只在"自己的 user/message 之后"**（requestSeq 下界），否则同 turn 里更早请求的文本会张冠李戴。
+ * 不能用"把所有未知 turn 事件一律提前标记 used"来简化——那会破坏缺前半段快照的合法回填。
+ */
+const flushDeferred = (tracker) => {
+  if (!Array.isArray(tracker.deferred) || tracker.deferred.length === 0) return
+  const pending = tracker.deferred.slice().sort((a, b) => a.seq - b.seq)
+  tracker.deferred = []
+  const requestSeq = Number.isInteger(tracker.requestSeq) ? tracker.requestSeq : -1
+  for (const item of pending) {
+    if (tracker.usedSeqs.has(item.seq)) continue                  // 批内/跨回放去重
+    tracker.usedSeqs.add(item.seq)
+    if (item.turn !== undefined && item.turn !== tracker.turn) continue   // 明确属于别的回合 → 丢弃
+    if (item.seq < requestSeq) continue                           // 请求之前的文本不属于本请求
+    tracker.text += item.text
+  }
+}
+
+/**
+ * 消费一条会话事件。返回 `'settled'`（本请求的 turn 已结束）/ `'progress'` / `'ignored'`。
+ */
+export const consumeSessionEvent = (tracker, event) => {
+  if (tracker === undefined || tracker === null) return 'ignored'
+  if (Number.isInteger(tracker.floorSeq) && Number.isInteger(event?.seq) && event.seq <= tracker.floorSeq) return 'ignored'
+  if (event === null || typeof event !== 'object') return 'ignored'
+  const seq = typeof event.seq === 'number' ? event.seq : undefined
+  if (seq !== undefined) {
+    if (tracker.usedSeqs.has(seq)) return 'ignored'          // 已经用过的效果不重复施加
+    tracker.lastSeq = Math.max(tracker.lastSeq, seq)
+  }
+  const markUsed = () => { if (seq !== undefined) tracker.usedSeqs.add(seq) }
+  const data = dataOf(event)
+  if (event.type === 'turn/start') {
+    const turn = typeof data.turn === 'number' ? data.turn : undefined
+    if (turn !== undefined && !tracker.openTurns.includes(turn)) tracker.openTurns.push(turn)
+    markUsed()
+    return 'ignored'
+  }
+  if (event.type === 'user/message') {
+    const source = data.source !== undefined && data.source !== null && typeof data.source === 'object' ? data.source : {}
+    if (typeof source.rpcId !== 'string' || source.rpcId !== tracker.requestId) return 'ignored'
+    tracker.sawRequest = true
+    if (seq !== undefined && !Number.isInteger(tracker.requestSeq)) tracker.requestSeq = seq   // 本请求消息所在的 seq（回填下界）
+    if (tracker.turn === undefined) {
+      // user/message 没有 data.turn：归到此刻仍未闭合的那个 turn（有 data.turn 时以它为准）
+      const fallback = tracker.openTurns.length > 0 ? tracker.openTurns[tracker.openTurns.length - 1] : undefined
+      tracker.turn = typeof data.turn === 'number' ? data.turn : fallback
+    }
+    // 只有真的建立了 turn 关联才算"用过"；没有未闭合 turn 时留待回填。
+    if (tracker.turn !== undefined) {
+      markUsed()
+      flushDeferred(tracker)                                // 按 seq 顺序补上"绑定前"的助手文本（且只补一次）
+    }
+    return 'progress'
+  }
+  if (event.type === 'assistant/message') {
+    const text = assistantTextOf(event)
+    if (text === '') return 'ignored'
+    if (tracker.turn === undefined) {
+      // 还不知道自己的 turn：**排队等待按 seq 顺序回填**（不能直接丢，也不能在回读时才追加——
+      // 那会把更早的文本接到更晚的文本后面，root 复现过 AFTER → AFTER|BEFORE 的倒序）。
+      // 同时记下事件自带的 turn（若官方给了），回填时据此丢弃别的回合的文本；同一 seq 只入队一次
+      // （同一"缺前快照"喂两遍不得变成 OWNOWN）。
+      if (seq !== undefined && !tracker.deferred.some((item) => item.seq === seq)) {
+        tracker.deferred.push({ seq, turn: typeof data.turn === 'number' ? data.turn : undefined, text })
+      }
+      return 'ignored'
+    }
+    if (typeof data.turn === 'number' && data.turn !== tracker.turn) {
+      markUsed()                                            // 明确不是我们的 turn：用掉，避免反复评估
+      return 'ignored'
+    }
+    tracker.text += text
+    markUsed()
+    return 'progress'
+  }
+  if (event.type === 'turn/end') {
+    const turn = typeof data.turn === 'number' ? data.turn : undefined
+    if (turn !== undefined) tracker.openTurns = tracker.openTurns.filter((t) => t !== turn)
+    if (tracker.turn === undefined || turn !== tracker.turn) {
+      // 不是我们的回合：**不标记**，等自己那个 turn 绑定后若还有对应结束仍要能收到。
+      return 'ignored'
+    }
+    const reason = data.reason !== undefined && data.reason !== null && typeof data.reason === 'object' ? data.reason : {}
+    const kind = typeof reason.kind === 'string' ? reason.kind : 'unknown'
+    tracker.end = { kind, reason, seq }
+    markUsed()
+    return 'settled'
+  }
+  return 'ignored'
+}
+
+/**
+ * follow 开场的 snapshot 帧：`{type:'snapshot', records:[{type:'event', event:{…}}], …}`。
+ * **不能把 snapshot 整个丢掉**——快任务可能在派发与订阅之间就已经跑完，答案只在这个快照里。
+ */
+export const consumeSnapshotFrame = (tracker, frame) => {
+  const records = frame !== null && frame !== undefined && Array.isArray(frame.records)
+    ? frame.records
+    : (frame !== null && frame !== undefined && Array.isArray(frame.events) ? frame.events : [])
+  let last = 'ignored'
+  for (const record of records) {
+    if (record === null || typeof record !== 'object') continue
+    const event = record.type === 'event' && record.event !== undefined && record.event !== null
+      ? record.event
+      : (typeof record.type === 'string' && record.seq !== undefined ? record : undefined)
+    if (event === undefined) continue
+    const outcome = consumeSessionEvent(tracker, event)
+    if (outcome === 'settled') return 'settled'
+    if (outcome === 'progress') last = 'progress'
+  }
+  return last
+}
+
+/** 由 tracker 得出终态结论：只有 completed 算成功；其他 kind 明确失败；没有证据=未确认。 */
+export const turnOutcome = (end) => {
+  if (end === undefined || end === null) return { ok: false, unconfirmed: true, kind: 'unconfirmed' }
+  if (end.kind === SUCCESS_TURN_END) return { ok: true, unconfirmed: false, kind: end.kind }
+  return { ok: false, unconfirmed: false, kind: end.kind }
+}
+
 /**
  * 判定一次派发的目标。
  *
@@ -130,8 +396,10 @@ export const classifyTarget = (input) => {
     if (id === undefined && query === undefined) {
       return { ok: false, reason: REASONS.INVALID_TARGET, message: 'session target needs sessionId or query' }
     }
-    // session 语义自带工作目录与模型：混用会让人以为还能控制它们。
-    for (const [field, value] of [['cwd', raw.cwd], ['lane', raw.lane], ['model', raw.model]]) {
+    // session 语义自带工作目录：混用会让人以为还能控制它。
+    // **模型例外**（第五轮模型路由契约）：session 目标**接受** model/provider/modelFallback——扁平写法
+    // （sessionId+model）与 target.kind='session'+model 必须语义一致，两者都由任务级路由策略处理。
+    for (const [field, value] of [['cwd', raw.cwd], ['lane', raw.lane]]) {
       if (nonEmpty(value)) {
         return { ok: false, reason: REASONS.INVALID_TARGET, message: `${field} is not accepted with a session target` }
       }
@@ -283,6 +551,8 @@ export const rankTitleCandidates = (query, summaries, limit = 5) => {
 /** 任务在 HTTP 行上的回显：调用方一眼能看出这次是"新建"还是"接进哪个会话"。 */
 export const taskResponse = (task) => {
   const out = { taskId: task.taskId, status: task.status, kind: task.kind }
+  // 动态模型路由（M2）：回显实际选择/模式/是否允许降级（非秘密；不含任何凭据）。
+  if (task.route !== undefined && task.route !== null && typeof task.route === 'object') out.route = task.route
   const target = task.target !== undefined && task.target !== null
     ? task.target
     // 兼容 0.1.1 之前落下的记录（如 review 任务）：没有 target 字段时按 worker 回显。
@@ -299,5 +569,24 @@ export const taskResponse = (task) => {
   if (task.target !== undefined && task.target !== null && task.target.kind === 'session' && task.delivered === true) {
     out.delivered = true
   }
+  // 来源关联（R1）：回显发起这次任务的 Codex 对话 id，便于跨回合按 origin+taskId 精确收取。
+  if (typeof task.originThreadId === 'string' && task.originThreadId !== '') out.originThreadId = task.originThreadId
+  // 委托审批的**非秘密**定位/期限（第三轮修正）：客户端等待循环必须能凭它做认证续租，
+  // 否则慢模型超过初始租约就会把首个 ask 交回人工。raw key/摘要一律不出现在这里。
+  if (typeof task.grantId === 'string' && task.grantId !== '') {
+    out.grantId = task.grantId
+    if (Number.isFinite(task.grantExpiresAt)) out.grantExpiresAt = task.grantExpiresAt
+    if (Number.isFinite(task.grantLeaseUntil)) out.grantLeaseUntil = task.grantLeaseUntil
+  }
+  // 投递控制（第四轮）：回显投递模式与父/回执关系（非秘密），让调用方能区分"排队任务"与"补充回执"。
+  if (task.target !== undefined && task.target !== null && task.target.kind === 'session') {
+    const mode = task.requestedMode !== undefined ? task.requestedMode : task.deliver
+    if (mode !== undefined) out.deliver = mode
+    if (typeof task.parentTaskId === 'string' && task.parentTaskId !== '') out.parentTaskId = task.parentTaskId
+    if (typeof task.receiptState === 'string' && task.receiptState !== '') out.receiptState = task.receiptState
+    if (Number.isInteger(task.observedTurn)) out.observedTurn = task.observedTurn
+    if (Number.isInteger(task.expectedTurn)) out.expectedTurn = task.expectedTurn
+    if (typeof task.resultScope === 'string' && task.resultScope !== '') out.resultScope = task.resultScope
+  }
   return out
 }

package/harness/task-table.mjs

@@ -0,0 +1,34 @@
+/**
+ * task-table.mjs —— 网关内存任务表的淘汰策略（纯函数，可单测）。
+ *
+ * 为什么单独抽出来：原来三个入口都无条件 `tasks.splice(0, tasks.length - 200)`，会把
+ * **仍在执行**的任务挤掉，导致完成回调/会话观察器 `find(taskId)` 找不到它（结果丢失）。
+ * 现在只淘汰**终态**任务，且永不淘汰刚创建的那一条。
+ */
+
+export const DEFAULT_TASK_LIMIT = 200
+
+/**
+ * 把任务放进表里，并在超限时淘汰终态任务。
+ * @param {Array<object>} tasks 任务表（原地修改）
+ * @param {object} task 新任务
+ * @param {number} [limit]
+ * @returns {Array<object>} 同一个数组
+ */
+export const rememberTask = (tasks, task, limit = DEFAULT_TASK_LIMIT) => {
+  tasks.push(task)
+  const bound = typeof limit === 'number' && limit > 0 ? limit : DEFAULT_TASK_LIMIT
+  while (tasks.length > bound) {
+    // 淘汰**终态**（非 active）且不是刚加进来的那一条。
+    // active 含 accepted / running / needs-approval（等待审批的活任务不能被淘汰，
+    // 否则完成回调、会话观察器与审批 pending 都会失去归属）。
+    const index = tasks.findIndex((t) => t !== task && !isActiveTask(t))
+    if (index === -1) break                    // 全是活任务：宁可超过上限，也不丢执行中的任务
+    tasks.splice(index, 1)
+  }
+  return tasks
+}
+
+/** 是否处于"还在执行/等待中"的状态（完成回调与审批归属需要能找到它）。 */
+export const isActiveTask = (task) => task !== null && typeof task === 'object'
+  && (task.status === 'accepted' || task.status === 'running' || task.status === 'needs-approval' || task.awaitingOfficialEnd === true)