[latekvo]

Closes #1005

With minStableMs: 0, await-screen-idle settles on the first non-empty tree read, but its prose (tool description, param description, settled doc, tools.mdx row, argent-device-interact skill) said the content had held still. The wording now holds for 0 too: 0 confirms content, not stillness. settled=false also names an unreadable tree as a cause, not only the timeout. Prose only; behavior is unchanged.

Docs: the await-screen-idle row in reference/tools.mdx.

Verification

Scratch vitest (not committed) running the real tool.execute against a fake AX service. Its assertions check the prose, so "failed" below means the prose contradicted the observed result. Behavior is identical on both sides.

minStableMs: 0, one content read:

before: RESULT {"settled":true,"waitedMs":7,"polls":1}
        PARAM_DESC The screen must hold the same content for at least this long to count as settled (default 250).
after:  PARAM_DESC ... (default 250); 0 settles on the first non-empty read, confirming content, not stillness.

Dead tree source (every AX read throws), static screen:

RESULT {"settled":false,"waitedMs":401,"polls":9}
before: settled=false means that did not happen before the timeout.                                      -> 1 failed
after:  settled=false means that was not seen before the timeout, which includes a tree that could not be read.  -> 1 passed

Checks: npx tsc --build exit 0; tool-server vitest 229/229 across await-screen-idle, await-harmony, ios-device-backgrounded-observation, interaction-messages, tool-input-schema-contract, tool-description-external-devices, skill-index-capabilities, harmony-flag-tool-text; prettier and eslint clean on touched files; npx docusaurus build OK; SpiderShield gate passes at 9.07 (threshold 9.0), though it does not score this tool (#683).

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[latekvo]

[Diplomat, Opus 5.5]: Two prose inaccuracies found in a review pass; both are in the wording this PR rewrites.

[latekvo]

[Diplomat, Opus 5.5]: Re-checked the wording at edc3bef against execute() and pollDescribeTree. I ran the real tool.execute on mocked tree sources for: every read throwing, a read that outruns timeoutMs, a read straddling the deadline, empty trees between identical reads, a stale HarmonyOS tree, abort, and the minStableMs/pollIntervalMs/timeoutMs boundaries. Each result matched the new text. Local tsc --build, eslint, prettier, the tool-server suites (329 tests), the installer skill suites and docusaurus build all pass.

Two problems sit outside this diff:

• minStableMs >= timeoutMs can never settle and is reported as an unsettled screen. Filed as #1691.
• A settled: false caused by an unreadable tree carries no cause on the result. This is already tracked by #1011 and addressed in #967.

[latekvo]

Folded into #1753 as ded85e0, to review together with the other capture fixes.