Add CI concepts to the forge layer so builders read failure reasons instead of dumping logs into context

[pseudoseed]

codev has no CI concept at all. KNOWN_CONCEPTS in lib/forge.ts lists 18 concepts and none of them touch workflow runs. So when a builder needs to know why CI failed, it shells out to whatever it can and pastes log output into its context.

That is expensive and it is the wrong shape. A builder does not need the log. It needs the failing job, the failing step, and the assertion or error text. Everything else is noise it pays for.

Both providers already support this

GitHub, via gh:

• gh run list --branch X --status failure --json ...
• gh run view <id> --log-failed — already returns only failed steps

Forgejo/Gitea, via tea (verified on the installed CLI, 2026-08-21):

tea actions runs list --status failure --branch <b> --output json
tea actions runs view <id>
tea actions runs logs <id> [--job <id>] [--output json]

list filters by success, failure, pending, queued, in_progress, skipped, canceled and by branch. logs takes an optional --job, so a script can fetch only the failing job rather than the whole run.

Note the asymmetry: gh has --log-failed and does the extraction for you; tea does not, so the gitea script has to select the failing job itself and trim.

Proposed concepts

Concept	Inputs	Output
ci-runs	CODEV_BRANCH_NAME (opt), CODEV_CI_STATUS (opt)	JSON array of runs: id, name, status, conclusion, branch, sha, url
ci-run-view	CODEV_CI_RUN_ID	JSON: run detail plus per-job status
ci-failures	CODEV_CI_RUN_ID	JSON array of failures: job name, step name, and ONLY the failing output

ci-failures is the one that matters. It should return a bounded extract, not a log. Cap it (a few KB per failing step) and say in the output when it truncated, so a builder knows to go look rather than assuming it saw everything.

Why this is worth doing

A builder currently burns a large part of its context on log text to find one assertion. That context is the scarce resource. We watched a builder today spend two rounds on a bug because it could not cheaply see what the real failure was.

It also removes a class of guessing. Twice today, CI state was misread: once when I claimed a branch fixed a failing job when the job was flaky, and once when a green run was assumed to mean the installed build was current. A concept that returns structured run state makes those checkable instead of inferred.

Notes

• Implement for github and gitea in this fork. gitlab can follow or stay unimplemented (null in the preset) — it should degrade loudly, not silently.
• Add to KNOWN_CONCEPTS in lib/forge.ts and give each provider a script under scripts/forge/<provider>/.
• Bound every call with a timeout. A CI API that hangs must surface as an error, not a stuck phase. See Forgejo/Gitea forge parity: implement pr-search and pr-diff, fix the pr-exists hang #12, where pr-exists hangs with no output.
• Depends on nothing in Forgejo/Gitea forge parity: implement pr-search and pr-diff, fix the pr-exists hang #12, but the same person should probably do both since it is the same layer.

[pseudoseed]

Design notes before implementing

The naive version of this is tea actions runs logs | tail -50. That is wrong, and worth saying why up front.

Tailing gets the wrong lines

A failing test run prints the assertion, then a summary, then the runner exit noise. The last 50 lines are usually npm ERR! code 1 and a stack of node internals. The payload is in the middle. Extraction has to search, not truncate.

Tier the concepts so a cheap question stays cheap

A builder asks about CI at four different moments, and they cost very different amounts:

Question	What it needs	Should it fetch logs?
Did my push pass?	status per job	No
Is it still running?	status plus which jobs are pending	No
It failed, why?	failing job, step, error text	Yes, one job only
Is this mine or pre-existing?	same job on other commits or base branch	No

Only the third fetches a log. If ci-runs returns status cheaply, the common case never pays. Getting this wrong means every status check drags a log through a context window.

Extraction, in priority order

1. Recognize the runner. vitest and jest emit FAIL <path> > <test name> and AssertionError: expected X to be Y, plus a Test Files N failed summary. tsc emits error TS####:. Those lines ARE the answer. Match them and return them.
2. First error, with context. No recognized runner: find the FIRST line matching an error pattern and return it with a few lines either side. First, not last, because later errors are usually consequences of the first.
3. Give up honestly. Nothing matched: say so.

Never let a trimmed extract read as complete

This is the important one. If extraction finds no recognizable failure, it must NOT return the last N lines and let that pass as the cause. Return something explicit:

{ "extracted": false, "reason": "no recognized failure pattern", "logLines": 1247, "logUrl": "..." }

A builder that gets 50 arbitrary lines will treat them as the diagnosis and reason from noise. A builder told extraction failed will go read the log. The second is correct and cheaper.

Every response carries logLines, returnedLines, and truncated, so the caller always knows whether it saw everything.

Caps

Cap per step and overall. Suggest 2KB per failing step, 8KB per response. When multiple steps fail, prefer the FIRST failing step in the first failing job. Later failures are usually downstream.

Answering "is it mine or flaky"

ci-runs should be able to list recent runs of the same workflow filtered by job conclusion, so a builder can see whether a job also fails on other commits. This is not hypothetical. On 2026-08-21 I twice drew a wrong conclusion from CI: once treating a flaky job as fixed by a branch, once treating green as proof the installed build was current. Both were answerable from run history and neither was checked because it was awkward to ask.

Caching

A completed run log is immutable. Cache extracts by run id and job id. Repeat questions about the same failure should cost nothing.

Provider notes

gh run view --log-failed already does step selection, so the GitHub script gets structured input and only needs extraction. tea actions runs logs does not, so the gitea script must first call runs view to find the failing job id, then fetch that job alone. Do not fetch all jobs and filter locally, that is the thing this issue exists to avoid.

[pseudoseed]

Escape hatch: a separate raw-log concept

Correcting a gap in the notes above. I said extraction failure should return a log URL. A builder cannot cheaply read a URL behind auth, so that leaves it stuck. It needs a way to fetch raw log slices.

Make it a SEPARATE concept, ci-run-log, not a flag on ci-failures. If tail is a parameter on the main call, callers will pass it by habit and every status question drags a log again, which is what this issue exists to prevent. Separate concept means reaching for it is a deliberate act.

ci-run-log

Inputs: CODEV_CI_RUN_ID, CODEV_CI_JOB_ID (opt), and exactly one window:

Var	Meaning
CODEV_CI_LOG_TAIL	last N lines. The common case, and what a builder wants when a process died with output at the end
CODEV_CI_LOG_HEAD	first N lines. Setup, dependency install, and config failures live here
CODEV_CI_LOG_GREP	lines matching a pattern, with CODEV_CI_LOG_CONTEXT lines either side (default 3)

Three knobs, not a query language. Between tail, head, and grep-with-context you can chase essentially any failure, and anything more elaborate is better done by a human reading the run in a browser.

Always return logLines, returnedLines, from, to, so a builder knows where in the log it is looking and whether more exists. Cap the response the same way as ci-failures and mark truncation explicitly.

How the two compose

The intended flow, and ci-failures should return enough to make the second call targeted:

1. ci-failures <run> — usually enough, returns the assertion.
2. If it returns extracted: false, it still carries jobId, jobName and logLines. The builder then calls ci-run-log with that job id and a tail, rather than guessing.

So the failure response is not a dead end, it is a handoff with the parameters already in hand.

Not reinventing anything

This is remote head, tail and grep -C over a log. Deliberately so. The value codev adds is doing it against two forge APIs with one contract and bounded output, not inventing log analysis. Where a provider already does the work, use it: gh run view --log-failed already selects failed steps, so the GitHub script should not re-derive that.

[pseudoseed]

On it! Working on this with the PIR protocol (plan + dev-approval gates before PR).