Limitations (v1)

Known limitations of the current design, from the README and day-to-day experience.

Interaction model

• Pull-request comments are ignored. The natural place for a future reviewer agent, but today nothing listens there — discuss in the issue instead.
• One build label = one full rebuild. Build runs force-push agent/issue-N; there is no incremental follow-up on an existing PR.

Deployment constraints

• The factory repo must be public on the instance for cross-repo reusable workflows (uses: owner/repo/...) to resolve. Behind a firewall this only means anonymous readability. If that is unacceptable, copy .forgejo/workflows/agent.yml + glue/ into each project and drop the indirection.
• Container images are pinned by tag and cached by the runner — an updated image never auto-reaches projects; push a new tag and update the workflow input.

Operations

• No cost dashboards yet. Check opencode stats inside a job or the run logs.
• Batch CI model latency. Each hop starts a fresh container (~1 min); not suited to tight back-and-forth loops.
• issue_comment only triggers workflows on the default branch. Workflows on other branches never fire on comments.

Agent behavior

• Plan replies can lose the spec block. The glue appends a visible NOTE when that happens; ask the agent to re-include the markers — the next reply self-heals.
• Spec selection is strictly "last block wins." An old spec block pasted late in the thread silently overrides newer discussion.

Trigger quirks (observed on the live pipeline)

• Automatic triggers fire but the agent skips its work. When the thin per-project workflow delegates through uses:, the glue sees the event as workflow_call/<action> instead of the original issues / issue_comment event. In mode: auto it cannot infer plan vs build and exits with not addressed to the agent (unhandled event workflow_call/created) — skipping. Until this is fixed (see ai-factory#1), trigger runs with the manual workflow_dispatch and pass mode explicitly.
• The agent job's logs are not retrievable via API (GET /repos/{o}/{r}/actions/jobs/{id}/logs returns HTTP 500 for that job). The duplicated agent-1 job carries the full log — read that one.

Build-agent footgun: orphaned background servers

Three consecutive build runs on an Express bootstrap failed identically: the agent wrote correct code and its smoke test passed (HTTP 200 on the target endpoint), but it left the server running in the background. The orphaned process held the shell's stdout/stderr open, opencode's shell tool killed the command at its timeout (30 s, then 60 s on retry), and opencode died "with status null" — the glue marked the whole run failed and the completed work was lost with the ephemeral workspace.

• kill $SERVER_PID when the server was started via npm start & kills npm, not the node child — the orphan survives.
• Thread comments warning the agent helped with side decisions but did NOT reliably change the smoke-test pattern.
• What worked: editing the spec block (the designed human-repair mechanism) to add an explicit "Validation: static checks only — do NOT start the server" section. The next build run complied and produced a mergeable PR.
• Structural fixes are collected in ai-factory#1 (event inference under workflow_call; standing no-background-processes guidance; salvage-and-push when opencode crashes after writing files).