feat(implement-issues): active-run heartbeat + claim-before-git so concurrent sessions detect a live pass #1

New issue

Closed

opened 2026-07-05 16:32:21 +00:00 by ksamaschke · 0 comments

ksamaschke commented

2026-07-05 16:32:21 +00:00

Owner

Context

2026-07-05, fritz-ai-local: while an implement-issues pass was mid-implementation of an issue, a second (steering) Claude session on the same checkout found no observable trace of the active run — the tracker issue was still unassigned, no scratchpad/lock existed in the repo, git worktree list was clean. The steering session (wrongly, but plausibly) started its own pipeline for the same issue and created/deleted the very branch the loop was working on. The existing protections (tracker claim + 24h-staleness rule, scratchpad detection) all have a window at pass start and don't cover a run that claims late or crashes silently.

Ask

Make an active implement-issues pass visible and detectable on the checkout it operates on:

Heartbeat/claim file: at pass start (before the first git operation), write e.g. .claude/implement-issues.active in the target repo — agent id, pass started_at, current issue, last-updated timestamp. Refresh at phase transitions; remove on clean pass end. A heartbeat older than a defined staleness threshold may be treated as a crashed run (existing resume rules apply).
Claim before touching git: the tracker claim (Phase 2) must land before branch creation/worktree setup, closing the unclaimed-but-implementing window.
Mutual exclusion: Phase 0's resume check treats a fresh foreign heartbeat as "another run is primary" → skip/stand down instead of proceeding.

Acceptance criteria

Heartbeat file written before first git op, refreshed per phase, removed on completion; documented in SKILL.md (Phase 0/2 + loop-mode section).
A second concurrent pass on the same checkout detects the fresh heartbeat and stands down with a clear report line.
Stale-heartbeat threshold documented and consistent with the existing 24h claim-staleness rule.
The file is repo-local state, never committed (belongs in the same category as the existing .claude/ scratchpads).

Deployment (required — part of this work item)

Changes to this plugin only reach agents via the versioned plugin cache. Definition of done includes: (1) bump the plugin version (plugin.json / marketplace metadata per repo convention); (2) refresh the installed cache on the workstation (claude plugin update <plugin>@samaschke-skills or the repo's documented update path); (3) verify the new version is the one listed in ~/.claude/plugins/cache/samaschke-skills/... and note the "restart sessions to apply" caveat. Do not close this issue at "merged".

## Context 2026-07-05, fritz-ai-local: while an implement-issues pass was mid-implementation of an issue, a second (steering) Claude session on the same checkout found **no observable trace of the active run** — the tracker issue was still unassigned, no scratchpad/lock existed in the repo, `git worktree list` was clean. The steering session (wrongly, but plausibly) started its own pipeline for the same issue and created/deleted the very branch the loop was working on. The existing protections (tracker claim + 24h-staleness rule, scratchpad detection) all have a window at pass start and don't cover a run that claims late or crashes silently. ## Ask Make an active implement-issues pass **visible and detectable** on the checkout it operates on: 1. **Heartbeat/claim file**: at pass start (before the first git operation), write e.g. `.claude/implement-issues.active` in the target repo — agent id, pass started_at, current issue, last-updated timestamp. Refresh at phase transitions; remove on clean pass end. A heartbeat older than a defined staleness threshold may be treated as a crashed run (existing resume rules apply). 2. **Claim before touching git**: the tracker claim (Phase 2) must land before branch creation/worktree setup, closing the unclaimed-but-implementing window. 3. **Mutual exclusion**: Phase 0's resume check treats a *fresh* foreign heartbeat as "another run is primary" → skip/stand down instead of proceeding. ## Acceptance criteria - Heartbeat file written before first git op, refreshed per phase, removed on completion; documented in SKILL.md (Phase 0/2 + loop-mode section). - A second concurrent pass on the same checkout detects the fresh heartbeat and stands down with a clear report line. - Stale-heartbeat threshold documented and consistent with the existing 24h claim-staleness rule. - The file is repo-local state, never committed (belongs in the same category as the existing `.claude/` scratchpads). ## Deployment (required — part of this work item) Changes to this plugin only reach agents via the versioned plugin cache. Definition of done includes: (1) bump the plugin version (plugin.json / marketplace metadata per repo convention); (2) refresh the installed cache on the workstation (`claude plugin update <plugin>@samaschke-skills` or the repo's documented update path); (3) verify the new version is the one listed in `~/.claude/plugins/cache/samaschke-skills/...` and note the "restart sessions to apply" caveat. Do not close this issue at "merged".

ksamaschke self-assigned this

2026-07-05 18:55:58 +00:00

ksamaschke referenced this issue from a commit

2026-07-06 04:01:03 +00:00

feat(implement-issues): add active-run heartbeat (#1)

ksamaschke referenced this issue from a pull request that will close it,

2026-07-06 04:01:21 +00:00

feat(implement-issues): add active-run heartbeat #4

ksamaschke closed this issue

2026-07-06 04:01:47 +00:00