feat: post agent status comments on workflow start and completion

[ggallen]

Summary

• Adds .github/actions/agent-status-comment/ composite action that posts status comments on issues/PRs when agent workflows start and complete
• On completion, edits the start comment in place if it is still the last comment on the thread (one comment per agent run). If other activity appeared in between (reviews, other comments), posts a new completion comment to preserve timeline order
• Cancelled runs delete their start comment to avoid stale "in progress" messages
• Compact two-line format with UTC timestamps:
  • Start: 🤖 Reviewing this PR · Started 2:34 PM UTC
  • Completion (edited): 🤖 Finished Reviewing this PR · ✅ Success · Started 2:34 PM UTC · Completed 2:41 PM UTC
• Start comment steps gated on steps.app-token.outputs.token != '' to match completion steps
• description input documented as hardcoded-literal-only (no user-controlled content)
• Scaffold copy kept in sync

Closes #1859. Related: #837, #957.

Test plan

• make lint — clean
• YAML validation passes (check-yaml hook)
• GitHub Actions workflow linter passes
• Manual: trigger agent workflow, verify start comment appears with timestamp
• Manual: verify completion edits start comment in place when no intervening activity
• Manual: verify completion posts new comment when review/comment appears between start and completion
• Manual: verify cancelled run deletes its start comment

🤖 Generated with Claude Code

[github-actions]

Site preview

Preview: https://f556dba5-site.fullsend-ai.workers.dev

Commit: 4aae4445a73611b666a8920cbac9d0783a98fcf0

[fullsend-ai-review]

Review

Findings

Medium

• [protected-path] .github/actions/agent-status-comment/action.yml, .github/workflows/reusable-code.yml, .github/workflows/reusable-fix.yml, .github/workflows/reusable-retro.yml, .github/workflows/reusable-review.yml, .github/workflows/reusable-triage.yml — This PR modifies 6 files under .github/, which is a protected path. The PR links to issue feat: post agent status comments on workflow start and completion #1859 and the description clearly explains the rationale for the changes (status comments for agent workflow runs). Human approval is always required for protected-path changes, regardless of review quality.

Low

• [input-validation] .github/actions/agent-status-comment/action.yml:87 — The description input flows directly into the GitHub comment body via printf and gh issue comment --body. Safety relies on a documentation convention ("Must be a hardcoded literal") rather than programmatic enforcement. All current callers pass hardcoded strings, so present risk is negligible. A future caller passing user-controlled content could lead to markdown injection in comments.

• [race-condition] .github/actions/agent-status-comment/action.yml:109 — The edit-in-place logic has a TOCTOU race: LAST_COMMENT_ID is fetched, then the decision to PATCH or post is made. Between the check and the PATCH, another comment could appear. Impact is cosmetic only — completion info still lands correctly, but the start comment may be edited in place when it is no longer the last comment. No fix required given continue-on-error: true.

• [edge-case] .github/actions/agent-status-comment/action.yml:96 — The grep -oP for extracting start time uses a fixed pattern Started [0-9]+:[0-9]+ [AP]M UTC. This works for the current TIMESTAMP format (%-I:%M %p UTC) but will silently fail to extract the time if the format ever changes. The fallback (omitting start time from completion comment) is reasonable, so impact is cosmetic only.

Info

• [input-validation] .github/actions/agent-status-comment/action.yml:54 — The number input is validated for empty/null but not for being a positive integer. All current callers pass GitHub event payload number fields (integers), and gh issue comment would fail gracefully with an API error on non-numeric input. No practical risk.

• [api-pagination] .github/actions/agent-status-comment/action.yml:68 — The find_start_comment function uses --paginate to fetch all comments to find the start comment marker. On issues with many comments, this could make many API calls. Acceptable given the infrequency of the cancelled/completion paths and error suppression.

• [sub-agent-gap] N/A — The style-conventions sub-agent could not access PR branch files for pattern comparison (repo checked out on main). Manual style review recommended as part of human approval.

Previous run

Review

Findings

Medium

• [protected-path] .github/actions/agent-status-comment/action.yml, .github/workflows/reusable-code.yml, .github/workflows/reusable-fix.yml, .github/workflows/reusable-retro.yml, .github/workflows/reusable-review.yml, .github/workflows/reusable-triage.yml — This PR modifies 6 files under .github/, which is a protected path. The PR links to issues feat: post agent status comments on workflow start and completion #1859, Failed review agent runs should update the status comment on the PR #837, and Add agent failure notifications to the post-run lifecycle #957, and the description clearly explains the rationale for the changes. Human approval is always required for protected-path changes, regardless of review quality.

Low

• [input-validation] .github/actions/agent-status-comment/action.yml:87 — The description input flows directly into the GitHub comment body via printf and gh issue comment --body. Safety relies on a documentation convention ("Must be a hardcoded literal") rather than programmatic enforcement. All current callers pass hardcoded strings, so present risk is negligible. A future caller passing user-controlled content (e.g., issue title) could lead to markdown injection in comments.

Info

• [input-validation] .github/actions/agent-status-comment/action.yml:54 — The number input is validated for empty/null but not for being a positive integer. All current callers pass GitHub event payload number fields (integers), and gh issue comment would fail gracefully with an API error on non-numeric input. No practical risk.

• [api-pagination] .github/actions/agent-status-comment/action.yml:68 — The cancelled-run cleanup path uses --paginate to fetch all comments to find the start comment marker. On issues with many comments, this could make many API calls. Acceptable given the infrequency of the cancelled path and error suppression.

• [sub-agent-gap] N/A — The style-conventions sub-agent could not access PR branch files for pattern comparison. Manual style review recommended as part of human approval.

• [prior-finding-resolved] .github/workflows/reusable-code.yml — Prior finding [missing-guard] is resolved. All "Post start comment" steps now include the if: steps.app-token.outputs.token != '' guard, matching the completion comment steps.

• [prior-finding-resolved] .github/actions/agent-status-comment/action.yml — Prior finding [shell-expansion] is resolved. The code now uses printf -v BODY '%s\n...' with %s format specifiers instead of a heredoc, eliminating the shell expansion concern.

Previous run

Review

Findings

Medium

• [protected-path] .github/actions/agent-status-comment/action.yml, .github/workflows/reusable-code.yml, .github/workflows/reusable-fix.yml, .github/workflows/reusable-retro.yml, .github/workflows/reusable-review.yml, .github/workflows/reusable-triage.yml — This PR modifies 6 files under .github/, which is a protected path. The PR links to issues feat: post agent status comments on workflow start and completion #1859, Failed review agent runs should update the status comment on the PR #837, and Add agent failure notifications to the post-run lifecycle #957, and the description clearly explains the rationale for the changes. Human approval is always required for protected-path changes, regardless of review quality.

Low

• [input-validation] .github/actions/agent-status-comment/action.yml:87 — The description input flows directly into the GitHub comment body via printf and gh issue comment --body. Safety relies on a documentation convention ("Must be a hardcoded literal") rather than programmatic enforcement. All current callers pass hardcoded strings, so present risk is negligible. A future caller passing user-controlled content (e.g., issue title) could lead to markdown injection in comments.

Info

• [input-validation] .github/actions/agent-status-comment/action.yml:54 — The number input is validated for empty/null but not for being a positive integer. All current callers pass GitHub event payload number fields (integers), and gh issue comment would fail gracefully with an API error on non-numeric input. No practical risk.

• [api-pagination] .github/actions/agent-status-comment/action.yml:68 — The cancelled-run cleanup path uses --paginate to fetch all comments to find the start comment marker. On issues with many comments, this could make many API calls. Acceptable given the infrequency of the cancelled path and error suppression.

• [sub-agent-gap] N/A — The style-conventions sub-agent could not access PR branch files for pattern comparison. Manual style review recommended as part of human approval.

• [prior-finding-resolved] .github/workflows/reusable-code.yml — Prior finding [missing-guard] is resolved. All "Post start comment" steps now include the if: steps.app-token.outputs.token != '' guard, matching the completion comment steps.

• [prior-finding-resolved] .github/actions/agent-status-comment/action.yml — Prior finding [shell-expansion] is resolved. The code now uses printf -v BODY '%s\n...' with %s format specifiers instead of a heredoc, eliminating the shell expansion concern.

Previous run (2)

Review

Findings

Medium

• [protected-path] .github/actions/agent-status-comment/action.yml, .github/workflows/reusable-*.yml — This PR modifies files under .github/, which is a protected path requiring human approval. The PR links to issues feat: post agent status comments on workflow start and completion #1859, Failed review agent runs should update the status comment on the PR #837, and Add agent failure notifications to the post-run lifecycle #957, and the description clearly explains the rationale. Human approval is required regardless of review outcome.

Low

• [missing-guard] .github/workflows/reusable-code.yml (and 4 other reusable workflows) — The "Post start comment" steps lack the if: guard checking steps.app-token.outputs.token != '' that the "Post completion comment" steps have. If the app-token step fails, the start comment step runs with an empty token and fails silently (suppressed by continue-on-error: true). Not a functional bug, but an inconsistency that could mask token-minting failures in logs.

• [shell-expansion] .github/actions/agent-status-comment/action.yml:58 — The heredoc uses unquoted EOF, which allows shell variable expansion inside the body. If DESCRIPTION ever contained shell-special characters (backticks, $, backslashes), they would be interpreted by the shell. All current callers pass hardcoded strings so this is safe today, but quoting the delimiter (<<'EOF') would make the contract explicit.

• [input-validation] .github/actions/agent-status-comment/action.yml — The description input flows directly into the GitHub comment body via gh issue comment --body. While all current callers pass hardcoded strings and the input is set via env: (preventing shell injection), the action's interface does not enforce that description must be a literal. A future caller passing user-controlled content could inject arbitrary markdown into comments. Consider documenting this constraint or adding a character-set validation.

Info

• [api-pagination] .github/actions/agent-status-comment/action.yml:68 — The cancelled-run cleanup path uses --paginate to fetch all comments on the issue/PR to find the start comment marker. On issues with many comments, this could make many API calls. Since this only runs on the cancelled path (infrequent) and errors are suppressed, this is acceptable.

[ralphbean]

A couple things I think we should sort out before merging. See inline.

[ralphbean]

[important] So right now every agent run leaves two comments — a start and a completion. A review/fix/review cycle is 6 comments, and real PRs iterate. That adds up fast.

The cancelled-run path already knows how to find the start comment by its marker and delete it. What if the success/failure path did the same thing, but edited it in place instead of posting a new one? The completion step finds the start comment via the marker, PATCHes it with the final status, done. One comment per agent per run.

I think the "update the status comment" language in #837 was pointing in this direction too.

With that in mind — if we go with edit-in-place, the start comment becomes a living status indicator rather than a historical breadcrumb. That opens up some nice possibilities, like adding a "currently running step" update mid-agent if we ever want it.

[ggallen]

I initially considered that, but then decided against it. The problem as I see it is that, at least for review, there will potentially be the review in the middle of the start/end. If you update the start comment instead of posting it, they essentially become out of sequence. This seems odd, and against what a real timeline should look like.

[ralphbean]

That's fair - I guess, I'm unsure that users really want the "done" message, then. Like - it feels like debug output.

The start message does too, but it's more useful. I can imagine curious users (power users?) clicking it to go watch the log. But, the "done" message is less useful. The review was already posted!

[ralphbean]

Consider dropping the done message?

[ggallen]

But I feel like the done message is important for every agent except for the review agent (in the case that the review agent does an in-line review and not just update the comment. In cases where it doesn't, the done message is just as important).

I'd rather just update the start comment then not have any indication of completion.

Each comment is only three lines. We could probably squeeze it to two.

Or maybe we can determine if the start comment is the last comment? If so, update in place. If not, add an end comment.

Note also that this solves the problem of find the action associated with the agent! Nothing to do with this conversation, but just wanted to point it out.

[ggallen]

Also, are start and end times important? Do we want to be able to use the timeline to see how long things are taking?

[ggallen]

Implemented a hybrid approach: on completion, the action checks whether the start comment is still the last comment on the thread (per_page=1&direction=desc). If it is, it edits the start comment in place via PATCH. If something else appeared in between (a review, another comment), it posts a new completion comment instead — preserving timeline order.

Also reworked the format to two lines with timestamps:

Start:

🤖 Reviewing this PR · Started 2:34 PM UTC
Commit: a1b2c3d · View workflow run →

Completion (edited in place):

🤖 Finished Reviewing this PR · ✅ Success · Started 2:34 PM UTC · Completed 2:41 PM UTC
Commit: a1b2c3d · View workflow run →

Completion (new comment, when start isn't last):

🤖 Finished Reviewing this PR · ✅ Success · Completed 2:41 PM UTC
Commit: a1b2c3d · View workflow run →

This gives us one comment per agent run in the common case (no interleaved activity), while still preserving correct timeline ordering when reviews or other comments land between start and completion.

[ggallen]

Addressed the non-deferred findings:

Low — missing if: guard on start comment steps: Fixed. Added if: steps.app-token.outputs.token != '' to all five reusable workflow start comment steps, matching the guard already present on completion steps.

Low — heredoc indentation / shell expansion: Fixed. Replaced cat <<EOF heredocs with double-quoted string assignments. Body lines are now at column 0 (no code-block rendering), and variable expansion behavior is explicit.

Low — input validation: Added documentation to the description input: "Must be a hardcoded literal — do not pass user-controlled content."

Medium — protected path: Acknowledged — requires human approval.

Info — API pagination: Acceptable for the cancelled path (infrequent).

The edit-in-place discussion (start comment → living status indicator) is still open — deferring that change.

[ralphbean]

WDYT about adding this to fullsend run instead of as a new part of the gh workflow?

It could be a good thing to let users control in the future, by say adding this to their config.yaml:

agents:
   defaults:   # applies to all agents
       status_comments:
           start: enabled
           stop: disabled
    fix:  # for whatever reason, the user doesn't want fix agent to put comments when it starts work
        status_comments:
            start: disabled

I bring this up b/c I'm still an advocate of emoji reactions :D I'm expecting some users will want these status comments while others will want emoji reactions. Some will want both and some will want neither. If we put these in config.yaml, then fullsend run will already be in the position to parse and use that. Plus, it'll port over to kubernetes execution eventually.

[ggallen]

WDYT about adding this to fullsend run instead of as a new part of the gh workflow?

Curse you, @rbean.

Stand by.

[ggallen]

WDYT about adding this to fullsend run instead of as a new part of the gh workflow?

Curse you, @rbean.

Stand by.

@rbean, check out #1871.

[ggallen]

Superseeded by #1871.