Skip to main content
← Back to list
01Issue
FeatureOpenExtensionsPublic
AssigneesNone

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 awaiting event 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 whose when is 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 last awaiting event 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, and GET /api/work-items?factory=<name> while studio serve runs.

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 when is 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).

02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

10/12/2026, 3:38:52 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

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.