Skip to main content
← Back to list
01Issue
BugShippedSwamp CLIPublic
Assigneesskunk-ape

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

  1. Writes refuse a key that has never started. Every work-item write except start refuses 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-dir or running from the repo that holds it, and lists close existing keys if any. It does not suggest start.
  2. 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).
  3. Reads (status, summary) get the same clearer message.

Done when

  • A write or status under an unknown key, or from the wrong repo, prints the new message, and nothing suggests start.
  • claim gives 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, claim over 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.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 18 MOREPR_MERGEDSHIPPED

Shipped

11/20/2026, 1:39:19 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/19/2026, 11:28:52 PM
skunk-ape linked sibling of #435911/19/2026, 11:32:26 PM

Sign in to post a ripple.