[HugoXK]

Fixes #1521
Owner: Chief
Reviewer: Reviewer
Written-by: Dev-2

Base: 92a6aab
Tip: 97f8705 (the fork head; its tree is a1b46c24e29d70062a9b7eaeaa1b12435a271744, the tree every number below was measured on, through local commit d89d10ee)
Tree: a1b46c24e29d70062a9b7eaeaa1b12435a271744

What was wrong

Five stage controls in the Workflow sidebar called the host with only a .then: a graph commit, Reset, Pause, Resume and Stop. plugins/workflow/client.js at 92a6aabd0e has 10 .then( and 0 .catch(, and the client call() (core/src/client/api.js) throws on a network error, an HTTP error or an {ok:false} answer and has no default timeout. So a click whose call threw, rejected, or never answered left the UI exactly as it was: no alert, no message, an unhandledRejection in the console, and the user believing the run had been reset or stopped when it had not. The value?.ok === false branch inside each then could not see any of that.

Sites on 92a6aabd0e: :1286 Stage onCommit (graph save), :1295 onReset, :1299 onPause, :1302 onResume, :1305 onStop.

What changed

One helper, settledCall(call, name, body, fallback, timeoutMs), wraps each of the five calls: a synchronous throw, a rejection, a null/undefined answer, an { ok: false, error } answer and a host silent for 10 s all settle as one { ok: false, error }, and the answer is ignored once settled. Its shape is copied from readWorkflows() + workflowCallError() in core/src/client/workflows.js (not refactored out of it).

Each of the five controls then reports a failure in the section's existing .wf-err alert (role="alert", the message the call threw, else a per-control fallback), and a success sets the alert to empty so a stale one does not outlive the failure it described:

control	call	fallback
graph save (onCommit)	workflow/graph	Could not save this workflow
Reset	workflow/reset	Could not reset this workflow
Pause	workflow/pause	Could not pause this run
Resume	workflow/resume	Could not resume this run
Stop	workflow/reset (with runId, as today)	Could not stop this run

Five new UI strings have ZH entries. The success path is otherwise unchanged: the same setPack(value) runs on the same answers, no new endpoint, no schema, credential or permission change, stageMessages() and the scrolling effect are untouched, and core/ and patches/ are absent from this diff.

Scope note: none of :1095 (the ingest effect's refresh()), :1315 (CreateModal onTemplate) and the six await call( sites (refresh, rename, delete, assign ×2, create) is part of this fix; they are tracked for a separate change.

Tests

plugins/workflow/test/client.test.js, through the existing mount() and stub style, no new dependency. Five new tests:

• a failed stage graph save is reported, not swallowed
• a failed stage reset is reported instead of leaving the button dead
• a failed pause or stop from the run strip is reported
• a failed resume from the run strip is reported
• a stage control that never answers settles as an error

Red first, on base 92a6aabd0e with the product code reverted and only the new tests added: npm --prefix plugins/workflow test — 34 tests, 29 pass, 5 fail, exactly those five. The four refusing cases fail as failureType: unhandledRejection with 'The workflow store refused the write', 'The reset was refused', 'The pause was refused', 'The resume was refused'; the timeout case fails with TypeError: client.settledCall is not a function.

Green at this tree: client 34 tests, 34 pass, 0 fail; the whole workflow suite 95 tests, 95 pass (base 90).

Each test also asserts there is no unhandledRejection (process.on('unhandledRejection') around the click) and that the alert carries the thrown message — the red run is the assertion that the failure is visible, not only the crash.

Files

4 files changed, 184 insertions(+), 7 deletions(-)
 changelog.d/1521.fixed.md            |   1 +
 docs/subsystems/workflow.md          |   2 +-
 plugins/workflow/client.js           |  71 ++++++++++++++++++++++++----
 plugins/workflow/test/client.test.js | 117 +++++++++++++++++++++++++++++++++++

The doc sentence is the arch-docs gate: plugins/workflow/ is owned by docs/subsystems/workflow.md, so the stage's failure behavior is written on that page's client.js row rather than waived.

Verification at the tip

All numbers were measured on this pull request's tree a1b46c24… (pushed head 97f87053, local commit d89d10ee — one tree):

• TZ=UTC ARCH_DOCS_BASE=92a6aabd0e npm run verify — exit 0: core 1853/1853, social 527, tree 125, timeline 125, workflow 95, .github 548, interop 37, live-e2e 24; oxlint 0 errors (only the repository's existing warnings; none from plugins/workflow/client.js or the new tests).
• arch-docs: OK (4 changed file(s)) against ARCH_DOCS_BASE=92a6aabd0e (= live main at the time of this push).
• node .github/scripts/changelog.mjs check — changelog: 48 fragment(s) in changelog.d/ are well formed.

Not run: no live instance (no instance access), no browser beyond the test harness, CI not waited on.

Overlap with #1505

Zero overlap. #1505 changes the settings page's three calls (workflow/state, workflow/graph on the settings canvas, workflow/set-model, lines :829/:849/:894); this changes the five stage controls. The only shared code is the settledCall helper, which each branch defines its own copy of from the same base 92a6aabd0e — first merge keeps it, the later one drops the duplicate while rebasing.

Checkpoint

{
  "pr": 1522,
  "claim": "Chief",
  "issue": 1521,
  "summary": "Five Workflow stage controls (graph save, Reset, Pause, Resume, Stop) called the host with a bare .then, so a throw, a rejection or a host that never answers left the button dead with no message. Each of the five now settles through one helper that turns every outcome into a single error string shown in the stage's .wf-err alert, and a host silent for 10 s is reported as a failure. A successful call clears the alert. The success path, stageMessages() and core/ are untouched, and the settings page calls stay with #1505.",
  "files": [
    "plugins/workflow/client.js",
    "plugins/workflow/test/client.test.js",
    "docs/subsystems/workflow.md",
    "changelog.d/1521.fixed.md"
  ],
  "checks": {
    "ran": "TZ=UTC ARCH_DOCS_BASE=92a6aabd0e npm run verify at tree a1b46c24 (exit 0: core 1853, workflow 95), red-first on base 92a6aabd0e (34 tests, 29 pass, 5 fail), changelog check",
    "result": "green",
    "at": "97f8705310fbbff4c170766a1b5187ae63c20f75"
  },
  "next": "none — ready for review"
}

[HugoXK]

@Birfy tests-ok is green at 97f8705310fb and this PR has no review yet. Could you review this tip?

[Birfy]

Verdict: PASS at 97f8705
Written-by: Reviewer
Attestation: 97f8705 role=Reviewer

Ran at this tip (2026-10-28T06:04Z):

$ cd plugins/workflow && TZ=UTC node --test test/client.test.js        # tip 97f87053, tarball from the API
# tests 34
# pass 34
# fail 0

$ cd plugins/workflow && TZ=UTC node --test "test/*.test.js"           # tip 97f87053
# tests 95
# pass 95
# fail 0

$ # red knife: the same tip tree, plugins/workflow/client.js put back to the base 92a6aabd blob, the new tests kept
not ok 52 - a failed stage graph save is reported, not swallowed
  failureType: 'unhandledRejection', error: 'The workflow store refused the write'
not ok 53 - a failed stage reset is reported instead of leaving the button dead
  failureType: 'unhandledRejection', error: 'The reset was refused'
not ok 54 - a failed pause or stop from the run strip is reported
  failureType: 'unhandledRejection', error: 'The pause was refused'
not ok 55 - a failed resume from the run strip is reported
  failureType: 'unhandledRejection', error: 'The resume was refused'
not ok 56 - a stage control that never answers settles as an error
  failureType: 'testCodeFailure', error: 'client.settledCall is not a function'
# tests 95
# pass 90
# fail 5

$ cd plugins/workflow && TZ=UTC node --test "test/*.test.js"           # base 92a6aabd tree, unmodified
# tests 90
# pass 90
# fail 0

$ node --check plugins/workflow/client.js && node --check plugins/workflow/test/client.test.js
exit 0

$ node scripts/ds-bot-patches.mjs check
skipped pin (no git): the tree hash cannot be computed here
ok   10 patches apply cleanly in order
ok   core/ equals ds-bot/ + patches/ds-bot/

$ TZ=UTC node .github/scripts/changelog.mjs check
changelog: 48 fragment(s) in changelog.d/ are well formed

$ # body read live: Tip: 97f8705310…f75 == head; checkpoint parsed by enqueue-rules.mjs → 1143 chars, 0 reasons

审查要点：

• tip 与正文对得上：head 97f87053 = 正文 Tip:，父提交 = base 92a6aabd；compare 92a6aabd...97f87053 恰好 4 文件 +184/−7，Fixes #1521 在第一行。该 tip 上没有任何评论或 review，14 条 check-run 全 completed，唯一红的 enqueue-guard 只写 no Verifier report names the tip 97f8705310fb —— 就是这条 PASS 补的缺口；正文 Owner: Chief / Reviewer: Reviewer / Written-by: Dev-2 与 checkpoint 的 pr/claim/issue/files/checks.at 已对齐，块长 1143 < 1500，claimed Reviewer: 是 writers 名且 Birfy 在 reviewers 里。
• 红先成立（自己复跑，不引正文数字）：把 plugins/workflow/client.js 换回 base 92a6aabd 的 blob、只留新测试，node --test 的 95 条里 90 绿 5 红，红的正是那五条：四条控制用例以 unhandledRejection 带正文所称的消息失败，超时用例以 client.settledCall is not a function 失败；换回 tip 的 client.js 同命令 95/95，client.test.js 单文件 34/34，base 整树 90/90 —— 与正文 34/29/5、34/34、95、base 90 的每个数字都对得上。新用例同时断言没有 unhandledRejection 且告警带出抛出的消息，不是空断言。
• 实现是对的：settledCall 把同步 throw、rejection、null/undefined 答案、{ok:false} 和 10 s 静默统一成 {ok:false,error}；settled 标志丢弃晚到的答案，pending 上挂着 .catch，所以超时后原来的 rejection 不会再变成 unhandledRejection；五个站点把失败写进既有 .wf-err[role="alert"]，成功清空旧错误。payload 与 base 一致（Stop 仍走 workflow/reset + runId），setPack 路径未动，stageMessages()/滚动未碰。
• 范围与文档：4 文件只在 plugins/workflow、docs/subsystems/workflow.md、changelog.d/；未碰 core/、patches/、生成的 core/client.js。plugins/workflow/client.js 的 owned path 那行补了失败行为说明，changelog.d/1521.fixed.md 合法，ds-bot-patches check 与 changelog check 都绿。base 落后 main 9af16ae0 13 个提交，但 main 只改到 Settings 画布/其它端点，这五个站点在 main 上仍是无 catch 的 .then，mergeable=true，合并树由队列重测。
• 边界，记录但不阻断：五个中文文案写进了 tr 映射（client.js:110–114），但 fallback 以裸字符串传给 settledCall（client.js:1326/1333/1337/1343/1349），渲染处直接输出 error，所以超时/空答案路径在中文界面仍显示英文；既有 'The workflow host did not answer' 是同一种写法，建议下一次把它们包成 tr('…')（五处一行）。另：#1505 若先合，两边同名 settledCall 需要后者重基时删掉重复定义，正文 “Overlap with fix(workflow): report a failed host call on the settings page #1505” 已写明。
• 未跑：整仓 npm run verify（本机没有 node_modules/oxlint/esbuild，跑不全）与浏览器像素级复核（无浏览器）；这两块由 tip 上绿的 tests-ok（含 plugins (workflow)、package）覆盖。正文没有独立的 Risk 栏，风险面在 “Overlap with fix(workflow): report a failed host call on the settings page #1505” 和 Scope note 里交代——不是门禁字段，一并记录。