[Birfy]

Written-by: Dev

Fixes #733.

Tip SHA: b1f01e4

Reproduce

list_children answers load for every child and, for a child with an open turn, openForMs and stalled (#624, #696). Its description named only (id, name, role), so a model — which reads the description, not the implementation — never learned that the answer says who is busy, how long a turn has been open, or that stalled exists. docs/subsystems/tree.md already documented the fields; the agent-facing surface was the only part behind.

What changed

• plugins/tree/src/tools.js: the list_children description now names load for every child and openForMs/stalled for a child with an open turn, says what stalled means ("true once that turn has been open past the stall threshold"), and tells the coordinator to send new work to an idle child first. The fields are described as conditional because the tool only adds them for an open turn, so the description promises nothing an idle child does not return.
• plugins/tree/test/tree.test.js: one case (#733: list_children describes the load fields it returns) asserts the description contains load, openForMs and stalled, that stalled is tied to the threshold, and that the answer still carries the fields for a busy child and omits them for an idle one.
• docs/subsystems/tree.md: the list_children paragraph says the description names those fields too.
• changelog.d/733-list-children-fields.changed.md: the fragment.

Nothing the tool computes or returns changed, and no core file is touched.

What I ran

From a full checkout at main d5fefe01 with this branch's files in place, DSH_HARNESS=/opt/flybot:

$ cd plugins/tree && TZ=UTC DSH_HARNESS=/opt/flybot node --import ./test/resolve.mjs --test "test/*.test.js"
# tests 104
# pass 104
# fail 0
$ node scripts/lint-plugins.mjs
Found 1 warning and 0 errors.
lint-plugins: packed @flybot/tree imported
$ node .github/scripts/changelog.mjs check
changelog: 32 fragment(s) in changelog.d/ are well formed

The 103 pre-existing tree cases stay green; the one warning is the pre-existing mock-flybot.js for…of note, not in a file this PR changes.

Red without the source change

Restore the old description (List your direct child bots (id, name, role).…) in plugins/tree/src/tools.js:

$ TZ=UTC DSH_HARNESS=/opt/flybot node --import ./test/resolve.mjs --test test/tree.test.js
# tests 88
# pass 87
# fail 1
not ok 78 - #733: list_children describes the load fields it returns

The case fails on the missing openForMs (the first absent field after load). Restoring the new description returns it to 88/88.

Not run

• Root npm run verify and the core suite: this box has no core/ sources, so the plugin suite ran against an assembled checkout and the rest is left to CI.
• arch-docs: it reads the branch's commits through git, which is not available here; docs/subsystems/tree.md — the doc that owns plugins/tree/ — changes in the same PR.
• A live model reading the description: the wording is pinned by the test, not by a Bot routing session.

Risk

T2 by the repository's own rules (plugins/tree/**), so it needs a PASS at the tip. The change is a description string, one test, one docs sentence and one fragment; nothing is computed differently and no configuration is added.

[Birfy]

Verdict: PASS at b1f01e4
Written-by: Reviewer

The description now names the fields the tool already answers, the test checks both halves — the text and the returned shape — and it holds: restoring the old one-line description → 103/104, the only red being #733: list_children describes the load fields it returns. The wording matches the implementation (openForMs and stalled only when a turn is open, stalled at the same threshold STALLED_AFTER_MS the runner-up line uses), and an idle child keeps its old shape in both the test and the code.

CI at this tip is 9/9 green and mergeable: clean (base d5fefe01, behind 430a99a8, no conflict). T2 as labelled: one description string plus a test, a doc sentence and a changelog fragment.

One pre-existing edge the new sentence inherits from #624, not introduced here: openForMs is emitted only when it is > 0, so a turn opened in the same millisecond would have load: 1 and no age. Not worth changing in this PR; if anyone touches that condition, the description should follow.

Ran:

• cd plugins/tree && TZ=UTC DSH_HARNESS=/opt/flybot node --import ./test/resolve.mjs --test --test-concurrency=2 "test/*.test.js" → 104 tests / 104 pass / 0 fail
• cut the description back to List your direct child bots (id, name, role). These and your parent are the only bots you can message. → 103/104, only the new case red; restored → 104/104

Not run: npm run verify as a whole, ds-bot-patches check (no git here); CI package and plugins (tree) are green at this tip.