fix(gate): dedupe in-flight issue formatting

.github/workflows/agents-issue-format-guard.yml

@@ -143,24 +143,30 @@ jobs:
           if jq -e '[.labels[].name] | any(. == "agents:format")' live.json >/dev/null; then
             has_format_label=true
           fi
-          # Dedup completed handoffs, but retry when a prior dispatch/optimizer run
-          # left agents:format set (marker without a finished optimizer pass).
+          # The marker is written only after dispatch succeeds.  Keep the label as
+          # the in-flight lease: a repeated guard run must not enqueue another
+          # optimizer while that lease is still present.  If the label was removed,
+          # retry the dispatch because the earlier handoff no longer owns the work.
           dispatch=true
-          if [[ "$trusted_marker" == true && "$has_format_label" != true ]]; then
-            echo "Identical invalid body was already routed; skipping duplicate dispatch."
+          if [[ "$trusted_marker" == true && "$has_format_label" == true ]]; then
+            echo "Identical invalid body is already routed and in flight; skipping duplicate dispatch."
             dispatch=false
-          elif [[ "$trusted_marker" == true && "$has_format_label" == true ]]; then
-            echo "Prior format-guard marker present but agents:format still set — retrying optimizer dispatch."
+          elif [[ "$trusted_marker" == true ]]; then
+            echo "Prior format-guard marker present but agents:format is absent — retrying optimizer dispatch."
           fi
           if jq -e '[.labels[].name] | any(. == "agents:formatted")' live.json >/dev/null; then
             gh issue edit "$NUMBER" --repo "$GITHUB_REPOSITORY" --remove-label "agents:formatted" \
               || echo "::warning::could not remove agents:formatted"
           fi
-          gh issue edit "$NUMBER" --repo "$GITHUB_REPOSITORY" --add-label "agents:format" \
-            || echo "::warning::could not apply agents:format (label missing in this repo?)"
           if [[ "$dispatch" != true ]]; then
             exit 0
           fi
+          # Acquiring the label is the handoff lease. Do not dispatch without it:
+          # otherwise a trusted marker alone could repeat the optimizer dispatch.
+          if ! gh issue edit "$NUMBER" --repo "$GITHUB_REPOSITORY" --add-label "agents:format"; then
+            echo "::error::could not acquire agents:format lease; refusing optimizer dispatch"
+            exit 1
+          fi
           # GITHUB_TOKEN label edits do not start issues:labeled workflows; dispatch is explicit.
           # Persist the completion marker only after a successful workflow_dispatch so a
           # failed run remains retryable on the next guard pass.

.github/workflows/agents-issue-optimizer.yml

@@ -510,7 +510,7 @@ jobs:
 
           # Do not publish agents:formatted for apply-phase output that fails
           # the same fleet contract enforced by the issue-event guard.
-          python .github/scripts/issue_format.py /tmp/updated_body.md
+          python3 .github/scripts/issue_format.py /tmp/updated_body.md
 
           # Update issue body
           node - <<'NODE'
@@ -580,7 +580,7 @@ jobs:
 
           # Do not advertise a formatted issue until it satisfies the same
           # fleet contract enforced by the issue-event guard.
-          python .github/scripts/issue_format.py /tmp/formatted_body.md
+          python3 .github/scripts/issue_format.py /tmp/formatted_body.md
 
           # Update issue body with formatted version
           node - <<'NODE'
@@ -718,3 +718,14 @@ jobs:
           NODE
             echo "Labels updated: removed format, added formatted"
           fi
+
+      - name: Release failed format lease
+        if: failure() && steps.check.outputs.should_run == 'true' && steps.check.outputs.phase == 'format'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ISSUE_NUMBER: ${{ steps.check.outputs.issue_number }}
+        run: |
+          set -euo pipefail
+          # A guard retry may proceed only after the failed format run releases its lease.
+          gh issue edit "$ISSUE_NUMBER" --remove-label "agents:format" \
+            || echo "::warning::could not release failed agents:format lease"

config/template-drift-allowlist.txt

@@ -113,9 +113,9 @@ reason = Intentional divergence re-baselined 2026-06-30: root and consumer guard
 [pair.11]
 main = .github/workflows/agents-issue-optimizer.yml
 template = templates/consumer-repo/.github/workflows/agents-issue-optimizer.yml
-main_sha256 = d99f29c3433fa3430c68338cffe0c9ad7c6e22801303fea1916ddeab4040dc90
-template_sha256 = a4ab5b6f0039c1c20d3fb3133fed3a38902f7943cd46c951cf7695a0d3e41858
-reason = Intentional divergence re-baselined 2026-08-08: root and consumer issue-optimizer workflows keep different auth plumbing/action pin surfaces. Both validate format output before adding agents:formatted; the consumer explicitly sparse-checks out .github/scripts/issue_format.py plus config/scripts/langchain/tools from Workflows, while root runs those files in-tree. Do not align wholesale because that would strip consumer action pins/token setup.
+main_sha256 = 3ad86a30a866167dc78ec21150fc2dba475dc70b2504cfe3373906ed95a2502d
+template_sha256 = 3f76718542ab27978fc819118a9e671a9f34439e388fa0ea6f0359937e7bbb57
+reason = Intentional divergence re-baselined 2026-08-08: root and consumer issue-optimizer workflows keep different auth plumbing/action pin surfaces. Both validate format output with python3, require the agents:format lease before dispatch, and release that lease on a failed format run; the consumer explicitly sparse-checks out .github/scripts/issue_format.py plus config/scripts/langchain/tools from Workflows, while root runs those files in-tree. Do not align wholesale because that would strip consumer action pins/token setup.
 
 [pair.12]
 main = .github/workflows/agents-keepalive-loop-reporter.yml

templates/consumer-repo/.github/workflows/agents-issue-format-guard.yml

@@ -143,24 +143,30 @@ jobs:
           if jq -e '[.labels[].name] | any(. == "agents:format")' live.json >/dev/null; then
             has_format_label=true
           fi
-          # Dedup completed handoffs, but retry when a prior dispatch/optimizer run
-          # left agents:format set (marker without a finished optimizer pass).
+          # The marker is written only after dispatch succeeds.  Keep the label as
+          # the in-flight lease: a repeated guard run must not enqueue another
+          # optimizer while that lease is still present.  If the label was removed,
+          # retry the dispatch because the earlier handoff no longer owns the work.
           dispatch=true
-          if [[ "$trusted_marker" == true && "$has_format_label" != true ]]; then
-            echo "Identical invalid body was already routed; skipping duplicate dispatch."
+          if [[ "$trusted_marker" == true && "$has_format_label" == true ]]; then
+            echo "Identical invalid body is already routed and in flight; skipping duplicate dispatch."
             dispatch=false
-          elif [[ "$trusted_marker" == true && "$has_format_label" == true ]]; then
-            echo "Prior format-guard marker present but agents:format still set — retrying optimizer dispatch."
+          elif [[ "$trusted_marker" == true ]]; then
+            echo "Prior format-guard marker present but agents:format is absent — retrying optimizer dispatch."
           fi
           if jq -e '[.labels[].name] | any(. == "agents:formatted")' live.json >/dev/null; then
             gh issue edit "$NUMBER" --repo "$GITHUB_REPOSITORY" --remove-label "agents:formatted" \
               || echo "::warning::could not remove agents:formatted"
           fi
-          gh issue edit "$NUMBER" --repo "$GITHUB_REPOSITORY" --add-label "agents:format" \
-            || echo "::warning::could not apply agents:format (label missing in this repo?)"
           if [[ "$dispatch" != true ]]; then
             exit 0
           fi
+          # Acquiring the label is the handoff lease. Do not dispatch without it:
+          # otherwise a trusted marker alone could repeat the optimizer dispatch.
+          if ! gh issue edit "$NUMBER" --repo "$GITHUB_REPOSITORY" --add-label "agents:format"; then
+            echo "::error::could not acquire agents:format lease; refusing optimizer dispatch"
+            exit 1
+          fi
           # GITHUB_TOKEN label edits do not start issues:labeled workflows; dispatch is explicit.
           # Persist the completion marker only after a successful workflow_dispatch so a
           # failed run remains retryable on the next guard pass.

templates/consumer-repo/.github/workflows/agents-issue-optimizer.yml

@@ -468,7 +468,7 @@ jobs:
           " || exit 1
 
           # Keep agents:formatted truthful for apply-phase output too.
-          python workflows-scripts/.github/scripts/issue_format.py /tmp/updated_body.md
+          python3 workflows-scripts/.github/scripts/issue_format.py /tmp/updated_body.md
 
           # Update issue body
           gh issue edit "${ISSUE_NUMBER}" --body-file /tmp/updated_body.md
@@ -511,7 +511,7 @@ jobs:
           # Keep the format-result label truthful: the generated issue must
           # pass the canonical Workflows validator before it can be marked
           # agents:formatted below.
-          python workflows-scripts/.github/scripts/issue_format.py /tmp/formatted_body.md
+          python3 workflows-scripts/.github/scripts/issue_format.py /tmp/formatted_body.md
 
           # Update issue body with formatted version
           gh issue edit "${ISSUE_NUMBER}" --body-file /tmp/formatted_body.md
@@ -537,6 +537,17 @@ jobs:
             echo "Labels updated: removed format, added formatted"
           fi
 
+      - name: Release failed format lease
+        if: failure() && steps.check.outputs.should_run == 'true' && steps.check.outputs.phase == 'format'
+        env:
+          GH_TOKEN: ${{ steps.token.outputs.token || github.token }}
+          ISSUE_NUMBER: ${{ steps.check.outputs.issue_number }}
+        run: |
+          set -euo pipefail
+          # A guard retry may proceed only after the failed format run releases its lease.
+          gh issue edit "$ISSUE_NUMBER" --remove-label "agents:format" \
+            || echo "::warning::could not release failed agents:format lease"
+
       - name: Report workflow failure
         if: failure()
         env:

tests/workflows/test_agents_issue_optimizer_format_trigger.py

@@ -32,14 +32,37 @@ def test_issue_optimizer_validates_format_and_apply_bodies() -> None:
     consumer_text = consumer.read_text(encoding="utf-8")
     assert "issue_format.py /tmp/formatted_body.md" in consumer_text
     assert "issue_format.py /tmp/updated_body.md" in consumer_text
+    assert "python3 .github/scripts/issue_format.py" in text
+    assert "python3 workflows-scripts/.github/scripts/issue_format.py" in consumer_text
 
 
-def test_format_guard_retries_incomplete_optimizer_dispatch() -> None:
+def test_format_guard_deduplicates_inflight_optimizer_dispatch() -> None:
     guard = Path(".github/workflows/agents-issue-format-guard.yml").read_text(encoding="utf-8")
     assert "Re-fetch before side effects" in guard
     assert "no completion marker written so later runs can retry" in guard
     assert 'marker="<!-- format-guard:$fingerprint -->"' in guard
+    assert '"$trusted_marker" == true && "$has_format_label" == true' in guard
+    assert "already routed and in flight; skipping duplicate dispatch" in guard
     consumer = Path(
         "templates/consumer-repo/.github/workflows/agents-issue-format-guard.yml"
     ).read_text(encoding="utf-8")
     assert "no completion marker written so later runs can retry" in consumer
+    assert '"$trusted_marker" == true && "$has_format_label" == true' in consumer
+
+
+def test_format_lease_is_required_and_released_after_failure() -> None:
+    guard = Path(".github/workflows/agents-issue-format-guard.yml").read_text(encoding="utf-8")
+    consumer_guard = Path(
+        "templates/consumer-repo/.github/workflows/agents-issue-format-guard.yml"
+    ).read_text(encoding="utf-8")
+    for text in (guard, consumer_guard):
+        assert "could not acquire agents:format lease" in text
+        assert text.index("could not acquire agents:format lease") < text.index(
+            "gh workflow run agents-issue-optimizer.yml"
+        )
+    consumer_optimizer = Path(
+        "templates/consumer-repo/.github/workflows/agents-issue-optimizer.yml"
+    ).read_text(encoding="utf-8")
+    for text in (WORKFLOW_PATH.read_text(encoding="utf-8"), consumer_optimizer):
+        assert "Release failed format lease" in text
+        assert "failure() && steps.check.outputs.should_run == 'true'" in text