docs: Clarify CLI vs UI agent distinction in keepalive system by stranske · Pull Request #700 · stranske/Workflows

stranske · 2026-01-09T15:06:12Z

Source: Issue #695

Automated Status Summary

Scope

Problem

When PRs are created from issues (e.g., via verify:create-issue label), the Issue Intake workflow in consumer repos was always passing post_agent_comment: false, preventing the coding agent from automatically starting work.

This caused PRs to be stuck in agent-run-skipped state because:

Context for Agent

Design Decisions & Constraints

1. Keepalive loop skips agent execution
| Keepalive | ❌ disabled |

Related Issues/PRs

References

Workflows/templates/consumer-repo/.github/workflows/agents-issue-intake.yml

Lines 170 to 182 in dcc98cd

    
             # Agent bridge mode: Call the Workflows repo reusable issue bridge 
        
             bridge: 
        
               needs: [route, check_labels] 
        
               if: | 
        
                 needs.route.outputs.should_run_bridge == 'true' && 
        
                 needs.check_labels.outputs.should_run == 'true' 
        
               uses: stranske/Workflows/.github/workflows/reusable-agents-issue-bridge.yml@main 
        
               with: 
        
                 agent: ${{ needs.check_labels.outputs.agent }} 
        
                 issue_number: ${{ needs.check_labels.outputs.issue_number }} 
        
                 mode: "create" 
        
                 post_agent_comment: ${{ github.event_name == 'workflow_dispatch' && (inputs.post_codex_comment && 'true' || 'false') || 'true' }} 
        
                 agent_pr_draft: ${{ inputs.bridge_draft_pr && 'true' || 'false' }}

https://chatgpt.com/s/cd_69610ee7e67c81918fdeddff25601eeb

Tasks

1. Issue event triggers have undefined inputs
2. Template evaluates inputs.post_codex_comment && 'true' || 'false' → 'false'
3. No @codex start comment is posted
4. Keepalive loop skips agent execution

Acceptance criteria

- Default to 'true' for issue events (auto-start agent)
- Respect inputs.post_codex_comment only for workflow_dispatch
- Matches the reusable workflow's default behavior

Head SHA: 3515688
Latest Runs: ✅ success — Gate
Required: gate: ✅ success

Workflow / Job	Result	Logs
Agents PR meta manager	❔ in progress	View run
CI Autofix Loop	✅ success	View run
Gate	✅ success	View run
Health 40 Sweep	✅ success	View run
Health 44 Gate Branch Protection	✅ success	View run
Health 45 Agents Guard	✅ success	View run
Health 50 Security Scan	✅ success	View run
Maint 52 Validate Workflows	✅ success	View run
PR 11 - Minimal invariant CI	✅ success	View run
Selftest CI	✅ success	View run

The consumer repo template for agents-issue-intake.yml was always passing post_agent_comment as false for issue-triggered events (when inputs are undefined), preventing the coding agent from auto-starting. Changed to default to 'true' for issue events, allowing workflow_dispatch to override via the post_codex_comment input parameter. This matches the reusable workflow's default behavior. Fixes the issue where PRs created from issues (e.g., via verify:create-issue) would never start the coding agent, leaving them stuck in 'agent-run-skipped' state across all consumer repos.

Add comprehensive explanation of the two Codex execution modes to prevent common troubleshooting mistakes: 1. CLI Agent (workflow-based) - Primary keepalive system 2. UI Agent (comment-based) - Backup for manual interventions Key clarifications: - Why orchestrator skips PRs with agent:* labels (by design) - Decision tree for debugging keepalive issues - Clear guidance on when each mode is appropriate Updated: - CLAUDE.md: Added 'Two Ways to Run Codex' section with flow diagram - KEEPALIVE_TROUBLESHOOTING.md: New section explaining CLI vs UI distinction This addresses confusion where agents think the orchestrator skip is a bug when it's actually correct behavior for CLI agent PRs.

Copilot

Pull request overview

This PR adds comprehensive documentation to clarify the distinction between CLI-based and comment-based Codex execution modes, addressing confusion about why the orchestrator skips PRs with agent:* labels. A minor workflow logic change is included as a follow-up fix from PR #695.

Key Changes

Added detailed explanation of CLI Agent (workflow-based) vs UI Agent (comment-based) execution modes
Documented why the orchestrator intentionally skips agent:* labeled PRs
Added debugging decision tree for troubleshooting keepalive issues
Updated post_agent_comment logic to always post comments for issue-triggered events while respecting manual input for workflow_dispatch

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
`templates/consumer-repo/.github/workflows/agents-issue-intake.yml`	Modified `post_agent_comment` parameter to conditionally respect `inputs.post_codex_comment` only for workflow_dispatch events, defaulting to 'true' for issue events
`docs/keepalive/KEEPALIVE_TROUBLESHOOTING.md`	Added comprehensive "Understanding CLI vs UI Agents" section with activation flows, debugging decision tree, and common mistakes to avoid
`CLAUDE.md`	Added "Two Ways to Run Codex" section with flow diagram and explanation of why the orchestrator skips CLI agent labels, plus references to canonical documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b33bbc8254

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

templates/consumer-repo/.github/workflows/agents-issue-intake.yml

@codex

…ment When PRs are created from issues labeled with agent:codex, the template was posting @codex start comments which triggered the UI agent. However, the CLI keepalive loop already handles codex PRs through the workflow system. Having both agents run simultaneously causes conflicts. This fix: - Skips post_agent_comment for agent:codex (CLI keepalive handles it) - Keeps post_agent_comment for other agents like agent:claude - Preserves workflow_dispatch behavior for manual overrides Addresses P2 issue raised in PR #700 review comment. See docs/keepalive/Agents.md for CLI vs UI agent distinction.

github-actions · 2026-01-09T16:17:36Z

Gate fast-pass: docs-only change detected; heavy checks skipped.

github-actions · 2026-01-09T16:17:38Z

🤖 Keepalive Loop Status

PR #700 | Agent: Codex | Iteration 0/5

Current State

Metric	Value
Iteration progress	[----------] 0/5
Action	wait (missing-agent-label)
Disposition	skipped (transient)
Gate	success
Tasks	0/7 complete
Keepalive	❌ disabled
Autofix	❌ disabled

🔍 Failure Classification

github-actions · 2026-01-09T16:28:23Z

🤖 Keepalive Loop Status

PR #700 | Agent: Codex | Iteration 0/5

Current State

Metric	Value
Iteration progress	[----------] 0/5
Action	wait (missing-agent-label)
Disposition	skipped (transient)
Gate	success
Tasks	0/7 complete
Keepalive	❌ disabled
Autofix	❌ disabled

🔍 Failure Classification

@codex

…ment When PRs are created from issues labeled with agent:codex, the template was posting @codex start comments which triggered the UI agent. However, the CLI keepalive loop already handles codex PRs through the workflow system. Having both agents run simultaneously causes conflicts. This fix: - Skips post_agent_comment for agent:codex (CLI keepalive handles it) - Keeps post_agent_comment for other agents like agent:claude - Preserves workflow_dispatch behavior for manual overrides Supersedes PR #701 (which had unrelated commits mixed in) Addresses P2 issue raised in PR #700 review comment. See docs/keepalive/Agents.md for CLI vs UI agent distinction.

@codex

…ment (#705) When PRs are created from issues labeled with agent:codex, the template was posting @codex start comments which triggered the UI agent. However, the CLI keepalive loop already handles codex PRs through the workflow system. Having both agents run simultaneously causes conflicts. This fix: - Skips post_agent_comment for agent:codex (CLI keepalive handles it) - Keeps post_agent_comment for other agents like agent:claude - Preserves workflow_dispatch behavior for manual overrides Supersedes PR #701 (which had unrelated commits mixed in) Addresses P2 issue raised in PR #700 review comment. See docs/keepalive/Agents.md for CLI vs UI agent distinction.

stranske added 2 commits January 9, 2026 14:20

Copilot AI review requested due to automatic review settings January 9, 2026 15:06

stranske temporarily deployed to agent-high-privilege January 9, 2026 15:06 — with GitHub Actions Inactive

Copilot started reviewing on behalf of stranske January 9, 2026 15:06 View session

Copilot AI reviewed Jan 9, 2026

View reviewed changes

chatgpt-codex-connector bot reviewed Jan 9, 2026

View reviewed changes

templates/consumer-repo/.github/workflows/agents-issue-intake.yml Show resolved Hide resolved

Merge branch 'main' into fix/auto-start-issue-triggered-prs

8ab96fc

stranske temporarily deployed to agent-high-privilege January 9, 2026 15:10 — with GitHub Actions Inactive

stranske mentioned this pull request Jan 9, 2026

fix: prevent dual-agent conflict for codex in consumer template #701

Closed

Merge branch 'main' into fix/auto-start-issue-triggered-prs

4691569

stranske temporarily deployed to agent-standard January 9, 2026 16:17 — with GitHub Actions Inactive

Merge branch 'main' into fix/auto-start-issue-triggered-prs

3515688

stranske temporarily deployed to agent-standard January 9, 2026 16:28 — with GitHub Actions Inactive

stranske merged commit 7f85af5 into main Jan 9, 2026
93 checks passed

stranske deleted the fix/auto-start-issue-triggered-prs branch January 9, 2026 16:29

stranske mentioned this pull request Jan 9, 2026

fix: prevent dual-agent conflict for codex by skipping post_agent_comment #705

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Clarify CLI vs UI agent distinction in keepalive system#700

docs: Clarify CLI vs UI agent distinction in keepalive system#700
stranske merged 5 commits intomainfrom
fix/auto-start-issue-triggered-prs

stranske commented Jan 9, 2026 •

edited by agents-workflows-bot bot

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

github-actions bot commented Jan 9, 2026

Uh oh!

github-actions bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	# Agent bridge mode: Call the Workflows repo reusable issue bridge
	bridge:
	needs: [route, check_labels]
	if: \|
	needs.route.outputs.should_run_bridge == 'true' &&
	needs.check_labels.outputs.should_run == 'true'
	uses: stranske/Workflows/.github/workflows/reusable-agents-issue-bridge.yml@main
	with:
	agent: ${{ needs.check_labels.outputs.agent }}
	issue_number: ${{ needs.check_labels.outputs.issue_number }}
	mode: "create"
	post_agent_comment: ${{ github.event_name == 'workflow_dispatch' && (inputs.post_codex_comment && 'true' \|\| 'false') \|\| 'true' }}
	agent_pr_draft: ${{ inputs.bridge_draft_pr && 'true' \|\| 'false' }}

Conversation

stranske commented Jan 9, 2026 • edited by agents-workflows-bot bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Automated Status Summary

Scope

Problem

Context for Agent

Design Decisions & Constraints

Related Issues/PRs

References

Tasks

Acceptance criteria

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

github-actions bot commented Jan 9, 2026

Uh oh!

github-actions bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Keepalive Loop Status

Current State

🔍 Failure Classification

Uh oh!

github-actions bot commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Keepalive Loop Status

Current State

🔍 Failure Classification

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

stranske commented Jan 9, 2026 •

edited by agents-workflows-bot bot

Loading

github-actions bot commented Jan 9, 2026 •

edited

Loading

github-actions bot commented Jan 9, 2026 •

edited

Loading