Skip to content

docs: update Agent Relay SIEM alert messages for v0.15.0 - #31985

Merged
nickvigilante merged 1 commit into
mainfrom
docs/agent-relay-siem-messages
Nov 12, 2026
Merged

nickvigilante merged 1 commit into
mainfrom
docs/agent-relay-siem-messages

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Updates monitoring/siem.md to the log messages Agent Relay v0.15.0 writes.

Old msg v0.15.0 msg
workspace ready, runner handoff workspace built, runner handoff (agent-relay#154)
workspace build passed the session deadline, reporting retryable and deleting workspace build passed the session deadline, reporting failure (also lists workspace build succeeded after the session deadline)
workspace build failed, reporting retryable and deleting workspace build failed
delete workspace failed, leaving for reconciliation delete workspace failed, leaving it for the reaper

The PR also adds the agent_lifecycle field, which appears on the handoff record and on reaper records.

Verification notes:

  • Every other quoted msg in siem.md was checked by grepping internal/ at 9b96578 and still matches.
  • leaving for reconciliation doesn't exist at v0.15.0. Its replacement comes from Dispatcher.deleteWorkspace.

Stack 3/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

@coderagents coderagents Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Automated documentation check for this PR. See the summary comment for the full list.

| `build_status` | The latest build's status when Agent Relay rebuilds a workspace or the reaper evaluates it |
| `deadline` | Claude Code: when Anthropic stops waiting for a runner. Logged when the deadline passes before dispatch. |
| `status` | Reaper: the runner status the workspace reported, such as `working`, `done 1`, `failed <reason>`, or `orphaned` |
| `agent_lifecycle` | The workspace agent's lifecycle state, such as `starting` or `ready`, on `workspace built, runner handoff` and reaper records. Empty when no agent is connected. `starting` means startup scripts are still running, and `start_error` or `start_timeout` means they failed. |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: This locates agent_lifecycle by quoting workspace built, runner handoff as the lookup key, but the page's own "Match rules" section a few headings down says msg text can change between Agent Relay releases and warns readers not to rely on it that way. Tying the field's provenance to an unstable msg string is evidence (which code path emits it), not the reader-facing fact of when the field is present (docs/.style/content-guidelines.md#evidence-justifies-a-claim-and-does-not-belong-in-the-claim). (Reader Advocate)

Separately, in the same cell, "start_error or start_timeout means they failed" has no clean antecedent for "they": the clause-2 subject (start_error/start_timeout) is singular and isn't itself the thing that "failed," so the reader has to reach back into the prior clause's object ("startup scripts") to resolve it (docs/.style/style-guide/voice-and-tone.md#give-each-pronoun-one-clear-referent). (Copy Editor)

Combining both fixes:

Suggested change
| `agent_lifecycle` | The workspace agent's lifecycle state, such as `starting` or `ready`, on `workspace built, runner handoff` and reaper records. Empty when no agent is connected. `starting` means startup scripts are still running, and `start_error` or `start_timeout` means they failed. |
| `agent_lifecycle` | The workspace agent's lifecycle state, such as `starting` or `ready`, present once a workspace finishes building and on every reaper record. Empty when no agent is connected. `starting` means startup scripts are still running, and `start_error` or `start_timeout` means the scripts failed. |

| Rate threshold | `workspace build failed, reporting retryable and deleting` | Both | `job_error` | A template or infrastructure failure, such as exhausted quota. Agent Relay deletes the workspace right away, so `job_error` might be the only record of why. |
| Rate threshold | `workspace build passed the session deadline, reporting retryable and deleting` | Both | `pool` | Builds take longer than the pool's `dispatch_deadline`. |
| Rate threshold | `workspace build failed` | Both | `job_error` | A template or infrastructure failure, such as exhausted quota. Agent Relay deletes the workspace right away, so `job_error` might be the only record of why. |
| Rate threshold | `workspace build passed the session deadline, reporting failure` or `workspace build succeeded after the session deadline` | Both | `pool` | Builds take longer than the pool's `dispatch_deadline`. |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Blocking: This row now lists two different outcomes under one "Why": workspace build passed the session deadline, reporting failure (a failure) and the new workspace build succeeded after the session deadline (the build actually finished, just late). Two problems with that:

  1. docs/agent-relay/claude-code.md's "Build budget" section still says unconditionally that "When a build misses the budget, Agent Relay reports the failure to Anthropic, cancels the build if it's still running, and deletes the workspace," and docs/agent-relay/cursor.md's "Build deadline" section still says unconditionally that "When the deadline passes, Agent Relay deletes the workspace and the developer's chat shows agent-relay: workspace build exceeded the spawn budget." Neither page mentions the late-success case this new message implies exists; the old siem.md wording ("...reporting retryable and deleting") matched those pages, the new wording no longer does. (Continuity Editor)
  2. Even within this table, the shared "Why" column ("Builds take longer than the pool's dispatch_deadline.") doesn't say whether an alert firing on the second value needs the same urgent response as the first, or is only an informational, late-success signal. (Newcomer)

Fix either by adding a sentence to claude-code.md and cursor.md describing the late-success case, or by splitting this row so each msg value has its own "Why" text that says whether it means failure or late success.

@coderagents

coderagents Bot commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Documentation Check

Blocking

  • docs/agent-relay/monitoring/siem.md (open) - The agent_lifecycle row locates the field by an unstable msg string and has an ambiguous pronoun in "means they failed"
  • docs/agent-relay/monitoring/siem.md (open) - The split workspace build passed the session deadline alert now covers a late-success case that claude-code.md and cursor.md don't mention, and this table's own "Why" column doesn't say whether the late-success message needs the same response as the failure message

Related open PRs

Findings for agents
- id: audience-1
  persona: audience
  class: rule
  blocking: true
  file: docs/agent-relay/monitoring/siem.md
  line: 91
  quote: "The workspace agent's lifecycle state, such as `starting` or `ready`, on `workspace built, runner handoff` and reaper records."
  evidence:
    - docs/agent-relay/monitoring/siem.md:206-211
  rule: docs/.style/content-guidelines.md#evidence-justifies-a-claim-and-does-not-belong-in-the-claim
  problem: The location clause names provenance (which msg string the field rides on) rather than what the reader does, and ties it to text the page itself warns is unstable between releases.
  fix: "present once a workspace finishes building and on every reaper record"
  verified: true
- id: language-1
  persona: language
  class: rule
  blocking: true
  file: docs/agent-relay/monitoring/siem.md
  line: 91
  quote: "`starting` means startup scripts are still running, and `start_error` or `start_timeout` means they failed."
  evidence: []
  rule: style-guide/voice-and-tone.md#give-each-pronoun-one-clear-referent
  problem: "they" has no clean antecedent in its own clause; the reader must reach into the prior clause's object ("startup scripts") to resolve it.
  fix: "`start_error` or `start_timeout` means the scripts failed"
  verified: true
- id: consistency-1
  persona: consistency
  class: rule
  blocking: true
  file: docs/agent-relay/monitoring/siem.md
  line: 228
  quote: "`workspace build passed the session deadline, reporting failure` or `workspace build succeeded after the session deadline`"
  evidence:
    - docs/agent-relay/claude-code.md:220
    - docs/agent-relay/cursor.md:199
  rule: null
  problem: claude-code.md and cursor.md still describe a missed deadline as unconditionally ending in failure and deletion, but the new split msg value implies a build can finish successfully after the deadline; this PR's edit is what exposed that contradiction.
  fix: Add a sentence on claude-code.md and cursor.md describing the late-success case, or soften the unconditional "reports the failure ... and deletes" wording.
  verified: true
- id: learner-2
  persona: learner
  class: missing
  blocking: true
  file: docs/agent-relay/monitoring/siem.md
  line: 228
  quote: "`workspace build passed the session deadline, reporting failure` or `workspace build succeeded after the session deadline`"
  evidence: []
  rule: null
  problem: The row's shared "Why" column doesn't say whether the late-success message needs the same response as the failure message, so a reader can't tell from this table alone.
  fix: Split the row so each msg value has its own "Why" text, or add a sentence distinguishing the two outcomes.
  verified: true

Automated review via Coder Agents. Reply to a finding's thread with the reason if the finding is wrong.

nickvigilante added a commit that referenced this pull request Nov 12, 2026
Agent Relay v0.15.0 made the reaper's 15-minute startup window
configurable
([agent-relay#152](coder/agent-relay#152)) and
added a reap delay
([agent-relay#134](coder/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:
- #31834 (merged)
- #31984
- #31985
- #31986
- #31987
- #32094

Refs DOCS-1171

> Generated by Coder Agents.

---------

Co-authored-by: coder[bot] <137810501+coder[bot]@users.noreply.github.com>
Co-authored-by: Bobby Ho <bobby@coder.com>
Base automatically changed from docs/agent-relay-reaper-timing to main November 12, 2026 18:08
@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you 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


You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

Match the log messages that Agent Relay v0.15.0 writes, and document the agent_lifecycle field from coder/agent-relay#154.
@nickvigilante
nickvigilante merged commit b5c43f8 into main Nov 12, 2026
31 of 33 checks passed
@nickvigilante
nickvigilante deleted the docs/agent-relay-siem-messages branch November 12, 2026 18:14
@nickvigilante
nickvigilante temporarily deployed to main November 12, 2026 18:14 — 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 — 1143e433 Deployed Nov 12, 2026 by nickvigilante via cla #255147
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