Relationships
#3297 stagecraft: a factory-wide read of work items waiting on a person (no studio, no per-item status loop)
Opened by skunk-ape · 10/12/2026
Problem
An operator or a driving agent often needs one answer: which work items on a factory are waiting on a person right now, and at which exits. Stagecraft already computes this correctly, but only the studio can show it.
- When an exit becomes held only by a person, the engine records an
awaitingevent in the run journal (personHeldExits,_lib/engine/awaiting.ts). Every gate other than the approval must pass. A cooldown counts from when it lifts (readyAt). An approval declined earlier in the stage waits on rework. A conditional approval whosewhenis false does not count. A manual exit is a decision only when the agent has no way out of its own. waitingOf(_lib/engine/studio_work_items.ts) turns the run's lastawaitingevent into "waiting on a person since T, at these exits". It drops exits whose cooldown has not lifted yet.- Only the studio uses
waitingOf: the Board's "waiting on a person" badge, andGET /api/work-items?factory=<name>whilestudio serveruns.
Without the studio, a script or agent has two choices: run status once per work item, or copy waitingOf's rules over a swamp data query of the run records. The predicate language can't filter on nested journal entries either.
Proposed
Add a read-only method on @swamp/stagecraft/factory, e.g. waiting. It returns every active work item of that factory that is held by a person:
- the key, title, stage and cycle;
- each held exit: transition, target stage, manual or not, and the pending gate ids;
since: when the earliest held exit became held.
Requirements:
- Same code as the Board. Use the studio's query and
waitingOf, so the studio and the method cannot disagree. - Computed at read time. Don't add a stored field: a cooldown can lift between writes, and a stored value would go stale.
- One read for the whole factory. No per-item method runs, and no writes.
- Dispatch-cap parks reported beside it. Items parked at the dispatch cap (
awaitingDispatchOverride) also wait on a person, for an override rather than an approval.
Acceptance
- Each case is included or excluded exactly as the Board shows it: a work item at a pending approval whose other gates pass is included; one whose other gates still fail is excluded; one in a cooldown is excluded until it lifts; one declined and waiting on rework is excluded; a conditional approval whose
whenis false is excluded. - One call on a factory with dozens of work items returns the list, and makes no method runs on the work items.
- REFERENCE.md documents the method, and the skill uses it to answer "what is waiting on me".
Context
Raised by #3225 (software-factory has the same need, and its pendingApprovals also reports approvals whose other gates still fail; stagecraft does not have that problem). Also relevant to moving from software-factory to stagecraft (#3141).
Open
No activity in this phase yet.
system commented 10/12/2026, 3:38:52 PM
Classified automatically when this issue was filed.
- Source: Extensions
If you feel this classification is incorrect, add a ripple to tell us so.
Sign in to post a ripple.