Skip to content

docs: document Agent Relay reaper startup grace and reap delay - #31984

Merged
nickvigilante merged 6 commits into
mainfrom
docs/agent-relay-reaper-timing
Nov 12, 2026
Merged

nickvigilante merged 6 commits into
mainfrom
docs/agent-relay-reaper-timing

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Agent Relay v0.15.0 made the reaper's 15-minute startup window configurable (agent-relay#152) and added a reap delay (agent-relay#134).

  • configuration.md: add --reap-startup-grace (Helm reapStartupGrace) and --reap-delay, plus the per-pool reap_delay field, under an intro that says how the two options differ. The Cursor dispatch_deadline: 0 row now points at the startup grace.
  • setup.md: fix the script-ordering note and Workspace lifecycle, which hardcoded 15 minutes and said failed builds are deleted "on the next sweep". Workspace lifecycle now states the 30-second gap between sweeps, and Choose cleanup settings maps each goal to its setting.
  • cursor.md: fix the Build deadline bullet and the pending lifecycle row.
  • troubleshooting.md: the "session ended but its workspace remains" row mentions the reap delay.
  • monitoring/index.md: add the delayed verdict to agent_relay_reaper_verdicts_total and define it as a wait before delete or failed.

Verification notes:

  • The chart has no reapDelay value at v0.15.0 (only reapStartupGrace; checked values.yaml and templates/_helpers.tpl), so the docs say to set CODER_AGENT_RELAY_REAP_DELAY through extraEnv.
  • Pending or starting builds wait max(grace, dispatch_deadline). A finished build whose runner reports pending or nothing fails after the grace alone (workspacereaper/lifecycle.go).
  • The reap delay counts from the latest build's Job.CompletedAt, not from the worker's exit, so a session that ran longer than the delay gets no extra time (reapDeadline in workspacereaper/reaper.go).
  • delayed is only a metric label. A sweep records it when the verdict is delete or failed but the delay hasn't passed. The Verdict type has only keep, delete, failed, and stuck.
  • The reaper sleeps 30 seconds after it sweeps every pool, rather than running on a fixed ticker (sweepLoop in servicereaper/reaper.go).

Stack 2/6. Review and merge in order:

Refs DOCS-1171

Generated by Coder Agents.

@nickvigilante nickvigilante added the community Pull Requests and issues created by the community. label Nov 10, 2026
@nickvigilante nickvigilante self-assigned this Nov 10, 2026
@linear-code

linear-code Bot commented Nov 10, 2026

Copy link
Copy Markdown

DOCS-1171

@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:53 — with GitHub Actions Inactive
@nickvigilante
nickvigilante temporarily deployed to main November 10, 2026 15:53 — with GitHub Actions Inactive
coder Bot and others added 4 commits November 12, 2026 14:50
Agent Relay v0.15.0 makes the reaper's 15-minute startup window configurable (coder/agent-relay#152) and adds a reap delay (coder/agent-relay#134).
…ttings

Atif found the reaper options hard to tell apart. Describe what the
reaper does in Workspace lifecycle, add a table of which cleanup setting
to change for which goal, and say when to use each option. Drop the
per-option version notes in favor of the latest release.
Review feedback on #31835 found the reaper docs hard to tell apart and
the reap delay wording ambiguous. The delay counts from the latest
build's completion, not from the worker's exit, so the earlier wording
promised retention for long sessions that the reaper doesn't give.

Contrast the startup grace and the reap delay at the top of the
reaper reference, state when the delay starts and which outcomes it
holds, define the delayed verdict as a wait before delete or failed,
and describe the 30-second gap between sweeps exactly.

Refs DOCS-1171
@nickvigilante
nickvigilante temporarily deployed to main November 12, 2026 15:08 — with GitHub Actions Inactive
@BobbyHo
BobbyHo requested a review from Emyrk November 12, 2026 15:38

@BobbyHo BobbyHo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, left a minor, non-blocking comment.

Comment thread docs/agent-relay/configuration.md Resolved
Clarify the impact of `dispatch_deadline` on a workspace

Co-authored-by: Bobby Ho <bobby@coder.com>
@github-actions

Copy link
Copy Markdown
Contributor


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


1 out of 2 committers have signed the CLA.
✅ (nickvigilante)[https://github.com/nickvigilante]
❌ @coder[bot]
You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

@nickvigilante
nickvigilante merged commit 75574df into main Nov 12, 2026
30 of 33 checks passed
@nickvigilante
nickvigilante deleted the docs/agent-relay-reaper-timing branch November 12, 2026 18:08
@nickvigilante
nickvigilante temporarily deployed to main November 12, 2026 18:08 — with GitHub Actions Inactive
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 12, 2026

This branch was previously deployed

1 inactive deployment
main — 8e0a1805 Deployed Nov 12, 2026 by nickvigilante via cla #255142
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

community Pull Requests and issues created by the community.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants