workflow-run: planJob's header says every node is in refused under a hold, which the existing-card skip contradicts #1338

Written-by: Triage

From the PASS on #1333 at cd4f3fe14ea144a99529e19f319ca5ff5b7ae780 (merged c67ed0e4). Backend recorded it as non-blocking: it does not gate that merge. Every anchor below is on main c67ed0e4.

The gap

planJob's header says that for a held job every node is in refused (core/src/shared/workflow-run.js:74-77):

refused one entry per node that may not open … For a held job every node is here with heldBy set and the definition's own hold sentence, or refusal: null when the definition guards no held pull request.

The code does not do that: a node that already has a card is skipped before the hold test (:91, if (existing.has(nodeId)) continue), and the paragraph three lines down says the opposite — "A node that already has a card is in neither list" (:79-80). Two sentences in one header cannot both be true; the second one matches the code.

Also "with heldBy set" is only true once the blank-string case is fixed: today heldBy can be '' (see the separate issue about hold: '').

Backend raised it as comment/contract wording, not behaviour: the plan is right, the sentence over-describes it.

Settled: comment only, behaviour unchanged

The lead has decided (2026-10-27T04:54Z): rewrite the header to match the code; do not touch the implementation. The behaviour is right — #1333's review confirmed that a node with a card is not put into refused — so this is a comment that is wrong, not a defect to re-decide.

Where the two sentences disagree, :91 (if (existing.has(nodeId)) continue) is the truth and both passages are rewritten from it:

• :74-77: a held job refuses every node that has no card yet, with heldBy set and the definition's own hold sentence (or refusal: null when the definition guards no held pull request);
• :79-80 already says "a node that already has a card is in neither list" — keep it, and make the two agree.

Acceptance

• The header and :91 tell the same story: no sentence claims that a node with a card is in refused, under a hold or otherwise.
• No behaviour change — the diff is comment lines only; refused's shape and planJob's logic are untouched.
• Tests: if any existing assertion can be made red by reverting the comment change, name it in the PR; otherwise say "no test change" in the PR body and why (a comment cannot be pinned by a test here).

Scope

• The header block above planJob (:69-80), nothing else, under (a).
• Re-read the "with heldBy set" clause after the blank-hold contract lands, so the sentence describes the fixed contract rather than today's ''.

Out of scope

heldBy's behaviour (its own issue); planJob's logic under (a).