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

package/README.md

@@ -16,18 +16,26 @@ action does.
   session (top-level UI session) in the current workspace, or in another
   workspace when you pass `workspaceId` / `cwd`. It can send one first prompt
   and optionally block until the first reply. Provider / model / reasoning
-  effort are inherited from the calling session by default.
+  effort are inherited from the calling session by default. An async create
+  (no `waitForReply`) returns a `sinceSeq` anchor for a later precise `wait`.
 - **Send messages to any session.** `session_bridge_send` appends a turn
   (`mode=queue`) or injects steering into the running step (`mode=steer`), and
-  can optionally wait for the next reply.
+  can optionally wait for the next reply. An async send also returns a
+  `sinceSeq` anchor.
 - **Wait for a reply or a segment.** `session_bridge_wait` blocks until new
-  assistant output appears after a given seq: `waitFor=reply` (default) returns
-  as soon as a new **text** reply is readable; `waitFor=segment` returns as
-  soon as any new **completed output step** appears (an `assistant/message` —
-  text, reasoning, or tool-call turn), *without* waiting for the whole turn, so
-  you can observe output paragraph by paragraph as it is produced. With
-  `requireTurnEnd` it additionally waits for the turn to settle.
-  Timeout / abort return the partial result rather than throwing.
+  assistant output appears after `sinceSeq` (default: the latest event seq at
+  call time): `waitFor=reply` (default) returns as soon as a new **text** reply
+  is readable; `waitFor=segment` returns as soon as any new **completed output
+  step** appears (an `assistant/message` — text, reasoning, or tool-call turn),
+  *without* waiting for the whole turn, so you can observe output paragraph by
+  paragraph as it is produced. With `requireTurnEnd` it additionally waits for
+  the turn to settle. Timeout / abort return the partial result rather than
+  throwing. **An already-landed reply is never lost**: when no new output
+  arrives within the budget, the latest PRE-EXISTING reply/segment is returned
+  with `stale: true` (no more `(no text)`). To retrieve exactly "the reply to
+  what I sent", pass the `sinceSeq` returned by `session_bridge_send` /
+  `session_bridge_create` (works regardless of caller latency); `sinceSeq: -1`
+  counts existing events too, i.e. the anchor for a brand-new session.
 - **Read any session.** `session_bridge_read` folds a session's event log into
   readable rows — live or offline (from persistence) — with `sinceSeq` paging,
   role filtering, and a `limit` (default 20, max 100).
@@ -44,7 +52,9 @@ action does.
   working directory. Bridge-registered titles act as aliases.
 - **Monitor and schedule a main task.** `session_bridge_status` reads a
   session's real-time progress (running/idle, open turn, time since the last
-  event for stall detection, pending work, latest reply). `session_bridge_cancel`
+  event for stall detection, pending work, latest reply); only a **running**
+  session is flagged `[STALLED]` (a quiet idle session is not stuck — same rule
+  as the watchdog). `session_bridge_cancel`
   stops a running session. `session_bridge_monitor_start` runs a **background
   watchdog loop** that polls the task, nudges it when it stalls, corrects it
   when it drifts, terminates it after it stays stuck, and wraps up when it
@@ -68,7 +78,9 @@ action does.
 | Making progress | Reset the stall counter (steady) |
 
 The watchdog only treats **running** sessions as stalled, so a finished or idle
-task is wrapped up rather than nudged forever. Logs go to
+task is wrapped up rather than nudged forever (the `[STALLED]` marker in
+`session_bridge_status` follows the same rule and is shown for running sessions
+only). Logs go to
 `~/.dsh/super-injector/dsh-session-bridge-monitor.log` (overridable).
 
 Control it with `session_bridge_monitor_start` / `_stop` / `_list`.
@@ -122,6 +134,9 @@ bash scripts/build.sh && npm run build:client
 # type-check src/ against the dsh that is actually installed (no checkout needed)
 npm run check:compat
 
+# regression tests for the wait/stall core logic (Node type stripping, no deps)
+npm test
+
 # via the injector toolchain
 dev_build_plugin dsh-session-bridge
 ```
@@ -248,14 +263,14 @@ registration and junction; not re-assembled on restart).
 
 | Tool | What it does |
 |---|---|
-| `session_bridge_create` | Create a main session (current or another workspace via `workspaceId` / `cwd`); optional first prompt + `waitForReply`. |
-| `session_bridge_send` | Send a message (`mode=queue`/`steer`); optional wait-for-reply. |
-| `session_bridge_wait` | Wait for new output after `sinceSeq`: `waitFor=reply` (text) or `waitFor=segment` (any completed step, no full-turn wait); optional `requireTurnEnd`. |
+| `session_bridge_create` | Create a main session (current or another workspace via `workspaceId` / `cwd`); optional first prompt + `waitForReply`; async creates return a `sinceSeq` anchor. |
+| `session_bridge_send` | Send a message (`mode=queue`/`steer`); optional wait-for-reply; async sends return a `sinceSeq` anchor. |
+| `session_bridge_wait` | Wait for new output after `sinceSeq` (default: latest seq at call time; `-1` counts existing events): `waitFor=reply` (text) or `waitFor=segment` (any completed step, no full-turn wait); optional `requireTurnEnd`; falls back to the pre-existing reply with `stale` when nothing new arrives. |
 | `session_bridge_read` | Read messages — live or offline; `sinceSeq` paging, `role` filter, `limit`. |
 | `session_bridge_segments` | Read completed output segments (each finished assistant step) incrementally by paragraph — live or offline. |
 | `session_bridge_resume` | Bring a persisted session back online (idempotent). |
 | `session_bridge_find` | Find sessions by title / id / workspace / directory across workspaces. |
-| `session_bridge_status` | Read a session's live progress (running, open turn, stall detection, pending work, latest reply) plus live/finalized chain-of-thought (`reasoning` param). |
+| `session_bridge_status` | Read a session's live progress (running, open turn, stall detection, pending work, latest reply) plus live/finalized chain-of-thought (`reasoning` param); `[STALLED]` is shown for running sessions only. |
 | `session_bridge_cancel` | Stop a running session (abort active turn; clear queued/steering work unless `keepInbox`). |
 | `session_bridge_monitor_start` | Start a background watchdog on a main session (poll, nudge, correct, cancel, wrap up); supports chain-of-thought `coRules` (e.g. reasoning not-contains "I'm" → cancel). |
 | `session_bridge_monitor_stop` | Stop a watchdog (keep the session itself running). |
@@ -264,7 +279,7 @@ registration and junction; not re-assembled on restart).
 | `session_bridge_archived` | List the archive set, optionally resolving titles. |
 
 All tools return lossless JSON; wait-style tools never throw on timeout — they
-return a `timedOut` / `aborted` flag.
+return a `timedOut` / `aborted` / `stale` flag.
 
 ## Project layout
 
@@ -277,6 +292,7 @@ src/
   registry.ts bridge-side title/workspace registry (~/.dsh/session-bridge-registry.json)
 scripts/
   build.sh    type-check + link types against the DSH checkout
+  test-bridge-core.mjs  wait/stall regression tests (npm test)
 ```
 
 ## Lifecycle and unloading

package/README.zh.md

@@ -11,14 +11,19 @@
 
 - **创建真实 DSH 会话。** `session_bridge_create` 在当前工作区创建新的主会话（顶层 UI 会话），
   传 `workspaceId` / `cwd` 则跨工作区；可选发送首条 prompt 并阻塞等待首条回复。provider / model /
-  reasoning effort 默认继承调用会话。
+  reasoning effort 默认继承调用会话。异步创建（不带 `waitForReply`）会返回 `sinceSeq` 锚点，
+  之后可用它精确地 `session_bridge_wait` 取回首条回复。
 - **向任意会话发消息。** `session_bridge_send` 追加一轮（`mode=queue`）或向运行中的步骤注入
-  steering（`mode=steer`），可选等待下一条回复。
-- **等待回复或段落。** `session_bridge_wait` 阻塞直至 `sinceSeq` 之后出现新的 assistant 输出：
-  `waitFor=reply`（默认）在有新的**文本**回复可读时立即返回；`waitFor=segment` 在任意新**已完成
-  输出步骤**出现时立即返回（一个 `assistant/message`——文本、推理或工具调用段），*无需*等整个
-  turn 结束，从而可以按段落逐段观察输出。开 `requireTurnEnd` 则同时等待回合收尾。
-  超时 / 中止返回部分结果，而非抛错。
+  steering（`mode=steer`），可选等待下一条回复；异步发送同样返回 `sinceSeq` 锚点。
+- **等待回复或段落。** `session_bridge_wait` 阻塞直至 `sinceSeq` 之后出现新的 assistant 输出
+  （默认 `sinceSeq` = 调用时刻的最新事件 seq）：`waitFor=reply`（默认）在有新的**文本**回复可读时
+  立即返回；`waitFor=segment` 在任意新**已完成输出步骤**出现时立即返回（一个 `assistant/message`
+  ——文本、推理或工具调用段），*无需*等整个 turn 结束，从而可以按段落逐段观察输出。开
+  `requireTurnEnd` 则同时等待回合收尾。超时 / 中止返回部分结果，而非抛错。
+  **回复早已落地也不会丢**：预算内没等到新输出时，会返回预算前就存在的最新回复/段落并置
+  `stale: true`（不会再出现 `(no text)`）。要精确取回"某次发送之后的回复"，把 `session_bridge_send` /
+  `session_bridge_create` 异步返回的 `sinceSeq` 作为锚点传进来即可（与调用方延迟无关）；
+  `sinceSeq: -1` 表示"连既有事件也算"，即新建会话的锚点。
 - **读取任意会话。** `session_bridge_read` 把会话事件日志折叠为可读行——live 或离线（持久化）均可；
   支持 `sinceSeq` 分页、role 过滤、`limit`（默认 20，最大 100）。
 - **按段落读取输出。** `session_bridge_segments` 返回会话的**已完成输出段落**——每个已完成的
@@ -29,7 +34,8 @@
 - **查找会话。** `session_bridge_find` 跨全部工作区按 标题 / id / workspace / 目录 匹配，返回
   live/running 状态、标题、工作目录；bridge 登记的标题作为别名参与匹配。
 - **监控并调度主任务。** `session_bridge_status` 读取会话实时进度（running/idle、是否 `openTurn`、
-  距最近事件毫秒数做卡住检测、待处理消息、最新回复）；`session_bridge_cancel` 停止一个运行中的会话；
+  距最近事件毫秒数做卡住检测、待处理消息、最新回复）；只有 **running** 会话才会被标 `[STALLED]`
+  （空闲会话没有进展是正常状态，与守护循环判定一致）。`session_bridge_cancel` 停止一个运行中的会话；
   `session_bridge_monitor_start` 运行一个**后台守护循环**，轮询任务、卡住时催办、偏离时纠偏、
   持续卡住则终止、完成即收尾。
 - **归档会话。** `session_bridge_archive` 把会话加入 DSH workspace 归档集合（从所有分组视图隐藏，
@@ -48,7 +54,8 @@
 | 连续卡住 ≥ `maxStuckCycles` | `cancel` 终止 |
 | 正常推进 | 重置卡住计数（steady） |
 
-守护只对 **running** 会话判定"卡住"，因此已完成/空闲的任务会被收尾而非无限催办。日志写入
+守护只对 **running** 会话判定"卡住"，因此已完成/空闲的任务会被收尾而非无限催办
+（`session_bridge_status` 的 `[STALLED]` 标注同理，只对 running 会话显示）。日志写入
 `~/.dsh/super-injector/dsh-session-bridge-monitor.log`（可用 `logFile` 覆盖）。
 
 用 `session_bridge_monitor_start` / `_stop` / `_list` 控制。
@@ -90,6 +97,9 @@ bash scripts/build.sh && npm run build:client
 # 针对"实际安装的 dsh"做类型检查（不需要 checkout）
 npm run check:compat
 
+# 核心 wait/卡住判定的回归测试（Node 类型擦除直跑 src/core.ts，零依赖）
+npm test
+
 # 或经注入器工具链
 dev_build_plugin dsh-session-bridge
 ```
@@ -194,14 +204,14 @@ dev_inject_plugin D:\code\dsh-session-bridge
 
 | 工具 | 作用 |
 |---|---|
-| `session_bridge_create` | 创建主会话（当前或其它工作区，经 `workspaceId` / `cwd`）；可选首条 prompt + `waitForReply`。 |
-| `session_bridge_send` | 发消息（`mode=queue`/`steer`）；可选等待回复。 |
-| `session_bridge_wait` | 等待 `sinceSeq` 之后新输出：`waitFor=reply`（文本）或 `waitFor=segment`（任一已完成步骤即返回，无需等整个 turn）；可选 `requireTurnEnd`。 |
+| `session_bridge_create` | 创建主会话（当前或其它工作区，经 `workspaceId` / `cwd`）；可选首条 prompt + `waitForReply`；异步时返回 `sinceSeq` 锚点。 |
+| `session_bridge_send` | 发消息（`mode=queue`/`steer`）；可选等待回复；异步时返回 `sinceSeq` 锚点。 |
+| `session_bridge_wait` | 等待 `sinceSeq` 之后新输出（默认 = 调用时刻最新 seq，`-1` = 从头发算）：`waitFor=reply`（文本）或 `waitFor=segment`（任一已完成步骤即返回，无需等整个 turn）；可选 `requireTurnEnd`；零新输出时回落既有回复并置 `stale`。 |
 | `session_bridge_read` | 读取消息 —— live 或离线；`sinceSeq` 分页、`role` 过滤、`limit`。 |
 | `session_bridge_segments` | 增量读取已完成输出段落（每个已完成的 assistant 步骤）—— live 或离线。 |
 | `session_bridge_resume` | 让持久化会话重新上线（幂等）。 |
 | `session_bridge_find` | 跨工作区按 标题 / id / workspace / 目录 查找会话。 |
-| `session_bridge_status` | 读取会话实时进度（running、openTurn、卡住检测、待处理、最新回复）及实时/已定型思维链（`reasoning` 参数）。 |
+| `session_bridge_status` | 读取会话实时进度（running、openTurn、卡住检测、待处理、最新回复）及实时/已定型思维链（`reasoning` 参数）；`[STALLED]` 仅对 running 会话显示。 |
 | `session_bridge_cancel` | 停止运行中的会话（中止活动 turn；`keepInbox` 保留排队/steering 输入）。 |
 | `session_bridge_monitor_start` | 对一个主会话启动后台守护（轮询、催办、纠偏、终止、收尾）；支持思维链 `coRules`（如 reasoning not-contains "I'm" → cancel）。 |
 | `session_bridge_monitor_stop` | 停止守护（会话本身不终止）。 |
@@ -209,7 +219,7 @@ dev_inject_plugin D:\code\dsh-session-bridge
 | `session_bridge_archive` | 归档会话（从分组隐藏；历史与位置保留）。 |
 | `session_bridge_archived` | 列出归档集合，可选解析标题。 |
 
-所有工具输出 lossless JSON；等待类工具超时不抛错，返回 `timedOut` / `aborted` 标记。
+所有工具输出 lossless JSON；等待类工具超时不抛错，返回 `timedOut` / `aborted` / `stale` 标记。
 
 ## 项目结构
 
@@ -222,6 +232,7 @@ src/
   registry.ts 桥侧标题/workspace 登记表（~/.dsh/session-bridge-registry.json）
 scripts/
   build.sh    类型检查 + 链接 DSH checkout 类型
+  test-bridge-core.mjs  wait/卡住判定回归测试（npm test）
 ```
 
 ## 生命周期与卸载

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-external/dsh-session-bridge",
-  "version": "0.3.2-alpha.2",
+  "version": "0.3.2-alpha.3",
   "main": "./lib/index.js",
   "description": "会话桥：创建主会话 / 向任意会话发消息 / 等待回复 / 读取消息 / 按名或 id 查找会话（支持跨工作区）；另含监控/调度主任务与归档会话。",
   "engines": {

package/lib/index.js

@@ -9535,8 +9535,11 @@ function sleep(ms) {
 * 因此默认不再用 turn/end 作门控；需要完整收尾语义时用 requireTurnEnd:true 显式开启，
 * 此时才会等到其后出现 turn/end。
 *
-* 返回时 message 为"最新的带文本 assistant 行"，否则为最新 assistant 行（可能无文本，
-* 如纯工具调用中间态）；超时/中止返回已收集内容。
+* 返回的 message：默认是 baseline 之后最新的一条**带文本** assistant 行；整个等待
+* 窗口内没有等到新文本回复时，回落为 baseline 及之前最新的一条带文本回复并置
+* stale:true（绝不把更晚的无文本中间行当回复返回 —— 那正是渲染层打印 "(no text)"
+* 的来源）。segment 模式同理：新段落优先，否则回落既有段落。
+* 超时/中止返回已收集内容；timedOut 表示"本次等待要求的输出未在预算内出现"。
 */
 async function waitForReply(opts) {
 	const started = Date.now();
@@ -9573,7 +9576,25 @@ async function waitForReply(opts) {
 		if (Date.now() >= deadline) break;
 		await sleep(100);
 	}
-	let message = waitForSegment && segment !== null ? {
+	const observedNew = waitForSegment ? segment !== null : textReply !== null;
+	const sawNewRow = latest !== null;
+	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;
+		}
+	}
+	const message = waitForSegment && segment !== null ? {
 		seq: segment.seq,
 		time: segment.time,
 		role: "assistant",
@@ -9581,16 +9602,34 @@ async function waitForReply(opts) {
 		...segment.text !== void 0 ? { text: segment.text } : {},
 		...segment.reasoning !== void 0 ? { 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,
+		timedOut: requireTurnEnd ? !(sawNewRow && turnEnded) : !observedNew,
+		stale,
 		aborted: opts.signal !== void 0 && opts.signal.aborted,
 		waitedMs: Date.now() - started
 	};
 }
+/** seq 及之前最新一个已完成输出段落（wait 零新输出时回落既有段落）。 */
+function lastSegmentUpTo(events, seq) {
+	const segs = segmentsSince(events);
+	for (let i = segs.length - 1; i >= 0; i -= 1) {
+		const seg = segs[i];
+		if (seg !== void 0 && seg.seq <= seq) return seg;
+	}
+	return null;
+}
+/** seq 及之前最新一条带文本的 assistant 行（wait 零新文本回复时回落既有回复）。 */
+function lastTextRowUpTo(rows, seq) {
+	for (let i = rows.length - 1; i >= 0; i -= 1) {
+		const row = rows[i];
+		if (row !== void 0 && row.role === "assistant" && row.text !== void 0 && row.seq <= seq) return row;
+	}
+	return null;
+}
 /**
 * 解析目标工作目录：workspaceId（注册表）> cwd（绝对路径/任意拼写）> 调用者会话 cwd。
 * 跨工作区由 workspaceId / cwd 任意指定实现。
@@ -9642,6 +9681,14 @@ async function attachSessionToWorkspace(ctx, sessionId, cwd) {
 	return workspace.id;
 }
 /**
+* 卡住判定（唯一真源，status 渲染与监控 watchdog 共用）：只有 **running** 会话才可能
+* "卡住" —— 空闲/已收尾的会话没有进展是正常状态，不能报 stall。阈值语义为"超过"
+* （严格大于），与工具描述/README 的 "more than stalledMs" 一致。
+*/
+function isStalled(running, stalledMs, thresholdMs) {
+	return running === "running" && stalledMs !== null && stalledMs > thresholdMs;
+}
+/**
 * 计算一个 live 会话的监控快照（agent 状态 + 事件折叠出的进度/卡住事实）。
 * 纯读，无副作用。用于 `session_bridge_status`。
 */
@@ -9861,7 +9908,7 @@ var SessionMonitor = class {
 			this.stopWithLog(sessionId);
 			return;
 		}
-		if (snapshot.running === "running" && snapshot.stalledMs !== null && snapshot.stalledMs > (entry.config.stalledMs ?? 6e4)) {
+		if (isStalled(snapshot.running, snapshot.stalledMs, entry.config.stalledMs ?? 6e4)) {
 			entry.stuckCount += 1;
 			entry.lastActionAt = Date.now();
 			if (this.shouldCancel(entry)) {
@@ -14141,6 +14188,14 @@ function liveAgent(env, sessionId) {
 function liveAgents(env) {
 	return env.ctx.agents.list();
 }
+/** 等待结果里的状态附注行（wait / send / create 三处渲染共用）。 */
+function waitNotes(reply) {
+	const notes = [];
+	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) {
 	const row = wait.message;
@@ -14156,6 +14211,7 @@ function renderWait(wait) {
 		seq: wait.seq,
 		turnEnded: wait.turnEnded,
 		timedOut: wait.timedOut,
+		...wait.stale === true ? { stale: true } : {},
 		aborted: wait.aborted,
 		waitedMs: wait.waitedMs
 	};
@@ -14227,9 +14283,10 @@ function registerCreate(env) {
 				if (typeof v.cwd === "string") lines.push(`cwd: ${v.cwd}`);
 				if (typeof v.title === "string") lines.push(`title: ${v.title}`);
 				const reply = v.reply;
+				if (typeof v.sinceSeq === "number") lines.push(`sinceSeq: ${String(v.sinceSeq)} (pass to session_bridge_wait)`);
 				if (reply !== void 0) {
 					lines.push(`reply: ${String(reply.message?.text ?? "(no text)")}`);
-					if (reply.timedOut === true) lines.push("[wait timed out]");
+					lines.push(...waitNotes(reply));
 				}
 				return [{
 					type: "text",
@@ -14296,8 +14353,10 @@ function registerCreate(env) {
 				source: "create"
 			});
 			let reply;
+			let createBaseline;
 			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) reply = await maybeWait(env, agent.session, baseline, args, exec.signal);
@@ -14307,6 +14366,7 @@ function registerCreate(env) {
 				cwd: targetCwd,
 				...workspaceId === void 0 ? {} : { workspaceId },
 				...typeof args.title === "string" && args.title.trim() !== "" ? { title: args.title.trim() } : {},
+				...reply === void 0 && createBaseline !== void 0 ? { sinceSeq: createBaseline } : {},
 				...reply === void 0 ? {} : { reply }
 			});
 		}
@@ -14350,9 +14410,10 @@ function registerSend(env) {
 				const v = value;
 				const reply = v.reply;
 				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 !== void 0) {
 					lines.push("reply: " + String(reply.message?.text ?? "(no text)"));
-					if (reply.timedOut === true) lines.push("[wait timed out]");
+					lines.push(...waitNotes(reply));
 				}
 				return [{
 					type: "text",
@@ -14378,7 +14439,7 @@ function registerSend(env) {
 			return asJson({
 				accepted: true,
 				sessionId: args.sessionId,
-				...reply === void 0 ? {} : { reply }
+				...reply === void 0 ? { sinceSeq: baseline } : { reply }
 			});
 		}
 	}));
@@ -14473,7 +14534,7 @@ function registerResume(env) {
 function registerWait(env) {
 	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",
@@ -14482,7 +14543,7 @@ function registerWait(env) {
 			},
 			sinceSeq: {
 				type: "number",
-				description: "Only replies after this event seq count (default: latest seq at call time)."
+				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",
@@ -14510,10 +14571,9 @@ function registerWait(env) {
 					text: "no reply observed"
 				}];
 				const message = reply.message;
-				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",
 					text: lines.join("\n")
@@ -14524,28 +14584,19 @@ function registerWait(env) {
 			if (typeof args.sessionId !== "string" || args.sessionId.trim() === "") throw new Error("invalid sessionId: expected a non-empty string");
 			const agent = liveAgent(env, args.sessionId);
 			if (agent === void 0) throw new Error("session " + JSON.stringify(args.sessionId) + " is not live — call session_bridge_resume first (waiting requires a live session)");
-			const waitSegment = args.waitFor === "segment";
-			let baseline;
-			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 !== void 0) lastText = row.seq;
-				baseline = lastText;
-			}
+			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"
 			});
@@ -15151,7 +15202,11 @@ function pruneReasoning(snapshot, mode) {
 	else delete rest.lastReasoning;
 	return rest;
 }
-/** 渲染监控快照为一行摘要：运行态 + openTurn + 卡住/待处理 + 最新回复(+ 思维链预览)。 */
+/**
+* 渲染监控快照为一行摘要：运行态 + openTurn + 卡住/待处理 + 最新回复(+ 思维链预览)。
+* 卡住判定走 core.isStalled（唯一真源）：只有 running 会话才可能被标 [STALLED] ——
+* 空闲/已收尾的会话"很久没事件"是正常状态，不是卡住（与监控 watchdog 一致）。
+*/
 function renderStatus(snapshot, stalledMsThreshold) {
 	const lines = [];
 	const runLabel = snapshot.running === "running" ? "running" : "idle";
@@ -15159,7 +15214,7 @@ function renderStatus(snapshot, stalledMsThreshold) {
 	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`);
@@ -15173,7 +15228,7 @@ function renderStatus(snapshot, stalledMsThreshold) {
 function registerStatus(env) {
 	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",
@@ -15182,7 +15237,7 @@ function registerStatus(env) {
 			},
 			stalledMsThreshold: {
 				type: "number",
-				description: "Mark the session STALLED when time since the last event exceeds this many ms (default 60000)."
+				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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-bridge",
-  "version": "0.3.2-alpha.2",
+  "version": "0.3.2-alpha.3",
   "description": "会话桥（dsh-session-bridge）：通过提示词创建新的主会话（顶层 UI 会话）、向任意会话发送消息、等待会话的下一条回复、读取会话消息，并按会话名或 id 跨工作区查找会话；此外支持监控/调度主任务与归档会话。",
   "private": false,
   "type": "module",
@@ -83,6 +83,7 @@
     "build": "bash scripts/build.sh",
     "build:client": "tsdown",
     "check:compat": "node scripts/check-dsh-compat.mjs",
+    "test": "node --experimental-strip-types scripts/test-bridge-core.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/scripts/check-dsh-compat.mjs

@@ -79,6 +79,13 @@ function resolveScopeDir(argv) {
     }
   } catch { /* dsh not on PATH; the other anchors decide */ }
 
+  // Anchor 3 (last resort): this repository's own install. CI pins the
+  // @deepseek-ai packages through pnpm overrides and installs no DSH app, so
+  // the scope only exists here; probing it keeps check:compat runnable in CI.
+  // A developer machine resolves one of the anchors above first, so the
+  // *running* harness keeps priority there.
+  candidates.push(join(ROOT, 'node_modules', '@deepseek-ai'))
+
   for (const candidate of candidates) if (isScopeDir(candidate)) return candidate
   return undefined
 }
@@ -115,6 +122,13 @@ function dshVersionOf(scopeDir) {
     const manifest = readJson(candidate)
     if (manifest?.name === '@deepseek-ai/dsh' && typeof manifest.version === 'string') return manifest.version
   }
+  // Repo-local install (CI overrides): there is no `dsh` app package, but the
+  // release versions every dsh-* package together, so any of them names the
+  // harness version the types and the bundle were resolved from.
+  for (const pkg of ['dsh-tools', 'dsh-session', 'dsh-agent']) {
+    const manifest = readJson(join(scopeDir, pkg, 'package.json'))
+    if (typeof manifest?.version === 'string') return manifest.version
+  }
   return undefined
 }
 
@@ -142,8 +156,11 @@ function artifactProvenance() {
     // Source checkout: <root>/packages/... or <root>/vendor/... (relative to the map in lib/).
     const checkout = source.match(/^(.*?)[/\\](?:packages|vendor)[/\\]/)
     if (checkout !== null) { roots.add(resolve(ROOT, 'lib', checkout[1])); continue }
-    // Registry install: .../.pnpm/@deepseek-ai+<name>@<version>[_hash]/node_modules/...
-    const registry = source.match(/[\\/]\.pnpm[\\/]@deepseek-ai\+[a-z0-9-]+@([^\\/]+)[\\/]node_modules/)
+    // Registry install: .../.pnpm/@deepseek-ai+dsh-<name>@<version>[_hash]/node_modules/...
+    // Only dsh-* packages name the harness release; sibling @deepseek-ai
+    // packages (cordis, schemastery) are versioned independently, so counting
+    // them would make every CI build look like a provenance mismatch.
+    const registry = source.match(/[\\/]\.pnpm[\\/]@deepseek-ai\+dsh-[a-z0-9-]+@([^\\/]+)[\\/]node_modules/)
     if (registry !== null) {
       const version = registry[1].replace(/_.*$/, '')
       if (/^\d/.test(version)) versions.add(version)

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
 }
@@ -429,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()
@@ -466,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
@@ -550,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.' },
     },