v0.3.3

TeamFlow v0.3.3

发布日期：2026-11-01。变更清单按 release-npm-package 铁律 1 由 git log v0.3.2..HEAD 生成
（28 笔提交 / 27 个文件 / +1930 −526；该区间另含依赖/CI 合并与本次发版提交），不凭会话记忆。
⚠️ 本版含一处行为变更（子代理续跑等待判据）与一处 engines 变更（宿主下限抬到 0.2.1-rc.5）。
逐笔归属与真机取证见 docs/devlog.md 的 v0.3.3 批次。本文件面向使用者；内部流水不在正文里。

中文

⬆️ 升级要点

• engines 有变：宿主 dsh 下限由 0.2.1-alpha.2 抬到 0.2.1-rc.5（上界仍 <0.3.0）；Node ≥ 22.18。
  升完重启 dsh --profile web（桌面版重启应用）——修复都在宿主侧，不重启不生效。
• 一处行为变更：子代理续跑的等待由「固定 25 分钟墙钟」改为「有进展就续等」。此前一个正常跑长任务的
  子代理（写测试 + 反复跑构建）会被旧逻辑在 25 分钟处误判失败，而它实际仍在推进、最终成功。
• 无 teamflow_* 工具 schema / journal / 任务夹契约改动，不需要迁移。

① 长任务不再被墙钟误杀（修复）

现象：人工 resume 复活的子代理这一轮正常跑了很久，插件在固定 25 分钟到顶时判「没拿到正文」失败；卡片
还显示首次尝试的时长（几分钟），看起来像「早就失败的弃子」，实际它仍在正常干活。

根因：续跑等待是固定墙钟，到顶即放弃，不看是否还在推进；且判失败时不更新该阶段记录，结束时间停在首次运行。

修复：放弃判据改为「无新事件、无产物变更持续 10 分钟才放手」（天花板 2 小时）；判失败时落真实结束时刻。

② 续跑与重试复用同一个子代理（省 token）

现象：每次重试都新起子代理，对上一轮一无所知，从零重读 PRD/技术方案/源码，单阶段可烧掉千万级 token。

修复：重试与中断后的 resume 都在原 child 里继续；指令投递成功后绝不回落新起——两个子代理会并发改同一批
文件，宁可本轮按失败收场转人工。

③ 切模型即时到达子代理

现象：界面切成别的模型后，子代理仍打旧（已不可用/被限流）的模型。

根因：只读父会话「上一次实际请求」的配置，而它只在父代理真正发请求后才刷新 ⇒ 切模型后是陈旧快照。

修复：优先读「待生效选择」；旧模型确属外部不可用且用户已切模型时，改道新起子代理吃新路由。

④ 开发阶段的边界守卫（修复）

越界发现落成「收口任务」；依赖成环改为串行化（读者不再与写者同波）；技术方案钉死的数值常量被改动直接停
（不等验收）；本轮有失败就不再起收口任务（失败态下 spawn 起不来，白烧两次尝试）。

⑤ QA 回环在 resume 后不再失效（修复）

QA 打回轮次改为跨 resume 累计（续跑后曾有界闭环整个失效）；超限日志不再谎称「跳过产品验收」；长命令挂住时
给出可见提醒 + QA 命令纪律（一条命令只做一件事、带超时）。

⑥ 供应链加固 + 宿主下限锚定

CI 的 action 钉 commit SHA、引入 dependabot 分组、进程调用改 execFileSync（去掉 shell 字符串）；
engines.dsh 下限抬到 0.2.1-rc.5。

English

⬆️ Upgrade notes

• engines changed: the host dsh floor is raised from 0.2.1-alpha.2 to 0.2.1-rc.5 (upper bound
  still <0.3.0); Node ≥ 22.18. Restart dsh --profile web (or the desktop app) after upgrading — all
  fixes live host-side and do not take effect until restart.
• One behavior change: the sub-agent continuation wait changes from a fixed 25-minute wall clock to
  "keep waiting as long as there is progress". A sub-agent legitimately working on a long task (writing
  tests, re-running builds) used to be marked failed at the 25-minute mark while it was still making
  progress and would eventually succeed.
• No teamflow_* tool schema / journal / task-folder contract changes — no migration needed.

① Long-running sub-agents no longer killed by the wall clock (fix)

Symptom: A resumed sub-agent that legitimately ran long was declared failed at the fixed 25-minute mark
("no reply text"), and the card showed the first attempt's duration (a few minutes), looking like an
abandoned task — while it was still working and finally went green.

Root cause: The continuation wait was a fixed wall clock that gave up regardless of progress; and on
failure the stage record was not updated, leaving its end time at the first run.

Fix: Give up only after 10 minutes with no new event and no artifact change (cap raised to 2 hours);
on failure, record the real end time.

② Retry and resume reuse the same sub-agent (token savings)

Symptom: Every retry spawned a fresh sub-agent that knew nothing about the previous round and re-read
PRD / design / source from scratch — a single stage could burn millions of tokens.

Fix: Retries and post-interrupt resumes continue in the original child; once an instruction is
delivered we never fall back to a new child — two agents editing the same files is worse than failing,
so we stop and hand off to a human instead.

③ Model switch reaches sub-agents immediately

Symptom: After switching models in the UI, sub-agents still hit the old (unavailable / rate-limited) one.

Root cause: The route was read from the parent's "last actual request" config, which only refreshes after
the parent itself issues a request — a stale snapshot right after a switch.

Fix: Prefer the parent's pending selection; reroute to a fresh child (with the new route) only when
the old model is externally unavailable and the user has actually switched.

④ Boundary guards in the dev stage (fix)

Out-of-scope discoveries become a serial "cleanup task"; dependency cycles are serialized instead of dropped
(no reader running alongside a writer); a numeric constant pinned by the tech design, if changed, stops the
run immediately (no waiting for acceptance); a failed round no longer spawns the cleanup task (spawning fails
in a failed state, burning two attempts).

⑤ QA rework loop survives resume (fix)

QA rework rounds now accumulate across resume (the bounded loop previously collapsed after a resume);
the over-limit log no longer falsely claims "product acceptance skipped"; a hung long command emits a visible
reminder plus QA command discipline (one command per call, with timeouts).

⑥ Supply-chain hardening + host floor anchored

CI actions pinned to commit SHAs, dependabot groups added, process invocations switched to execFileSync
(no shell strings); engines.dsh floor raised to 0.2.1-rc.5.