dsh-session-bridge 0.3.2-alpha.1 → 0.3.2-alpha.3

package/scripts/test-bridge-core.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * Regression tests for the session-bridge core wait/stall logic (GitHub issue #1):
+ *
+ *   Bug 1 — session_bridge_wait 返回 "(no text)" 并跑满超时，即使回复早已存在。
+ *   Bug 2 — session_bridge_status 把空闲会话标成 [STALLED]。
+ *
+ * Runs against src/core.ts directly (Node type stripping — no build, no deps, no
+ * host/Dsh runtime needed): `npm test`. The fake Session only has to expose the
+ * read path core.sessionEvents() probes (`snapshotEvents()`).
+ */
+import assert from 'node:assert/strict'
+import { foldMessages, isStalled, maxSeq, waitForReply } from '../src/core.ts'
+
+let passed = 0
+let failed = 0
+
+async function test(name, fn) {
+  try {
+    await fn()
+    passed += 1
+    console.log('PASS ' + name)
+  } catch (error) {
+    failed += 1
+    console.error('FAIL ' + name)
+    console.error('     ' + (error instanceof Error ? error.message : String(error)))
+  }
+}
+
+// --- synthetic event log -----------------------------------------------------
+const turnStart = (seq, turn = 1) => ({ seq, time: seq, type: 'turn/start', data: { turn } })
+const turnEnd = (seq, turn = 1) => ({ seq, time: seq, type: 'turn/end', data: { turn } })
+const userMsg = (seq, text) => ({ seq, time: seq, type: 'user/message', data: { source: { kind: 'user' }, content: [{ type: 'text', text }] } })
+const assistantText = (seq, text, step = 1) => ({ seq, time: seq, type: 'assistant/message', data: { turn: 1, step, message: { content: [{ type: 'text', text }] } } })
+/** 纯工具调用中间行：无文本（foldMessages 会给出一个没有 text 的 assistant 行）。 */
+const assistantTool = (seq, name = 'bash', step = 2) => ({ seq, time: seq, type: 'assistant/message', data: { turn: 1, step, message: { content: [{ type: 'text', text: '' }], toolCalls: [{ name }] } } })
+/** 带 reasoning 的已完成段落。 */
+const assistantReasoning = (seq, reasoning, text) => ({ seq, time: seq, type: 'assistant/message', data: { turn: 1, step: 1, message: { content: [{ type: 'reasoning', text: reasoning }, { type: 'text', text }] } } })
+/** 假 Session：core.sessionEvents() 会走 snapshotEvents() 分支。 */
+const fakeSession = (events) => ({ snapshotEvents: () => events })
+
+// --- Bug 2: stall semantics ---------------------------------------------------
+await test('isStalled: idle sessions are never stalled (issue #1 Bug 2)', () => {
+  assert.equal(isStalled('idle', 10_000_000, 60_000), false)
+  assert.equal(isStalled('idle', 0, 60_000), false)
+})
+
+await test('isStalled: running sessions stall only past the threshold', () => {
+  assert.equal(isStalled('running', 10_000_000, 60_000), true)
+  assert.equal(isStalled('running', 60_000, 60_000), false) // "exceeds" is strict
+  assert.equal(isStalled('running', 60_001, 60_000), true)
+  assert.equal(isStalled('running', null, 60_000), false)
+})
+
+// --- Bug 1: wait never loses an already-landed reply --------------------------
+await test('wait reply-mode: pre-existing reply at baseline -> stale + text (main symptom)', async () => {
+  const events = [turnStart(0), userMsg(1, 'hi'), assistantText(2, 'pong'), turnEnd(3)]
+  const result = await waitForReply({ session: fakeSession(events), baselineSeq: 2, timeoutMs: 1 })
+  assert.equal(result.message?.text, 'pong')
+  assert.equal(result.message?.seq, 2)
+  assert.equal(result.stale, true)
+  assert.equal(result.timedOut, true)
+  assert.equal(result.seq, 2)
+})
+
+await test('wait reply-mode: never returns a later text-less step as the reply', async () => {
+  // 回复已落地，目标会话随后又跑了工具调用/推理步（更晚但无文本）。
+  // 旧实现 message = textReply ?? latest 会把这个无文本行交出去 -> 渲染 "(no text)"。
+  const events = [turnStart(0), userMsg(1, 'hi'), assistantText(2, 'pong'), assistantTool(3), turnEnd(4)]
+  const result = await waitForReply({ session: fakeSession(events), baselineSeq: maxSeq(events), timeoutMs: 1 })
+  assert.equal(result.message?.text, 'pong')
+  assert.equal(result.message?.seq, 2)
+  assert.equal(result.stale, true)
+  assert.equal(result.timedOut, true)
+})
+
+await test('wait reply-mode: legacy baseline (last text row) with a newer tool row', async () => {
+  // 旧默认 baseline = 最后一条带文本行；更晚的无文本行让它返回无文本行。
+  const events = [turnStart(0), userMsg(1, 'hi'), assistantText(2, 'pong'), assistantTool(3)]
+  const result = await waitForReply({ session: fakeSession(events), baselineSeq: 2, timeoutMs: 1 })
+  assert.equal(result.message?.text, 'pong')
+  assert.equal(result.stale, true)
+  assert.equal(result.timedOut, true)
+})
+
+await test('wait reply-mode: a genuinely new reply returns immediately, stale=false', async () => {
+  const events = [turnStart(0), userMsg(1, 'hi'), assistantText(2, 'old')]
+  const baseline = maxSeq(events)
+  setTimeout(() => { events.push(assistantText(3, 'new')) }, 30)
+  const started = Date.now()
+  const result = await waitForReply({ session: fakeSession(events), baselineSeq: baseline, timeoutMs: 2_000 })
+  assert.equal(result.message?.text, 'new')
+  assert.equal(result.stale, false)
+  assert.equal(result.timedOut, false)
+  assert.ok(Date.now() - started < 1_000, 'should return as soon as the new reply lands')
+})
+
+await test('wait segment-mode: pre-existing segment -> stale + segment fields', async () => {
+  const events = [turnStart(0), userMsg(1, 'hi'), assistantReasoning(2, 'thinking…', 'answer'), turnEnd(3)]
+  const result = await waitForReply({ session: fakeSession(events), baselineSeq: maxSeq(events), timeoutMs: 1, waitForSegment: true })
+  assert.equal(result.stale, true)
+  assert.equal(result.seq, 2)
+  assert.equal(result.message?.text, 'answer')
+  assert.equal(result.message?.reasoning, 'thinking…')
+})
+
+await test('wait reply-mode: no assistant text at all -> message null, stale=false', async () => {
+  const events = [turnStart(0), userMsg(1, 'hi'), assistantTool(2)]
+  const result = await waitForReply({ session: fakeSession(events), baselineSeq: maxSeq(events), timeoutMs: 1 })
+  assert.equal(result.message, null)
+  assert.equal(result.stale, false)
+  assert.equal(result.timedOut, true)
+  assert.equal(result.seq, maxSeq(events))
+})
+
+await test('wait requireTurnEnd: new row without turn/end -> timedOut, stale fallback text', async () => {
+  const events = [turnStart(0), userMsg(1, 'hi'), assistantText(2, 'first'), assistantTool(3)]
+  const result = await waitForReply({ session: fakeSession(events), baselineSeq: 2, timeoutMs: 1, requireTurnEnd: true })
+  assert.equal(result.timedOut, true)
+  assert.equal(result.turnEnded, false)
+  assert.equal(result.stale, true)
+  assert.equal(result.message?.text, 'first')
+})
+
+await test('wait requireTurnEnd: nothing new at all -> timedOut (was misreported as false)', async () => {
+  const events = [turnStart(0), userMsg(1, 'hi'), assistantText(2, 'first'), assistantTool(3), turnEnd(4)]
+  const result = await waitForReply({ session: fakeSession(events), baselineSeq: maxSeq(events), timeoutMs: 1, requireTurnEnd: true })
+  assert.equal(result.timedOut, true)
+  assert.equal(result.stale, true)
+  assert.equal(result.message?.text, 'first')
+})
+
+await test('wait sinceSeq=-1 anchor (create path): existing reply counts as new', async () => {
+  const events = [turnStart(0), userMsg(1, 'hi'), assistantText(2, 'hello')]
+  const started = Date.now()
+  const result = await waitForReply({ session: fakeSession(events), baselineSeq: -1, timeoutMs: 2_000 })
+  assert.equal(result.message?.text, 'hello')
+  assert.equal(result.stale, false)
+  assert.equal(result.timedOut, false)
+  assert.ok(Date.now() - started < 1_000, 'should return without waiting (nothing to wait for)')
+})
+
+// --- sanity -------------------------------------------------------------------
+await test('maxSeq: empty log is -1 (anchor sentinel)', () => {
+  assert.equal(maxSeq([]), -1)
+  assert.equal(maxSeq(undefined), -1)
+  assert.equal(maxSeq([turnStart(0), assistantText(5, 'x')]), 5)
+  assert.equal(foldMessages([assistantTool(1)]).length, 1)
+  assert.equal(foldMessages([assistantTool(1)])[0].text, undefined)
+})
+
+console.log('')
+console.log(String(passed) + ' passed, ' + String(failed) + ' failed')
+if (failed > 0) process.exit(1)

package/src/core.ts

@@ -44,6 +44,12 @@ export interface BridgeWaitResult {
   seq: number
   turnEnded: boolean
   timedOut: boolean
+  /**
+   * true = 返回的是等待开始前就已经存在的输出（整个等待窗口内没有出现新的文本
+   * 回复 / 新段落）。此时 message 仍带正文，调用方据此区分"等到了新回复"与
+   * "拿到的是既有回复"。不变式：stale === (message !== null && message.seq <= baselineSeq)。
+   */
+  stale: boolean
   aborted: boolean
   waitedMs: number
 }
@@ -64,11 +70,19 @@ export interface BridgeFindItem {
 
 /**
  * 兼容读取不同 dsh-session 版本上的会话事件：
- * - 旧版 `Session` 暴露 `get events(): readonly SessionEvent[]`；
- * - 新版（如宿主实际运行的 0.1.2-rc.x）将 `get events` 改为
- *   `snapshotEvents(fromSeq?, toSeqExclusive?)` 方法——`.events` 直接读取会
- *   得到 `undefined`，对 for...of 迭代即抛 `events is not iterable`。
+ * - 旧版 \`Session\` 暴露 \`get events(): readonly SessionEvent[]\`；
+ * - 新版将 \`get events\` 改为 \`snapshotEvents(fromSeq?, toSeqExclusive?)\` 方法——
+ *   \`.events\` 直接读取会得到 \`undefined\`，对 for...of 迭代即抛
+ *   \`events is not iterable\`。
  * 两者都读不到（或 session 不存在）时回退为空数组，绝不抛迭代错误。
+ *
+ * 注意：dsh 0.1.6-alpha.1 起 \`snapshotEvents()\`（连同 \`eventAt()\` /
+ * \`ownEvents()\`）已标记 @deprecated —— 官方策略是"现有逻辑可暂不迁移，但禁止
+ * 新增调用"；其替代不是同步读，而是（a）恢复后读取 Session 投影/派生状态，或
+ * （b）按需异步分页读取历史窗口（见 dsh 决策
+ * 2026-09-09-deprecate-synchronous-session-event-reads）。本函数的调用方
+ * （foldMessages / segmentsSince / wait 基线）仍依赖完整同步快照，故按该决定暂缓
+ * 迁移；将来官方补齐分页读后，只需改造这一个入口。
  */
 export function sessionEvents(session: unknown): readonly SessionEvent[] {
   const s = session as {
@@ -421,8 +435,11 @@ export interface WaitForReplyOptions {
  * 因此默认不再用 turn/end 作门控；需要完整收尾语义时用 requireTurnEnd:true 显式开启，
  * 此时才会等到其后出现 turn/end。
  *
- * 返回时 message 为"最新的带文本 assistant 行"，否则为最新 assistant 行（可能无文本，
- * 如纯工具调用中间态）；超时/中止返回已收集内容。
+ * 返回的 message：默认是 baseline 之后最新的一条**带文本** assistant 行；整个等待
+ * 窗口内没有等到新文本回复时，回落为 baseline 及之前最新的一条带文本回复并置
+ * stale:true（绝不把更晚的无文本中间行当回复返回 —— 那正是渲染层打印 "(no text)"
+ * 的来源）。segment 模式同理：新段落优先，否则回落既有段落。
+ * 超时/中止返回已收集内容；timedOut 表示"本次等待要求的输出未在预算内出现"。
  */
 export async function waitForReply(opts: WaitForReplyOptions): Promise<BridgeWaitResult> {
   const started = Date.now()
@@ -458,23 +475,60 @@ export async function waitForReply(opts: WaitForReplyOptions): Promise<BridgeWai
     if (Date.now() >= deadline) break
     await sleep(100)
   }
+  // 等待窗口内是否观察到新输出（即 done 条件是否达成）：用于 timedOut / stale 判定。
+  const observedNew = waitForSegment ? segment !== null : textReply !== null
+  const sawNewRow = latest !== null
+  // 零新输出时回落既有内容；回落扫描限定 seq <= baselineSeq，保证 stale 不变式成立，
+  // 也不会把"其实算新"的内容标成 stale。
+  let stale = false
+  if (waitForSegment) {
+    if (segment === null) {
+      const prev = lastSegmentUpTo(sessionEvents(opts.session), opts.baselineSeq)
+      if (prev !== null) { segment = prev; stale = true }
+    }
+  } else if (textReply === null) {
+    const prev = lastTextRowUpTo(foldMessages(sessionEvents(opts.session)), opts.baselineSeq)
+    if (prev !== null) { textReply = prev; stale = true }
+  }
   // 段落模式返回该段（把 reasoning 并进返回行，便于“按段落读思维链”）；否则返回最新文本行。
-  let message: BridgeMessageRow | null = waitForSegment && segment !== null ? {
+  const message: BridgeMessageRow | null = waitForSegment && segment !== null ? {
     seq: segment.seq, time: segment.time, role: 'assistant', images: 0,
     ...(segment.text !== undefined ? { text: segment.text } : {}),
     ...(segment.reasoning !== undefined ? { reasoning: segment.reasoning } : {}),
     ...(segment.toolCalls.length > 0 ? { toolCalls: segment.toolCalls } : {}),
-  } : (textReply ?? latest)
+  } : textReply
   return {
     message,
     seq: message === null ? opts.baselineSeq : message.seq,
     turnEnded,
-    timedOut: requireTurnEnd ? (latest !== null && !turnEnded) : waitForSegment ? segment === null : textReply === null,
+    // done 条件未达成即超时。requireTurnEnd 下"连新行都没出现"同样算超时
+    // （旧写法 latest !== null && !turnEnded 会把这种情况误报为未超时）。
+    timedOut: requireTurnEnd ? !(sawNewRow && turnEnded) : !observedNew,
+    stale,
     aborted: opts.signal !== undefined && opts.signal.aborted,
     waitedMs: Date.now() - started,
   }
 }
 
+/** seq 及之前最新一个已完成输出段落（wait 零新输出时回落既有段落）。 */
+function lastSegmentUpTo(events: readonly SessionEvent[], seq: number): BridgeSegment | null {
+  const segs = segmentsSince(events)
+  for (let i = segs.length - 1; i >= 0; i -= 1) {
+    const seg = segs[i]
+    if (seg !== undefined && seg.seq <= seq) return seg
+  }
+  return null
+}
+
+/** seq 及之前最新一条带文本的 assistant 行（wait 零新文本回复时回落既有回复）。 */
+function lastTextRowUpTo(rows: readonly BridgeMessageRow[], seq: number): BridgeMessageRow | null {
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const row = rows[i]
+    if (row !== undefined && row.role === 'assistant' && row.text !== undefined && row.seq <= seq) return row
+  }
+  return null
+}
+
 export interface TargetCwdArgs {
   workspaceId?: string
   cwd?: string
@@ -542,6 +596,15 @@ export async function attachSessionToWorkspace(ctx: Context, sessionId: SessionI
   return workspace.id
 }
 
+/**
+ * 卡住判定（唯一真源，status 渲染与监控 watchdog 共用）：只有 **running** 会话才可能
+ * "卡住" —— 空闲/已收尾的会话没有进展是正常状态，不能报 stall。阈值语义为"超过"
+ * （严格大于），与工具描述/README 的 "more than stalledMs" 一致。
+ */
+export function isStalled(running: 'running' | 'idle', stalledMs: number | null, thresholdMs: number): boolean {
+  return running === 'running' && stalledMs !== null && stalledMs > thresholdMs
+}
+
 /** 一次会话监控快照：供"监控线程"判断主任务是否在跑、有无进展、是否卡住。 */
 export interface BridgeStatusSnapshot {
   sessionId: string

package/src/monitor.ts

@@ -14,6 +14,7 @@ import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import {
   cancelLiveSession,
   getLiveAgent,
+  isStalled,
   sendLiveMessage,
   statusSnapshot,
   type BridgeStatusSnapshot,
@@ -224,9 +225,8 @@ export class SessionMonitor {
     }
 
     // 2) 卡住判定：仅对 running 会话有意义（距最近事件超过阈值）。
-    const stalled = snapshot.running === 'running'
-      && snapshot.stalledMs !== null
-      && snapshot.stalledMs > (entry.config.stalledMs ?? 60000)
+    //    判定走 core.isStalled（唯一真源，与 session_bridge_status 的 [STALLED] 标注一致）。
+    const stalled = isStalled(snapshot.running, snapshot.stalledMs, entry.config.stalledMs ?? 60000)
     if (stalled) {
       entry.stuckCount += 1
       entry.lastActionAt = Date.now()

package/src/tools.ts

@@ -20,6 +20,7 @@ import {
   attachSessionToWorkspace,
   foldMessages,
   inspectPersistedSession,
+  isStalled,
   maxSeq,
   resolveTargetCwd,
   segmentsSince,
@@ -76,6 +77,15 @@ function liveAgents(env: BridgeEnv): LiveAgentLike[] {
   return agents.list()
 }
 
+/** 等待结果里的状态附注行（wait / send / create 三处渲染共用）。 */
+function waitNotes(reply: Record<string, unknown>): string[] {
+  const notes: string[] = []
+  if (reply.timedOut === true) notes.push('[wait timed out]')
+  if (reply.stale === true) notes.push('[stale] pre-existing reply — nothing new arrived during the wait')
+  if (reply.aborted === true) notes.push('[wait aborted]')
+  return notes
+}
+
 /** 渲染等待结果为 JSON 友好值。 */
 function renderWait(wait: BridgeWaitResult): Record<string, unknown> {
   const row = wait.message
@@ -91,6 +101,7 @@ function renderWait(wait: BridgeWaitResult): Record<string, unknown> {
     seq: wait.seq,
     turnEnded: wait.turnEnded,
     timedOut: wait.timedOut,
+    ...(wait.stale === true ? { stale: true } : {}),
     aborted: wait.aborted,
     waitedMs: wait.waitedMs,
   }
@@ -154,9 +165,10 @@ function registerCreate(env: BridgeEnv): void {
         if (typeof v.cwd === 'string') lines.push(`cwd: ${v.cwd}`)
         if (typeof v.title === 'string') lines.push(`title: ${v.title}`)
         const reply = v.reply as Record<string, unknown> | undefined
+        if (typeof v.sinceSeq === 'number') lines.push(`sinceSeq: ${String(v.sinceSeq)} (pass to session_bridge_wait)`)
         if (reply !== undefined) {
           lines.push(`reply: ${String((reply.message as Record<string, unknown> | null)?.text ?? '(no text)')}`)
-          if (reply.timedOut === true) lines.push('[wait timed out]')
+          lines.push(...waitNotes(reply))
         }
         return [{ type: 'text' as const, text: lines.join('\n') }]
       },
@@ -245,8 +257,12 @@ function registerCreate(env: BridgeEnv): void {
       })
 
       let reply: ReturnType<typeof renderWait> | undefined
+      // 发送 prompt 之前的日志锚点：异步创建时交还调用方，供之后精确 wait 取回首条回复。
+      // 新建会话的 maxSeq 为 -1（尚无事件），所以"未发送"用 undefined 哨兵而不是数值比较。
+      let createBaseline: number | undefined
       if (typeof args.prompt === 'string' && args.prompt.trim() !== '') {
         const baseline = maxSeq(sessionEvents(agent.session))
+        createBaseline = baseline
         agent.followup(userMessage(args.prompt.trim()))
         env.registry.touch(sessionId)
         if (args.waitForReply === true) {
@@ -259,6 +275,7 @@ function registerCreate(env: BridgeEnv): void {
         cwd: targetCwd,
         ...(workspaceId === undefined ? {} : { workspaceId }),
         ...(typeof args.title === 'string' && args.title.trim() !== '' ? { title: args.title.trim() } : {}),
+        ...(reply === undefined && createBaseline !== undefined ? { sinceSeq: createBaseline } : {}),
         ...(reply === undefined ? {} : { reply }),
       })
     },
@@ -290,9 +307,10 @@ function registerSend(env: BridgeEnv): void {
         const v = value as Record<string, unknown>
         const reply = v.reply as Record<string, unknown> | null | undefined
         const lines = ['sent to ' + String(v.sessionId)]
+        if (typeof v.sinceSeq === 'number') lines.push('sinceSeq: ' + String(v.sinceSeq) + ' (pass to session_bridge_wait)')
         if (reply !== null && reply !== undefined) {
           lines.push('reply: ' + String((reply.message as Record<string, unknown> | null)?.text ?? '(no text)'))
-          if ((reply as Record<string, unknown>).timedOut === true) lines.push('[wait timed out]')
+          lines.push(...waitNotes(reply))
         }
         return [{ type: 'text' as const, text: lines.join('\n') }]
       },
@@ -316,7 +334,9 @@ function registerSend(env: BridgeEnv): void {
         ...(sendWorkspaceId === undefined ? {} : { workspaceId: sendWorkspaceId }),
       })
       const reply = await maybeWait(env, agent.session, baseline, args, exec.signal)
-      return asJson({ accepted: true, sessionId: args.sessionId, ...(reply === undefined ? {} : { reply }) })
+      // 未同步等待时把发送前的锚点交还给调用方：之后无论隔多久，用该 sinceSeq 调
+      // session_bridge_wait 都能稳定取回"本次发送之后的回复"（不受调用方延迟影响）。
+      return asJson({ accepted: true, sessionId: args.sessionId, ...(reply === undefined ? { sinceSeq: baseline } : { reply }) })
     },
   }))
 }
@@ -413,10 +433,10 @@ interface WaitArgsTool {
 function registerWait(env: BridgeEnv): void {
   env.ctx.tools.register(defineTool({
     name: 'session_bridge_wait',
-    description: 'Wait for a session next assistant output: blocks (polling the session log) until a NEW assistant output appears after sinceSeq (default: the latest seq at call time). waitFor=reply returns as soon as a new assistant TEXT reply is readable; waitFor=segment returns as soon as any new COMPLETED output segment appears (an assistant/message step — text, reasoning, or tool-call turn), i.e. it does NOT wait for the whole turn, so you can observe the chain-of-thought/output paragraph by paragraph as it is produced. Returns the output summary, or timedOut/aborted when the deadline or caller cancellation ends the wait. Use it to consume output produced asynchronously by another session (e.g. a session you sent a message to, or one working on its own).',
+    description: 'Wait for a session next assistant output: blocks (polling the session log) until a NEW assistant output appears after sinceSeq (default: the latest seq at call time). waitFor=reply returns as soon as a new assistant TEXT reply is readable; waitFor=segment returns as soon as any new COMPLETED output segment appears (an assistant/message step — text, reasoning, or tool-call turn), i.e. it does NOT wait for the whole turn, so you can observe the chain-of-thought/output paragraph by paragraph as it is produced. If no new output arrives within the budget, the latest PRE-EXISTING reply/segment is returned with stale=true (so an already-landed reply is never lost as "(no text)"). Returns the output summary, or timedOut/aborted when the deadline or caller cancellation ends the wait. Use it to consume output produced asynchronously by another session (e.g. a session you sent a message to, or one working on its own); to read a reply that may already exist, pass the sinceSeq anchor returned by send/create.',
     parameters: {
       sessionId: { type: 'string', required: true, description: 'Session id to wait on.' },
-      sinceSeq: { type: 'number', description: 'Only replies after this event seq count (default: latest seq at call time).' },
+      sinceSeq: { type: 'number', description: 'Only replies after this event seq count (default: latest seq at call time; -1 = count every event, the anchor returned by create for a brand-new session).' },
       timeoutMs: { type: 'number', description: 'Wait budget in milliseconds (default 180000, max 3600000); timed out waits return the partial result instead of failing.' },
       requireTurnEnd: { type: 'boolean', description: 'When true, wait for the reply turn/end to settle before returning (default false; false returns as soon as the reply text is readable).' },
       waitFor: { type: 'string', enum: ['reply', 'segment'], description: 'reply (default) waits for a new assistant TEXT reply; segment waits for any new completed output segment (an assistant/message step, incl. reasoning/tool turns) and returns it immediately, without waiting for the whole turn.' },
@@ -428,10 +448,11 @@ function registerWait(env: BridgeEnv): void {
         const reply = v.reply as Record<string, unknown> | null | undefined
         if (reply === null || reply === undefined) return [{ type: 'text' as const, text: 'no reply observed' }]
         const message = (reply.message as Record<string, unknown> | null)
-        const lines = ['reply seq ' + String(reply.seq) + ': ' + String(message === null ? '(no text)' : message.text ?? '(no text)')]
+        const lines = [message === null
+          ? 'no new reply within ' + String(reply.waitedMs ?? '?') + 'ms (no assistant text in this session)'
+          : 'reply seq ' + String(reply.seq) + ': ' + String(message.text ?? '(no text)')]
         if (typeof reply.turnEnded === 'boolean') lines.push('turnEnded: ' + String(reply.turnEnded))
-        if (reply.timedOut === true) lines.push('[wait timed out]')
-        if (reply.aborted === true) lines.push('[wait aborted]')
+        lines.push(...waitNotes(reply))
         return [{ type: 'text' as const, text: lines.join('\n') }]
       },
     },
@@ -441,34 +462,25 @@ function registerWait(env: BridgeEnv): void {
       if (agent === undefined) {
         throw new Error('session ' + JSON.stringify(args.sessionId) + ' is not live — call session_bridge_resume first (waiting requires a live session)')
       }
-      // 默认 baseline = 当前最后一条（带文本的）assistant 行的 seq：让 wait 只等待
-      // 之后新出现的输出，避免把"已存在的输出"当成待等内容，同时不被文本后追加的
-      // 无文本中间块（推理尾块/工具结果）干扰。segment 模式下以最后一个已完成段落为界。
-      const waitSegment = args.waitFor === 'segment'
-      let baseline: number
-      if (typeof args.sinceSeq === 'number' && Number.isInteger(args.sinceSeq) && args.sinceSeq >= 0) {
-        baseline = args.sinceSeq
-      } else if (waitSegment) {
-        const segs = segmentsSince(sessionEvents(agent.session))
-        baseline = segs.length === 0 ? -1 : (segs[segs.length - 1]?.seq ?? -1)
-      } else {
-        let lastText = -1
-        for (const row of foldMessages(sessionEvents(agent.session))) {
-          if (row.text !== undefined) lastText = row.seq
-        }
-        baseline = lastText
-      }
+      // 默认 baseline = 调用时刻的日志最大 seq（即工具描述承诺的 "latest seq at call
+      // time"，两种 waitFor 模式统一）：只等待之后新出现的输出。既有回复不会被误当成
+      // 新输出，但也绝不会被吞掉 —— waitForReply 在零新输出时会回落它并置 stale:true。
+      // 调用方若要在"回复早已落地"之后再精确取回它，应传 send/create 返回的 sinceSeq 锚点。
+      const baseline = typeof args.sinceSeq === 'number' && Number.isInteger(args.sinceSeq) && args.sinceSeq >= -1
+        ? args.sinceSeq
+        : maxSeq(sessionEvents(agent.session))
       const result = await waitForReply({
         session: agent.session,
         baselineSeq: baseline,
         timeoutMs: clampTimeout(args.timeoutMs),
         signal: exec.signal,
         requireTurnEnd: args.requireTurnEnd === true,
-        ...(waitSegment ? { waitForSegment: true } : {}),
+        ...(args.waitFor === 'segment' ? { waitForSegment: true } : {}),
       })
       env.registry.touch(args.sessionId)
       return asJson({
         sessionId: args.sessionId,
+        sinceSeq: baseline,
         reply: renderWait(result),
         running: agent.status === 'running',
       })
@@ -961,7 +973,11 @@ function pruneReasoning(snapshot: BridgeStatusSnapshot, mode: StatusReasoning):
   return rest
 }
 
-/** 渲染监控快照为一行摘要：运行态 + openTurn + 卡住/待处理 + 最新回复(+ 思维链预览)。 */
+/**
+ * 渲染监控快照为一行摘要：运行态 + openTurn + 卡住/待处理 + 最新回复(+ 思维链预览)。
+ * 卡住判定走 core.isStalled（唯一真源）：只有 running 会话才可能被标 [STALLED] ——
+ * 空闲/已收尾的会话"很久没事件"是正常状态，不是卡住（与监控 watchdog 一致）。
+ */
 function renderStatus(snapshot: BridgeStatusSnapshot, stalledMsThreshold: number): string[] {
   const lines: string[] = []
   const runLabel = snapshot.running === 'running' ? 'running' : 'idle'
@@ -969,7 +985,7 @@ function renderStatus(snapshot: BridgeStatusSnapshot, stalledMsThreshold: number
   if (snapshot.openTurn) lines.push(`openTurn: yes (turn #${snapshot.lastTurn})`)
   else lines.push(`openTurn: no (last turn #${snapshot.lastTurn})`)
   if (snapshot.stalledMs !== null) {
-    const stalled = snapshot.stalledMs >= stalledMsThreshold
+    const stalled = isStalled(snapshot.running, snapshot.stalledMs, stalledMsThreshold)
     lines.push(`lastActivity: now-${snapshot.stalledMs}ms${stalled ? ' [STALLED]' : ''}`)
   }
   if (snapshot.pendingWork) lines.push(`pendingWork: ${snapshot.nextTurnCount} turn + ${snapshot.nextStepCount} step`)
@@ -984,10 +1000,10 @@ function renderStatus(snapshot: BridgeStatusSnapshot, stalledMsThreshold: number
 function registerStatus(env: BridgeEnv): void {
   env.ctx.tools.register(defineTool({
     name: 'session_bridge_status',
-    description: 'Inspect a session\'s live progress for monitoring/scheduling. Returns running/idle, whether a turn is open, last turn number, time since the last event (for stall detection), pending queued work, and the latest text reply. It also surfaces the session\'s chain-of-thought: lastReasoning is the most recent finalized reasoning block, liveReasoning is the in-flight reasoning streamed for the current handled turn (reasoning-delta), and reasoningTail is a compact merged preview. reasoning=none drops all three to keep tokens small. When stalledMsThreshold is given, marks the session as stalled when the time since the last event exceeds it. Pass sessionId of a live session (use session_bridge_find to locate; session_bridge_resume to bring an offline one online). Use this as the "observe" step of a monitor→decide→steer/cancel loop.',
+    description: 'Inspect a session\'s live progress for monitoring/scheduling. Returns running/idle, whether a turn is open, last turn number, time since the last event (for stall detection), pending queued work, and the latest text reply. It also surfaces the session\'s chain-of-thought: lastReasoning is the most recent finalized reasoning block, liveReasoning is the in-flight reasoning streamed for the current handled turn (reasoning-delta), and reasoningTail is a compact merged preview. reasoning=none drops all three to keep tokens small. When stalledMsThreshold is given, marks a RUNNING session as stalled once the time since the last event exceeds it (idle sessions are never flagged — a quiet finished session is not stuck). Pass sessionId of a live session (use session_bridge_find to locate; session_bridge_resume to bring an offline one online). Use this as the "observe" step of a monitor→decide→steer/cancel loop.',
     parameters: {
       sessionId: { type: 'string', required: true, description: 'Session id to inspect (must be live).' },
-      stalledMsThreshold: { type: 'number', description: 'Mark the session STALLED when time since the last event exceeds this many ms (default 60000).' },
+      stalledMsThreshold: { type: 'number', description: 'Mark a RUNNING session STALLED when time since the last event exceeds this many ms (default 60000); idle sessions are never marked.' },
       recent: { type: 'number', description: 'Number of recent messages to include in the snapshot (default 8, max 20).' },
       reasoning: { type: 'string', enum: ['none', 'last', 'live', 'tail'], description: 'Which chain-of-thought fields to include: tail (default) returns lastReasoning/liveReasoning/reasoningTail; last only the finalized reasoning; live only the in-flight reasoning; none drops all reasoning fields.' },
     },