fix(ci): report agent workflow handoff failures

[laceyp99]

Related Links

• Issue: Escape wildcard characters in free-text memory search #26
• Failed Action run: https://github.com/laceyp99/Memories-API/actions/runs/28641249445

What

• Added runtime validation guidance to the Codex issue implementation prompt for Ubuntu GitHub Actions runs.
• Added a fallback issue comment path for unhandled issue implementation workflow failures, including push, draft PR creation, label update, install, and Codex action failures that were not already covered by validation/artifact/no-change handlers.
• Added a fallback PR comment path for unhandled PR review workflow failures.
• Documented that draft PR creation requires the repository Actions setting that allows GitHub Actions to create and approve pull requests.

Why

The issue #26 implementation run succeeded through Codex, workflow validation, commit, and branch push, then failed at draft PR creation with:

GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest)

The workflow already requested pull-requests: write, so the missing piece was the repository-level Actions setting. That setting has now been enabled, and this PR makes the workflow behavior more explicit and resilient for future runs.

The same run also showed Codex interrupting broad or quiet pytest commands after they appeared to hang, even though the following workflow validation completed successfully with all tests passing. The prompt now tells the cloud agent to run focused checks, avoid quiet broad pytest when progress matters, and hand off to the workflow validation step when broad validation stalls.

How

• Added prompt guidance for non-interactive Ubuntu runner behavior and validation handoff.
• Added step IDs for push and issue-label update steps so fallback comments can report their outcomes.
• Added an always() && failure() issue workflow fallback that comments on the issue, records step outcomes, links the run, includes the working branch when available, and moves the issue from agent-ready to agent-blocked.
• Added an always() && failure() PR review fallback that comments on the PR with the failed workflow run and relevant step outcomes.

Test Steps

• git diff --check
• Parsed .github/workflows/issue-implement.yml and .github/workflows/pr-review.yml with Python YAML loading
• Commit hooks passed: YAML check, mixed-line-ending check, and pytest
• Push hooks passed

Other Notes

• The repository setting can_approve_pull_request_reviews was enabled separately through the GitHub API. The workflow permissions block alone cannot enable that setting.
• actionlint was not installed locally, so it was not run.
• The failed run already pushed agent/issue-26-run-28641249445; this PR does not create a retroactive PR for that branch.

[laceyp99]

Follow-up: harden agent workflow handoffs

What

• Updated the PR review workflow to request pull-requests: write, matching the permission needed to post PR comments reliably.
• Moved PR review Codex home config to the trusted default-branch checkout.
• Added trusted default-branch Codex asset checkout to the issue implementation workflow and pointed both its prompt and Codex home config there.
• Made both fallback workflow failure comment steps non-masking with continue-on-error: true so fallback comment failures do not obscure the original workflow failure.
• Cleaned up the issue workflow fallback if: expression so actionlint validates it correctly.

Why

The PR review action for run 28645241189 completed validation and Codex review successfully, then failed while posting the PR comment with 403 Resource not accessible by integration. The fallback comment step failed the same way, adding a second failure instead of clarifying the first. These changes address the permission mismatch and make the failure-reporting path less noisy.

Validation

• python -c "import yaml; [yaml.safe_load(open(p, encoding='utf-8-sig')) for p in ['.github/workflows/pr-review.yml','.github/workflows/issue-implement.yml']]; print('yaml ok')"
• git diff --check -- .github/workflows/pr-review.yml .github/workflows/issue-implement.yml
• go run github.com/rhysd/actionlint/cmd/actionlint@latest .github/workflows/pr-review.yml .github/workflows/issue-implement.yml
• Commit hooks passed, including pytest
• Push hooks passed

Commit

• 16bb545 fix(ci): harden agent workflow handoffs

[github-actions]

Agent PR review

Validation

Validation passed: ruff format --check ., ruff check ., and pytest all completed successfully.

Summary

This PR hardens the agent workflows by adding trusted Codex asset checkout for issue implementation, fallback failure comments for issue implementation and PR review workflows, clearer draft PR permission documentation, and runtime validation guidance in the issue implementation prompt.

Issues and risks

• severity: low
• file or area: .github/workflows/pr-review.yml
• why it matters: The PR review workflow now grants pull-requests: write, but the changed workflow still appears to post feedback through github.rest.issues.createComment, which is covered by issues: write. I did not find a use of pull request write APIs in this workflow. This broadens token scope without clear need.
• suggested fix: Revert this permission to pull-requests: read unless there is a specific GitHub API call requiring write access.

Test coverage

The PR context reports ruff format --check ., ruff check ., and pytest passed. I also verified locally that git diff --check is clean and both changed workflow YAML files parse with Python YAML loading.

Important remaining gap: actionlint was not available, so the GitHub Actions expressions and permission changes have not been validated with a workflow-specific linter. Given this PR mainly changes workflow control flow, running actionlint would be the most useful additional check.

Recommendation

Needs changes before merge. The implementation is mostly targeted, but the PR review workflow should keep least-privilege permissions unless pull-requests: write is actually required.

---

This is an automated review. Please treat it as advisory; human review is still required.

[laceyp99]

Looks good! The PR review ran successfully, and I have a successful Issue Implementation PR to review as well. I'm going to merge from here and handle any issues/additional changes within this repo before integrating these workflows in other repos.