[codex] Fix DeployBot delivery stalls and observability

README.md

@@ -87,11 +87,12 @@ the user does not repeat `deploy`. No polling timer is involved.
 Install `examples/github-workflow.yml` on the default branch. It reacts to
 deploy labels, ready/synchronize events, reviews, named CI `workflow_run`
 completions, and completed external check suites. Keep its `workflows` list
-aligned with `pipeline.ci_workflows`. The privileged worker never checks out or
-executes pull-request code. The Action follows releases by default so the same
-serialized worker can dispatch deployment when GitHub suppresses the
-`workflow_run` event for token-dispatched CI. Pin the Action to the full
-reviewed release commit:
+aligned with `pipeline.ci_workflows`. A five-minute scheduled reconciliation
+rereads all durable state in case GitHub concurrency coalesces the last pending
+event in a burst. The privileged worker never checks out or executes
+pull-request code. The Action follows releases by default so the same serialized
+worker can dispatch deployment when GitHub suppresses the `workflow_run` event
+for token-dispatched CI. Pin the Action to the full reviewed release commit:
 
 ```yaml
 - uses: Forward-Future/DeployBot@b06346119a29d0be1c25d1643fdc06a03f7b94a9
@@ -150,14 +151,19 @@ they cannot create the original per-pull-request deploy intent.
 ## Delivery controller
 
 `deploybot status` reports active metadata-only agent threads, pending native
-notifications, every PR stage, deploy requests, queue order, overlaps,
-exact-`main` CI, deployment, and pipeline pause state. It never stores prompts,
+notifications, every PR stage, deploy requests and their exact authorized heads,
+queue order, queued and pre-queue intent overlaps, exact-`main` CI, deployment,
+and pipeline pause state. It alerts when a deploy request exceeds the configured
+ready-to-merge target and names the current gate. It never stores prompts,
 transcripts, source, or credentials.
 
 `deploybot react` promotes ready intent, skips blockers, drains independent
-work, and creates integration PRs when configured. A conflict produces a repair
-handoff containing the source thread, base/head SHAs, source paths, and one
-return command:
+work, and creates integration PRs when configured. Draft status and incomplete
+checks or reviews remain waiting states; they do not create a repair latch. A
+conflict, failed gate, unresolved review, manual block, or stale authorized head
+produces a repair handoff containing the source thread, base/head SHAs, source
+paths, and one return command. Old draft-only repair latches self-clear once the
+controller recognizes them:
 
 In `overlap` mode, a ready source waits when another active, near-ready intent
 belongs to the same source-overlap component. Unrelated ready work still drains,

adapters/claude-code/skills/deploybot/SKILL.md

@@ -27,6 +27,10 @@ exact heads, pending checks/reviews, blockers, dependencies, overlaps, exact
 is still waiting outside it. Never publish prompts, transcripts, source, or
 credentials to the thread registry.
 
+Treat `active_intent_overlap_groups` as the pre-queue collision view. Treat a
+`request-to-ready` alert as an ownership signal: report its exact active gate and
+the source-thread action, rather than describing the empty queue as idle.
+
 Use these state meanings:
 
 - `ready`: every configured merge gate passes.

adapters/codex/agent-merge-queue/skills/deploybot/SKILL.md

@@ -27,6 +27,10 @@ exact heads, pending checks/reviews, blockers, dependencies, overlaps, exact
 is still waiting outside it. Never publish prompts, transcripts, source, or
 credentials to the thread registry.
 
+Treat `active_intent_overlap_groups` as the pre-queue collision view. Treat a
+`request-to-ready` alert as an ownership signal: report its exact active gate and
+the source-thread action, rather than describing the empty queue as idle.
+
 Use these state meanings:
 
 - `ready`: every configured merge gate passes.

docs/reference.md

@@ -23,7 +23,7 @@ DeployBot resolves the pull request for the current branch.
 | `deploybot init [--force]` | Write a safe starter policy. Existing files are preserved unless `--force` is supplied. |
 | `deploybot ensure-labels` | Create or refresh the configured queue, blocked, intent, pause, and registry labels. |
 | `deploybot doctor [--json]` | Check authentication, policy, labels, actors, checks, workflows, and branch protection without changing repository state. |
-| `deploybot status [--json]` | Read active thread metadata, pending native notifications, PR stages, deploy intent, queue state, exact-main CI, deployment, and pipeline control state. |
+| `deploybot status [--json]` | Read active thread metadata, pending native notifications, PR stages, exact-head deploy intent, pre-queue intent overlaps, request-stage timing alerts, queue state, exact-main CI, deployment, and pipeline control state. |
 | `deploybot plan [--json]` | Read the ordered queue, dependencies, blockers, and source-overlap groups. |
 | `deploybot inspect [PR] [--json]` | Evaluate one exact PR head without granting merge authority. |
 | `deploybot metrics [--limit N] [--json]` | Summarize p50, p95, and maximum delivery timings for recent merged PRs. The default limit is 25. |
@@ -164,7 +164,7 @@ Provider fields are:
 | `batch_settle_seconds` | Non-negative window for coalescing near-ready deploy requests before freezing a batch. Default: 15. |
 | `ci_failure_grace_seconds` | Non-negative window for an exact-main CI retry to replace a failed attempt before the release fails. Default: 90. |
 | `promotion_workers` | Positive maximum number of deploy requests promoted concurrently. Default: 4. |
-| `ready_to_merge_target_minutes` | Positive timing target; default 15. |
+| `ready_to_merge_target_minutes` | Positive request-to-ready and queued-to-merge timing target; default 15. |
 | `merge_to_live_target_minutes` | Positive timing target; default 10. |
 | `auto_promote` | Default `true`. |
 | `intent_scope` | Currently must be `"head"`. |
@@ -195,10 +195,11 @@ The composite Action runs `deploybot react` from the checked-out default branch.
 | `timeout` | `"1800"` | Release-follow timeout in seconds. |
 
 The workflow needs `contents: write`, `pull-requests: write`, `checks: read`,
-`issues: write`, and `actions: write`. Use the event filters and concurrency
-group in [`examples/github-workflow.yml`](../examples/github-workflow.yml), pin
-the Action to a reviewed full commit SHA, and keep its `workflow_run.workflows`
-list aligned with `pipeline.ci_workflows`.
+`issues: write`, and `actions: write`. Use the event filters, concurrency group,
+and scheduled full-state reconciliation in
+[`examples/github-workflow.yml`](../examples/github-workflow.yml), pin the Action
+to a reviewed full commit SHA, and keep its `workflow_run.workflows` list aligned
+with `pipeline.ci_workflows`.
 
 ## Authentication and environment
 

examples/github-workflow.yml

@@ -11,6 +11,10 @@ on:
     types: [completed]
   check_suite:
     types: [completed]
+  # GitHub concurrency coalesces pending event bursts. Reconcile the complete
+  # durable state periodically so the last cancelled event cannot strand work.
+  schedule:
+    - cron: "*/5 * * * *"
   workflow_dispatch:
 
 permissions:

skills/deploybot/SKILL.md

@@ -27,6 +27,10 @@ exact heads, pending checks/reviews, blockers, dependencies, overlaps, exact
 is still waiting outside it. Never publish prompts, transcripts, source, or
 credentials to the thread registry.
 
+Treat `active_intent_overlap_groups` as the pre-queue collision view. Treat a
+`request-to-ready` alert as an ownership signal: report its exact active gate and
+the source-thread action, rather than describing the empty queue as idle.
+
 Use these state meanings:
 
 - `ready`: every configured merge gate passes.