Skip to content

· Synx Data Labs

The Claim Mechanism, In Depth

How Synx Data Labs lets a human and an always-on cron loop share one task backlog without colliding — the claimed_by frontmatter field, why claiming a task is itself a tiny pull request, why a race resolves exactly like a merge conflict, and a real edge case a stale status field can leave behind.

At Synx Data

Last week’s post covered the daily ritual that runs every hour, unattended, checking the backlog for something worth waking up for. That raises an obvious question: if an hourly cron and a human can both be reading from the same dev/TODO/ backlog at the same time, what stops them from picking up the same task and quietly stepping on each other? This post covers the mechanism in ccxp-skills that answers that — _session/task_claim.sh, public like everything else in the skill set, so every claim below is something you can go read yourself.

The identity: claimed_by:

Every task file under dev/TODO/ is a markdown file with YAML frontmatter, and one field exists purely for concurrency: claimed_by:. When a session — human or cron — starts working a task, it stamps that field with a value shaped like cc1-<machine-id>:<path-hash>. That’s not a username; it’s a clone identity — this specific machine, this specific checkout on disk. Two interactive sessions running out of two different directories on the same laptop get two different ids, while the same checkout, re-invoked later, is recognized as the same claimant rather than locking itself out of its own work.

Claiming is itself a tiny pull request

Picking up a task doesn’t just edit a file and keep going — it lands on main first, before any design or implementation work starts. The sequence is: branch, release every other task this identity currently holds (more on that below), stamp claimed_by: and flip the task’s status, then commit and open a pull request. It’s a pure frontmatter change, so CI is fast and it merges under the same docs-only auto-merge tier as any other pure status update. The point isn’t ceremony — it’s that the board is never lying about who’s working on what, even mid-task. A claim that only existed in an uncommitted working tree would be invisible to every other session and to anyone watching the project board; a claim that’s a merged commit on main is durable and visible the moment it lands.

Why a race resolves exactly like a merge conflict

Here’s the detail that actually makes shared access safe: there’s no separate lock service anywhere in this design. Two sessions racing to claim the same task are racing to land the exact same line of text — the same claimed_by: field, in the same file — onto main. Whichever pull request merges first wins outright, for the ordinary reason that it did. The second session’s branch, rebased onto the now-updated main, expects that line to still be empty and finds someone else’s id sitting there instead; the rebase conflicts, and the merge is rejected. Nothing clever has to happen for this to work — it’s the same conflict resolution every git user already relies on for any other file, pointed at one specific line whose only job is to say who owns a task. The losing session doesn’t force it through. It reads the fresh claimed_by:, sees it’s no longer empty, and goes back to the backlog for something else. The git merge is the lock.

Holding at most one claim: release-on-pickup

Before acquiring a new claim, a session first releases every task its own identity already holds, except the one it’s about to pick up. That single rule — never hold more than one active claim — is what keeps a long-lived session from quietly accumulating claims across tasks it started but never finished, the kind of drift that eventually leaves a backlog reading “fully claimed” by sessions that no longer exist. Re-claiming the same task you’re already holding is a safe no-op, since that one task is explicitly excluded from the release step.

The sharp edge: a status field isn’t the same thing as a pull request

Release-on-pickup is careful about most of a task’s other state. If the task being freed is still marked as being in review — meaning a pull request against it is presumably open and waiting on a person — the release step leaves its status alone; only a task still marked as actively-in-progress-but-abandoned gets reset back to open and pickable. That’s a reasonable rule, and it depends on one assumption holding every time: that the moment a pull request opens against a task, that task’s own status field gets flipped to reflect it, in the same breath.

That assumption doesn’t always hold, and a real instance of it surfaced while drafting this very series. One post’s claim step correctly released a stale claim this clone held on a sibling post in the series — except that sibling’s pull request had already been opened, while its task file’s status field hadn’t yet been updated to match. Release-on-pickup did exactly what it’s designed to do: it read a status that looked like abandoned, in-progress work, and reset it to open. Nothing was actually abandoned — a real pull request was sitting there, checks green, waiting on review — the file just hadn’t caught up to GitHub yet. The fix was a one-line correction, bundled into the very commit that caused the drift: flip the sibling’s status back, in the same pull request, before anything merged.

It’s worth stating plainly rather than glossing over, in a post that’s otherwise making the case that this system is safe: the lock itself has no edge case in it anywhere. A merge conflict on one line is exactly as reliable as git’s conflict resolution always is. What’s softer is the status bookkeeping layered on top of that lock — it’s only ever as accurate as whichever commit last remembered to update it, because it reads a text field, never GitHub’s actual state. That’s a real, repeatable gap, not a one-off mistake, and the fix is procedural (update the status in the same commit that opens the pull request) rather than something the locking mechanism can enforce on its own.

Stale claims: the second safety valve

Release-on-pickup only fires when the original session comes back and claims something else. It does nothing for a session that vanishes entirely — a crashed process, a machine that’s gone, a human who moved on — and never picks up anything again. For that case there’s a second, independent check: a claim is only considered reclaimable when both of two staleness signals clear a window — days since the task was last touched by a commit on main, and days since its open pull request (if any) last saw any activity at all, a push, a comment, a review. An open pull request that’s still getting reviewed or revised stays live no matter how old the original claim is; one that’s gone quiet for a while becomes fair game for another session to pick up. The two signals cover each other’s blind spot — a task with no open pull request has no PR-activity signal to check, so the commit-recency signal carries it, and a task whose real work lives entirely on an unmerged branch (invisible to main’s own git log) is covered by the PR-activity signal instead.

That’s the whole mechanism: a clone-stable identity, a lock that’s nothing more exotic than a git merge, a rule that keeps any one identity from holding more than it’s working, and a staleness check for when a claim’s owner simply isn’t coming back. It has exactly one soft spot — a status field that can drift from GitHub’s real state until a commit corrects it — and that’s worth knowing before treating the status column as if it carried the same guarantee as the lock underneath it. Next week’s post covers /drive’s full phase chain — the pick, claim, design, implement, review, merge, and close sequence this lock exists to protect — and what happens when a task turns out to be blocked by another one mid-flight.