Relationships
↔ sibling #4359#4922 stagecraft: an empty, never-started instance takes a work item's key, so claim falls back to <key>-<tracker>
Opened by skunk-ape · 11/19/2026· Shipped 11/20/2026
Also fixes #4359: the same misleading "has not started" message, seen from the wrong repo. Carry both through one lifecycle (link_issue).
Problem
A work item's key is <prefix>-<n> (DESIGN.md, "Keys"). claim adds the tracker instance's name (<key>-<tracker>) only when the plain key is taken. In a factory repo used daily, that fallback fired on three work items. In each case the key was "taken" only by an empty instance that had never started:
| plain key | run records | key claim gave | run records |
|---|---|---|---|
cue-15 |
0 | cue-15-cue-board |
33 |
cue-17 |
0 | cue-17-cue-board |
26 |
| (unnamed) | 0 | ext-2-ext-board |
44 |
Every work item without such a stray has the plain key.
How it happens: running any work-item method under a name with no instance makes swamp create one. Stagecraft then answers the work item has not started; run start with --input factory=<factory>. That hint is misleading. Following it, from the wrong repo or under a mistyped key, starts a second, empty work item. The empty instance then blocks the real key at claim.
#4359 is the same trap seen from another side. A work-item command run from a different repo than the one that holds the work item gets the same "has not started" message. That reads as lost state, not a wrong directory.
What to change
- Writes refuse a key that has never started. Every work-item write except
startrefuses when the key has no run record. The message says no work item by that name exists in this repository, names the repository path, suggests--repo-diror running from the repo that holds it, and lists close existing keys if any. It does not suggeststart. - An empty instance doesn't take a key.
claim's key-free check treats an instance with no run record as free, so the plain key is used. If the engine can avoid leaving an empty instance behind in the first place, it should. If swamp core always creates the instance before the method runs, say so in the plan, and rely on (1) and (2). - Reads (
status,summary) get the same clearer message.
Done when
- A write or
statusunder an unknown key, or from the wrong repo, prints the new message, and nothing suggestsstart. claimgives the plain<prefix>-<n>key when the only thing under it is a never-started instance.<key>-<tracker>still applies to real collisions (two trackers sharing a prefix, or a started work item holding the key).- Tests cover the wrong-repo case, an unknown key,
claimover an empty instance, and a real collision. - The skill and driving reference say what the message means. DESIGN "Keys" says an empty instance doesn't count.
Out of scope
Renaming existing <key>-<tracker> work items, and deleting existing empty instances. People do that by hand once this ships.
Shipped
Click a lifecycle step above to view its details.