Workflow engine step 4: the running layer — a job instantiates its node cards, the queue hands each by role, current inputs open the next #1316

Written-by: Triage
Part of #1272 — step 4, its own issue. One child issue per step; the PR for this step carries Fixes #<this issue>, never Fixes #1272.

Owner: Dev3（2026-10-27T04:00Z 改派：Dev4 两次卡死/被停、零进展——一直没打 agent-working、没有分支、没有 PR；切片落在 core/ 面，Dev3 接手，分支 dev3/1316-workflow-run）

The gap, in one paragraph

#1272 answers one question: may this node open, now, on these facts? (workflow.js enterNode :461, inputStates :361, renderRefusal :318; facts from workflow-facts.js, step 2). Nothing answers the question after it: a job arrives, and nothing turns it into the node cards, nothing hands node n to the queue by node.role, and nothing opens node n+1 when n's outputs become current. Today that layer is a person: the lead reads the table, writes one card by hand, @-s the Bot, and when the PR is PASSed writes the next card. The definition is data, the guard is code, the runtime is still a habit — which is exactly the thing #1272 exists to remove.

So this is the running layer, and only that:

job (one issue card) → node cards (its subtasks) → queue (by node.role, #1247)
                     → outputs current → next node's card, in the definition's order

It is not a second engine and not a second board. It uses enterNode to answer "may this open", renderRefusal to say why not, the existing task record to hold a card, and the existing pull queue to hand it out.

What already exists (read before designing; do not build a third of any of these)

• core/src/shared/workflow.js — nodes/edges/artifacts, topologicalOrder :183, enterNode :461 (returns ok + the refusing input), renderRefusal :318, workflowColumns :209. Pure: no clock, no fs, no network.
• core/src/host/workflow-facts.js — one function per fact (FACT_NAMES :16), unreadable() :26; a fact that could not be read never becomes a guess.
• core/src/host/tasks.js — the card. parentId :282, child completion rolls the parent up :322-332, matchChild :375; the queue: unclaimed() :418, role match :421-422, requeue() :425, claimQueued() :505.
• core/src/host/task-drive.js — DRIVING :20, backoff :12, driveOnce() :223, consider() :349. This is the only beat that wakes a Bot; the runtime gets no beat of its own.
• A pull queue: the lead enqueues work, an idle member of the role claims it #1247 (closed, shipped) — the pull queue: enqueue with a role, a single-winner claim, WIP=1.
• One board: the delivery board and the task board are one board, and a repository task is its issue #1265 (open) — one board: the repo card is the issue card, and the work record hangs under it. Step 3 of One board: the delivery board and the task board are one board, and a repository task is its issue #1265 is what makes the parent a real card; until it lands, part (a) below is testable against a fixture card and part (b) waits.
• The workflow engine: each node names its Bot and its inputs and outputs, the nodes are drawn as a flowchart, and a node missing an input is refused on the card #1272's fixed promises still hold here: no model in the guard path, hold refuses every node, history append-only, the client never writes GitHub.

What this issue pins

1. One job, one card, node cards as its children. A node is a task with parentId = the job card, not a second GitHub issue and not a new card schema (that would be a second board). The card gains workflow and node (already in The workflow engine: each node names its Bot and its inputs and outputs, the nodes are drawn as a flowchart, and a node missing an input is refused on the card #1272's model); the child carries nodeId and the artifacts it has produced, nothing more.
2. A node card exists only when the node may open. Creation calls enterNode with live facts; when it returns not-ok, no card is created and the reason is the definition's own sentence via renderRefusal — never a new sentence invented by the runtime.
3. The hand-off is the queue, not a mention. Enqueue with role: node.role and no assignee; the claimer is the assignee the card shows. No @, no direct wake, no second dispatch path — driveOnce is the only beat.
4. Idempotent and resumable. (jobId, nodeId) has at most one open card; a restart, a replayed tick or a re-read of the same facts creates no second card. The node history (The workflow engine: each node names its Bot and its inputs and outputs, the nodes are drawn as a flowchart, and a node missing an input is refused on the card #1272 promise 4) is the record, so "did I already open this one" is answered from state, not from a process-local flag.
5. Opening the next node is a fact, not a follow-up action. n+1 opens when every artifact on its incoming edges is present and current (artifact.js freshness); a stale one refuses in the producer's words (e.g. 评审 的输入 check:tests-ok@abc1234 已过期：tip 现在是 def5678). If two nodes are ready at once the definition said so — open both; WIP=1 per Bot is still the queue's rule (A pull queue: the lead enqueues work, an idle member of the role claims it #1247), not a second limit here.
6. A job is done when its terminal node's outputs exist — not when someone says so, and never by claiming a merge GitHub did not perform.
7. Hold refuses every node of every workflow, including one a maintainer Bot asks for; the runtime refuses to create a card for a held job and says who holds it.
8. No clock, no timer, no scheduler. Evaluation happens on the driveOnce tick (and on the board write that produced a fact). Nothing polls GitHub from the client; reads go through the host, writes through the task record and its authz allow-list (TASK_ENDPOINTS).

Acceptance (each with its own test; the knives are the point)

1. A job instantiates: one fixture job on repo-dev produces exactly one node card, parentId = the job card, node = triage, queued for Triage, no assignee. (Knife: delete the enterNode gate → a job whose issue.ready is missing must then wrongly produce a card, and test 2 fails.)
2. A missing or stale input creates nothing, and the refusal text equals renderRefusal's output for that node/fact pair (byte-equal, asserted).
3. Hand-off by role: the queued item's queueRole is node.role; a Bot of another role gets not-in-role on claim (the existing A pull queue: the lead enqueues work, an idle member of the role claims it #1247 refusal, not a new one).
4. Idempotency: two instantiate passes on the same facts → one card. Restart the host between the passes; still one. (Knife: remove the (jobId,nodeId) guard → test 4 red.)
5. Next node waits: with branch/pr not current, node 2 does not open, and the reason names the missing artifact and its revision; when the fact flips current, the next tick opens exactly node 2.
6. Stale revision refuses: an old verdict@sha against a moved tip opens nothing and says both revisions; the card that is already open is untouched.
7. Hold: a held job creates no card on any node, in any workflow; a maintainer Bot's attempt refuses too.
8. Unreadable fact: no card, and the card/job says the fact could not be read (no pass on a guess, Delivery view fails whole when one request fails: a 404 reads as no GitHub connection, with no retry and no per-endpoint diagnosis #1211).
9. Append-only: re-running the tick appends history entries and rewrites no earlier one; a definition edit does not rewrite a card's past nodes.
10. No second dispatch: with the runtime enabled, @-free, a queued node card wakes its role exactly once per item (assert the wake list, not the text); no timer exists to assert because none is added.
11. node --test for the touched suites plus npm run verify green; node scripts/ds-bot-patches.mjs check green with the new files mirrored under patches/ds-bot/.

Sequencing (each slice reviewable alone)

• (a) Pure planner — core/src/shared/workflow-run.js: given a definition (or preset id), the job card's state and a facts map, return the nodes that may open and the refusal for the ones that may not. No fs, no clock, no network, no host imports. Tests drive it with a fixture facts map. This is the part that can start today.
• (b) Host writer — core/src/host/workflow-run.js, called from task-drive.js driveOnce and after a task write: creates/queues the card through the existing record, keyed (jobId, nodeId); waits for One board: the delivery board and the task board are one board, and a repository task is its issue #1265 step 3 so the parent is the real issue card.
• (c) Closure — when a node's card is done and its declared outputs are current, append the node's completion and open the next. No write to GitHub, no label change, no merge.

Out of scope

• No second board, no second card schema, no new client surface (the card already renders workflow/node; step 3 shipped it).
• No scheduler, no cron, no "wake a Bot because time passed" — waking stays A pull queue: the lead enqueues work, an idle member of the role claims it #1247's claim on driveOnce.
• No GitHub writes from the client, no ruleset change, no model in the path.
• Not parallel execution of one workflow beyond what its edges declare; not retries/compensation beyond the queue's requeue (a failed node card is blocked and says why).
• Not the runtime's job to judge a PR or merge one: it asks the facts, it does not become a gate.