[Bugfix #1137] Fix gitea forge preset against the real tea CLI

[pseudoseed]

Fixes#1137.

Bugfix-protocol re-do of the earlier SPIR-style PR #1138 (now closed), per maintainer request. Same root cause, plus a real regression test.

Problem

The gitea forge preset was authored against the Gitea REST API JSON shape, but the scripts invoke the tea CLI, whose output shape differs — and several concepts referenced flags/fields/subcommands tea doesn't have. Per the in-repo #920 note, tea wasn't available in the authoring environment, so the preset was never run end-to-end.

Fix

Route the read concepts through tea api (raw REST passthrough returning the shape forge-contracts.ts + the jq normalizers expect):

• user-identity: tea api user | jq .login (tea whoami has no --output json)
• pr-view: tea api repos/<repo>/pulls/N → PrViewResult (incl. additions/deletions)
• pr-list: tea api repos/<repo>/pulls?state=open → PrListItem[]
• pr-exists: tea api repos/<repo>/pulls?state=all with nested .head.ref / .merged
• issue-view: tea api repos/<repo>/issues/N + a second call for the comments array (Gitea reports comments as an int count, which would crash .comments.filter(...))
• recently-merged: tea api repos/<repo>/pulls?state=closed, filter .merged, using real .merged_at
• issue-comment: tea comments add (tea issues has no comment subcommand)

tea api needs an explicit owner/repo path segment, so each api-based script derives owner/repo from the origin remote (honoring CODEV_REPO when set).

Testing

• New regression test stubs a fake tea on PATH answering api <endpoint> with captured Gitea REST fixtures (tea isn't in CI, per vscode: editor-tab webview for rich backlog search #920), runs each real script, and asserts the normalized output conforms to forge-contracts.ts — incl. comments-as-array, merged-only filtering, open/merged/closed pr-exists, and CODEV_REPO override.
• Updates the pr_exists porch check fails when PR is merged before gate approval #568pr-exists assertion for the new state=all query param.
• Full suite green locally: build ✓, 3443 tests pass.

🤖 Generated with Claude Code

---

Rebased onto main (2026-08-14)

This branch was 2063 commits behind and mergeable=CONFLICTING. Rebased onto upstream/main; force-pushed to the fork. All 5 original commits preserved.

Exactly one file conflicted, twice — scripts/forge/gitea/pr-view.sh.

⚠️ Behaviour change from the conflict resolution: pr-view now emits url

While this branch sat, PIR #1179 landed on main and gave gitea pr-view a url field mapped from Gitea's html_url:

tea pulls view "$CODEV_PR_NUMBER" --output json | jq '.url = (.html_url // .url)'

This PR rewrites that same script onto tea api with an explicit normalizer — which emitted no url at all. Taking either side of the conflict wholesale loses something: take ours and #1179 is silently reverted, take theirs and the tea api fix is lost.

Resolution: both. The script keeps this PR's tea api routing and re-adds url: (.html_url // .url).

So, stated plainly rather than left in the diff: gitea pr-view now returns a url field that the pre-rebase branch did not return. That is a restoration of main's behaviour, not a new invention — forge-contracts.ts documents the Gitea mapping by name ("Gitea html_url — Gitea's url is the API endpoint, do not use it") — but it is a real change to this concept's output versus what this PR previously proposed, so it should not be discovered from the diff.

bugfix-1137-gitea-tea-api.test.ts was updated accordingly: the pulls/42 fixture now carries both html_url and url, and the assertion pins that the browser page, not the API endpoint, is what reaches the contract.

Two smaller deliberate deviations

• _lib.sh is committed 100755, not 100644.scripts/postinstall.mjs chmods every scripts/forge/**/*.sh to 755 unconditionally, so 644 is a mode that never survives an install and leaves a permanently dirty worktree for anyone who runs pnpm install. The file is sourced, not executed; the bit is inert.
• The test-fixture update was applied inside the test commit (via an interactive rebase stop) rather than as a trailing fixup, so every commit is green in isolation — verified by checking out and testing all 5 individually.

Relationship to #1458

#1458 (pr-create as a forge concept) landed while this PR was open, and its gitea pr-create.sh looked the new PR up with tea pulls list --limit 200 — the exact call this PR proves silently truncates. That has been fixed on #1458's branch, not here: it now creates via tea api -X POST …/pulls, which returns the created PR directly, so the lookup is gone rather than paginated.

Re-confirmed live against Forgejo 15.0.2 while doing so: settings/api reports max_response_items: 50, and a ?limit=200 request returns exactly 50 items on a list where paging at 50 returns 53. The premise behind this PR's pagination work holds.

Merge-order implications are spelled out in full at the end of this description.

Verification

• All 5 commits pass the forge suites individually (bugfix-1137-gitea-tea-api, bugfix-568-pr-exists-state-all, forge, bugfix-693-forge-exec-bit).
• Full @cluesmith/codev unit suite, rebased tip: 3193 passed, 126 failed (67 files).
• Baseline run of the same suite on unmodified upstream/main in the same worktree: 3176 passed, 126 failed (67 files) — the same 67 files and the same 126 tests.
• So: zero regressions; this branch adds 17 passing tests and breaks nothing. The pre-existing failures are all agent-farm / terminal / consolidate (attach, session-manager, shellper sockets, SQLite state), environment-dependent — this worktree has no built dist/, which those tests spawn from, and a live Tower is running against the same state. None is in a file this PR touches, and every forge suite passes.

Merge order with the sibling PR — verified, not assumed

#1146 and #1458 come from the same fork and both touch packages/codev/scripts/forge/gitea/, so the ordering question is fair. The answer:

Either order is safe. There is no dependency and no conflict.

Question	Answer	How it was checked
Do they conflict?	No.	git merge-tree on the two branch tips merges cleanly. The only file both touch is the builder thread log, which is the identical blob on both branches and auto-merges.
Must one merge first?	No.	#1458's pr-create.sh does not source _lib.sh and does not call gitea_repo or tea_api_paged. Nothing in it resolves against #1146.
Does the merged result hold together?	Yes.	In the merged tree, _lib.sh and pr-view.sh are byte-identical to #1146's versions and pr-create.sh byte-identical to #1458's — no silent blending. The bugfix-693 invariant (every entry under each provider dir is a *.sh) still holds with _lib.sh present.

Does #1458 duplicate something #1146 makes shared?

The paginator: no, and it shouldn't._lib.sh#tea_api_paged exists to walk a truncating list endpoint. pr-create no longer lists anything — it reads the new PR out of the create response — so there is no pagination for it to share. That is the point of the reconcile rather than an oversight.

Repo resolution: yes, there are two paths, and this is worth a follow-up.

• [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146's read concepts: . _lib.sh → gitea_repo(), which honours CODEV_REPO, else derives owner/repo from the origin remote, and fails fast naming CODEV_REPO as the remedy.
• [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458's pr-create: tea's own {owner}/{repo} placeholders, with CODEV_PR_REPO forwarded as tea --repo.

They were kept separate deliberately, for two reasons rather than by omission:

1. Different contract.pr-create takes CODEV_PR_REPO; the read concepts take CODEV_REPO. gitea_repo() reads the latter and takes no argument, so pr-create could not call it without changing its signature — which would mean editing a [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146 file from [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 and creating exactly the merge-order coupling this avoids.
2. --repo does more than fill a path. It also supplies tea's repo/login context, verified working from a cwd whose remote is not a Gitea host. A path-only helper does not do that.

Recommended follow-up (not done here, deliberately): once both PRs have landed, unify the two behind one helper that takes the override variable as a parameter — e.g. gitea_repo "$CODEV_PR_REPO" — so there is one repo-resolution path with one error message. Doing it now would couple two independent PRs; doing it never leaves two paths that will drift. It is a small, mechanical change against a tree where both are already present.

The one ergonomic gap that split created has been closed in the meantime: an unresolvable repo used to surface from pr-create as a bare 404 page not found, and now names CODEV_PR_REPO as the remedy, matching gitea_repo()'s fail-fast message.

[waleedkadous]

Excellent work — thank you for the disciplined re-do, and apologies for the review latency. This is what a model bugfix PR looks like: every tea-CLI deficiency documented in-script with reasoning, the REST passthrough returning exactly the shape forge-contracts.ts expects, and a genuinely well-built regression suite (fake tea on PATH serving captured REST fixtures, the real scripts executed, contract-shape assertions, the comments-as-int crash and null-login team reviewers both covered). We verified every output mapping field-by-field against the contracts — all conform — and the switch from string-interpolated jq to --arg in pr-exists is a quiet security improvement worth crediting.

One substantive question before merge, and two optional polish items:

1. Pagination cap (the one we'd like addressed or answered). Gitea servers cap page size at max_response_items (default 50), so ?limit=200 likely returns 50 items with no client-side pagination in the raw passthrough. That means pr-exists?state=all can false-negative for a branch whose PR isn't in the most recent ~50 (which would block a porch pr_exists gate), and recently-merged (previously --limit 1000) can miss on a busy repo. A pagination loop (page=1..N until a short page) would settle it — or at minimum a comment documenting the server-side cap and the false-negative window, so the next debugger isn't blind. Happy with either; we'd just like the behavior to be chosen rather than inherited.

2. (Polish, optional) With no origin remote or an unusual URL, REPO silently becomes empty/garbage and tea api "repos//…" fails with a confusing 404. An explicit [ -n "$REPO" ] || { echo "…set CODEV_REPO" >&2; exit 1; } naming the remedy would fit this repo's fail-fast convention — ideally factored once since the derivation appears in five scripts.

3. (Polish, optional) A failed comments fetch silently yields comments: [] — indistinguishable from "no comments" for consumers reading issue discussion. A stderr warning on the degraded path would keep the graceful behavior while leaving a trace.

Verdict: approve once item 1 is addressed (fix or documented caveat — your choice). Items 2–3 are welcome in this PR or a follow-up, contributor's choice.

[pseudoseed]

Thanks for the thorough review — all three items addressed in 3c2e3c2b.

1. Pagination — fixed (real page loop, not a comment). You're right that ?limit=200 inherited Gitea's max_response_items cap (default 50) and silently truncated. Added a shared tea_api_paged helper in a new scripts/forge/gitea/_lib.sh that requests page=1,2,3… at an explicit limit=50, concatenates each page's array (jq -s add), and stops when a page comes back shorter than the limit (or empty). Chosen behavior: it paginates, with a hard ceiling of 100 pages (100 × 50 = 5000 items) so a misbehaving server can't spin forever — documented in the helper. Wired into all three list reads: pr-exists (state=all), pr-list (state=open), recently-merged (state=closed). Output shape is unchanged — the concatenated array feeds the existing jq normalizers untouched. New tests serve a full 50-item page 1 + a short page 2 and assert an item that exists only on page 2 is found by each of the three scripts (pr-exists returns true for it, pr-list/recently-merged include it).

2. REPO fail-fast, factored once — done. The CODEV_REPO/origin-derivation line (duplicated in five scripts) now lives in _lib.sh#gitea_repo, sourced via . "$(dirname "$0")/_lib.sh" by issue-view, pr-exists, pr-list, pr-view, and recently-merged. It validates the result is a clean owner/repo; if not (no origin, unusual URL), it prints set CODEV_REPO=owner/repo to stderr and exits non-zero instead of letting tea api "repos//…" 404. Verified before factoring: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist (a leading-underscore file is never registered as a concept), package.jsonfiles ships scripts/forge so _lib.sh is packaged, it's POSIX sh (no bashisms), and $0-relative sourcing works when the script is invoked by absolute path (how forge runs it via sh -c). Tests cover missing-origin and garbage-URL → non-zero exit + the stderr remedy.

3. Degraded comments warn — done.issue-view still degrades a failed comments fetch to [], but now writes gitea forge: comments fetch failed for issue N; reporting 0 comments to stderr while stdout stays pure JSON. Test asserts both (comments: [] on stdout and the stderr warning).

Full suite green in the worktree: 3449 passed | 48 skipped, 0 failures (pnpm build + pnpm test). The #568pr-existsstate=all assertion stays green (the helper is still called with state=all).

[pseudoseed]

@waleedkadous let me know if there's anything else that needs to be addressed with this one :)

[pseudoseed]

Verified against a real Forgejo + tea — all six concepts pass

The PR notes that tea wasn't available in the authoring environment and the preset was never run end to end. It has now been. I ran this branch's scripts against a live Forgejo instance with tea 0.14.2, on a repo with ~355 issues and ~350 PRs.

Environment: Forgejo, tea 0.14.2 (go-sdk v1.1.0), single configured login, scripts invoked directly with CODEV_REPO set.

Before — released version, same environment

concept	result
user-identity	FAILIncorrect Usage: flag provided but not defined: -output
issue-view	FAILjq: Cannot index array with string "html_url"
pr-list	FAIL, exit 0 — prints Error: invalid field 'description' and still returns success
recently-merged	FAIL, exit 0 — same
pr-view	returns a list, not the requested PR
issue-list, issue-search, pr-exists, recently-closed, auth-status	OK

The two exit-0 cases are the nastiest: a caller checking the exit status sees success and gets an error string where JSON should be.

After — this branch, same environment

concept	result
user-identity	OK — user
issue-view	OK — object with title, body, state, url, comments[]
pr-list	OK — normalized PrListItem[]
pr-view	OK — single PR object, correct one
pr-exists	OK — true
recently-merged	OK — merged-only, correct merged_at ordering

All six previously-broken concepts now work. No regressions in the five that already worked.

Two notes

The comments-as-int catch is real and would have bitten immediately. Gitea returns comments as an integer count on the issue object; our issue-view on the released version failed exactly there. The second call for the comments array is necessary, not defensive.

One nearly-false report from me, worth stating so nobody repeats it. My first run of this branch's issue-view failed with Cannot index array with string "title". That was my harness, not your code — I had exported CODEV_ISSUE_NUMBER where the contract is CODEV_ISSUE_ID, so the path resolved to the issue list endpoint. With the correct variable it works. Flagging it because the failure mode is plausible-looking and someone else testing this could draw the wrong conclusion.

Unrelated gap this surfaced

pr-create is not a forge concept at all, so gh pr create stays hardcoded in the skeleton prompts (porch/prompts/pr.md, protocols/{air,spir,pir,bugfix,maintain}/…). That means a Gitea/Forgejo user still needs a gh shim on PATH no matter how complete this preset becomes. Not this PR's problem — filing separately — but relevant if anyone assumes a working gitea preset makes gh unnecessary.

Happy to re-run against any further revisions.

[amrmelsayed]

Reviewer Integration Review (CMAP-3)

Three-lane consultation (Gemini, GPT-5.6 Sol via Codex, Claude Opus) plus an independent architect pass. Every finding below was re-verified by the reviewing architect against the actual source, and the tea-CLI claims against the installed release binary, before being credited.

Verdict: REQUEST CHANGES (light). The core fix is correct, honestly documented, and the best-evidenced community PR this repo has received: the tea api rerouting, the pagination premise, the #1179 conflict resolution, and the merge-order analysis vs #1458 all check out. Lane split: Gemini APPROVE; Codex and Claude REQUEST_CHANGES. Two items are blocking; the rest are tiered below so nothing has to be rediscovered later.

Verified solid (no action)

• _lib.sh is safely inert as a concept: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist, so a leading-underscore file is never registered. Verified at forge.ts:64.
• $(dirname "$0") sourcing holds in the real call path: executeForgeCommand runs the absolute script path via sh -c.
• package.jsonfiles ships scripts/forge, and the bugfix-693 invariant (every provider-dir entry matches *.sh) still holds with _lib.sh present. The 755-mode argument is correct (postinstall chmods unconditionally).
• All four emitted shapes conform exactly to forge-contracts.ts (PrViewResult, PrListItem, MergedPrItem, IssueViewResult), and the --arg branch switch in pr-exists is a real injection fix.
• Pagination premise re-confirmed: issue gitea forge preset is broken against the real tea CLI (0.14.2) #1137 is still open, no forge-script drift on main since your 08-14 rebase, branch is MERGEABLE.

Blocking

1. issue-comment.sh breaks on the current released tea (0.14.1).tea comments add only exists from tea 0.14.2; on 0.14.1 (current Homebrew release) it exits with No help topic for 'comments'. Verified against the installed 0.14.1 binary and the tea source at both tags: tea comment "$CODEV_ISSUE_ID" "$CODEV_COMMENT_BODY" exists on 0.14.1 and is explicitly preserved as a shorthand in 0.14.2+, so it works on every version. This slipped through because issue-comment is the one concept absent from the live-verification tables (that run used tea 0.14.2), and the fake-tea stub implements comments add by fiat, pinning the assumption rather than testing it. One-word fix plus updating the stub to answer comment instead.

2. Paginator failure exits 0 with empty stdout, which reads as a false-negative pr_exists gate.tea_api_paged's return 1 sits on the left of a pipe in POSIX sh (no pipefail), so the script's exit status is jq's (0) and stdout is empty. Porch's pr-exists check (checks.ts:365) maps anything that isn't "true" to passed: false, so a transient failure mid-walk reports "no PR exists": the exact failure mode pagination was added to prevent. Fix in all three list scripts by capturing first:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

This also converts the jq -s add raw-type-error wart you flagged in the thread log into a clean non-zero exit.

Strongly recommended in this PR (both small, both introduced here)

3. codev doctor regression for gitea users.extractExecutable (forge.ts:192) skips comments, if, and assignments, but not dot-sourcing: the first substantive token in the five sourced scripts is ., and which . fails, so doctor shows five false "not found" rows and stops verifying tea for those concepts. Note the fix is not just skipping .: after the source line and the REPO= assignment are skipped, the next token in the three list scripts is tea_api_paged (a shell function), which also fails the which check. The extraction needs to resolve through sourced-helper calls (or the gitea preset needs declared executables), plus a test; no existing test covers this path, which is why the suite stayed green.

4. The stop condition trusts that the server honored limit=50.max_response_items is admin-tunable; on a server capped below 50, every page is "short", the loop breaks after page 1, and silent truncation returns on exactly the servers that tuned the cap. Derive the effective page size from page 1's item count and break when a page is shorter than that (or stop only on an empty page, at the cost of one extra request per walk). Worth a test with a sub-50 cap.

Maintainer's call: in-PR or filed as follow-ups

• recently-merged ignores CODEV_SINCE_DATE and now walks the full closed-PR history (up to 100 sequential requests, 2 jq spawns per page) inside forge's 30s timeout (forge.ts:323). On a large Gitea repo that risks timeout, and a timeout yields null: a worse dashboard outcome than truncation was. An early-exit on the since-date or a tighter page bound for this concept would cover it.
• Non-paged reads don't validate tea api's exit-0-on-error responses. An HTTP error body piped into the pr-view/issue-view/user-identity normalizers emits a structurally valid all-null contract object at exit 0. [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 guards this exact mode explicitly, so the two halves of the preset currently disagree about a documented behavior. Same class: issue-view's comments degrade path only handles a blank response, not an error-object one (--argjson then fails with a raw jq error instead of the warned [] degrade).

Follow-up issues to file after merge (none blocking)

• The preset is now two idioms: issue-list / issue-search / recently-closed still use tea pulls|issues list --fields … --limit 200/1000 with the same truncation premise this PR disproves. Migrate them onto tea api + tea_api_paged.
• Repo-resolution unification (already proposed in the PR body) should absorb a third path: repo-archive.sh uses bare ${CODEV_REPO} with no fail-fast.
• forge-contracts.ts doc drift: the reviewRequests comment still says "GitLab/Gitea emit []", but gitea now populates real reviewer logins.
• Test gaps: no 3+ page walk, no mid-walk failure, no sub-50 server cap.
• _lib.sh creates a sibling-file dependency for hand-copied .codev/scripts/forge/gitea/ overrides; worth a line in the header.

Process notes

• The rebase documentation is exemplary: the vscode: one-step 'view issue N' / 'view pr N' from QuickPick + Cmd+K P for direct PR-by-ID open #1179url restoration, the 755 mode rationale, and the per-commit green verification were all stated up front and all verified true.
• Merge order vs [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 confirmed independent; either order is safe. The [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 reconcile (dropping list-and-search in favor of reading the create response) is the right shape.

Merge authority rests with the maintainer; this review is the reviewing architect's recommendation, not a gate approval.

[amrmelsayed]

Follow-up from the reviewing architect: finding 3 just got smaller

Merge order has been ruled by the maintainer: #1458 first, then this PR.

That changes the shape of one item in the review above. #1458 ships a # forge-executable: <tool> declaration that extractExecutable honours ahead of its first-substantive-line heuristic. With #1458 merged first, the "strongly recommended" finding 3 (the codev doctor regression) collapses to adding one line to each of the five sourced scripts:

#!/bin/sh# Forge concept: pr-exists (Gitea via tea CLI)# forge-executable: tea

The deeper extraction work the review asked for (resolving through sourced-helper calls, plus a test) is not required of you — that burden moved to #1458's mechanism, and a hardening addition to its builtin skip list is being pressed on that PR separately.

Everything else stands as written, and none of it waits on #1458: the two blockers (tea comment on 0.14.1, and capture-first in the three paginated scripts so a mid-walk failure can't read as a false-negative pr_exists gate) can be fixed now in either order. Finding 4 (the sub-50 max_response_items stop condition) is likewise independent.

[pseudoseed]

Review follow-up (2026-08-20)

Addressed both blocking items and the strongly-recommended item from the 2026-08-17 review, pushed as c9f55a537 (+ 481956e12 for the builder thread log):

1. (blocking) issue-comment.sh — tea comments add doesn't exist on 0.14.1
tea comments add is a 0.14.2+-only subcommand and fails on the still-current 0.14.1 release ("No help topic for comments"). Switched to the top-level tea comment <id> <body> shorthand, which works on both 0.14.1 and 0.14.2+.

2. (blocking) masked pipe failures in the paginated scripts
pr-exists.sh, pr-list.sh, and recently-merged.sh piped tea_api_paged | jq directly. POSIX sh has no pipefail, so a mid-walk pagination failure (tea_api_paged returning 1) was masked by jq's exit status — jq exits 0 on empty stdin, so pr-exists in particular would print "false" for a real API failure instead of erroring. That's a silent false-negative that could pass a porch pr_exists gate on a genuine error rather than an absent PR.

Fixed by capturing the paginator's output into a variable and checking its exit status before piping to jq:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

3. (strongly recommended, done) sub-limit server cap
tea_api_paged's stop condition compared each page's item count against the requested limit (50). A server whose max_response_items is tuned below that requested limit truncates every page — including non-last pages — to its own cap, so every page looked "short" against 50 and the loop broke after page 1, silently missing pages 2+. Now compares against the size actually observed on page 1 instead, so it keeps walking until a page is genuinely shorter than what the server has been returning.

4. (deferred, not done in this PR)
The # forge-executable: tea header convention depends on #1458 landing extractExecutable's header-parsing support first. Checked — #1458 is still open/unmerged, so this isn't actionable yet. Left as a follow-up once #1458 merges, matching the merge order already noted in the PR description (#1458 first, then this PR).

Testing

Added regression coverage for all three fixes in bugfix-1137-gitea-tea-api.test.ts:

• Updated the fake-tea stub to answer comment (not comments add).
• A mid-walk pagination failure fixture (full page 1, erroring page 2) exercised against all three paginated scripts — asserts non-zero exit and empty stdout rather than a silently wrong/empty result.
• A 3-page sub-50-per-page-cap fixture (30 + 30 + 6 items) proving pr-list keeps walking past a page that's full-but-capped rather than stopping because it's short relative to the requested limit.

Full local suite: 3197 passed, 126 failed (67 files) — the same pre-existing environment-dependent failures (agent-farm/terminal/consolidate; no built dist/ in this worktree) as the unmodified baseline reported earlier in this PR. Zero regressions, +4 new passing tests over the prior 3193.

[waleedkadous]

First — apologies for how long this sat; two months without a review is not how we want to treat a contribution, and this one is good: the real-script fake-CLI suite (contract normalization, pagination past page one, sub-50 server caps, mid-walk failures, tea 0.14.1 comment compatibility) is exactly the evidence this kind of fix needs, and moving branch input through jq --arg is a security improvement. Both integration reviews (codex + claude) agree the core mapping is right. Four things I'd like fixed before merge, all in the same spirit as the fix itself — fail loudly, never silently:

1. codev doctor regression. The five scripts that now source _lib.sh make doctor's executable extractor report . (and later tea_api_paged) instead of tea — verified, which . fails under /bin/sh. #1458 introduces a # forge-executable: tea header declaration for exactly this; please add those five lines here regardless of merge order so the regression can't ship.
2. Silent truncation at GITEA_MAX_PAGES. Reaching 100 pages without seeing a terminal short/empty page returns a partial array at exit 0 — the same false-negative pr-exists class the paginator exists to prevent. Fail explicitly instead.
3. Error bodies normalized into valid-looking output.tea api exits 0 on HTTP errors, and pr-view/user-identity/issue-view normalize without validating the response shape — an error object becomes an all-null PR (pr-view even leaks the error body's url into the contract) or the username null, at exit 0. Validate required fields/types before normalizing; the paginated scripts already fail loudly, so this brings the rest in line.
4. recently-merged.sh ignores CODEV_SINCE_DATE and can issue up to 100 sequential requests inside forge's 30-second timeout — on an established repo that turns the analytics path into null. Honoring the since-date bounds it.

Smaller, take-or-leave: CODEV_REPO is now overloaded (repo-archive's foreign-repo input vs. gitea read targeting) — a line in forge.md and both SKILL.md copies would help; and forge-contracts.ts's reviewRequests/isDraft comments go stale with this PR.

Merge order: #1458 first (it brings the # forge-executable mechanism), then this. Happy to turn the two around quickly once these land — and thank you for sticking with it.

[waleedkadous]

Given how long this waited on us, we'll take the last mile ourselves rather than hand you a list: a builder will push the review items directly onto this branch (you enabled maintainer edits — thank you), your commits and authorship stay as they are, and I'll re-review and merge once green. If you'd rather make the changes yourself, just say so and we'll hold off.

[waleedkadous]

Pushed the review items onto this branch as we offered — four commits on top of yours, nothing rebased or squashed, all ten of your commits and their authorship untouched. Thank you again for the contribution and for the patience; the real-script fake-CLI suite you built is what made all of this cheap to do, and every fix below is a test in your harness.

Also merged main in: #1458 landed, so the # forge-executable: mechanism is live.

The four required items

1. # forge-executable: tea headers. On six scripts, not five. The five that source _lib.sh are the ones the review named, but fixing item 3 in user-identity.sh required capturing tea api user before the jq pipe, which moves tea off the first substantive line — so without a header of its own, that fix would have caused the regression this item closes. Verified against the merged extractExecutable, not a simulation of it: all fourteen gitea concepts now resolve to tea.

2. The page ceiling fails loudly. Reaching GITEA_MAX_PAGES with every page full means we don't know we have the whole list, so it errors rather than returning the partial array at exit 0. One wrinkle worth naming: a list whose length is an exact multiple of the page size hits the ceiling with nothing missing, so it probes one page past before failing — a hard error on a complete result would be its own bug.

3. Shape validation before normalizing. The nastiest part of this one is that Gitea's error bodies carry a url (the swagger link), so url: (.html_url // .url)succeeded on them and shipped that link as the PR's browser page inside an otherwise all-null contract object. Required fields are now type-checked and failures carry the server's own .message on stderr. issue-view is validated before its comments are fetched, so a bad id reports only its own error instead of also warning about degraded comments on an issue that isn't there.

4. recently-merged honors CODEV_SINCE_DATE — it asks for sort=recentupdate and stops at the first page reaching past the cutoff. Details below, because this is where the reviewers earned their keep.

Plus the take-or-leave items: CODEV_REPO's two meanings documented in forge.md and both SKILL.md copies, and the reviewRequests/isDraft comments in forge-contracts.ts corrected — they claimed GitLab and Gitea emit empty/false, but all three presets populate them for real.

What the consultation caught, because it's the interesting part

I first wrote the since-date bound to fire when the current page was non-increasing in updated_at, reasoning that proved the server had honored sort=recentupdate. Both reviewers broke that, and they were right. Gitea's default order is index/created-DESC, and on a repo where PRs are opened and merged in order, index-DESC is non-increasing in updated_at. A long-lived PR opened in January and merged after the cutoff then sits on page 2, and we stop at page 1 and drop it — a silent loss in exactly the analytics path the bound was meant to protect.

The fix is to check for the property we actually need — the ordering — rather than for evidence that we asked for it. A stop now requires the order to survive a page boundary (previous page descending too, its oldest no older than this page's newest) and never fires on page 1, where there's nothing to compare against. A server that ignores the parameter falls back to your full walk: slower, never wrong. Costs exactly one extra request on an honest server.

The other finding I'm glad we ran: passing a page to the stop filter through jq --argjson blows up on Linux. MAX_ARG_STRLEN caps a single argv string at 128KiB regardless of ARG_MAX, and a 50-item Gitea pulls page — every object embedding full base.repo and head.repo — measures ~90KiB before anyone writes a long PR body. macOS has no per-argument cap, so it passed locally and would have failed on CI and for every Linux adopter. Both pages go in on stdin now.

Smaller ones from the same pass: jq length is 0 for both null and {}, so an error body mid-walk looked exactly like an exhausted list; jq on empty stdin emits nothing and exits 0, so two scripts were "succeeding" with empty stdout and never running their validators at all; a non-string .message threw a raw jq error instead of the legible one; and the test env inherited CODEV_* from the developer's shell, so the "no CODEV_SINCE_DATE" test was asserting the absence of a variable it didn't control.

Testing

41 tests in bugfix-1137-gitea-tea-api.test.ts, +20 on what you had. Your fake tea grew error bodies at exit 0 for pulls/issues/user, a comments endpoint answering with an error object and one answering with non-objects, a repo whose pages never end, one whose length is an exact multiple of the page size, ~150KB pages for the argv cap, and the sorted/lagging pair for the since-date bound — acme/lagging is the reviewer's counterexample verbatim.

Full suite after merging main: 5549 passed | 48 skipped, 0 failures. Every script also exercised under dash, which is what /bin/sh is on the CI runner, rather than only bash.

Two follow-ups from the earlier reviews are still unfiled and still worth doing, neither in scope here: migrating issue-list/issue-search/recently-closed off tea <entity> list --limit onto tea_api_paged (same truncation premise this PR disproved), and repo-archive.sh's bare ${CODEV_REPO} with no fail-fast.

Over to @waleedkadous for the re-review.

[waleedkadous]

Re-reviewed after the maintainer-side commits: six # forge-executable: tea headers (verified against the merged extractExecutable — all fourteen gitea concepts resolve to tea), the paginator now fails loudly at the page ceiling with a one-page probe so exact-multiple lists don't false-alarm, non-array error bodies are refused instead of normalized to null, recently-merged honors CODEV_SINCE_DATE with the stop filter fed via stdin (Linux argv cap), plus the docs and stale comments. 41 tests in the contributor's own fake-CLI harness; CI 7/7 green on a6eddb6. Approving and merging — thank you, @pseudoseed, for the contribution and the patience.

[pseudoseed]

Fixes#1137.

Bugfix-protocol re-do of the earlier SPIR-style PR #1138 (now closed), per maintainer request. Same root cause, plus a real regression test.

Problem

The gitea forge preset was authored against the Gitea REST API JSON shape, but the scripts invoke the tea CLI, whose output shape differs — and several concepts referenced flags/fields/subcommands tea doesn't have. Per the in-repo #920 note, tea wasn't available in the authoring environment, so the preset was never run end-to-end.

Fix

Route the read concepts through tea api (raw REST passthrough returning the shape forge-contracts.ts + the jq normalizers expect):

• user-identity: tea api user | jq .login (tea whoami has no --output json)
• pr-view: tea api repos/<repo>/pulls/N → PrViewResult (incl. additions/deletions)
• pr-list: tea api repos/<repo>/pulls?state=open → PrListItem[]
• pr-exists: tea api repos/<repo>/pulls?state=all with nested .head.ref / .merged
• issue-view: tea api repos/<repo>/issues/N + a second call for the comments array (Gitea reports comments as an int count, which would crash .comments.filter(...))
• recently-merged: tea api repos/<repo>/pulls?state=closed, filter .merged, using real .merged_at
• issue-comment: tea comments add (tea issues has no comment subcommand)

tea api needs an explicit owner/repo path segment, so each api-based script derives owner/repo from the origin remote (honoring CODEV_REPO when set).

Testing

• New regression test stubs a fake tea on PATH answering api <endpoint> with captured Gitea REST fixtures (tea isn't in CI, per vscode: editor-tab webview for rich backlog search #920), runs each real script, and asserts the normalized output conforms to forge-contracts.ts — incl. comments-as-array, merged-only filtering, open/merged/closed pr-exists, and CODEV_REPO override.
• Updates the pr_exists porch check fails when PR is merged before gate approval #568pr-exists assertion for the new state=all query param.
• Full suite green locally: build ✓, 3443 tests pass.

🤖 Generated with Claude Code

---

Rebased onto main (2026-08-14)

This branch was 2063 commits behind and mergeable=CONFLICTING. Rebased onto upstream/main; force-pushed to the fork. All 5 original commits preserved.

Exactly one file conflicted, twice — scripts/forge/gitea/pr-view.sh.

⚠️ Behaviour change from the conflict resolution: pr-view now emits url

While this branch sat, PIR #1179 landed on main and gave gitea pr-view a url field mapped from Gitea's html_url:

tea pulls view "$CODEV_PR_NUMBER" --output json | jq '.url = (.html_url // .url)'

This PR rewrites that same script onto tea api with an explicit normalizer — which emitted no url at all. Taking either side of the conflict wholesale loses something: take ours and #1179 is silently reverted, take theirs and the tea api fix is lost.

Resolution: both. The script keeps this PR's tea api routing and re-adds url: (.html_url // .url).

So, stated plainly rather than left in the diff: gitea pr-view now returns a url field that the pre-rebase branch did not return. That is a restoration of main's behaviour, not a new invention — forge-contracts.ts documents the Gitea mapping by name ("Gitea html_url — Gitea's url is the API endpoint, do not use it") — but it is a real change to this concept's output versus what this PR previously proposed, so it should not be discovered from the diff.

bugfix-1137-gitea-tea-api.test.ts was updated accordingly: the pulls/42 fixture now carries both html_url and url, and the assertion pins that the browser page, not the API endpoint, is what reaches the contract.

Two smaller deliberate deviations

• _lib.sh is committed 100755, not 100644.scripts/postinstall.mjs chmods every scripts/forge/**/*.sh to 755 unconditionally, so 644 is a mode that never survives an install and leaves a permanently dirty worktree for anyone who runs pnpm install. The file is sourced, not executed; the bit is inert.
• The test-fixture update was applied inside the test commit (via an interactive rebase stop) rather than as a trailing fixup, so every commit is green in isolation — verified by checking out and testing all 5 individually.

Relationship to #1458

#1458 (pr-create as a forge concept) landed while this PR was open, and its gitea pr-create.sh looked the new PR up with tea pulls list --limit 200 — the exact call this PR proves silently truncates. That has been fixed on #1458's branch, not here: it now creates via tea api -X POST …/pulls, which returns the created PR directly, so the lookup is gone rather than paginated.

Re-confirmed live against Forgejo 15.0.2 while doing so: settings/api reports max_response_items: 50, and a ?limit=200 request returns exactly 50 items on a list where paging at 50 returns 53. The premise behind this PR's pagination work holds.

Merge-order implications are spelled out in full at the end of this description.

Verification

• All 5 commits pass the forge suites individually (bugfix-1137-gitea-tea-api, bugfix-568-pr-exists-state-all, forge, bugfix-693-forge-exec-bit).
• Full @cluesmith/codev unit suite, rebased tip: 3193 passed, 126 failed (67 files).
• Baseline run of the same suite on unmodified upstream/main in the same worktree: 3176 passed, 126 failed (67 files) — the same 67 files and the same 126 tests.
• So: zero regressions; this branch adds 17 passing tests and breaks nothing. The pre-existing failures are all agent-farm / terminal / consolidate (attach, session-manager, shellper sockets, SQLite state), environment-dependent — this worktree has no built dist/, which those tests spawn from, and a live Tower is running against the same state. None is in a file this PR touches, and every forge suite passes.

Merge order with the sibling PR — verified, not assumed

#1146 and #1458 come from the same fork and both touch packages/codev/scripts/forge/gitea/, so the ordering question is fair. The answer:

Either order is safe. There is no dependency and no conflict.

Question	Answer	How it was checked
Do they conflict?	No.	git merge-tree on the two branch tips merges cleanly. The only file both touch is the builder thread log, which is the identical blob on both branches and auto-merges.
Must one merge first?	No.	#1458's pr-create.sh does not source _lib.sh and does not call gitea_repo or tea_api_paged. Nothing in it resolves against #1146.
Does the merged result hold together?	Yes.	In the merged tree, _lib.sh and pr-view.sh are byte-identical to #1146's versions and pr-create.sh byte-identical to #1458's — no silent blending. The bugfix-693 invariant (every entry under each provider dir is a *.sh) still holds with _lib.sh present.

Does #1458 duplicate something #1146 makes shared?

The paginator: no, and it shouldn't._lib.sh#tea_api_paged exists to walk a truncating list endpoint. pr-create no longer lists anything — it reads the new PR out of the create response — so there is no pagination for it to share. That is the point of the reconcile rather than an oversight.

Repo resolution: yes, there are two paths, and this is worth a follow-up.

• [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146's read concepts: . _lib.sh → gitea_repo(), which honours CODEV_REPO, else derives owner/repo from the origin remote, and fails fast naming CODEV_REPO as the remedy.
• [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458's pr-create: tea's own {owner}/{repo} placeholders, with CODEV_PR_REPO forwarded as tea --repo.

They were kept separate deliberately, for two reasons rather than by omission:

1. Different contract.pr-create takes CODEV_PR_REPO; the read concepts take CODEV_REPO. gitea_repo() reads the latter and takes no argument, so pr-create could not call it without changing its signature — which would mean editing a [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146 file from [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 and creating exactly the merge-order coupling this avoids.
2. --repo does more than fill a path. It also supplies tea's repo/login context, verified working from a cwd whose remote is not a Gitea host. A path-only helper does not do that.

Recommended follow-up (not done here, deliberately): once both PRs have landed, unify the two behind one helper that takes the override variable as a parameter — e.g. gitea_repo "$CODEV_PR_REPO" — so there is one repo-resolution path with one error message. Doing it now would couple two independent PRs; doing it never leaves two paths that will drift. It is a small, mechanical change against a tree where both are already present.

The one ergonomic gap that split created has been closed in the meantime: an unresolvable repo used to surface from pr-create as a bare 404 page not found, and now names CODEV_PR_REPO as the remedy, matching gitea_repo()'s fail-fast message.

[waleedkadous]

Excellent work — thank you for the disciplined re-do, and apologies for the review latency. This is what a model bugfix PR looks like: every tea-CLI deficiency documented in-script with reasoning, the REST passthrough returning exactly the shape forge-contracts.ts expects, and a genuinely well-built regression suite (fake tea on PATH serving captured REST fixtures, the real scripts executed, contract-shape assertions, the comments-as-int crash and null-login team reviewers both covered). We verified every output mapping field-by-field against the contracts — all conform — and the switch from string-interpolated jq to --arg in pr-exists is a quiet security improvement worth crediting.

One substantive question before merge, and two optional polish items:

1. Pagination cap (the one we'd like addressed or answered). Gitea servers cap page size at max_response_items (default 50), so ?limit=200 likely returns 50 items with no client-side pagination in the raw passthrough. That means pr-exists?state=all can false-negative for a branch whose PR isn't in the most recent ~50 (which would block a porch pr_exists gate), and recently-merged (previously --limit 1000) can miss on a busy repo. A pagination loop (page=1..N until a short page) would settle it — or at minimum a comment documenting the server-side cap and the false-negative window, so the next debugger isn't blind. Happy with either; we'd just like the behavior to be chosen rather than inherited.

2. (Polish, optional) With no origin remote or an unusual URL, REPO silently becomes empty/garbage and tea api "repos//…" fails with a confusing 404. An explicit [ -n "$REPO" ] || { echo "…set CODEV_REPO" >&2; exit 1; } naming the remedy would fit this repo's fail-fast convention — ideally factored once since the derivation appears in five scripts.

3. (Polish, optional) A failed comments fetch silently yields comments: [] — indistinguishable from "no comments" for consumers reading issue discussion. A stderr warning on the degraded path would keep the graceful behavior while leaving a trace.

Verdict: approve once item 1 is addressed (fix or documented caveat — your choice). Items 2–3 are welcome in this PR or a follow-up, contributor's choice.

[pseudoseed]

Thanks for the thorough review — all three items addressed in 3c2e3c2b.

1. Pagination — fixed (real page loop, not a comment). You're right that ?limit=200 inherited Gitea's max_response_items cap (default 50) and silently truncated. Added a shared tea_api_paged helper in a new scripts/forge/gitea/_lib.sh that requests page=1,2,3… at an explicit limit=50, concatenates each page's array (jq -s add), and stops when a page comes back shorter than the limit (or empty). Chosen behavior: it paginates, with a hard ceiling of 100 pages (100 × 50 = 5000 items) so a misbehaving server can't spin forever — documented in the helper. Wired into all three list reads: pr-exists (state=all), pr-list (state=open), recently-merged (state=closed). Output shape is unchanged — the concatenated array feeds the existing jq normalizers untouched. New tests serve a full 50-item page 1 + a short page 2 and assert an item that exists only on page 2 is found by each of the three scripts (pr-exists returns true for it, pr-list/recently-merged include it).

2. REPO fail-fast, factored once — done. The CODEV_REPO/origin-derivation line (duplicated in five scripts) now lives in _lib.sh#gitea_repo, sourced via . "$(dirname "$0")/_lib.sh" by issue-view, pr-exists, pr-list, pr-view, and recently-merged. It validates the result is a clean owner/repo; if not (no origin, unusual URL), it prints set CODEV_REPO=owner/repo to stderr and exits non-zero instead of letting tea api "repos//…" 404. Verified before factoring: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist (a leading-underscore file is never registered as a concept), package.jsonfiles ships scripts/forge so _lib.sh is packaged, it's POSIX sh (no bashisms), and $0-relative sourcing works when the script is invoked by absolute path (how forge runs it via sh -c). Tests cover missing-origin and garbage-URL → non-zero exit + the stderr remedy.

3. Degraded comments warn — done.issue-view still degrades a failed comments fetch to [], but now writes gitea forge: comments fetch failed for issue N; reporting 0 comments to stderr while stdout stays pure JSON. Test asserts both (comments: [] on stdout and the stderr warning).

Full suite green in the worktree: 3449 passed | 48 skipped, 0 failures (pnpm build + pnpm test). The #568pr-existsstate=all assertion stays green (the helper is still called with state=all).

[pseudoseed]

@waleedkadous let me know if there's anything else that needs to be addressed with this one :)

[pseudoseed]

Verified against a real Forgejo + tea — all six concepts pass

The PR notes that tea wasn't available in the authoring environment and the preset was never run end to end. It has now been. I ran this branch's scripts against a live Forgejo instance with tea 0.14.2, on a repo with ~355 issues and ~350 PRs.

Environment: Forgejo, tea 0.14.2 (go-sdk v1.1.0), single configured login, scripts invoked directly with CODEV_REPO set.

Before — released version, same environment

concept	result
user-identity	FAILIncorrect Usage: flag provided but not defined: -output
issue-view	FAILjq: Cannot index array with string "html_url"
pr-list	FAIL, exit 0 — prints Error: invalid field 'description' and still returns success
recently-merged	FAIL, exit 0 — same
pr-view	returns a list, not the requested PR
issue-list, issue-search, pr-exists, recently-closed, auth-status	OK

The two exit-0 cases are the nastiest: a caller checking the exit status sees success and gets an error string where JSON should be.

After — this branch, same environment

concept	result
user-identity	OK — user
issue-view	OK — object with title, body, state, url, comments[]
pr-list	OK — normalized PrListItem[]
pr-view	OK — single PR object, correct one
pr-exists	OK — true
recently-merged	OK — merged-only, correct merged_at ordering

All six previously-broken concepts now work. No regressions in the five that already worked.

Two notes

The comments-as-int catch is real and would have bitten immediately. Gitea returns comments as an integer count on the issue object; our issue-view on the released version failed exactly there. The second call for the comments array is necessary, not defensive.

One nearly-false report from me, worth stating so nobody repeats it. My first run of this branch's issue-view failed with Cannot index array with string "title". That was my harness, not your code — I had exported CODEV_ISSUE_NUMBER where the contract is CODEV_ISSUE_ID, so the path resolved to the issue list endpoint. With the correct variable it works. Flagging it because the failure mode is plausible-looking and someone else testing this could draw the wrong conclusion.

Unrelated gap this surfaced

pr-create is not a forge concept at all, so gh pr create stays hardcoded in the skeleton prompts (porch/prompts/pr.md, protocols/{air,spir,pir,bugfix,maintain}/…). That means a Gitea/Forgejo user still needs a gh shim on PATH no matter how complete this preset becomes. Not this PR's problem — filing separately — but relevant if anyone assumes a working gitea preset makes gh unnecessary.

Happy to re-run against any further revisions.

[amrmelsayed]

Reviewer Integration Review (CMAP-3)

Three-lane consultation (Gemini, GPT-5.6 Sol via Codex, Claude Opus) plus an independent architect pass. Every finding below was re-verified by the reviewing architect against the actual source, and the tea-CLI claims against the installed release binary, before being credited.

Verdict: REQUEST CHANGES (light). The core fix is correct, honestly documented, and the best-evidenced community PR this repo has received: the tea api rerouting, the pagination premise, the #1179 conflict resolution, and the merge-order analysis vs #1458 all check out. Lane split: Gemini APPROVE; Codex and Claude REQUEST_CHANGES. Two items are blocking; the rest are tiered below so nothing has to be rediscovered later.

Verified solid (no action)

• _lib.sh is safely inert as a concept: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist, so a leading-underscore file is never registered. Verified at forge.ts:64.
• $(dirname "$0") sourcing holds in the real call path: executeForgeCommand runs the absolute script path via sh -c.
• package.jsonfiles ships scripts/forge, and the bugfix-693 invariant (every provider-dir entry matches *.sh) still holds with _lib.sh present. The 755-mode argument is correct (postinstall chmods unconditionally).
• All four emitted shapes conform exactly to forge-contracts.ts (PrViewResult, PrListItem, MergedPrItem, IssueViewResult), and the --arg branch switch in pr-exists is a real injection fix.
• Pagination premise re-confirmed: issue gitea forge preset is broken against the real tea CLI (0.14.2) #1137 is still open, no forge-script drift on main since your 08-14 rebase, branch is MERGEABLE.

Blocking

1. issue-comment.sh breaks on the current released tea (0.14.1).tea comments add only exists from tea 0.14.2; on 0.14.1 (current Homebrew release) it exits with No help topic for 'comments'. Verified against the installed 0.14.1 binary and the tea source at both tags: tea comment "$CODEV_ISSUE_ID" "$CODEV_COMMENT_BODY" exists on 0.14.1 and is explicitly preserved as a shorthand in 0.14.2+, so it works on every version. This slipped through because issue-comment is the one concept absent from the live-verification tables (that run used tea 0.14.2), and the fake-tea stub implements comments add by fiat, pinning the assumption rather than testing it. One-word fix plus updating the stub to answer comment instead.

2. Paginator failure exits 0 with empty stdout, which reads as a false-negative pr_exists gate.tea_api_paged's return 1 sits on the left of a pipe in POSIX sh (no pipefail), so the script's exit status is jq's (0) and stdout is empty. Porch's pr-exists check (checks.ts:365) maps anything that isn't "true" to passed: false, so a transient failure mid-walk reports "no PR exists": the exact failure mode pagination was added to prevent. Fix in all three list scripts by capturing first:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

This also converts the jq -s add raw-type-error wart you flagged in the thread log into a clean non-zero exit.

Strongly recommended in this PR (both small, both introduced here)

3. codev doctor regression for gitea users.extractExecutable (forge.ts:192) skips comments, if, and assignments, but not dot-sourcing: the first substantive token in the five sourced scripts is ., and which . fails, so doctor shows five false "not found" rows and stops verifying tea for those concepts. Note the fix is not just skipping .: after the source line and the REPO= assignment are skipped, the next token in the three list scripts is tea_api_paged (a shell function), which also fails the which check. The extraction needs to resolve through sourced-helper calls (or the gitea preset needs declared executables), plus a test; no existing test covers this path, which is why the suite stayed green.

4. The stop condition trusts that the server honored limit=50.max_response_items is admin-tunable; on a server capped below 50, every page is "short", the loop breaks after page 1, and silent truncation returns on exactly the servers that tuned the cap. Derive the effective page size from page 1's item count and break when a page is shorter than that (or stop only on an empty page, at the cost of one extra request per walk). Worth a test with a sub-50 cap.

Maintainer's call: in-PR or filed as follow-ups

• recently-merged ignores CODEV_SINCE_DATE and now walks the full closed-PR history (up to 100 sequential requests, 2 jq spawns per page) inside forge's 30s timeout (forge.ts:323). On a large Gitea repo that risks timeout, and a timeout yields null: a worse dashboard outcome than truncation was. An early-exit on the since-date or a tighter page bound for this concept would cover it.
• Non-paged reads don't validate tea api's exit-0-on-error responses. An HTTP error body piped into the pr-view/issue-view/user-identity normalizers emits a structurally valid all-null contract object at exit 0. [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 guards this exact mode explicitly, so the two halves of the preset currently disagree about a documented behavior. Same class: issue-view's comments degrade path only handles a blank response, not an error-object one (--argjson then fails with a raw jq error instead of the warned [] degrade).

Follow-up issues to file after merge (none blocking)

• The preset is now two idioms: issue-list / issue-search / recently-closed still use tea pulls|issues list --fields … --limit 200/1000 with the same truncation premise this PR disproves. Migrate them onto tea api + tea_api_paged.
• Repo-resolution unification (already proposed in the PR body) should absorb a third path: repo-archive.sh uses bare ${CODEV_REPO} with no fail-fast.
• forge-contracts.ts doc drift: the reviewRequests comment still says "GitLab/Gitea emit []", but gitea now populates real reviewer logins.
• Test gaps: no 3+ page walk, no mid-walk failure, no sub-50 server cap.
• _lib.sh creates a sibling-file dependency for hand-copied .codev/scripts/forge/gitea/ overrides; worth a line in the header.

Process notes

• The rebase documentation is exemplary: the vscode: one-step 'view issue N' / 'view pr N' from QuickPick + Cmd+K P for direct PR-by-ID open #1179url restoration, the 755 mode rationale, and the per-commit green verification were all stated up front and all verified true.
• Merge order vs [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 confirmed independent; either order is safe. The [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 reconcile (dropping list-and-search in favor of reading the create response) is the right shape.

Merge authority rests with the maintainer; this review is the reviewing architect's recommendation, not a gate approval.

[amrmelsayed]

Follow-up from the reviewing architect: finding 3 just got smaller

Merge order has been ruled by the maintainer: #1458 first, then this PR.

That changes the shape of one item in the review above. #1458 ships a # forge-executable: <tool> declaration that extractExecutable honours ahead of its first-substantive-line heuristic. With #1458 merged first, the "strongly recommended" finding 3 (the codev doctor regression) collapses to adding one line to each of the five sourced scripts:

#!/bin/sh# Forge concept: pr-exists (Gitea via tea CLI)# forge-executable: tea

The deeper extraction work the review asked for (resolving through sourced-helper calls, plus a test) is not required of you — that burden moved to #1458's mechanism, and a hardening addition to its builtin skip list is being pressed on that PR separately.

Everything else stands as written, and none of it waits on #1458: the two blockers (tea comment on 0.14.1, and capture-first in the three paginated scripts so a mid-walk failure can't read as a false-negative pr_exists gate) can be fixed now in either order. Finding 4 (the sub-50 max_response_items stop condition) is likewise independent.

[pseudoseed]

Review follow-up (2026-08-20)

Addressed both blocking items and the strongly-recommended item from the 2026-08-17 review, pushed as c9f55a537 (+ 481956e12 for the builder thread log):

1. (blocking) issue-comment.sh — tea comments add doesn't exist on 0.14.1
tea comments add is a 0.14.2+-only subcommand and fails on the still-current 0.14.1 release ("No help topic for comments"). Switched to the top-level tea comment <id> <body> shorthand, which works on both 0.14.1 and 0.14.2+.

2. (blocking) masked pipe failures in the paginated scripts
pr-exists.sh, pr-list.sh, and recently-merged.sh piped tea_api_paged | jq directly. POSIX sh has no pipefail, so a mid-walk pagination failure (tea_api_paged returning 1) was masked by jq's exit status — jq exits 0 on empty stdin, so pr-exists in particular would print "false" for a real API failure instead of erroring. That's a silent false-negative that could pass a porch pr_exists gate on a genuine error rather than an absent PR.

Fixed by capturing the paginator's output into a variable and checking its exit status before piping to jq:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

3. (strongly recommended, done) sub-limit server cap
tea_api_paged's stop condition compared each page's item count against the requested limit (50). A server whose max_response_items is tuned below that requested limit truncates every page — including non-last pages — to its own cap, so every page looked "short" against 50 and the loop broke after page 1, silently missing pages 2+. Now compares against the size actually observed on page 1 instead, so it keeps walking until a page is genuinely shorter than what the server has been returning.

4. (deferred, not done in this PR)
The # forge-executable: tea header convention depends on #1458 landing extractExecutable's header-parsing support first. Checked — #1458 is still open/unmerged, so this isn't actionable yet. Left as a follow-up once #1458 merges, matching the merge order already noted in the PR description (#1458 first, then this PR).

Testing

Added regression coverage for all three fixes in bugfix-1137-gitea-tea-api.test.ts:

• Updated the fake-tea stub to answer comment (not comments add).
• A mid-walk pagination failure fixture (full page 1, erroring page 2) exercised against all three paginated scripts — asserts non-zero exit and empty stdout rather than a silently wrong/empty result.
• A 3-page sub-50-per-page-cap fixture (30 + 30 + 6 items) proving pr-list keeps walking past a page that's full-but-capped rather than stopping because it's short relative to the requested limit.

Full local suite: 3197 passed, 126 failed (67 files) — the same pre-existing environment-dependent failures (agent-farm/terminal/consolidate; no built dist/ in this worktree) as the unmodified baseline reported earlier in this PR. Zero regressions, +4 new passing tests over the prior 3193.

[waleedkadous]

First — apologies for how long this sat; two months without a review is not how we want to treat a contribution, and this one is good: the real-script fake-CLI suite (contract normalization, pagination past page one, sub-50 server caps, mid-walk failures, tea 0.14.1 comment compatibility) is exactly the evidence this kind of fix needs, and moving branch input through jq --arg is a security improvement. Both integration reviews (codex + claude) agree the core mapping is right. Four things I'd like fixed before merge, all in the same spirit as the fix itself — fail loudly, never silently:

1. codev doctor regression. The five scripts that now source _lib.sh make doctor's executable extractor report . (and later tea_api_paged) instead of tea — verified, which . fails under /bin/sh. #1458 introduces a # forge-executable: tea header declaration for exactly this; please add those five lines here regardless of merge order so the regression can't ship.
2. Silent truncation at GITEA_MAX_PAGES. Reaching 100 pages without seeing a terminal short/empty page returns a partial array at exit 0 — the same false-negative pr-exists class the paginator exists to prevent. Fail explicitly instead.
3. Error bodies normalized into valid-looking output.tea api exits 0 on HTTP errors, and pr-view/user-identity/issue-view normalize without validating the response shape — an error object becomes an all-null PR (pr-view even leaks the error body's url into the contract) or the username null, at exit 0. Validate required fields/types before normalizing; the paginated scripts already fail loudly, so this brings the rest in line.
4. recently-merged.sh ignores CODEV_SINCE_DATE and can issue up to 100 sequential requests inside forge's 30-second timeout — on an established repo that turns the analytics path into null. Honoring the since-date bounds it.

Smaller, take-or-leave: CODEV_REPO is now overloaded (repo-archive's foreign-repo input vs. gitea read targeting) — a line in forge.md and both SKILL.md copies would help; and forge-contracts.ts's reviewRequests/isDraft comments go stale with this PR.

Merge order: #1458 first (it brings the # forge-executable mechanism), then this. Happy to turn the two around quickly once these land — and thank you for sticking with it.

[waleedkadous]

Given how long this waited on us, we'll take the last mile ourselves rather than hand you a list: a builder will push the review items directly onto this branch (you enabled maintainer edits — thank you), your commits and authorship stay as they are, and I'll re-review and merge once green. If you'd rather make the changes yourself, just say so and we'll hold off.

[waleedkadous]

Pushed the review items onto this branch as we offered — four commits on top of yours, nothing rebased or squashed, all ten of your commits and their authorship untouched. Thank you again for the contribution and for the patience; the real-script fake-CLI suite you built is what made all of this cheap to do, and every fix below is a test in your harness.

Also merged main in: #1458 landed, so the # forge-executable: mechanism is live.

The four required items

1. # forge-executable: tea headers. On six scripts, not five. The five that source _lib.sh are the ones the review named, but fixing item 3 in user-identity.sh required capturing tea api user before the jq pipe, which moves tea off the first substantive line — so without a header of its own, that fix would have caused the regression this item closes. Verified against the merged extractExecutable, not a simulation of it: all fourteen gitea concepts now resolve to tea.

2. The page ceiling fails loudly. Reaching GITEA_MAX_PAGES with every page full means we don't know we have the whole list, so it errors rather than returning the partial array at exit 0. One wrinkle worth naming: a list whose length is an exact multiple of the page size hits the ceiling with nothing missing, so it probes one page past before failing — a hard error on a complete result would be its own bug.

3. Shape validation before normalizing. The nastiest part of this one is that Gitea's error bodies carry a url (the swagger link), so url: (.html_url // .url)succeeded on them and shipped that link as the PR's browser page inside an otherwise all-null contract object. Required fields are now type-checked and failures carry the server's own .message on stderr. issue-view is validated before its comments are fetched, so a bad id reports only its own error instead of also warning about degraded comments on an issue that isn't there.

4. recently-merged honors CODEV_SINCE_DATE — it asks for sort=recentupdate and stops at the first page reaching past the cutoff. Details below, because this is where the reviewers earned their keep.

Plus the take-or-leave items: CODEV_REPO's two meanings documented in forge.md and both SKILL.md copies, and the reviewRequests/isDraft comments in forge-contracts.ts corrected — they claimed GitLab and Gitea emit empty/false, but all three presets populate them for real.

What the consultation caught, because it's the interesting part

I first wrote the since-date bound to fire when the current page was non-increasing in updated_at, reasoning that proved the server had honored sort=recentupdate. Both reviewers broke that, and they were right. Gitea's default order is index/created-DESC, and on a repo where PRs are opened and merged in order, index-DESC is non-increasing in updated_at. A long-lived PR opened in January and merged after the cutoff then sits on page 2, and we stop at page 1 and drop it — a silent loss in exactly the analytics path the bound was meant to protect.

The fix is to check for the property we actually need — the ordering — rather than for evidence that we asked for it. A stop now requires the order to survive a page boundary (previous page descending too, its oldest no older than this page's newest) and never fires on page 1, where there's nothing to compare against. A server that ignores the parameter falls back to your full walk: slower, never wrong. Costs exactly one extra request on an honest server.

The other finding I'm glad we ran: passing a page to the stop filter through jq --argjson blows up on Linux. MAX_ARG_STRLEN caps a single argv string at 128KiB regardless of ARG_MAX, and a 50-item Gitea pulls page — every object embedding full base.repo and head.repo — measures ~90KiB before anyone writes a long PR body. macOS has no per-argument cap, so it passed locally and would have failed on CI and for every Linux adopter. Both pages go in on stdin now.

Smaller ones from the same pass: jq length is 0 for both null and {}, so an error body mid-walk looked exactly like an exhausted list; jq on empty stdin emits nothing and exits 0, so two scripts were "succeeding" with empty stdout and never running their validators at all; a non-string .message threw a raw jq error instead of the legible one; and the test env inherited CODEV_* from the developer's shell, so the "no CODEV_SINCE_DATE" test was asserting the absence of a variable it didn't control.

Testing

41 tests in bugfix-1137-gitea-tea-api.test.ts, +20 on what you had. Your fake tea grew error bodies at exit 0 for pulls/issues/user, a comments endpoint answering with an error object and one answering with non-objects, a repo whose pages never end, one whose length is an exact multiple of the page size, ~150KB pages for the argv cap, and the sorted/lagging pair for the since-date bound — acme/lagging is the reviewer's counterexample verbatim.

Full suite after merging main: 5549 passed | 48 skipped, 0 failures. Every script also exercised under dash, which is what /bin/sh is on the CI runner, rather than only bash.

Two follow-ups from the earlier reviews are still unfiled and still worth doing, neither in scope here: migrating issue-list/issue-search/recently-closed off tea <entity> list --limit onto tea_api_paged (same truncation premise this PR disproved), and repo-archive.sh's bare ${CODEV_REPO} with no fail-fast.

Over to @waleedkadous for the re-review.

[waleedkadous]

Re-reviewed after the maintainer-side commits: six # forge-executable: tea headers (verified against the merged extractExecutable — all fourteen gitea concepts resolve to tea), the paginator now fails loudly at the page ceiling with a one-page probe so exact-multiple lists don't false-alarm, non-array error bodies are refused instead of normalized to null, recently-merged honors CODEV_SINCE_DATE with the stop filter fed via stdin (Linux argv cap), plus the docs and stale comments. 41 tests in the contributor's own fake-CLI harness; CI 7/7 green on a6eddb6. Approving and merging — thank you, @pseudoseed, for the contribution and the patience.

[pseudoseed]

Fixes#1137.

Bugfix-protocol re-do of the earlier SPIR-style PR #1138 (now closed), per maintainer request. Same root cause, plus a real regression test.

Problem

The gitea forge preset was authored against the Gitea REST API JSON shape, but the scripts invoke the tea CLI, whose output shape differs — and several concepts referenced flags/fields/subcommands tea doesn't have. Per the in-repo #920 note, tea wasn't available in the authoring environment, so the preset was never run end-to-end.

Fix

Route the read concepts through tea api (raw REST passthrough returning the shape forge-contracts.ts + the jq normalizers expect):

• user-identity: tea api user | jq .login (tea whoami has no --output json)
• pr-view: tea api repos/<repo>/pulls/N → PrViewResult (incl. additions/deletions)
• pr-list: tea api repos/<repo>/pulls?state=open → PrListItem[]
• pr-exists: tea api repos/<repo>/pulls?state=all with nested .head.ref / .merged
• issue-view: tea api repos/<repo>/issues/N + a second call for the comments array (Gitea reports comments as an int count, which would crash .comments.filter(...))
• recently-merged: tea api repos/<repo>/pulls?state=closed, filter .merged, using real .merged_at
• issue-comment: tea comments add (tea issues has no comment subcommand)

tea api needs an explicit owner/repo path segment, so each api-based script derives owner/repo from the origin remote (honoring CODEV_REPO when set).

Testing

• New regression test stubs a fake tea on PATH answering api <endpoint> with captured Gitea REST fixtures (tea isn't in CI, per vscode: editor-tab webview for rich backlog search #920), runs each real script, and asserts the normalized output conforms to forge-contracts.ts — incl. comments-as-array, merged-only filtering, open/merged/closed pr-exists, and CODEV_REPO override.
• Updates the pr_exists porch check fails when PR is merged before gate approval #568pr-exists assertion for the new state=all query param.
• Full suite green locally: build ✓, 3443 tests pass.

🤖 Generated with Claude Code

---

Rebased onto main (2026-08-14)

This branch was 2063 commits behind and mergeable=CONFLICTING. Rebased onto upstream/main; force-pushed to the fork. All 5 original commits preserved.

Exactly one file conflicted, twice — scripts/forge/gitea/pr-view.sh.

⚠️ Behaviour change from the conflict resolution: pr-view now emits url

While this branch sat, PIR #1179 landed on main and gave gitea pr-view a url field mapped from Gitea's html_url:

tea pulls view "$CODEV_PR_NUMBER" --output json | jq '.url = (.html_url // .url)'

This PR rewrites that same script onto tea api with an explicit normalizer — which emitted no url at all. Taking either side of the conflict wholesale loses something: take ours and #1179 is silently reverted, take theirs and the tea api fix is lost.

Resolution: both. The script keeps this PR's tea api routing and re-adds url: (.html_url // .url).

So, stated plainly rather than left in the diff: gitea pr-view now returns a url field that the pre-rebase branch did not return. That is a restoration of main's behaviour, not a new invention — forge-contracts.ts documents the Gitea mapping by name ("Gitea html_url — Gitea's url is the API endpoint, do not use it") — but it is a real change to this concept's output versus what this PR previously proposed, so it should not be discovered from the diff.

bugfix-1137-gitea-tea-api.test.ts was updated accordingly: the pulls/42 fixture now carries both html_url and url, and the assertion pins that the browser page, not the API endpoint, is what reaches the contract.

Two smaller deliberate deviations

• _lib.sh is committed 100755, not 100644.scripts/postinstall.mjs chmods every scripts/forge/**/*.sh to 755 unconditionally, so 644 is a mode that never survives an install and leaves a permanently dirty worktree for anyone who runs pnpm install. The file is sourced, not executed; the bit is inert.
• The test-fixture update was applied inside the test commit (via an interactive rebase stop) rather than as a trailing fixup, so every commit is green in isolation — verified by checking out and testing all 5 individually.

Relationship to #1458

#1458 (pr-create as a forge concept) landed while this PR was open, and its gitea pr-create.sh looked the new PR up with tea pulls list --limit 200 — the exact call this PR proves silently truncates. That has been fixed on #1458's branch, not here: it now creates via tea api -X POST …/pulls, which returns the created PR directly, so the lookup is gone rather than paginated.

Re-confirmed live against Forgejo 15.0.2 while doing so: settings/api reports max_response_items: 50, and a ?limit=200 request returns exactly 50 items on a list where paging at 50 returns 53. The premise behind this PR's pagination work holds.

Merge-order implications are spelled out in full at the end of this description.

Verification

• All 5 commits pass the forge suites individually (bugfix-1137-gitea-tea-api, bugfix-568-pr-exists-state-all, forge, bugfix-693-forge-exec-bit).
• Full @cluesmith/codev unit suite, rebased tip: 3193 passed, 126 failed (67 files).
• Baseline run of the same suite on unmodified upstream/main in the same worktree: 3176 passed, 126 failed (67 files) — the same 67 files and the same 126 tests.
• So: zero regressions; this branch adds 17 passing tests and breaks nothing. The pre-existing failures are all agent-farm / terminal / consolidate (attach, session-manager, shellper sockets, SQLite state), environment-dependent — this worktree has no built dist/, which those tests spawn from, and a live Tower is running against the same state. None is in a file this PR touches, and every forge suite passes.

Merge order with the sibling PR — verified, not assumed

#1146 and #1458 come from the same fork and both touch packages/codev/scripts/forge/gitea/, so the ordering question is fair. The answer:

Either order is safe. There is no dependency and no conflict.

Question	Answer	How it was checked
Do they conflict?	No.	git merge-tree on the two branch tips merges cleanly. The only file both touch is the builder thread log, which is the identical blob on both branches and auto-merges.
Must one merge first?	No.	#1458's pr-create.sh does not source _lib.sh and does not call gitea_repo or tea_api_paged. Nothing in it resolves against #1146.
Does the merged result hold together?	Yes.	In the merged tree, _lib.sh and pr-view.sh are byte-identical to #1146's versions and pr-create.sh byte-identical to #1458's — no silent blending. The bugfix-693 invariant (every entry under each provider dir is a *.sh) still holds with _lib.sh present.

Does #1458 duplicate something #1146 makes shared?

The paginator: no, and it shouldn't._lib.sh#tea_api_paged exists to walk a truncating list endpoint. pr-create no longer lists anything — it reads the new PR out of the create response — so there is no pagination for it to share. That is the point of the reconcile rather than an oversight.

Repo resolution: yes, there are two paths, and this is worth a follow-up.

• [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146's read concepts: . _lib.sh → gitea_repo(), which honours CODEV_REPO, else derives owner/repo from the origin remote, and fails fast naming CODEV_REPO as the remedy.
• [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458's pr-create: tea's own {owner}/{repo} placeholders, with CODEV_PR_REPO forwarded as tea --repo.

They were kept separate deliberately, for two reasons rather than by omission:

1. Different contract.pr-create takes CODEV_PR_REPO; the read concepts take CODEV_REPO. gitea_repo() reads the latter and takes no argument, so pr-create could not call it without changing its signature — which would mean editing a [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146 file from [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 and creating exactly the merge-order coupling this avoids.
2. --repo does more than fill a path. It also supplies tea's repo/login context, verified working from a cwd whose remote is not a Gitea host. A path-only helper does not do that.

Recommended follow-up (not done here, deliberately): once both PRs have landed, unify the two behind one helper that takes the override variable as a parameter — e.g. gitea_repo "$CODEV_PR_REPO" — so there is one repo-resolution path with one error message. Doing it now would couple two independent PRs; doing it never leaves two paths that will drift. It is a small, mechanical change against a tree where both are already present.

The one ergonomic gap that split created has been closed in the meantime: an unresolvable repo used to surface from pr-create as a bare 404 page not found, and now names CODEV_PR_REPO as the remedy, matching gitea_repo()'s fail-fast message.

[waleedkadous]

Excellent work — thank you for the disciplined re-do, and apologies for the review latency. This is what a model bugfix PR looks like: every tea-CLI deficiency documented in-script with reasoning, the REST passthrough returning exactly the shape forge-contracts.ts expects, and a genuinely well-built regression suite (fake tea on PATH serving captured REST fixtures, the real scripts executed, contract-shape assertions, the comments-as-int crash and null-login team reviewers both covered). We verified every output mapping field-by-field against the contracts — all conform — and the switch from string-interpolated jq to --arg in pr-exists is a quiet security improvement worth crediting.

One substantive question before merge, and two optional polish items:

1. Pagination cap (the one we'd like addressed or answered). Gitea servers cap page size at max_response_items (default 50), so ?limit=200 likely returns 50 items with no client-side pagination in the raw passthrough. That means pr-exists?state=all can false-negative for a branch whose PR isn't in the most recent ~50 (which would block a porch pr_exists gate), and recently-merged (previously --limit 1000) can miss on a busy repo. A pagination loop (page=1..N until a short page) would settle it — or at minimum a comment documenting the server-side cap and the false-negative window, so the next debugger isn't blind. Happy with either; we'd just like the behavior to be chosen rather than inherited.

2. (Polish, optional) With no origin remote or an unusual URL, REPO silently becomes empty/garbage and tea api "repos//…" fails with a confusing 404. An explicit [ -n "$REPO" ] || { echo "…set CODEV_REPO" >&2; exit 1; } naming the remedy would fit this repo's fail-fast convention — ideally factored once since the derivation appears in five scripts.

3. (Polish, optional) A failed comments fetch silently yields comments: [] — indistinguishable from "no comments" for consumers reading issue discussion. A stderr warning on the degraded path would keep the graceful behavior while leaving a trace.

Verdict: approve once item 1 is addressed (fix or documented caveat — your choice). Items 2–3 are welcome in this PR or a follow-up, contributor's choice.

[pseudoseed]

Thanks for the thorough review — all three items addressed in 3c2e3c2b.

1. Pagination — fixed (real page loop, not a comment). You're right that ?limit=200 inherited Gitea's max_response_items cap (default 50) and silently truncated. Added a shared tea_api_paged helper in a new scripts/forge/gitea/_lib.sh that requests page=1,2,3… at an explicit limit=50, concatenates each page's array (jq -s add), and stops when a page comes back shorter than the limit (or empty). Chosen behavior: it paginates, with a hard ceiling of 100 pages (100 × 50 = 5000 items) so a misbehaving server can't spin forever — documented in the helper. Wired into all three list reads: pr-exists (state=all), pr-list (state=open), recently-merged (state=closed). Output shape is unchanged — the concatenated array feeds the existing jq normalizers untouched. New tests serve a full 50-item page 1 + a short page 2 and assert an item that exists only on page 2 is found by each of the three scripts (pr-exists returns true for it, pr-list/recently-merged include it).

2. REPO fail-fast, factored once — done. The CODEV_REPO/origin-derivation line (duplicated in five scripts) now lives in _lib.sh#gitea_repo, sourced via . "$(dirname "$0")/_lib.sh" by issue-view, pr-exists, pr-list, pr-view, and recently-merged. It validates the result is a clean owner/repo; if not (no origin, unusual URL), it prints set CODEV_REPO=owner/repo to stderr and exits non-zero instead of letting tea api "repos//…" 404. Verified before factoring: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist (a leading-underscore file is never registered as a concept), package.jsonfiles ships scripts/forge so _lib.sh is packaged, it's POSIX sh (no bashisms), and $0-relative sourcing works when the script is invoked by absolute path (how forge runs it via sh -c). Tests cover missing-origin and garbage-URL → non-zero exit + the stderr remedy.

3. Degraded comments warn — done.issue-view still degrades a failed comments fetch to [], but now writes gitea forge: comments fetch failed for issue N; reporting 0 comments to stderr while stdout stays pure JSON. Test asserts both (comments: [] on stdout and the stderr warning).

Full suite green in the worktree: 3449 passed | 48 skipped, 0 failures (pnpm build + pnpm test). The #568pr-existsstate=all assertion stays green (the helper is still called with state=all).

[pseudoseed]

@waleedkadous let me know if there's anything else that needs to be addressed with this one :)

[pseudoseed]

Verified against a real Forgejo + tea — all six concepts pass

The PR notes that tea wasn't available in the authoring environment and the preset was never run end to end. It has now been. I ran this branch's scripts against a live Forgejo instance with tea 0.14.2, on a repo with ~355 issues and ~350 PRs.

Environment: Forgejo, tea 0.14.2 (go-sdk v1.1.0), single configured login, scripts invoked directly with CODEV_REPO set.

Before — released version, same environment

concept	result
user-identity	FAILIncorrect Usage: flag provided but not defined: -output
issue-view	FAILjq: Cannot index array with string "html_url"
pr-list	FAIL, exit 0 — prints Error: invalid field 'description' and still returns success
recently-merged	FAIL, exit 0 — same
pr-view	returns a list, not the requested PR
issue-list, issue-search, pr-exists, recently-closed, auth-status	OK

The two exit-0 cases are the nastiest: a caller checking the exit status sees success and gets an error string where JSON should be.

After — this branch, same environment

concept	result
user-identity	OK — user
issue-view	OK — object with title, body, state, url, comments[]
pr-list	OK — normalized PrListItem[]
pr-view	OK — single PR object, correct one
pr-exists	OK — true
recently-merged	OK — merged-only, correct merged_at ordering

All six previously-broken concepts now work. No regressions in the five that already worked.

Two notes

The comments-as-int catch is real and would have bitten immediately. Gitea returns comments as an integer count on the issue object; our issue-view on the released version failed exactly there. The second call for the comments array is necessary, not defensive.

One nearly-false report from me, worth stating so nobody repeats it. My first run of this branch's issue-view failed with Cannot index array with string "title". That was my harness, not your code — I had exported CODEV_ISSUE_NUMBER where the contract is CODEV_ISSUE_ID, so the path resolved to the issue list endpoint. With the correct variable it works. Flagging it because the failure mode is plausible-looking and someone else testing this could draw the wrong conclusion.

Unrelated gap this surfaced

pr-create is not a forge concept at all, so gh pr create stays hardcoded in the skeleton prompts (porch/prompts/pr.md, protocols/{air,spir,pir,bugfix,maintain}/…). That means a Gitea/Forgejo user still needs a gh shim on PATH no matter how complete this preset becomes. Not this PR's problem — filing separately — but relevant if anyone assumes a working gitea preset makes gh unnecessary.

Happy to re-run against any further revisions.

[amrmelsayed]

Reviewer Integration Review (CMAP-3)

Three-lane consultation (Gemini, GPT-5.6 Sol via Codex, Claude Opus) plus an independent architect pass. Every finding below was re-verified by the reviewing architect against the actual source, and the tea-CLI claims against the installed release binary, before being credited.

Verdict: REQUEST CHANGES (light). The core fix is correct, honestly documented, and the best-evidenced community PR this repo has received: the tea api rerouting, the pagination premise, the #1179 conflict resolution, and the merge-order analysis vs #1458 all check out. Lane split: Gemini APPROVE; Codex and Claude REQUEST_CHANGES. Two items are blocking; the rest are tiered below so nothing has to be rediscovered later.

Verified solid (no action)

• _lib.sh is safely inert as a concept: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist, so a leading-underscore file is never registered. Verified at forge.ts:64.
• $(dirname "$0") sourcing holds in the real call path: executeForgeCommand runs the absolute script path via sh -c.
• package.jsonfiles ships scripts/forge, and the bugfix-693 invariant (every provider-dir entry matches *.sh) still holds with _lib.sh present. The 755-mode argument is correct (postinstall chmods unconditionally).
• All four emitted shapes conform exactly to forge-contracts.ts (PrViewResult, PrListItem, MergedPrItem, IssueViewResult), and the --arg branch switch in pr-exists is a real injection fix.
• Pagination premise re-confirmed: issue gitea forge preset is broken against the real tea CLI (0.14.2) #1137 is still open, no forge-script drift on main since your 08-14 rebase, branch is MERGEABLE.

Blocking

1. issue-comment.sh breaks on the current released tea (0.14.1).tea comments add only exists from tea 0.14.2; on 0.14.1 (current Homebrew release) it exits with No help topic for 'comments'. Verified against the installed 0.14.1 binary and the tea source at both tags: tea comment "$CODEV_ISSUE_ID" "$CODEV_COMMENT_BODY" exists on 0.14.1 and is explicitly preserved as a shorthand in 0.14.2+, so it works on every version. This slipped through because issue-comment is the one concept absent from the live-verification tables (that run used tea 0.14.2), and the fake-tea stub implements comments add by fiat, pinning the assumption rather than testing it. One-word fix plus updating the stub to answer comment instead.

2. Paginator failure exits 0 with empty stdout, which reads as a false-negative pr_exists gate.tea_api_paged's return 1 sits on the left of a pipe in POSIX sh (no pipefail), so the script's exit status is jq's (0) and stdout is empty. Porch's pr-exists check (checks.ts:365) maps anything that isn't "true" to passed: false, so a transient failure mid-walk reports "no PR exists": the exact failure mode pagination was added to prevent. Fix in all three list scripts by capturing first:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

This also converts the jq -s add raw-type-error wart you flagged in the thread log into a clean non-zero exit.

Strongly recommended in this PR (both small, both introduced here)

3. codev doctor regression for gitea users.extractExecutable (forge.ts:192) skips comments, if, and assignments, but not dot-sourcing: the first substantive token in the five sourced scripts is ., and which . fails, so doctor shows five false "not found" rows and stops verifying tea for those concepts. Note the fix is not just skipping .: after the source line and the REPO= assignment are skipped, the next token in the three list scripts is tea_api_paged (a shell function), which also fails the which check. The extraction needs to resolve through sourced-helper calls (or the gitea preset needs declared executables), plus a test; no existing test covers this path, which is why the suite stayed green.

4. The stop condition trusts that the server honored limit=50.max_response_items is admin-tunable; on a server capped below 50, every page is "short", the loop breaks after page 1, and silent truncation returns on exactly the servers that tuned the cap. Derive the effective page size from page 1's item count and break when a page is shorter than that (or stop only on an empty page, at the cost of one extra request per walk). Worth a test with a sub-50 cap.

Maintainer's call: in-PR or filed as follow-ups

• recently-merged ignores CODEV_SINCE_DATE and now walks the full closed-PR history (up to 100 sequential requests, 2 jq spawns per page) inside forge's 30s timeout (forge.ts:323). On a large Gitea repo that risks timeout, and a timeout yields null: a worse dashboard outcome than truncation was. An early-exit on the since-date or a tighter page bound for this concept would cover it.
• Non-paged reads don't validate tea api's exit-0-on-error responses. An HTTP error body piped into the pr-view/issue-view/user-identity normalizers emits a structurally valid all-null contract object at exit 0. [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 guards this exact mode explicitly, so the two halves of the preset currently disagree about a documented behavior. Same class: issue-view's comments degrade path only handles a blank response, not an error-object one (--argjson then fails with a raw jq error instead of the warned [] degrade).

Follow-up issues to file after merge (none blocking)

• The preset is now two idioms: issue-list / issue-search / recently-closed still use tea pulls|issues list --fields … --limit 200/1000 with the same truncation premise this PR disproves. Migrate them onto tea api + tea_api_paged.
• Repo-resolution unification (already proposed in the PR body) should absorb a third path: repo-archive.sh uses bare ${CODEV_REPO} with no fail-fast.
• forge-contracts.ts doc drift: the reviewRequests comment still says "GitLab/Gitea emit []", but gitea now populates real reviewer logins.
• Test gaps: no 3+ page walk, no mid-walk failure, no sub-50 server cap.
• _lib.sh creates a sibling-file dependency for hand-copied .codev/scripts/forge/gitea/ overrides; worth a line in the header.

Process notes

• The rebase documentation is exemplary: the vscode: one-step 'view issue N' / 'view pr N' from QuickPick + Cmd+K P for direct PR-by-ID open #1179url restoration, the 755 mode rationale, and the per-commit green verification were all stated up front and all verified true.
• Merge order vs [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 confirmed independent; either order is safe. The [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 reconcile (dropping list-and-search in favor of reading the create response) is the right shape.

Merge authority rests with the maintainer; this review is the reviewing architect's recommendation, not a gate approval.

[amrmelsayed]

Follow-up from the reviewing architect: finding 3 just got smaller

Merge order has been ruled by the maintainer: #1458 first, then this PR.

That changes the shape of one item in the review above. #1458 ships a # forge-executable: <tool> declaration that extractExecutable honours ahead of its first-substantive-line heuristic. With #1458 merged first, the "strongly recommended" finding 3 (the codev doctor regression) collapses to adding one line to each of the five sourced scripts:

#!/bin/sh# Forge concept: pr-exists (Gitea via tea CLI)# forge-executable: tea

The deeper extraction work the review asked for (resolving through sourced-helper calls, plus a test) is not required of you — that burden moved to #1458's mechanism, and a hardening addition to its builtin skip list is being pressed on that PR separately.

Everything else stands as written, and none of it waits on #1458: the two blockers (tea comment on 0.14.1, and capture-first in the three paginated scripts so a mid-walk failure can't read as a false-negative pr_exists gate) can be fixed now in either order. Finding 4 (the sub-50 max_response_items stop condition) is likewise independent.

[pseudoseed]

Review follow-up (2026-08-20)

Addressed both blocking items and the strongly-recommended item from the 2026-08-17 review, pushed as c9f55a537 (+ 481956e12 for the builder thread log):

1. (blocking) issue-comment.sh — tea comments add doesn't exist on 0.14.1
tea comments add is a 0.14.2+-only subcommand and fails on the still-current 0.14.1 release ("No help topic for comments"). Switched to the top-level tea comment <id> <body> shorthand, which works on both 0.14.1 and 0.14.2+.

2. (blocking) masked pipe failures in the paginated scripts
pr-exists.sh, pr-list.sh, and recently-merged.sh piped tea_api_paged | jq directly. POSIX sh has no pipefail, so a mid-walk pagination failure (tea_api_paged returning 1) was masked by jq's exit status — jq exits 0 on empty stdin, so pr-exists in particular would print "false" for a real API failure instead of erroring. That's a silent false-negative that could pass a porch pr_exists gate on a genuine error rather than an absent PR.

Fixed by capturing the paginator's output into a variable and checking its exit status before piping to jq:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

3. (strongly recommended, done) sub-limit server cap
tea_api_paged's stop condition compared each page's item count against the requested limit (50). A server whose max_response_items is tuned below that requested limit truncates every page — including non-last pages — to its own cap, so every page looked "short" against 50 and the loop broke after page 1, silently missing pages 2+. Now compares against the size actually observed on page 1 instead, so it keeps walking until a page is genuinely shorter than what the server has been returning.

4. (deferred, not done in this PR)
The # forge-executable: tea header convention depends on #1458 landing extractExecutable's header-parsing support first. Checked — #1458 is still open/unmerged, so this isn't actionable yet. Left as a follow-up once #1458 merges, matching the merge order already noted in the PR description (#1458 first, then this PR).

Testing

Added regression coverage for all three fixes in bugfix-1137-gitea-tea-api.test.ts:

• Updated the fake-tea stub to answer comment (not comments add).
• A mid-walk pagination failure fixture (full page 1, erroring page 2) exercised against all three paginated scripts — asserts non-zero exit and empty stdout rather than a silently wrong/empty result.
• A 3-page sub-50-per-page-cap fixture (30 + 30 + 6 items) proving pr-list keeps walking past a page that's full-but-capped rather than stopping because it's short relative to the requested limit.

Full local suite: 3197 passed, 126 failed (67 files) — the same pre-existing environment-dependent failures (agent-farm/terminal/consolidate; no built dist/ in this worktree) as the unmodified baseline reported earlier in this PR. Zero regressions, +4 new passing tests over the prior 3193.

[waleedkadous]

First — apologies for how long this sat; two months without a review is not how we want to treat a contribution, and this one is good: the real-script fake-CLI suite (contract normalization, pagination past page one, sub-50 server caps, mid-walk failures, tea 0.14.1 comment compatibility) is exactly the evidence this kind of fix needs, and moving branch input through jq --arg is a security improvement. Both integration reviews (codex + claude) agree the core mapping is right. Four things I'd like fixed before merge, all in the same spirit as the fix itself — fail loudly, never silently:

1. codev doctor regression. The five scripts that now source _lib.sh make doctor's executable extractor report . (and later tea_api_paged) instead of tea — verified, which . fails under /bin/sh. #1458 introduces a # forge-executable: tea header declaration for exactly this; please add those five lines here regardless of merge order so the regression can't ship.
2. Silent truncation at GITEA_MAX_PAGES. Reaching 100 pages without seeing a terminal short/empty page returns a partial array at exit 0 — the same false-negative pr-exists class the paginator exists to prevent. Fail explicitly instead.
3. Error bodies normalized into valid-looking output.tea api exits 0 on HTTP errors, and pr-view/user-identity/issue-view normalize without validating the response shape — an error object becomes an all-null PR (pr-view even leaks the error body's url into the contract) or the username null, at exit 0. Validate required fields/types before normalizing; the paginated scripts already fail loudly, so this brings the rest in line.
4. recently-merged.sh ignores CODEV_SINCE_DATE and can issue up to 100 sequential requests inside forge's 30-second timeout — on an established repo that turns the analytics path into null. Honoring the since-date bounds it.

Smaller, take-or-leave: CODEV_REPO is now overloaded (repo-archive's foreign-repo input vs. gitea read targeting) — a line in forge.md and both SKILL.md copies would help; and forge-contracts.ts's reviewRequests/isDraft comments go stale with this PR.

Merge order: #1458 first (it brings the # forge-executable mechanism), then this. Happy to turn the two around quickly once these land — and thank you for sticking with it.

[waleedkadous]

Given how long this waited on us, we'll take the last mile ourselves rather than hand you a list: a builder will push the review items directly onto this branch (you enabled maintainer edits — thank you), your commits and authorship stay as they are, and I'll re-review and merge once green. If you'd rather make the changes yourself, just say so and we'll hold off.

[waleedkadous]

Pushed the review items onto this branch as we offered — four commits on top of yours, nothing rebased or squashed, all ten of your commits and their authorship untouched. Thank you again for the contribution and for the patience; the real-script fake-CLI suite you built is what made all of this cheap to do, and every fix below is a test in your harness.

Also merged main in: #1458 landed, so the # forge-executable: mechanism is live.

The four required items

1. # forge-executable: tea headers. On six scripts, not five. The five that source _lib.sh are the ones the review named, but fixing item 3 in user-identity.sh required capturing tea api user before the jq pipe, which moves tea off the first substantive line — so without a header of its own, that fix would have caused the regression this item closes. Verified against the merged extractExecutable, not a simulation of it: all fourteen gitea concepts now resolve to tea.

2. The page ceiling fails loudly. Reaching GITEA_MAX_PAGES with every page full means we don't know we have the whole list, so it errors rather than returning the partial array at exit 0. One wrinkle worth naming: a list whose length is an exact multiple of the page size hits the ceiling with nothing missing, so it probes one page past before failing — a hard error on a complete result would be its own bug.

3. Shape validation before normalizing. The nastiest part of this one is that Gitea's error bodies carry a url (the swagger link), so url: (.html_url // .url)succeeded on them and shipped that link as the PR's browser page inside an otherwise all-null contract object. Required fields are now type-checked and failures carry the server's own .message on stderr. issue-view is validated before its comments are fetched, so a bad id reports only its own error instead of also warning about degraded comments on an issue that isn't there.

4. recently-merged honors CODEV_SINCE_DATE — it asks for sort=recentupdate and stops at the first page reaching past the cutoff. Details below, because this is where the reviewers earned their keep.

Plus the take-or-leave items: CODEV_REPO's two meanings documented in forge.md and both SKILL.md copies, and the reviewRequests/isDraft comments in forge-contracts.ts corrected — they claimed GitLab and Gitea emit empty/false, but all three presets populate them for real.

What the consultation caught, because it's the interesting part

I first wrote the since-date bound to fire when the current page was non-increasing in updated_at, reasoning that proved the server had honored sort=recentupdate. Both reviewers broke that, and they were right. Gitea's default order is index/created-DESC, and on a repo where PRs are opened and merged in order, index-DESC is non-increasing in updated_at. A long-lived PR opened in January and merged after the cutoff then sits on page 2, and we stop at page 1 and drop it — a silent loss in exactly the analytics path the bound was meant to protect.

The fix is to check for the property we actually need — the ordering — rather than for evidence that we asked for it. A stop now requires the order to survive a page boundary (previous page descending too, its oldest no older than this page's newest) and never fires on page 1, where there's nothing to compare against. A server that ignores the parameter falls back to your full walk: slower, never wrong. Costs exactly one extra request on an honest server.

The other finding I'm glad we ran: passing a page to the stop filter through jq --argjson blows up on Linux. MAX_ARG_STRLEN caps a single argv string at 128KiB regardless of ARG_MAX, and a 50-item Gitea pulls page — every object embedding full base.repo and head.repo — measures ~90KiB before anyone writes a long PR body. macOS has no per-argument cap, so it passed locally and would have failed on CI and for every Linux adopter. Both pages go in on stdin now.

Smaller ones from the same pass: jq length is 0 for both null and {}, so an error body mid-walk looked exactly like an exhausted list; jq on empty stdin emits nothing and exits 0, so two scripts were "succeeding" with empty stdout and never running their validators at all; a non-string .message threw a raw jq error instead of the legible one; and the test env inherited CODEV_* from the developer's shell, so the "no CODEV_SINCE_DATE" test was asserting the absence of a variable it didn't control.

Testing

41 tests in bugfix-1137-gitea-tea-api.test.ts, +20 on what you had. Your fake tea grew error bodies at exit 0 for pulls/issues/user, a comments endpoint answering with an error object and one answering with non-objects, a repo whose pages never end, one whose length is an exact multiple of the page size, ~150KB pages for the argv cap, and the sorted/lagging pair for the since-date bound — acme/lagging is the reviewer's counterexample verbatim.

Full suite after merging main: 5549 passed | 48 skipped, 0 failures. Every script also exercised under dash, which is what /bin/sh is on the CI runner, rather than only bash.

Two follow-ups from the earlier reviews are still unfiled and still worth doing, neither in scope here: migrating issue-list/issue-search/recently-closed off tea <entity> list --limit onto tea_api_paged (same truncation premise this PR disproved), and repo-archive.sh's bare ${CODEV_REPO} with no fail-fast.

Over to @waleedkadous for the re-review.

[waleedkadous]

Re-reviewed after the maintainer-side commits: six # forge-executable: tea headers (verified against the merged extractExecutable — all fourteen gitea concepts resolve to tea), the paginator now fails loudly at the page ceiling with a one-page probe so exact-multiple lists don't false-alarm, non-array error bodies are refused instead of normalized to null, recently-merged honors CODEV_SINCE_DATE with the stop filter fed via stdin (Linux argv cap), plus the docs and stale comments. 41 tests in the contributor's own fake-CLI harness; CI 7/7 green on a6eddb6. Approving and merging — thank you, @pseudoseed, for the contribution and the patience.

[pseudoseed]

Fixes#1137.

Bugfix-protocol re-do of the earlier SPIR-style PR #1138 (now closed), per maintainer request. Same root cause, plus a real regression test.

Problem

The gitea forge preset was authored against the Gitea REST API JSON shape, but the scripts invoke the tea CLI, whose output shape differs — and several concepts referenced flags/fields/subcommands tea doesn't have. Per the in-repo #920 note, tea wasn't available in the authoring environment, so the preset was never run end-to-end.

Fix

Route the read concepts through tea api (raw REST passthrough returning the shape forge-contracts.ts + the jq normalizers expect):

• user-identity: tea api user | jq .login (tea whoami has no --output json)
• pr-view: tea api repos/<repo>/pulls/N → PrViewResult (incl. additions/deletions)
• pr-list: tea api repos/<repo>/pulls?state=open → PrListItem[]
• pr-exists: tea api repos/<repo>/pulls?state=all with nested .head.ref / .merged
• issue-view: tea api repos/<repo>/issues/N + a second call for the comments array (Gitea reports comments as an int count, which would crash .comments.filter(...))
• recently-merged: tea api repos/<repo>/pulls?state=closed, filter .merged, using real .merged_at
• issue-comment: tea comments add (tea issues has no comment subcommand)

tea api needs an explicit owner/repo path segment, so each api-based script derives owner/repo from the origin remote (honoring CODEV_REPO when set).

Testing

• New regression test stubs a fake tea on PATH answering api <endpoint> with captured Gitea REST fixtures (tea isn't in CI, per vscode: editor-tab webview for rich backlog search #920), runs each real script, and asserts the normalized output conforms to forge-contracts.ts — incl. comments-as-array, merged-only filtering, open/merged/closed pr-exists, and CODEV_REPO override.
• Updates the pr_exists porch check fails when PR is merged before gate approval #568pr-exists assertion for the new state=all query param.
• Full suite green locally: build ✓, 3443 tests pass.

🤖 Generated with Claude Code

---

Rebased onto main (2026-08-14)

This branch was 2063 commits behind and mergeable=CONFLICTING. Rebased onto upstream/main; force-pushed to the fork. All 5 original commits preserved.

Exactly one file conflicted, twice — scripts/forge/gitea/pr-view.sh.

⚠️ Behaviour change from the conflict resolution: pr-view now emits url

While this branch sat, PIR #1179 landed on main and gave gitea pr-view a url field mapped from Gitea's html_url:

tea pulls view "$CODEV_PR_NUMBER" --output json | jq '.url = (.html_url // .url)'

This PR rewrites that same script onto tea api with an explicit normalizer — which emitted no url at all. Taking either side of the conflict wholesale loses something: take ours and #1179 is silently reverted, take theirs and the tea api fix is lost.

Resolution: both. The script keeps this PR's tea api routing and re-adds url: (.html_url // .url).

So, stated plainly rather than left in the diff: gitea pr-view now returns a url field that the pre-rebase branch did not return. That is a restoration of main's behaviour, not a new invention — forge-contracts.ts documents the Gitea mapping by name ("Gitea html_url — Gitea's url is the API endpoint, do not use it") — but it is a real change to this concept's output versus what this PR previously proposed, so it should not be discovered from the diff.

bugfix-1137-gitea-tea-api.test.ts was updated accordingly: the pulls/42 fixture now carries both html_url and url, and the assertion pins that the browser page, not the API endpoint, is what reaches the contract.

Two smaller deliberate deviations

• _lib.sh is committed 100755, not 100644.scripts/postinstall.mjs chmods every scripts/forge/**/*.sh to 755 unconditionally, so 644 is a mode that never survives an install and leaves a permanently dirty worktree for anyone who runs pnpm install. The file is sourced, not executed; the bit is inert.
• The test-fixture update was applied inside the test commit (via an interactive rebase stop) rather than as a trailing fixup, so every commit is green in isolation — verified by checking out and testing all 5 individually.

Relationship to #1458

#1458 (pr-create as a forge concept) landed while this PR was open, and its gitea pr-create.sh looked the new PR up with tea pulls list --limit 200 — the exact call this PR proves silently truncates. That has been fixed on #1458's branch, not here: it now creates via tea api -X POST …/pulls, which returns the created PR directly, so the lookup is gone rather than paginated.

Re-confirmed live against Forgejo 15.0.2 while doing so: settings/api reports max_response_items: 50, and a ?limit=200 request returns exactly 50 items on a list where paging at 50 returns 53. The premise behind this PR's pagination work holds.

Merge-order implications are spelled out in full at the end of this description.

Verification

• All 5 commits pass the forge suites individually (bugfix-1137-gitea-tea-api, bugfix-568-pr-exists-state-all, forge, bugfix-693-forge-exec-bit).
• Full @cluesmith/codev unit suite, rebased tip: 3193 passed, 126 failed (67 files).
• Baseline run of the same suite on unmodified upstream/main in the same worktree: 3176 passed, 126 failed (67 files) — the same 67 files and the same 126 tests.
• So: zero regressions; this branch adds 17 passing tests and breaks nothing. The pre-existing failures are all agent-farm / terminal / consolidate (attach, session-manager, shellper sockets, SQLite state), environment-dependent — this worktree has no built dist/, which those tests spawn from, and a live Tower is running against the same state. None is in a file this PR touches, and every forge suite passes.

Merge order with the sibling PR — verified, not assumed

#1146 and #1458 come from the same fork and both touch packages/codev/scripts/forge/gitea/, so the ordering question is fair. The answer:

Either order is safe. There is no dependency and no conflict.

Question	Answer	How it was checked
Do they conflict?	No.	git merge-tree on the two branch tips merges cleanly. The only file both touch is the builder thread log, which is the identical blob on both branches and auto-merges.
Must one merge first?	No.	#1458's pr-create.sh does not source _lib.sh and does not call gitea_repo or tea_api_paged. Nothing in it resolves against #1146.
Does the merged result hold together?	Yes.	In the merged tree, _lib.sh and pr-view.sh are byte-identical to #1146's versions and pr-create.sh byte-identical to #1458's — no silent blending. The bugfix-693 invariant (every entry under each provider dir is a *.sh) still holds with _lib.sh present.

Does #1458 duplicate something #1146 makes shared?

The paginator: no, and it shouldn't._lib.sh#tea_api_paged exists to walk a truncating list endpoint. pr-create no longer lists anything — it reads the new PR out of the create response — so there is no pagination for it to share. That is the point of the reconcile rather than an oversight.

Repo resolution: yes, there are two paths, and this is worth a follow-up.

• [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146's read concepts: . _lib.sh → gitea_repo(), which honours CODEV_REPO, else derives owner/repo from the origin remote, and fails fast naming CODEV_REPO as the remedy.
• [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458's pr-create: tea's own {owner}/{repo} placeholders, with CODEV_PR_REPO forwarded as tea --repo.

They were kept separate deliberately, for two reasons rather than by omission:

1. Different contract.pr-create takes CODEV_PR_REPO; the read concepts take CODEV_REPO. gitea_repo() reads the latter and takes no argument, so pr-create could not call it without changing its signature — which would mean editing a [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146 file from [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 and creating exactly the merge-order coupling this avoids.
2. --repo does more than fill a path. It also supplies tea's repo/login context, verified working from a cwd whose remote is not a Gitea host. A path-only helper does not do that.

Recommended follow-up (not done here, deliberately): once both PRs have landed, unify the two behind one helper that takes the override variable as a parameter — e.g. gitea_repo "$CODEV_PR_REPO" — so there is one repo-resolution path with one error message. Doing it now would couple two independent PRs; doing it never leaves two paths that will drift. It is a small, mechanical change against a tree where both are already present.

The one ergonomic gap that split created has been closed in the meantime: an unresolvable repo used to surface from pr-create as a bare 404 page not found, and now names CODEV_PR_REPO as the remedy, matching gitea_repo()'s fail-fast message.

[waleedkadous]

Excellent work — thank you for the disciplined re-do, and apologies for the review latency. This is what a model bugfix PR looks like: every tea-CLI deficiency documented in-script with reasoning, the REST passthrough returning exactly the shape forge-contracts.ts expects, and a genuinely well-built regression suite (fake tea on PATH serving captured REST fixtures, the real scripts executed, contract-shape assertions, the comments-as-int crash and null-login team reviewers both covered). We verified every output mapping field-by-field against the contracts — all conform — and the switch from string-interpolated jq to --arg in pr-exists is a quiet security improvement worth crediting.

One substantive question before merge, and two optional polish items:

1. Pagination cap (the one we'd like addressed or answered). Gitea servers cap page size at max_response_items (default 50), so ?limit=200 likely returns 50 items with no client-side pagination in the raw passthrough. That means pr-exists?state=all can false-negative for a branch whose PR isn't in the most recent ~50 (which would block a porch pr_exists gate), and recently-merged (previously --limit 1000) can miss on a busy repo. A pagination loop (page=1..N until a short page) would settle it — or at minimum a comment documenting the server-side cap and the false-negative window, so the next debugger isn't blind. Happy with either; we'd just like the behavior to be chosen rather than inherited.

2. (Polish, optional) With no origin remote or an unusual URL, REPO silently becomes empty/garbage and tea api "repos//…" fails with a confusing 404. An explicit [ -n "$REPO" ] || { echo "…set CODEV_REPO" >&2; exit 1; } naming the remedy would fit this repo's fail-fast convention — ideally factored once since the derivation appears in five scripts.

3. (Polish, optional) A failed comments fetch silently yields comments: [] — indistinguishable from "no comments" for consumers reading issue discussion. A stderr warning on the degraded path would keep the graceful behavior while leaving a trace.

Verdict: approve once item 1 is addressed (fix or documented caveat — your choice). Items 2–3 are welcome in this PR or a follow-up, contributor's choice.

[pseudoseed]

Thanks for the thorough review — all three items addressed in 3c2e3c2b.

1. Pagination — fixed (real page loop, not a comment). You're right that ?limit=200 inherited Gitea's max_response_items cap (default 50) and silently truncated. Added a shared tea_api_paged helper in a new scripts/forge/gitea/_lib.sh that requests page=1,2,3… at an explicit limit=50, concatenates each page's array (jq -s add), and stops when a page comes back shorter than the limit (or empty). Chosen behavior: it paginates, with a hard ceiling of 100 pages (100 × 50 = 5000 items) so a misbehaving server can't spin forever — documented in the helper. Wired into all three list reads: pr-exists (state=all), pr-list (state=open), recently-merged (state=closed). Output shape is unchanged — the concatenated array feeds the existing jq normalizers untouched. New tests serve a full 50-item page 1 + a short page 2 and assert an item that exists only on page 2 is found by each of the three scripts (pr-exists returns true for it, pr-list/recently-merged include it).

2. REPO fail-fast, factored once — done. The CODEV_REPO/origin-derivation line (duplicated in five scripts) now lives in _lib.sh#gitea_repo, sourced via . "$(dirname "$0")/_lib.sh" by issue-view, pr-exists, pr-list, pr-view, and recently-merged. It validates the result is a clean owner/repo; if not (no origin, unusual URL), it prints set CODEV_REPO=owner/repo to stderr and exits non-zero instead of letting tea api "repos//…" 404. Verified before factoring: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist (a leading-underscore file is never registered as a concept), package.jsonfiles ships scripts/forge so _lib.sh is packaged, it's POSIX sh (no bashisms), and $0-relative sourcing works when the script is invoked by absolute path (how forge runs it via sh -c). Tests cover missing-origin and garbage-URL → non-zero exit + the stderr remedy.

3. Degraded comments warn — done.issue-view still degrades a failed comments fetch to [], but now writes gitea forge: comments fetch failed for issue N; reporting 0 comments to stderr while stdout stays pure JSON. Test asserts both (comments: [] on stdout and the stderr warning).

Full suite green in the worktree: 3449 passed | 48 skipped, 0 failures (pnpm build + pnpm test). The #568pr-existsstate=all assertion stays green (the helper is still called with state=all).

[pseudoseed]

@waleedkadous let me know if there's anything else that needs to be addressed with this one :)

[pseudoseed]

Verified against a real Forgejo + tea — all six concepts pass

The PR notes that tea wasn't available in the authoring environment and the preset was never run end to end. It has now been. I ran this branch's scripts against a live Forgejo instance with tea 0.14.2, on a repo with ~355 issues and ~350 PRs.

Environment: Forgejo, tea 0.14.2 (go-sdk v1.1.0), single configured login, scripts invoked directly with CODEV_REPO set.

Before — released version, same environment

concept	result
user-identity	FAILIncorrect Usage: flag provided but not defined: -output
issue-view	FAILjq: Cannot index array with string "html_url"
pr-list	FAIL, exit 0 — prints Error: invalid field 'description' and still returns success
recently-merged	FAIL, exit 0 — same
pr-view	returns a list, not the requested PR
issue-list, issue-search, pr-exists, recently-closed, auth-status	OK

The two exit-0 cases are the nastiest: a caller checking the exit status sees success and gets an error string where JSON should be.

After — this branch, same environment

concept	result
user-identity	OK — user
issue-view	OK — object with title, body, state, url, comments[]
pr-list	OK — normalized PrListItem[]
pr-view	OK — single PR object, correct one
pr-exists	OK — true
recently-merged	OK — merged-only, correct merged_at ordering

All six previously-broken concepts now work. No regressions in the five that already worked.

Two notes

The comments-as-int catch is real and would have bitten immediately. Gitea returns comments as an integer count on the issue object; our issue-view on the released version failed exactly there. The second call for the comments array is necessary, not defensive.

One nearly-false report from me, worth stating so nobody repeats it. My first run of this branch's issue-view failed with Cannot index array with string "title". That was my harness, not your code — I had exported CODEV_ISSUE_NUMBER where the contract is CODEV_ISSUE_ID, so the path resolved to the issue list endpoint. With the correct variable it works. Flagging it because the failure mode is plausible-looking and someone else testing this could draw the wrong conclusion.

Unrelated gap this surfaced

pr-create is not a forge concept at all, so gh pr create stays hardcoded in the skeleton prompts (porch/prompts/pr.md, protocols/{air,spir,pir,bugfix,maintain}/…). That means a Gitea/Forgejo user still needs a gh shim on PATH no matter how complete this preset becomes. Not this PR's problem — filing separately — but relevant if anyone assumes a working gitea preset makes gh unnecessary.

Happy to re-run against any further revisions.

[amrmelsayed]

Reviewer Integration Review (CMAP-3)

Three-lane consultation (Gemini, GPT-5.6 Sol via Codex, Claude Opus) plus an independent architect pass. Every finding below was re-verified by the reviewing architect against the actual source, and the tea-CLI claims against the installed release binary, before being credited.

Verdict: REQUEST CHANGES (light). The core fix is correct, honestly documented, and the best-evidenced community PR this repo has received: the tea api rerouting, the pagination premise, the #1179 conflict resolution, and the merge-order analysis vs #1458 all check out. Lane split: Gemini APPROVE; Codex and Claude REQUEST_CHANGES. Two items are blocking; the rest are tiered below so nothing has to be rediscovered later.

Verified solid (no action)

• _lib.sh is safely inert as a concept: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist, so a leading-underscore file is never registered. Verified at forge.ts:64.
• $(dirname "$0") sourcing holds in the real call path: executeForgeCommand runs the absolute script path via sh -c.
• package.jsonfiles ships scripts/forge, and the bugfix-693 invariant (every provider-dir entry matches *.sh) still holds with _lib.sh present. The 755-mode argument is correct (postinstall chmods unconditionally).
• All four emitted shapes conform exactly to forge-contracts.ts (PrViewResult, PrListItem, MergedPrItem, IssueViewResult), and the --arg branch switch in pr-exists is a real injection fix.
• Pagination premise re-confirmed: issue gitea forge preset is broken against the real tea CLI (0.14.2) #1137 is still open, no forge-script drift on main since your 08-14 rebase, branch is MERGEABLE.

Blocking

1. issue-comment.sh breaks on the current released tea (0.14.1).tea comments add only exists from tea 0.14.2; on 0.14.1 (current Homebrew release) it exits with No help topic for 'comments'. Verified against the installed 0.14.1 binary and the tea source at both tags: tea comment "$CODEV_ISSUE_ID" "$CODEV_COMMENT_BODY" exists on 0.14.1 and is explicitly preserved as a shorthand in 0.14.2+, so it works on every version. This slipped through because issue-comment is the one concept absent from the live-verification tables (that run used tea 0.14.2), and the fake-tea stub implements comments add by fiat, pinning the assumption rather than testing it. One-word fix plus updating the stub to answer comment instead.

2. Paginator failure exits 0 with empty stdout, which reads as a false-negative pr_exists gate.tea_api_paged's return 1 sits on the left of a pipe in POSIX sh (no pipefail), so the script's exit status is jq's (0) and stdout is empty. Porch's pr-exists check (checks.ts:365) maps anything that isn't "true" to passed: false, so a transient failure mid-walk reports "no PR exists": the exact failure mode pagination was added to prevent. Fix in all three list scripts by capturing first:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

This also converts the jq -s add raw-type-error wart you flagged in the thread log into a clean non-zero exit.

Strongly recommended in this PR (both small, both introduced here)

3. codev doctor regression for gitea users.extractExecutable (forge.ts:192) skips comments, if, and assignments, but not dot-sourcing: the first substantive token in the five sourced scripts is ., and which . fails, so doctor shows five false "not found" rows and stops verifying tea for those concepts. Note the fix is not just skipping .: after the source line and the REPO= assignment are skipped, the next token in the three list scripts is tea_api_paged (a shell function), which also fails the which check. The extraction needs to resolve through sourced-helper calls (or the gitea preset needs declared executables), plus a test; no existing test covers this path, which is why the suite stayed green.

4. The stop condition trusts that the server honored limit=50.max_response_items is admin-tunable; on a server capped below 50, every page is "short", the loop breaks after page 1, and silent truncation returns on exactly the servers that tuned the cap. Derive the effective page size from page 1's item count and break when a page is shorter than that (or stop only on an empty page, at the cost of one extra request per walk). Worth a test with a sub-50 cap.

Maintainer's call: in-PR or filed as follow-ups

• recently-merged ignores CODEV_SINCE_DATE and now walks the full closed-PR history (up to 100 sequential requests, 2 jq spawns per page) inside forge's 30s timeout (forge.ts:323). On a large Gitea repo that risks timeout, and a timeout yields null: a worse dashboard outcome than truncation was. An early-exit on the since-date or a tighter page bound for this concept would cover it.
• Non-paged reads don't validate tea api's exit-0-on-error responses. An HTTP error body piped into the pr-view/issue-view/user-identity normalizers emits a structurally valid all-null contract object at exit 0. [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 guards this exact mode explicitly, so the two halves of the preset currently disagree about a documented behavior. Same class: issue-view's comments degrade path only handles a blank response, not an error-object one (--argjson then fails with a raw jq error instead of the warned [] degrade).

Follow-up issues to file after merge (none blocking)

• The preset is now two idioms: issue-list / issue-search / recently-closed still use tea pulls|issues list --fields … --limit 200/1000 with the same truncation premise this PR disproves. Migrate them onto tea api + tea_api_paged.
• Repo-resolution unification (already proposed in the PR body) should absorb a third path: repo-archive.sh uses bare ${CODEV_REPO} with no fail-fast.
• forge-contracts.ts doc drift: the reviewRequests comment still says "GitLab/Gitea emit []", but gitea now populates real reviewer logins.
• Test gaps: no 3+ page walk, no mid-walk failure, no sub-50 server cap.
• _lib.sh creates a sibling-file dependency for hand-copied .codev/scripts/forge/gitea/ overrides; worth a line in the header.

Process notes

• The rebase documentation is exemplary: the vscode: one-step 'view issue N' / 'view pr N' from QuickPick + Cmd+K P for direct PR-by-ID open #1179url restoration, the 755 mode rationale, and the per-commit green verification were all stated up front and all verified true.
• Merge order vs [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 confirmed independent; either order is safe. The [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 reconcile (dropping list-and-search in favor of reading the create response) is the right shape.

Merge authority rests with the maintainer; this review is the reviewing architect's recommendation, not a gate approval.

[amrmelsayed]

Follow-up from the reviewing architect: finding 3 just got smaller

Merge order has been ruled by the maintainer: #1458 first, then this PR.

That changes the shape of one item in the review above. #1458 ships a # forge-executable: <tool> declaration that extractExecutable honours ahead of its first-substantive-line heuristic. With #1458 merged first, the "strongly recommended" finding 3 (the codev doctor regression) collapses to adding one line to each of the five sourced scripts:

#!/bin/sh# Forge concept: pr-exists (Gitea via tea CLI)# forge-executable: tea

The deeper extraction work the review asked for (resolving through sourced-helper calls, plus a test) is not required of you — that burden moved to #1458's mechanism, and a hardening addition to its builtin skip list is being pressed on that PR separately.

Everything else stands as written, and none of it waits on #1458: the two blockers (tea comment on 0.14.1, and capture-first in the three paginated scripts so a mid-walk failure can't read as a false-negative pr_exists gate) can be fixed now in either order. Finding 4 (the sub-50 max_response_items stop condition) is likewise independent.

[pseudoseed]

Review follow-up (2026-08-20)

Addressed both blocking items and the strongly-recommended item from the 2026-08-17 review, pushed as c9f55a537 (+ 481956e12 for the builder thread log):

1. (blocking) issue-comment.sh — tea comments add doesn't exist on 0.14.1
tea comments add is a 0.14.2+-only subcommand and fails on the still-current 0.14.1 release ("No help topic for comments"). Switched to the top-level tea comment <id> <body> shorthand, which works on both 0.14.1 and 0.14.2+.

2. (blocking) masked pipe failures in the paginated scripts
pr-exists.sh, pr-list.sh, and recently-merged.sh piped tea_api_paged | jq directly. POSIX sh has no pipefail, so a mid-walk pagination failure (tea_api_paged returning 1) was masked by jq's exit status — jq exits 0 on empty stdin, so pr-exists in particular would print "false" for a real API failure instead of erroring. That's a silent false-negative that could pass a porch pr_exists gate on a genuine error rather than an absent PR.

Fixed by capturing the paginator's output into a variable and checking its exit status before piping to jq:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

3. (strongly recommended, done) sub-limit server cap
tea_api_paged's stop condition compared each page's item count against the requested limit (50). A server whose max_response_items is tuned below that requested limit truncates every page — including non-last pages — to its own cap, so every page looked "short" against 50 and the loop broke after page 1, silently missing pages 2+. Now compares against the size actually observed on page 1 instead, so it keeps walking until a page is genuinely shorter than what the server has been returning.

4. (deferred, not done in this PR)
The # forge-executable: tea header convention depends on #1458 landing extractExecutable's header-parsing support first. Checked — #1458 is still open/unmerged, so this isn't actionable yet. Left as a follow-up once #1458 merges, matching the merge order already noted in the PR description (#1458 first, then this PR).

Testing

Added regression coverage for all three fixes in bugfix-1137-gitea-tea-api.test.ts:

• Updated the fake-tea stub to answer comment (not comments add).
• A mid-walk pagination failure fixture (full page 1, erroring page 2) exercised against all three paginated scripts — asserts non-zero exit and empty stdout rather than a silently wrong/empty result.
• A 3-page sub-50-per-page-cap fixture (30 + 30 + 6 items) proving pr-list keeps walking past a page that's full-but-capped rather than stopping because it's short relative to the requested limit.

Full local suite: 3197 passed, 126 failed (67 files) — the same pre-existing environment-dependent failures (agent-farm/terminal/consolidate; no built dist/ in this worktree) as the unmodified baseline reported earlier in this PR. Zero regressions, +4 new passing tests over the prior 3193.

[waleedkadous]

First — apologies for how long this sat; two months without a review is not how we want to treat a contribution, and this one is good: the real-script fake-CLI suite (contract normalization, pagination past page one, sub-50 server caps, mid-walk failures, tea 0.14.1 comment compatibility) is exactly the evidence this kind of fix needs, and moving branch input through jq --arg is a security improvement. Both integration reviews (codex + claude) agree the core mapping is right. Four things I'd like fixed before merge, all in the same spirit as the fix itself — fail loudly, never silently:

1. codev doctor regression. The five scripts that now source _lib.sh make doctor's executable extractor report . (and later tea_api_paged) instead of tea — verified, which . fails under /bin/sh. #1458 introduces a # forge-executable: tea header declaration for exactly this; please add those five lines here regardless of merge order so the regression can't ship.
2. Silent truncation at GITEA_MAX_PAGES. Reaching 100 pages without seeing a terminal short/empty page returns a partial array at exit 0 — the same false-negative pr-exists class the paginator exists to prevent. Fail explicitly instead.
3. Error bodies normalized into valid-looking output.tea api exits 0 on HTTP errors, and pr-view/user-identity/issue-view normalize without validating the response shape — an error object becomes an all-null PR (pr-view even leaks the error body's url into the contract) or the username null, at exit 0. Validate required fields/types before normalizing; the paginated scripts already fail loudly, so this brings the rest in line.
4. recently-merged.sh ignores CODEV_SINCE_DATE and can issue up to 100 sequential requests inside forge's 30-second timeout — on an established repo that turns the analytics path into null. Honoring the since-date bounds it.

Smaller, take-or-leave: CODEV_REPO is now overloaded (repo-archive's foreign-repo input vs. gitea read targeting) — a line in forge.md and both SKILL.md copies would help; and forge-contracts.ts's reviewRequests/isDraft comments go stale with this PR.

Merge order: #1458 first (it brings the # forge-executable mechanism), then this. Happy to turn the two around quickly once these land — and thank you for sticking with it.

[waleedkadous]

Given how long this waited on us, we'll take the last mile ourselves rather than hand you a list: a builder will push the review items directly onto this branch (you enabled maintainer edits — thank you), your commits and authorship stay as they are, and I'll re-review and merge once green. If you'd rather make the changes yourself, just say so and we'll hold off.

[waleedkadous]

Pushed the review items onto this branch as we offered — four commits on top of yours, nothing rebased or squashed, all ten of your commits and their authorship untouched. Thank you again for the contribution and for the patience; the real-script fake-CLI suite you built is what made all of this cheap to do, and every fix below is a test in your harness.

Also merged main in: #1458 landed, so the # forge-executable: mechanism is live.

The four required items

1. # forge-executable: tea headers. On six scripts, not five. The five that source _lib.sh are the ones the review named, but fixing item 3 in user-identity.sh required capturing tea api user before the jq pipe, which moves tea off the first substantive line — so without a header of its own, that fix would have caused the regression this item closes. Verified against the merged extractExecutable, not a simulation of it: all fourteen gitea concepts now resolve to tea.

2. The page ceiling fails loudly. Reaching GITEA_MAX_PAGES with every page full means we don't know we have the whole list, so it errors rather than returning the partial array at exit 0. One wrinkle worth naming: a list whose length is an exact multiple of the page size hits the ceiling with nothing missing, so it probes one page past before failing — a hard error on a complete result would be its own bug.

3. Shape validation before normalizing. The nastiest part of this one is that Gitea's error bodies carry a url (the swagger link), so url: (.html_url // .url)succeeded on them and shipped that link as the PR's browser page inside an otherwise all-null contract object. Required fields are now type-checked and failures carry the server's own .message on stderr. issue-view is validated before its comments are fetched, so a bad id reports only its own error instead of also warning about degraded comments on an issue that isn't there.

4. recently-merged honors CODEV_SINCE_DATE — it asks for sort=recentupdate and stops at the first page reaching past the cutoff. Details below, because this is where the reviewers earned their keep.

Plus the take-or-leave items: CODEV_REPO's two meanings documented in forge.md and both SKILL.md copies, and the reviewRequests/isDraft comments in forge-contracts.ts corrected — they claimed GitLab and Gitea emit empty/false, but all three presets populate them for real.

What the consultation caught, because it's the interesting part

I first wrote the since-date bound to fire when the current page was non-increasing in updated_at, reasoning that proved the server had honored sort=recentupdate. Both reviewers broke that, and they were right. Gitea's default order is index/created-DESC, and on a repo where PRs are opened and merged in order, index-DESC is non-increasing in updated_at. A long-lived PR opened in January and merged after the cutoff then sits on page 2, and we stop at page 1 and drop it — a silent loss in exactly the analytics path the bound was meant to protect.

The fix is to check for the property we actually need — the ordering — rather than for evidence that we asked for it. A stop now requires the order to survive a page boundary (previous page descending too, its oldest no older than this page's newest) and never fires on page 1, where there's nothing to compare against. A server that ignores the parameter falls back to your full walk: slower, never wrong. Costs exactly one extra request on an honest server.

The other finding I'm glad we ran: passing a page to the stop filter through jq --argjson blows up on Linux. MAX_ARG_STRLEN caps a single argv string at 128KiB regardless of ARG_MAX, and a 50-item Gitea pulls page — every object embedding full base.repo and head.repo — measures ~90KiB before anyone writes a long PR body. macOS has no per-argument cap, so it passed locally and would have failed on CI and for every Linux adopter. Both pages go in on stdin now.

Smaller ones from the same pass: jq length is 0 for both null and {}, so an error body mid-walk looked exactly like an exhausted list; jq on empty stdin emits nothing and exits 0, so two scripts were "succeeding" with empty stdout and never running their validators at all; a non-string .message threw a raw jq error instead of the legible one; and the test env inherited CODEV_* from the developer's shell, so the "no CODEV_SINCE_DATE" test was asserting the absence of a variable it didn't control.

Testing

41 tests in bugfix-1137-gitea-tea-api.test.ts, +20 on what you had. Your fake tea grew error bodies at exit 0 for pulls/issues/user, a comments endpoint answering with an error object and one answering with non-objects, a repo whose pages never end, one whose length is an exact multiple of the page size, ~150KB pages for the argv cap, and the sorted/lagging pair for the since-date bound — acme/lagging is the reviewer's counterexample verbatim.

Full suite after merging main: 5549 passed | 48 skipped, 0 failures. Every script also exercised under dash, which is what /bin/sh is on the CI runner, rather than only bash.

Two follow-ups from the earlier reviews are still unfiled and still worth doing, neither in scope here: migrating issue-list/issue-search/recently-closed off tea <entity> list --limit onto tea_api_paged (same truncation premise this PR disproved), and repo-archive.sh's bare ${CODEV_REPO} with no fail-fast.

Over to @waleedkadous for the re-review.

[waleedkadous]

Re-reviewed after the maintainer-side commits: six # forge-executable: tea headers (verified against the merged extractExecutable — all fourteen gitea concepts resolve to tea), the paginator now fails loudly at the page ceiling with a one-page probe so exact-multiple lists don't false-alarm, non-array error bodies are refused instead of normalized to null, recently-merged honors CODEV_SINCE_DATE with the stop filter fed via stdin (Linux argv cap), plus the docs and stale comments. 41 tests in the contributor's own fake-CLI harness; CI 7/7 green on a6eddb6. Approving and merging — thank you, @pseudoseed, for the contribution and the patience.

[pseudoseed]

Fixes#1137.

Bugfix-protocol re-do of the earlier SPIR-style PR #1138 (now closed), per maintainer request. Same root cause, plus a real regression test.

Problem

The gitea forge preset was authored against the Gitea REST API JSON shape, but the scripts invoke the tea CLI, whose output shape differs — and several concepts referenced flags/fields/subcommands tea doesn't have. Per the in-repo #920 note, tea wasn't available in the authoring environment, so the preset was never run end-to-end.

Fix

Route the read concepts through tea api (raw REST passthrough returning the shape forge-contracts.ts + the jq normalizers expect):

• user-identity: tea api user | jq .login (tea whoami has no --output json)
• pr-view: tea api repos/<repo>/pulls/N → PrViewResult (incl. additions/deletions)
• pr-list: tea api repos/<repo>/pulls?state=open → PrListItem[]
• pr-exists: tea api repos/<repo>/pulls?state=all with nested .head.ref / .merged
• issue-view: tea api repos/<repo>/issues/N + a second call for the comments array (Gitea reports comments as an int count, which would crash .comments.filter(...))
• recently-merged: tea api repos/<repo>/pulls?state=closed, filter .merged, using real .merged_at
• issue-comment: tea comments add (tea issues has no comment subcommand)

tea api needs an explicit owner/repo path segment, so each api-based script derives owner/repo from the origin remote (honoring CODEV_REPO when set).

Testing

• New regression test stubs a fake tea on PATH answering api <endpoint> with captured Gitea REST fixtures (tea isn't in CI, per vscode: editor-tab webview for rich backlog search #920), runs each real script, and asserts the normalized output conforms to forge-contracts.ts — incl. comments-as-array, merged-only filtering, open/merged/closed pr-exists, and CODEV_REPO override.
• Updates the pr_exists porch check fails when PR is merged before gate approval #568pr-exists assertion for the new state=all query param.
• Full suite green locally: build ✓, 3443 tests pass.

🤖 Generated with Claude Code

---

Rebased onto main (2026-08-14)

This branch was 2063 commits behind and mergeable=CONFLICTING. Rebased onto upstream/main; force-pushed to the fork. All 5 original commits preserved.

Exactly one file conflicted, twice — scripts/forge/gitea/pr-view.sh.

⚠️ Behaviour change from the conflict resolution: pr-view now emits url

While this branch sat, PIR #1179 landed on main and gave gitea pr-view a url field mapped from Gitea's html_url:

tea pulls view "$CODEV_PR_NUMBER" --output json | jq '.url = (.html_url // .url)'

This PR rewrites that same script onto tea api with an explicit normalizer — which emitted no url at all. Taking either side of the conflict wholesale loses something: take ours and #1179 is silently reverted, take theirs and the tea api fix is lost.

Resolution: both. The script keeps this PR's tea api routing and re-adds url: (.html_url // .url).

So, stated plainly rather than left in the diff: gitea pr-view now returns a url field that the pre-rebase branch did not return. That is a restoration of main's behaviour, not a new invention — forge-contracts.ts documents the Gitea mapping by name ("Gitea html_url — Gitea's url is the API endpoint, do not use it") — but it is a real change to this concept's output versus what this PR previously proposed, so it should not be discovered from the diff.

bugfix-1137-gitea-tea-api.test.ts was updated accordingly: the pulls/42 fixture now carries both html_url and url, and the assertion pins that the browser page, not the API endpoint, is what reaches the contract.

Two smaller deliberate deviations

• _lib.sh is committed 100755, not 100644.scripts/postinstall.mjs chmods every scripts/forge/**/*.sh to 755 unconditionally, so 644 is a mode that never survives an install and leaves a permanently dirty worktree for anyone who runs pnpm install. The file is sourced, not executed; the bit is inert.
• The test-fixture update was applied inside the test commit (via an interactive rebase stop) rather than as a trailing fixup, so every commit is green in isolation — verified by checking out and testing all 5 individually.

Relationship to #1458

#1458 (pr-create as a forge concept) landed while this PR was open, and its gitea pr-create.sh looked the new PR up with tea pulls list --limit 200 — the exact call this PR proves silently truncates. That has been fixed on #1458's branch, not here: it now creates via tea api -X POST …/pulls, which returns the created PR directly, so the lookup is gone rather than paginated.

Re-confirmed live against Forgejo 15.0.2 while doing so: settings/api reports max_response_items: 50, and a ?limit=200 request returns exactly 50 items on a list where paging at 50 returns 53. The premise behind this PR's pagination work holds.

Merge-order implications are spelled out in full at the end of this description.

Verification

• All 5 commits pass the forge suites individually (bugfix-1137-gitea-tea-api, bugfix-568-pr-exists-state-all, forge, bugfix-693-forge-exec-bit).
• Full @cluesmith/codev unit suite, rebased tip: 3193 passed, 126 failed (67 files).
• Baseline run of the same suite on unmodified upstream/main in the same worktree: 3176 passed, 126 failed (67 files) — the same 67 files and the same 126 tests.
• So: zero regressions; this branch adds 17 passing tests and breaks nothing. The pre-existing failures are all agent-farm / terminal / consolidate (attach, session-manager, shellper sockets, SQLite state), environment-dependent — this worktree has no built dist/, which those tests spawn from, and a live Tower is running against the same state. None is in a file this PR touches, and every forge suite passes.

Merge order with the sibling PR — verified, not assumed

#1146 and #1458 come from the same fork and both touch packages/codev/scripts/forge/gitea/, so the ordering question is fair. The answer:

Either order is safe. There is no dependency and no conflict.

Question	Answer	How it was checked
Do they conflict?	No.	git merge-tree on the two branch tips merges cleanly. The only file both touch is the builder thread log, which is the identical blob on both branches and auto-merges.
Must one merge first?	No.	#1458's pr-create.sh does not source _lib.sh and does not call gitea_repo or tea_api_paged. Nothing in it resolves against #1146.
Does the merged result hold together?	Yes.	In the merged tree, _lib.sh and pr-view.sh are byte-identical to #1146's versions and pr-create.sh byte-identical to #1458's — no silent blending. The bugfix-693 invariant (every entry under each provider dir is a *.sh) still holds with _lib.sh present.

Does #1458 duplicate something #1146 makes shared?

The paginator: no, and it shouldn't._lib.sh#tea_api_paged exists to walk a truncating list endpoint. pr-create no longer lists anything — it reads the new PR out of the create response — so there is no pagination for it to share. That is the point of the reconcile rather than an oversight.

Repo resolution: yes, there are two paths, and this is worth a follow-up.

• [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146's read concepts: . _lib.sh → gitea_repo(), which honours CODEV_REPO, else derives owner/repo from the origin remote, and fails fast naming CODEV_REPO as the remedy.
• [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458's pr-create: tea's own {owner}/{repo} placeholders, with CODEV_PR_REPO forwarded as tea --repo.

They were kept separate deliberately, for two reasons rather than by omission:

1. Different contract.pr-create takes CODEV_PR_REPO; the read concepts take CODEV_REPO. gitea_repo() reads the latter and takes no argument, so pr-create could not call it without changing its signature — which would mean editing a [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146 file from [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 and creating exactly the merge-order coupling this avoids.
2. --repo does more than fill a path. It also supplies tea's repo/login context, verified working from a cwd whose remote is not a Gitea host. A path-only helper does not do that.

Recommended follow-up (not done here, deliberately): once both PRs have landed, unify the two behind one helper that takes the override variable as a parameter — e.g. gitea_repo "$CODEV_PR_REPO" — so there is one repo-resolution path with one error message. Doing it now would couple two independent PRs; doing it never leaves two paths that will drift. It is a small, mechanical change against a tree where both are already present.

The one ergonomic gap that split created has been closed in the meantime: an unresolvable repo used to surface from pr-create as a bare 404 page not found, and now names CODEV_PR_REPO as the remedy, matching gitea_repo()'s fail-fast message.

[waleedkadous]

Excellent work — thank you for the disciplined re-do, and apologies for the review latency. This is what a model bugfix PR looks like: every tea-CLI deficiency documented in-script with reasoning, the REST passthrough returning exactly the shape forge-contracts.ts expects, and a genuinely well-built regression suite (fake tea on PATH serving captured REST fixtures, the real scripts executed, contract-shape assertions, the comments-as-int crash and null-login team reviewers both covered). We verified every output mapping field-by-field against the contracts — all conform — and the switch from string-interpolated jq to --arg in pr-exists is a quiet security improvement worth crediting.

One substantive question before merge, and two optional polish items:

1. Pagination cap (the one we'd like addressed or answered). Gitea servers cap page size at max_response_items (default 50), so ?limit=200 likely returns 50 items with no client-side pagination in the raw passthrough. That means pr-exists?state=all can false-negative for a branch whose PR isn't in the most recent ~50 (which would block a porch pr_exists gate), and recently-merged (previously --limit 1000) can miss on a busy repo. A pagination loop (page=1..N until a short page) would settle it — or at minimum a comment documenting the server-side cap and the false-negative window, so the next debugger isn't blind. Happy with either; we'd just like the behavior to be chosen rather than inherited.

2. (Polish, optional) With no origin remote or an unusual URL, REPO silently becomes empty/garbage and tea api "repos//…" fails with a confusing 404. An explicit [ -n "$REPO" ] || { echo "…set CODEV_REPO" >&2; exit 1; } naming the remedy would fit this repo's fail-fast convention — ideally factored once since the derivation appears in five scripts.

3. (Polish, optional) A failed comments fetch silently yields comments: [] — indistinguishable from "no comments" for consumers reading issue discussion. A stderr warning on the degraded path would keep the graceful behavior while leaving a trace.

Verdict: approve once item 1 is addressed (fix or documented caveat — your choice). Items 2–3 are welcome in this PR or a follow-up, contributor's choice.

[pseudoseed]

Thanks for the thorough review — all three items addressed in 3c2e3c2b.

1. Pagination — fixed (real page loop, not a comment). You're right that ?limit=200 inherited Gitea's max_response_items cap (default 50) and silently truncated. Added a shared tea_api_paged helper in a new scripts/forge/gitea/_lib.sh that requests page=1,2,3… at an explicit limit=50, concatenates each page's array (jq -s add), and stops when a page comes back shorter than the limit (or empty). Chosen behavior: it paginates, with a hard ceiling of 100 pages (100 × 50 = 5000 items) so a misbehaving server can't spin forever — documented in the helper. Wired into all three list reads: pr-exists (state=all), pr-list (state=open), recently-merged (state=closed). Output shape is unchanged — the concatenated array feeds the existing jq normalizers untouched. New tests serve a full 50-item page 1 + a short page 2 and assert an item that exists only on page 2 is found by each of the three scripts (pr-exists returns true for it, pr-list/recently-merged include it).

2. REPO fail-fast, factored once — done. The CODEV_REPO/origin-derivation line (duplicated in five scripts) now lives in _lib.sh#gitea_repo, sourced via . "$(dirname "$0")/_lib.sh" by issue-view, pr-exists, pr-list, pr-view, and recently-merged. It validates the result is a clean owner/repo; if not (no origin, unusual URL), it prints set CODEV_REPO=owner/repo to stderr and exits non-zero instead of letting tea api "repos//…" 404. Verified before factoring: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist (a leading-underscore file is never registered as a concept), package.jsonfiles ships scripts/forge so _lib.sh is packaged, it's POSIX sh (no bashisms), and $0-relative sourcing works when the script is invoked by absolute path (how forge runs it via sh -c). Tests cover missing-origin and garbage-URL → non-zero exit + the stderr remedy.

3. Degraded comments warn — done.issue-view still degrades a failed comments fetch to [], but now writes gitea forge: comments fetch failed for issue N; reporting 0 comments to stderr while stdout stays pure JSON. Test asserts both (comments: [] on stdout and the stderr warning).

Full suite green in the worktree: 3449 passed | 48 skipped, 0 failures (pnpm build + pnpm test). The #568pr-existsstate=all assertion stays green (the helper is still called with state=all).

[pseudoseed]

@waleedkadous let me know if there's anything else that needs to be addressed with this one :)

[pseudoseed]

Verified against a real Forgejo + tea — all six concepts pass

The PR notes that tea wasn't available in the authoring environment and the preset was never run end to end. It has now been. I ran this branch's scripts against a live Forgejo instance with tea 0.14.2, on a repo with ~355 issues and ~350 PRs.

Environment: Forgejo, tea 0.14.2 (go-sdk v1.1.0), single configured login, scripts invoked directly with CODEV_REPO set.

Before — released version, same environment

concept	result
user-identity	FAILIncorrect Usage: flag provided but not defined: -output
issue-view	FAILjq: Cannot index array with string "html_url"
pr-list	FAIL, exit 0 — prints Error: invalid field 'description' and still returns success
recently-merged	FAIL, exit 0 — same
pr-view	returns a list, not the requested PR
issue-list, issue-search, pr-exists, recently-closed, auth-status	OK

The two exit-0 cases are the nastiest: a caller checking the exit status sees success and gets an error string where JSON should be.

After — this branch, same environment

concept	result
user-identity	OK — user
issue-view	OK — object with title, body, state, url, comments[]
pr-list	OK — normalized PrListItem[]
pr-view	OK — single PR object, correct one
pr-exists	OK — true
recently-merged	OK — merged-only, correct merged_at ordering

All six previously-broken concepts now work. No regressions in the five that already worked.

Two notes

The comments-as-int catch is real and would have bitten immediately. Gitea returns comments as an integer count on the issue object; our issue-view on the released version failed exactly there. The second call for the comments array is necessary, not defensive.

One nearly-false report from me, worth stating so nobody repeats it. My first run of this branch's issue-view failed with Cannot index array with string "title". That was my harness, not your code — I had exported CODEV_ISSUE_NUMBER where the contract is CODEV_ISSUE_ID, so the path resolved to the issue list endpoint. With the correct variable it works. Flagging it because the failure mode is plausible-looking and someone else testing this could draw the wrong conclusion.

Unrelated gap this surfaced

pr-create is not a forge concept at all, so gh pr create stays hardcoded in the skeleton prompts (porch/prompts/pr.md, protocols/{air,spir,pir,bugfix,maintain}/…). That means a Gitea/Forgejo user still needs a gh shim on PATH no matter how complete this preset becomes. Not this PR's problem — filing separately — but relevant if anyone assumes a working gitea preset makes gh unnecessary.

Happy to re-run against any further revisions.

[amrmelsayed]

Reviewer Integration Review (CMAP-3)

Three-lane consultation (Gemini, GPT-5.6 Sol via Codex, Claude Opus) plus an independent architect pass. Every finding below was re-verified by the reviewing architect against the actual source, and the tea-CLI claims against the installed release binary, before being credited.

Verdict: REQUEST CHANGES (light). The core fix is correct, honestly documented, and the best-evidenced community PR this repo has received: the tea api rerouting, the pagination premise, the #1179 conflict resolution, and the merge-order analysis vs #1458 all check out. Lane split: Gemini APPROVE; Codex and Claude REQUEST_CHANGES. Two items are blocking; the rest are tiered below so nothing has to be rediscovered later.

Verified solid (no action)

• _lib.sh is safely inert as a concept: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist, so a leading-underscore file is never registered. Verified at forge.ts:64.
• $(dirname "$0") sourcing holds in the real call path: executeForgeCommand runs the absolute script path via sh -c.
• package.jsonfiles ships scripts/forge, and the bugfix-693 invariant (every provider-dir entry matches *.sh) still holds with _lib.sh present. The 755-mode argument is correct (postinstall chmods unconditionally).
• All four emitted shapes conform exactly to forge-contracts.ts (PrViewResult, PrListItem, MergedPrItem, IssueViewResult), and the --arg branch switch in pr-exists is a real injection fix.
• Pagination premise re-confirmed: issue gitea forge preset is broken against the real tea CLI (0.14.2) #1137 is still open, no forge-script drift on main since your 08-14 rebase, branch is MERGEABLE.

Blocking

1. issue-comment.sh breaks on the current released tea (0.14.1).tea comments add only exists from tea 0.14.2; on 0.14.1 (current Homebrew release) it exits with No help topic for 'comments'. Verified against the installed 0.14.1 binary and the tea source at both tags: tea comment "$CODEV_ISSUE_ID" "$CODEV_COMMENT_BODY" exists on 0.14.1 and is explicitly preserved as a shorthand in 0.14.2+, so it works on every version. This slipped through because issue-comment is the one concept absent from the live-verification tables (that run used tea 0.14.2), and the fake-tea stub implements comments add by fiat, pinning the assumption rather than testing it. One-word fix plus updating the stub to answer comment instead.

2. Paginator failure exits 0 with empty stdout, which reads as a false-negative pr_exists gate.tea_api_paged's return 1 sits on the left of a pipe in POSIX sh (no pipefail), so the script's exit status is jq's (0) and stdout is empty. Porch's pr-exists check (checks.ts:365) maps anything that isn't "true" to passed: false, so a transient failure mid-walk reports "no PR exists": the exact failure mode pagination was added to prevent. Fix in all three list scripts by capturing first:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

This also converts the jq -s add raw-type-error wart you flagged in the thread log into a clean non-zero exit.

Strongly recommended in this PR (both small, both introduced here)

3. codev doctor regression for gitea users.extractExecutable (forge.ts:192) skips comments, if, and assignments, but not dot-sourcing: the first substantive token in the five sourced scripts is ., and which . fails, so doctor shows five false "not found" rows and stops verifying tea for those concepts. Note the fix is not just skipping .: after the source line and the REPO= assignment are skipped, the next token in the three list scripts is tea_api_paged (a shell function), which also fails the which check. The extraction needs to resolve through sourced-helper calls (or the gitea preset needs declared executables), plus a test; no existing test covers this path, which is why the suite stayed green.

4. The stop condition trusts that the server honored limit=50.max_response_items is admin-tunable; on a server capped below 50, every page is "short", the loop breaks after page 1, and silent truncation returns on exactly the servers that tuned the cap. Derive the effective page size from page 1's item count and break when a page is shorter than that (or stop only on an empty page, at the cost of one extra request per walk). Worth a test with a sub-50 cap.

Maintainer's call: in-PR or filed as follow-ups

• recently-merged ignores CODEV_SINCE_DATE and now walks the full closed-PR history (up to 100 sequential requests, 2 jq spawns per page) inside forge's 30s timeout (forge.ts:323). On a large Gitea repo that risks timeout, and a timeout yields null: a worse dashboard outcome than truncation was. An early-exit on the since-date or a tighter page bound for this concept would cover it.
• Non-paged reads don't validate tea api's exit-0-on-error responses. An HTTP error body piped into the pr-view/issue-view/user-identity normalizers emits a structurally valid all-null contract object at exit 0. [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 guards this exact mode explicitly, so the two halves of the preset currently disagree about a documented behavior. Same class: issue-view's comments degrade path only handles a blank response, not an error-object one (--argjson then fails with a raw jq error instead of the warned [] degrade).

Follow-up issues to file after merge (none blocking)

• The preset is now two idioms: issue-list / issue-search / recently-closed still use tea pulls|issues list --fields … --limit 200/1000 with the same truncation premise this PR disproves. Migrate them onto tea api + tea_api_paged.
• Repo-resolution unification (already proposed in the PR body) should absorb a third path: repo-archive.sh uses bare ${CODEV_REPO} with no fail-fast.
• forge-contracts.ts doc drift: the reviewRequests comment still says "GitLab/Gitea emit []", but gitea now populates real reviewer logins.
• Test gaps: no 3+ page walk, no mid-walk failure, no sub-50 server cap.
• _lib.sh creates a sibling-file dependency for hand-copied .codev/scripts/forge/gitea/ overrides; worth a line in the header.

Process notes

• The rebase documentation is exemplary: the vscode: one-step 'view issue N' / 'view pr N' from QuickPick + Cmd+K P for direct PR-by-ID open #1179url restoration, the 755 mode rationale, and the per-commit green verification were all stated up front and all verified true.
• Merge order vs [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 confirmed independent; either order is safe. The [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 reconcile (dropping list-and-search in favor of reading the create response) is the right shape.

Merge authority rests with the maintainer; this review is the reviewing architect's recommendation, not a gate approval.

[amrmelsayed]

Follow-up from the reviewing architect: finding 3 just got smaller

Merge order has been ruled by the maintainer: #1458 first, then this PR.

That changes the shape of one item in the review above. #1458 ships a # forge-executable: <tool> declaration that extractExecutable honours ahead of its first-substantive-line heuristic. With #1458 merged first, the "strongly recommended" finding 3 (the codev doctor regression) collapses to adding one line to each of the five sourced scripts:

#!/bin/sh# Forge concept: pr-exists (Gitea via tea CLI)# forge-executable: tea

The deeper extraction work the review asked for (resolving through sourced-helper calls, plus a test) is not required of you — that burden moved to #1458's mechanism, and a hardening addition to its builtin skip list is being pressed on that PR separately.

Everything else stands as written, and none of it waits on #1458: the two blockers (tea comment on 0.14.1, and capture-first in the three paginated scripts so a mid-walk failure can't read as a false-negative pr_exists gate) can be fixed now in either order. Finding 4 (the sub-50 max_response_items stop condition) is likewise independent.

[pseudoseed]

Review follow-up (2026-08-20)

Addressed both blocking items and the strongly-recommended item from the 2026-08-17 review, pushed as c9f55a537 (+ 481956e12 for the builder thread log):

1. (blocking) issue-comment.sh — tea comments add doesn't exist on 0.14.1
tea comments add is a 0.14.2+-only subcommand and fails on the still-current 0.14.1 release ("No help topic for comments"). Switched to the top-level tea comment <id> <body> shorthand, which works on both 0.14.1 and 0.14.2+.

2. (blocking) masked pipe failures in the paginated scripts
pr-exists.sh, pr-list.sh, and recently-merged.sh piped tea_api_paged | jq directly. POSIX sh has no pipefail, so a mid-walk pagination failure (tea_api_paged returning 1) was masked by jq's exit status — jq exits 0 on empty stdin, so pr-exists in particular would print "false" for a real API failure instead of erroring. That's a silent false-negative that could pass a porch pr_exists gate on a genuine error rather than an absent PR.

Fixed by capturing the paginator's output into a variable and checking its exit status before piping to jq:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

3. (strongly recommended, done) sub-limit server cap
tea_api_paged's stop condition compared each page's item count against the requested limit (50). A server whose max_response_items is tuned below that requested limit truncates every page — including non-last pages — to its own cap, so every page looked "short" against 50 and the loop broke after page 1, silently missing pages 2+. Now compares against the size actually observed on page 1 instead, so it keeps walking until a page is genuinely shorter than what the server has been returning.

4. (deferred, not done in this PR)
The # forge-executable: tea header convention depends on #1458 landing extractExecutable's header-parsing support first. Checked — #1458 is still open/unmerged, so this isn't actionable yet. Left as a follow-up once #1458 merges, matching the merge order already noted in the PR description (#1458 first, then this PR).

Testing

Added regression coverage for all three fixes in bugfix-1137-gitea-tea-api.test.ts:

• Updated the fake-tea stub to answer comment (not comments add).
• A mid-walk pagination failure fixture (full page 1, erroring page 2) exercised against all three paginated scripts — asserts non-zero exit and empty stdout rather than a silently wrong/empty result.
• A 3-page sub-50-per-page-cap fixture (30 + 30 + 6 items) proving pr-list keeps walking past a page that's full-but-capped rather than stopping because it's short relative to the requested limit.

Full local suite: 3197 passed, 126 failed (67 files) — the same pre-existing environment-dependent failures (agent-farm/terminal/consolidate; no built dist/ in this worktree) as the unmodified baseline reported earlier in this PR. Zero regressions, +4 new passing tests over the prior 3193.

[waleedkadous]

First — apologies for how long this sat; two months without a review is not how we want to treat a contribution, and this one is good: the real-script fake-CLI suite (contract normalization, pagination past page one, sub-50 server caps, mid-walk failures, tea 0.14.1 comment compatibility) is exactly the evidence this kind of fix needs, and moving branch input through jq --arg is a security improvement. Both integration reviews (codex + claude) agree the core mapping is right. Four things I'd like fixed before merge, all in the same spirit as the fix itself — fail loudly, never silently:

1. codev doctor regression. The five scripts that now source _lib.sh make doctor's executable extractor report . (and later tea_api_paged) instead of tea — verified, which . fails under /bin/sh. #1458 introduces a # forge-executable: tea header declaration for exactly this; please add those five lines here regardless of merge order so the regression can't ship.
2. Silent truncation at GITEA_MAX_PAGES. Reaching 100 pages without seeing a terminal short/empty page returns a partial array at exit 0 — the same false-negative pr-exists class the paginator exists to prevent. Fail explicitly instead.
3. Error bodies normalized into valid-looking output.tea api exits 0 on HTTP errors, and pr-view/user-identity/issue-view normalize without validating the response shape — an error object becomes an all-null PR (pr-view even leaks the error body's url into the contract) or the username null, at exit 0. Validate required fields/types before normalizing; the paginated scripts already fail loudly, so this brings the rest in line.
4. recently-merged.sh ignores CODEV_SINCE_DATE and can issue up to 100 sequential requests inside forge's 30-second timeout — on an established repo that turns the analytics path into null. Honoring the since-date bounds it.

Smaller, take-or-leave: CODEV_REPO is now overloaded (repo-archive's foreign-repo input vs. gitea read targeting) — a line in forge.md and both SKILL.md copies would help; and forge-contracts.ts's reviewRequests/isDraft comments go stale with this PR.

Merge order: #1458 first (it brings the # forge-executable mechanism), then this. Happy to turn the two around quickly once these land — and thank you for sticking with it.

[waleedkadous]

Given how long this waited on us, we'll take the last mile ourselves rather than hand you a list: a builder will push the review items directly onto this branch (you enabled maintainer edits — thank you), your commits and authorship stay as they are, and I'll re-review and merge once green. If you'd rather make the changes yourself, just say so and we'll hold off.

[waleedkadous]

Pushed the review items onto this branch as we offered — four commits on top of yours, nothing rebased or squashed, all ten of your commits and their authorship untouched. Thank you again for the contribution and for the patience; the real-script fake-CLI suite you built is what made all of this cheap to do, and every fix below is a test in your harness.

Also merged main in: #1458 landed, so the # forge-executable: mechanism is live.

The four required items

1. # forge-executable: tea headers. On six scripts, not five. The five that source _lib.sh are the ones the review named, but fixing item 3 in user-identity.sh required capturing tea api user before the jq pipe, which moves tea off the first substantive line — so without a header of its own, that fix would have caused the regression this item closes. Verified against the merged extractExecutable, not a simulation of it: all fourteen gitea concepts now resolve to tea.

2. The page ceiling fails loudly. Reaching GITEA_MAX_PAGES with every page full means we don't know we have the whole list, so it errors rather than returning the partial array at exit 0. One wrinkle worth naming: a list whose length is an exact multiple of the page size hits the ceiling with nothing missing, so it probes one page past before failing — a hard error on a complete result would be its own bug.

3. Shape validation before normalizing. The nastiest part of this one is that Gitea's error bodies carry a url (the swagger link), so url: (.html_url // .url)succeeded on them and shipped that link as the PR's browser page inside an otherwise all-null contract object. Required fields are now type-checked and failures carry the server's own .message on stderr. issue-view is validated before its comments are fetched, so a bad id reports only its own error instead of also warning about degraded comments on an issue that isn't there.

4. recently-merged honors CODEV_SINCE_DATE — it asks for sort=recentupdate and stops at the first page reaching past the cutoff. Details below, because this is where the reviewers earned their keep.

Plus the take-or-leave items: CODEV_REPO's two meanings documented in forge.md and both SKILL.md copies, and the reviewRequests/isDraft comments in forge-contracts.ts corrected — they claimed GitLab and Gitea emit empty/false, but all three presets populate them for real.

What the consultation caught, because it's the interesting part

I first wrote the since-date bound to fire when the current page was non-increasing in updated_at, reasoning that proved the server had honored sort=recentupdate. Both reviewers broke that, and they were right. Gitea's default order is index/created-DESC, and on a repo where PRs are opened and merged in order, index-DESC is non-increasing in updated_at. A long-lived PR opened in January and merged after the cutoff then sits on page 2, and we stop at page 1 and drop it — a silent loss in exactly the analytics path the bound was meant to protect.

The fix is to check for the property we actually need — the ordering — rather than for evidence that we asked for it. A stop now requires the order to survive a page boundary (previous page descending too, its oldest no older than this page's newest) and never fires on page 1, where there's nothing to compare against. A server that ignores the parameter falls back to your full walk: slower, never wrong. Costs exactly one extra request on an honest server.

The other finding I'm glad we ran: passing a page to the stop filter through jq --argjson blows up on Linux. MAX_ARG_STRLEN caps a single argv string at 128KiB regardless of ARG_MAX, and a 50-item Gitea pulls page — every object embedding full base.repo and head.repo — measures ~90KiB before anyone writes a long PR body. macOS has no per-argument cap, so it passed locally and would have failed on CI and for every Linux adopter. Both pages go in on stdin now.

Smaller ones from the same pass: jq length is 0 for both null and {}, so an error body mid-walk looked exactly like an exhausted list; jq on empty stdin emits nothing and exits 0, so two scripts were "succeeding" with empty stdout and never running their validators at all; a non-string .message threw a raw jq error instead of the legible one; and the test env inherited CODEV_* from the developer's shell, so the "no CODEV_SINCE_DATE" test was asserting the absence of a variable it didn't control.

Testing

41 tests in bugfix-1137-gitea-tea-api.test.ts, +20 on what you had. Your fake tea grew error bodies at exit 0 for pulls/issues/user, a comments endpoint answering with an error object and one answering with non-objects, a repo whose pages never end, one whose length is an exact multiple of the page size, ~150KB pages for the argv cap, and the sorted/lagging pair for the since-date bound — acme/lagging is the reviewer's counterexample verbatim.

Full suite after merging main: 5549 passed | 48 skipped, 0 failures. Every script also exercised under dash, which is what /bin/sh is on the CI runner, rather than only bash.

Two follow-ups from the earlier reviews are still unfiled and still worth doing, neither in scope here: migrating issue-list/issue-search/recently-closed off tea <entity> list --limit onto tea_api_paged (same truncation premise this PR disproved), and repo-archive.sh's bare ${CODEV_REPO} with no fail-fast.

Over to @waleedkadous for the re-review.

[waleedkadous]

Re-reviewed after the maintainer-side commits: six # forge-executable: tea headers (verified against the merged extractExecutable — all fourteen gitea concepts resolve to tea), the paginator now fails loudly at the page ceiling with a one-page probe so exact-multiple lists don't false-alarm, non-array error bodies are refused instead of normalized to null, recently-merged honors CODEV_SINCE_DATE with the stop filter fed via stdin (Linux argv cap), plus the docs and stale comments. 41 tests in the contributor's own fake-CLI harness; CI 7/7 green on a6eddb6. Approving and merging — thank you, @pseudoseed, for the contribution and the patience.

[pseudoseed]

Fixes#1137.

Bugfix-protocol re-do of the earlier SPIR-style PR #1138 (now closed), per maintainer request. Same root cause, plus a real regression test.

Problem

The gitea forge preset was authored against the Gitea REST API JSON shape, but the scripts invoke the tea CLI, whose output shape differs — and several concepts referenced flags/fields/subcommands tea doesn't have. Per the in-repo #920 note, tea wasn't available in the authoring environment, so the preset was never run end-to-end.

Fix

Route the read concepts through tea api (raw REST passthrough returning the shape forge-contracts.ts + the jq normalizers expect):

• user-identity: tea api user | jq .login (tea whoami has no --output json)
• pr-view: tea api repos/<repo>/pulls/N → PrViewResult (incl. additions/deletions)
• pr-list: tea api repos/<repo>/pulls?state=open → PrListItem[]
• pr-exists: tea api repos/<repo>/pulls?state=all with nested .head.ref / .merged
• issue-view: tea api repos/<repo>/issues/N + a second call for the comments array (Gitea reports comments as an int count, which would crash .comments.filter(...))
• recently-merged: tea api repos/<repo>/pulls?state=closed, filter .merged, using real .merged_at
• issue-comment: tea comments add (tea issues has no comment subcommand)

tea api needs an explicit owner/repo path segment, so each api-based script derives owner/repo from the origin remote (honoring CODEV_REPO when set).

Testing

• New regression test stubs a fake tea on PATH answering api <endpoint> with captured Gitea REST fixtures (tea isn't in CI, per vscode: editor-tab webview for rich backlog search #920), runs each real script, and asserts the normalized output conforms to forge-contracts.ts — incl. comments-as-array, merged-only filtering, open/merged/closed pr-exists, and CODEV_REPO override.
• Updates the pr_exists porch check fails when PR is merged before gate approval #568pr-exists assertion for the new state=all query param.
• Full suite green locally: build ✓, 3443 tests pass.

🤖 Generated with Claude Code

---

Rebased onto main (2026-08-14)

This branch was 2063 commits behind and mergeable=CONFLICTING. Rebased onto upstream/main; force-pushed to the fork. All 5 original commits preserved.

Exactly one file conflicted, twice — scripts/forge/gitea/pr-view.sh.

⚠️ Behaviour change from the conflict resolution: pr-view now emits url

While this branch sat, PIR #1179 landed on main and gave gitea pr-view a url field mapped from Gitea's html_url:

tea pulls view "$CODEV_PR_NUMBER" --output json | jq '.url = (.html_url // .url)'

This PR rewrites that same script onto tea api with an explicit normalizer — which emitted no url at all. Taking either side of the conflict wholesale loses something: take ours and #1179 is silently reverted, take theirs and the tea api fix is lost.

Resolution: both. The script keeps this PR's tea api routing and re-adds url: (.html_url // .url).

So, stated plainly rather than left in the diff: gitea pr-view now returns a url field that the pre-rebase branch did not return. That is a restoration of main's behaviour, not a new invention — forge-contracts.ts documents the Gitea mapping by name ("Gitea html_url — Gitea's url is the API endpoint, do not use it") — but it is a real change to this concept's output versus what this PR previously proposed, so it should not be discovered from the diff.

bugfix-1137-gitea-tea-api.test.ts was updated accordingly: the pulls/42 fixture now carries both html_url and url, and the assertion pins that the browser page, not the API endpoint, is what reaches the contract.

Two smaller deliberate deviations

• _lib.sh is committed 100755, not 100644.scripts/postinstall.mjs chmods every scripts/forge/**/*.sh to 755 unconditionally, so 644 is a mode that never survives an install and leaves a permanently dirty worktree for anyone who runs pnpm install. The file is sourced, not executed; the bit is inert.
• The test-fixture update was applied inside the test commit (via an interactive rebase stop) rather than as a trailing fixup, so every commit is green in isolation — verified by checking out and testing all 5 individually.

Relationship to #1458

#1458 (pr-create as a forge concept) landed while this PR was open, and its gitea pr-create.sh looked the new PR up with tea pulls list --limit 200 — the exact call this PR proves silently truncates. That has been fixed on #1458's branch, not here: it now creates via tea api -X POST …/pulls, which returns the created PR directly, so the lookup is gone rather than paginated.

Re-confirmed live against Forgejo 15.0.2 while doing so: settings/api reports max_response_items: 50, and a ?limit=200 request returns exactly 50 items on a list where paging at 50 returns 53. The premise behind this PR's pagination work holds.

Merge-order implications are spelled out in full at the end of this description.

Verification

• All 5 commits pass the forge suites individually (bugfix-1137-gitea-tea-api, bugfix-568-pr-exists-state-all, forge, bugfix-693-forge-exec-bit).
• Full @cluesmith/codev unit suite, rebased tip: 3193 passed, 126 failed (67 files).
• Baseline run of the same suite on unmodified upstream/main in the same worktree: 3176 passed, 126 failed (67 files) — the same 67 files and the same 126 tests.
• So: zero regressions; this branch adds 17 passing tests and breaks nothing. The pre-existing failures are all agent-farm / terminal / consolidate (attach, session-manager, shellper sockets, SQLite state), environment-dependent — this worktree has no built dist/, which those tests spawn from, and a live Tower is running against the same state. None is in a file this PR touches, and every forge suite passes.

Merge order with the sibling PR — verified, not assumed

#1146 and #1458 come from the same fork and both touch packages/codev/scripts/forge/gitea/, so the ordering question is fair. The answer:

Either order is safe. There is no dependency and no conflict.

Question	Answer	How it was checked
Do they conflict?	No.	git merge-tree on the two branch tips merges cleanly. The only file both touch is the builder thread log, which is the identical blob on both branches and auto-merges.
Must one merge first?	No.	#1458's pr-create.sh does not source _lib.sh and does not call gitea_repo or tea_api_paged. Nothing in it resolves against #1146.
Does the merged result hold together?	Yes.	In the merged tree, _lib.sh and pr-view.sh are byte-identical to #1146's versions and pr-create.sh byte-identical to #1458's — no silent blending. The bugfix-693 invariant (every entry under each provider dir is a *.sh) still holds with _lib.sh present.

Does #1458 duplicate something #1146 makes shared?

The paginator: no, and it shouldn't._lib.sh#tea_api_paged exists to walk a truncating list endpoint. pr-create no longer lists anything — it reads the new PR out of the create response — so there is no pagination for it to share. That is the point of the reconcile rather than an oversight.

Repo resolution: yes, there are two paths, and this is worth a follow-up.

• [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146's read concepts: . _lib.sh → gitea_repo(), which honours CODEV_REPO, else derives owner/repo from the origin remote, and fails fast naming CODEV_REPO as the remedy.
• [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458's pr-create: tea's own {owner}/{repo} placeholders, with CODEV_PR_REPO forwarded as tea --repo.

They were kept separate deliberately, for two reasons rather than by omission:

1. Different contract.pr-create takes CODEV_PR_REPO; the read concepts take CODEV_REPO. gitea_repo() reads the latter and takes no argument, so pr-create could not call it without changing its signature — which would mean editing a [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146 file from [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 and creating exactly the merge-order coupling this avoids.
2. --repo does more than fill a path. It also supplies tea's repo/login context, verified working from a cwd whose remote is not a Gitea host. A path-only helper does not do that.

Recommended follow-up (not done here, deliberately): once both PRs have landed, unify the two behind one helper that takes the override variable as a parameter — e.g. gitea_repo "$CODEV_PR_REPO" — so there is one repo-resolution path with one error message. Doing it now would couple two independent PRs; doing it never leaves two paths that will drift. It is a small, mechanical change against a tree where both are already present.

The one ergonomic gap that split created has been closed in the meantime: an unresolvable repo used to surface from pr-create as a bare 404 page not found, and now names CODEV_PR_REPO as the remedy, matching gitea_repo()'s fail-fast message.

[waleedkadous]

Excellent work — thank you for the disciplined re-do, and apologies for the review latency. This is what a model bugfix PR looks like: every tea-CLI deficiency documented in-script with reasoning, the REST passthrough returning exactly the shape forge-contracts.ts expects, and a genuinely well-built regression suite (fake tea on PATH serving captured REST fixtures, the real scripts executed, contract-shape assertions, the comments-as-int crash and null-login team reviewers both covered). We verified every output mapping field-by-field against the contracts — all conform — and the switch from string-interpolated jq to --arg in pr-exists is a quiet security improvement worth crediting.

One substantive question before merge, and two optional polish items:

1. Pagination cap (the one we'd like addressed or answered). Gitea servers cap page size at max_response_items (default 50), so ?limit=200 likely returns 50 items with no client-side pagination in the raw passthrough. That means pr-exists?state=all can false-negative for a branch whose PR isn't in the most recent ~50 (which would block a porch pr_exists gate), and recently-merged (previously --limit 1000) can miss on a busy repo. A pagination loop (page=1..N until a short page) would settle it — or at minimum a comment documenting the server-side cap and the false-negative window, so the next debugger isn't blind. Happy with either; we'd just like the behavior to be chosen rather than inherited.

2. (Polish, optional) With no origin remote or an unusual URL, REPO silently becomes empty/garbage and tea api "repos//…" fails with a confusing 404. An explicit [ -n "$REPO" ] || { echo "…set CODEV_REPO" >&2; exit 1; } naming the remedy would fit this repo's fail-fast convention — ideally factored once since the derivation appears in five scripts.

3. (Polish, optional) A failed comments fetch silently yields comments: [] — indistinguishable from "no comments" for consumers reading issue discussion. A stderr warning on the degraded path would keep the graceful behavior while leaving a trace.

Verdict: approve once item 1 is addressed (fix or documented caveat — your choice). Items 2–3 are welcome in this PR or a follow-up, contributor's choice.

[pseudoseed]

Thanks for the thorough review — all three items addressed in 3c2e3c2b.

1. Pagination — fixed (real page loop, not a comment). You're right that ?limit=200 inherited Gitea's max_response_items cap (default 50) and silently truncated. Added a shared tea_api_paged helper in a new scripts/forge/gitea/_lib.sh that requests page=1,2,3… at an explicit limit=50, concatenates each page's array (jq -s add), and stops when a page comes back shorter than the limit (or empty). Chosen behavior: it paginates, with a hard ceiling of 100 pages (100 × 50 = 5000 items) so a misbehaving server can't spin forever — documented in the helper. Wired into all three list reads: pr-exists (state=all), pr-list (state=open), recently-merged (state=closed). Output shape is unchanged — the concatenated array feeds the existing jq normalizers untouched. New tests serve a full 50-item page 1 + a short page 2 and assert an item that exists only on page 2 is found by each of the three scripts (pr-exists returns true for it, pr-list/recently-merged include it).

2. REPO fail-fast, factored once — done. The CODEV_REPO/origin-derivation line (duplicated in five scripts) now lives in _lib.sh#gitea_repo, sourced via . "$(dirname "$0")/_lib.sh" by issue-view, pr-exists, pr-list, pr-view, and recently-merged. It validates the result is a clean owner/repo; if not (no origin, unusual URL), it prints set CODEV_REPO=owner/repo to stderr and exits non-zero instead of letting tea api "repos//…" 404. Verified before factoring: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist (a leading-underscore file is never registered as a concept), package.jsonfiles ships scripts/forge so _lib.sh is packaged, it's POSIX sh (no bashisms), and $0-relative sourcing works when the script is invoked by absolute path (how forge runs it via sh -c). Tests cover missing-origin and garbage-URL → non-zero exit + the stderr remedy.

3. Degraded comments warn — done.issue-view still degrades a failed comments fetch to [], but now writes gitea forge: comments fetch failed for issue N; reporting 0 comments to stderr while stdout stays pure JSON. Test asserts both (comments: [] on stdout and the stderr warning).

Full suite green in the worktree: 3449 passed | 48 skipped, 0 failures (pnpm build + pnpm test). The #568pr-existsstate=all assertion stays green (the helper is still called with state=all).

[pseudoseed]

@waleedkadous let me know if there's anything else that needs to be addressed with this one :)

[pseudoseed]

Verified against a real Forgejo + tea — all six concepts pass

The PR notes that tea wasn't available in the authoring environment and the preset was never run end to end. It has now been. I ran this branch's scripts against a live Forgejo instance with tea 0.14.2, on a repo with ~355 issues and ~350 PRs.

Environment: Forgejo, tea 0.14.2 (go-sdk v1.1.0), single configured login, scripts invoked directly with CODEV_REPO set.

Before — released version, same environment

concept	result
user-identity	FAILIncorrect Usage: flag provided but not defined: -output
issue-view	FAILjq: Cannot index array with string "html_url"
pr-list	FAIL, exit 0 — prints Error: invalid field 'description' and still returns success
recently-merged	FAIL, exit 0 — same
pr-view	returns a list, not the requested PR
issue-list, issue-search, pr-exists, recently-closed, auth-status	OK

The two exit-0 cases are the nastiest: a caller checking the exit status sees success and gets an error string where JSON should be.

After — this branch, same environment

concept	result
user-identity	OK — user
issue-view	OK — object with title, body, state, url, comments[]
pr-list	OK — normalized PrListItem[]
pr-view	OK — single PR object, correct one
pr-exists	OK — true
recently-merged	OK — merged-only, correct merged_at ordering

All six previously-broken concepts now work. No regressions in the five that already worked.

Two notes

The comments-as-int catch is real and would have bitten immediately. Gitea returns comments as an integer count on the issue object; our issue-view on the released version failed exactly there. The second call for the comments array is necessary, not defensive.

One nearly-false report from me, worth stating so nobody repeats it. My first run of this branch's issue-view failed with Cannot index array with string "title". That was my harness, not your code — I had exported CODEV_ISSUE_NUMBER where the contract is CODEV_ISSUE_ID, so the path resolved to the issue list endpoint. With the correct variable it works. Flagging it because the failure mode is plausible-looking and someone else testing this could draw the wrong conclusion.

Unrelated gap this surfaced

pr-create is not a forge concept at all, so gh pr create stays hardcoded in the skeleton prompts (porch/prompts/pr.md, protocols/{air,spir,pir,bugfix,maintain}/…). That means a Gitea/Forgejo user still needs a gh shim on PATH no matter how complete this preset becomes. Not this PR's problem — filing separately — but relevant if anyone assumes a working gitea preset makes gh unnecessary.

Happy to re-run against any further revisions.

[amrmelsayed]

Reviewer Integration Review (CMAP-3)

Three-lane consultation (Gemini, GPT-5.6 Sol via Codex, Claude Opus) plus an independent architect pass. Every finding below was re-verified by the reviewing architect against the actual source, and the tea-CLI claims against the installed release binary, before being credited.

Verdict: REQUEST CHANGES (light). The core fix is correct, honestly documented, and the best-evidenced community PR this repo has received: the tea api rerouting, the pagination premise, the #1179 conflict resolution, and the merge-order analysis vs #1458 all check out. Lane split: Gemini APPROVE; Codex and Claude REQUEST_CHANGES. Two items are blocking; the rest are tiered below so nothing has to be rediscovered later.

Verified solid (no action)

• _lib.sh is safely inert as a concept: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist, so a leading-underscore file is never registered. Verified at forge.ts:64.
• $(dirname "$0") sourcing holds in the real call path: executeForgeCommand runs the absolute script path via sh -c.
• package.jsonfiles ships scripts/forge, and the bugfix-693 invariant (every provider-dir entry matches *.sh) still holds with _lib.sh present. The 755-mode argument is correct (postinstall chmods unconditionally).
• All four emitted shapes conform exactly to forge-contracts.ts (PrViewResult, PrListItem, MergedPrItem, IssueViewResult), and the --arg branch switch in pr-exists is a real injection fix.
• Pagination premise re-confirmed: issue gitea forge preset is broken against the real tea CLI (0.14.2) #1137 is still open, no forge-script drift on main since your 08-14 rebase, branch is MERGEABLE.

Blocking

1. issue-comment.sh breaks on the current released tea (0.14.1).tea comments add only exists from tea 0.14.2; on 0.14.1 (current Homebrew release) it exits with No help topic for 'comments'. Verified against the installed 0.14.1 binary and the tea source at both tags: tea comment "$CODEV_ISSUE_ID" "$CODEV_COMMENT_BODY" exists on 0.14.1 and is explicitly preserved as a shorthand in 0.14.2+, so it works on every version. This slipped through because issue-comment is the one concept absent from the live-verification tables (that run used tea 0.14.2), and the fake-tea stub implements comments add by fiat, pinning the assumption rather than testing it. One-word fix plus updating the stub to answer comment instead.

2. Paginator failure exits 0 with empty stdout, which reads as a false-negative pr_exists gate.tea_api_paged's return 1 sits on the left of a pipe in POSIX sh (no pipefail), so the script's exit status is jq's (0) and stdout is empty. Porch's pr-exists check (checks.ts:365) maps anything that isn't "true" to passed: false, so a transient failure mid-walk reports "no PR exists": the exact failure mode pagination was added to prevent. Fix in all three list scripts by capturing first:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

This also converts the jq -s add raw-type-error wart you flagged in the thread log into a clean non-zero exit.

Strongly recommended in this PR (both small, both introduced here)

3. codev doctor regression for gitea users.extractExecutable (forge.ts:192) skips comments, if, and assignments, but not dot-sourcing: the first substantive token in the five sourced scripts is ., and which . fails, so doctor shows five false "not found" rows and stops verifying tea for those concepts. Note the fix is not just skipping .: after the source line and the REPO= assignment are skipped, the next token in the three list scripts is tea_api_paged (a shell function), which also fails the which check. The extraction needs to resolve through sourced-helper calls (or the gitea preset needs declared executables), plus a test; no existing test covers this path, which is why the suite stayed green.

4. The stop condition trusts that the server honored limit=50.max_response_items is admin-tunable; on a server capped below 50, every page is "short", the loop breaks after page 1, and silent truncation returns on exactly the servers that tuned the cap. Derive the effective page size from page 1's item count and break when a page is shorter than that (or stop only on an empty page, at the cost of one extra request per walk). Worth a test with a sub-50 cap.

Maintainer's call: in-PR or filed as follow-ups

• recently-merged ignores CODEV_SINCE_DATE and now walks the full closed-PR history (up to 100 sequential requests, 2 jq spawns per page) inside forge's 30s timeout (forge.ts:323). On a large Gitea repo that risks timeout, and a timeout yields null: a worse dashboard outcome than truncation was. An early-exit on the since-date or a tighter page bound for this concept would cover it.
• Non-paged reads don't validate tea api's exit-0-on-error responses. An HTTP error body piped into the pr-view/issue-view/user-identity normalizers emits a structurally valid all-null contract object at exit 0. [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 guards this exact mode explicitly, so the two halves of the preset currently disagree about a documented behavior. Same class: issue-view's comments degrade path only handles a blank response, not an error-object one (--argjson then fails with a raw jq error instead of the warned [] degrade).

Follow-up issues to file after merge (none blocking)

• The preset is now two idioms: issue-list / issue-search / recently-closed still use tea pulls|issues list --fields … --limit 200/1000 with the same truncation premise this PR disproves. Migrate them onto tea api + tea_api_paged.
• Repo-resolution unification (already proposed in the PR body) should absorb a third path: repo-archive.sh uses bare ${CODEV_REPO} with no fail-fast.
• forge-contracts.ts doc drift: the reviewRequests comment still says "GitLab/Gitea emit []", but gitea now populates real reviewer logins.
• Test gaps: no 3+ page walk, no mid-walk failure, no sub-50 server cap.
• _lib.sh creates a sibling-file dependency for hand-copied .codev/scripts/forge/gitea/ overrides; worth a line in the header.

Process notes

• The rebase documentation is exemplary: the vscode: one-step 'view issue N' / 'view pr N' from QuickPick + Cmd+K P for direct PR-by-ID open #1179url restoration, the 755 mode rationale, and the per-commit green verification were all stated up front and all verified true.
• Merge order vs [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 confirmed independent; either order is safe. The [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 reconcile (dropping list-and-search in favor of reading the create response) is the right shape.

Merge authority rests with the maintainer; this review is the reviewing architect's recommendation, not a gate approval.

[amrmelsayed]

Follow-up from the reviewing architect: finding 3 just got smaller

Merge order has been ruled by the maintainer: #1458 first, then this PR.

That changes the shape of one item in the review above. #1458 ships a # forge-executable: <tool> declaration that extractExecutable honours ahead of its first-substantive-line heuristic. With #1458 merged first, the "strongly recommended" finding 3 (the codev doctor regression) collapses to adding one line to each of the five sourced scripts:

#!/bin/sh# Forge concept: pr-exists (Gitea via tea CLI)# forge-executable: tea

The deeper extraction work the review asked for (resolving through sourced-helper calls, plus a test) is not required of you — that burden moved to #1458's mechanism, and a hardening addition to its builtin skip list is being pressed on that PR separately.

Everything else stands as written, and none of it waits on #1458: the two blockers (tea comment on 0.14.1, and capture-first in the three paginated scripts so a mid-walk failure can't read as a false-negative pr_exists gate) can be fixed now in either order. Finding 4 (the sub-50 max_response_items stop condition) is likewise independent.

[pseudoseed]

Review follow-up (2026-08-20)

Addressed both blocking items and the strongly-recommended item from the 2026-08-17 review, pushed as c9f55a537 (+ 481956e12 for the builder thread log):

1. (blocking) issue-comment.sh — tea comments add doesn't exist on 0.14.1
tea comments add is a 0.14.2+-only subcommand and fails on the still-current 0.14.1 release ("No help topic for comments"). Switched to the top-level tea comment <id> <body> shorthand, which works on both 0.14.1 and 0.14.2+.

2. (blocking) masked pipe failures in the paginated scripts
pr-exists.sh, pr-list.sh, and recently-merged.sh piped tea_api_paged | jq directly. POSIX sh has no pipefail, so a mid-walk pagination failure (tea_api_paged returning 1) was masked by jq's exit status — jq exits 0 on empty stdin, so pr-exists in particular would print "false" for a real API failure instead of erroring. That's a silent false-negative that could pass a porch pr_exists gate on a genuine error rather than an absent PR.

Fixed by capturing the paginator's output into a variable and checking its exit status before piping to jq:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

3. (strongly recommended, done) sub-limit server cap
tea_api_paged's stop condition compared each page's item count against the requested limit (50). A server whose max_response_items is tuned below that requested limit truncates every page — including non-last pages — to its own cap, so every page looked "short" against 50 and the loop broke after page 1, silently missing pages 2+. Now compares against the size actually observed on page 1 instead, so it keeps walking until a page is genuinely shorter than what the server has been returning.

4. (deferred, not done in this PR)
The # forge-executable: tea header convention depends on #1458 landing extractExecutable's header-parsing support first. Checked — #1458 is still open/unmerged, so this isn't actionable yet. Left as a follow-up once #1458 merges, matching the merge order already noted in the PR description (#1458 first, then this PR).

Testing

Added regression coverage for all three fixes in bugfix-1137-gitea-tea-api.test.ts:

• Updated the fake-tea stub to answer comment (not comments add).
• A mid-walk pagination failure fixture (full page 1, erroring page 2) exercised against all three paginated scripts — asserts non-zero exit and empty stdout rather than a silently wrong/empty result.
• A 3-page sub-50-per-page-cap fixture (30 + 30 + 6 items) proving pr-list keeps walking past a page that's full-but-capped rather than stopping because it's short relative to the requested limit.

Full local suite: 3197 passed, 126 failed (67 files) — the same pre-existing environment-dependent failures (agent-farm/terminal/consolidate; no built dist/ in this worktree) as the unmodified baseline reported earlier in this PR. Zero regressions, +4 new passing tests over the prior 3193.

[waleedkadous]

First — apologies for how long this sat; two months without a review is not how we want to treat a contribution, and this one is good: the real-script fake-CLI suite (contract normalization, pagination past page one, sub-50 server caps, mid-walk failures, tea 0.14.1 comment compatibility) is exactly the evidence this kind of fix needs, and moving branch input through jq --arg is a security improvement. Both integration reviews (codex + claude) agree the core mapping is right. Four things I'd like fixed before merge, all in the same spirit as the fix itself — fail loudly, never silently:

1. codev doctor regression. The five scripts that now source _lib.sh make doctor's executable extractor report . (and later tea_api_paged) instead of tea — verified, which . fails under /bin/sh. #1458 introduces a # forge-executable: tea header declaration for exactly this; please add those five lines here regardless of merge order so the regression can't ship.
2. Silent truncation at GITEA_MAX_PAGES. Reaching 100 pages without seeing a terminal short/empty page returns a partial array at exit 0 — the same false-negative pr-exists class the paginator exists to prevent. Fail explicitly instead.
3. Error bodies normalized into valid-looking output.tea api exits 0 on HTTP errors, and pr-view/user-identity/issue-view normalize without validating the response shape — an error object becomes an all-null PR (pr-view even leaks the error body's url into the contract) or the username null, at exit 0. Validate required fields/types before normalizing; the paginated scripts already fail loudly, so this brings the rest in line.
4. recently-merged.sh ignores CODEV_SINCE_DATE and can issue up to 100 sequential requests inside forge's 30-second timeout — on an established repo that turns the analytics path into null. Honoring the since-date bounds it.

Smaller, take-or-leave: CODEV_REPO is now overloaded (repo-archive's foreign-repo input vs. gitea read targeting) — a line in forge.md and both SKILL.md copies would help; and forge-contracts.ts's reviewRequests/isDraft comments go stale with this PR.

Merge order: #1458 first (it brings the # forge-executable mechanism), then this. Happy to turn the two around quickly once these land — and thank you for sticking with it.

[waleedkadous]

Given how long this waited on us, we'll take the last mile ourselves rather than hand you a list: a builder will push the review items directly onto this branch (you enabled maintainer edits — thank you), your commits and authorship stay as they are, and I'll re-review and merge once green. If you'd rather make the changes yourself, just say so and we'll hold off.

[waleedkadous]

Pushed the review items onto this branch as we offered — four commits on top of yours, nothing rebased or squashed, all ten of your commits and their authorship untouched. Thank you again for the contribution and for the patience; the real-script fake-CLI suite you built is what made all of this cheap to do, and every fix below is a test in your harness.

Also merged main in: #1458 landed, so the # forge-executable: mechanism is live.

The four required items

1. # forge-executable: tea headers. On six scripts, not five. The five that source _lib.sh are the ones the review named, but fixing item 3 in user-identity.sh required capturing tea api user before the jq pipe, which moves tea off the first substantive line — so without a header of its own, that fix would have caused the regression this item closes. Verified against the merged extractExecutable, not a simulation of it: all fourteen gitea concepts now resolve to tea.

2. The page ceiling fails loudly. Reaching GITEA_MAX_PAGES with every page full means we don't know we have the whole list, so it errors rather than returning the partial array at exit 0. One wrinkle worth naming: a list whose length is an exact multiple of the page size hits the ceiling with nothing missing, so it probes one page past before failing — a hard error on a complete result would be its own bug.

3. Shape validation before normalizing. The nastiest part of this one is that Gitea's error bodies carry a url (the swagger link), so url: (.html_url // .url)succeeded on them and shipped that link as the PR's browser page inside an otherwise all-null contract object. Required fields are now type-checked and failures carry the server's own .message on stderr. issue-view is validated before its comments are fetched, so a bad id reports only its own error instead of also warning about degraded comments on an issue that isn't there.

4. recently-merged honors CODEV_SINCE_DATE — it asks for sort=recentupdate and stops at the first page reaching past the cutoff. Details below, because this is where the reviewers earned their keep.

Plus the take-or-leave items: CODEV_REPO's two meanings documented in forge.md and both SKILL.md copies, and the reviewRequests/isDraft comments in forge-contracts.ts corrected — they claimed GitLab and Gitea emit empty/false, but all three presets populate them for real.

What the consultation caught, because it's the interesting part

I first wrote the since-date bound to fire when the current page was non-increasing in updated_at, reasoning that proved the server had honored sort=recentupdate. Both reviewers broke that, and they were right. Gitea's default order is index/created-DESC, and on a repo where PRs are opened and merged in order, index-DESC is non-increasing in updated_at. A long-lived PR opened in January and merged after the cutoff then sits on page 2, and we stop at page 1 and drop it — a silent loss in exactly the analytics path the bound was meant to protect.

The fix is to check for the property we actually need — the ordering — rather than for evidence that we asked for it. A stop now requires the order to survive a page boundary (previous page descending too, its oldest no older than this page's newest) and never fires on page 1, where there's nothing to compare against. A server that ignores the parameter falls back to your full walk: slower, never wrong. Costs exactly one extra request on an honest server.

The other finding I'm glad we ran: passing a page to the stop filter through jq --argjson blows up on Linux. MAX_ARG_STRLEN caps a single argv string at 128KiB regardless of ARG_MAX, and a 50-item Gitea pulls page — every object embedding full base.repo and head.repo — measures ~90KiB before anyone writes a long PR body. macOS has no per-argument cap, so it passed locally and would have failed on CI and for every Linux adopter. Both pages go in on stdin now.

Smaller ones from the same pass: jq length is 0 for both null and {}, so an error body mid-walk looked exactly like an exhausted list; jq on empty stdin emits nothing and exits 0, so two scripts were "succeeding" with empty stdout and never running their validators at all; a non-string .message threw a raw jq error instead of the legible one; and the test env inherited CODEV_* from the developer's shell, so the "no CODEV_SINCE_DATE" test was asserting the absence of a variable it didn't control.

Testing

41 tests in bugfix-1137-gitea-tea-api.test.ts, +20 on what you had. Your fake tea grew error bodies at exit 0 for pulls/issues/user, a comments endpoint answering with an error object and one answering with non-objects, a repo whose pages never end, one whose length is an exact multiple of the page size, ~150KB pages for the argv cap, and the sorted/lagging pair for the since-date bound — acme/lagging is the reviewer's counterexample verbatim.

Full suite after merging main: 5549 passed | 48 skipped, 0 failures. Every script also exercised under dash, which is what /bin/sh is on the CI runner, rather than only bash.

Two follow-ups from the earlier reviews are still unfiled and still worth doing, neither in scope here: migrating issue-list/issue-search/recently-closed off tea <entity> list --limit onto tea_api_paged (same truncation premise this PR disproved), and repo-archive.sh's bare ${CODEV_REPO} with no fail-fast.

Over to @waleedkadous for the re-review.

[waleedkadous]

Re-reviewed after the maintainer-side commits: six # forge-executable: tea headers (verified against the merged extractExecutable — all fourteen gitea concepts resolve to tea), the paginator now fails loudly at the page ceiling with a one-page probe so exact-multiple lists don't false-alarm, non-array error bodies are refused instead of normalized to null, recently-merged honors CODEV_SINCE_DATE with the stop filter fed via stdin (Linux argv cap), plus the docs and stale comments. 41 tests in the contributor's own fake-CLI harness; CI 7/7 green on a6eddb6. Approving and merging — thank you, @pseudoseed, for the contribution and the patience.

[pseudoseed]

Fixes#1137.

Bugfix-protocol re-do of the earlier SPIR-style PR #1138 (now closed), per maintainer request. Same root cause, plus a real regression test.

Problem

The gitea forge preset was authored against the Gitea REST API JSON shape, but the scripts invoke the tea CLI, whose output shape differs — and several concepts referenced flags/fields/subcommands tea doesn't have. Per the in-repo #920 note, tea wasn't available in the authoring environment, so the preset was never run end-to-end.

Fix

Route the read concepts through tea api (raw REST passthrough returning the shape forge-contracts.ts + the jq normalizers expect):

• user-identity: tea api user | jq .login (tea whoami has no --output json)
• pr-view: tea api repos/<repo>/pulls/N → PrViewResult (incl. additions/deletions)
• pr-list: tea api repos/<repo>/pulls?state=open → PrListItem[]
• pr-exists: tea api repos/<repo>/pulls?state=all with nested .head.ref / .merged
• issue-view: tea api repos/<repo>/issues/N + a second call for the comments array (Gitea reports comments as an int count, which would crash .comments.filter(...))
• recently-merged: tea api repos/<repo>/pulls?state=closed, filter .merged, using real .merged_at
• issue-comment: tea comments add (tea issues has no comment subcommand)

tea api needs an explicit owner/repo path segment, so each api-based script derives owner/repo from the origin remote (honoring CODEV_REPO when set).

Testing

• New regression test stubs a fake tea on PATH answering api <endpoint> with captured Gitea REST fixtures (tea isn't in CI, per vscode: editor-tab webview for rich backlog search #920), runs each real script, and asserts the normalized output conforms to forge-contracts.ts — incl. comments-as-array, merged-only filtering, open/merged/closed pr-exists, and CODEV_REPO override.
• Updates the pr_exists porch check fails when PR is merged before gate approval #568pr-exists assertion for the new state=all query param.
• Full suite green locally: build ✓, 3443 tests pass.

🤖 Generated with Claude Code

---

Rebased onto main (2026-08-14)

This branch was 2063 commits behind and mergeable=CONFLICTING. Rebased onto upstream/main; force-pushed to the fork. All 5 original commits preserved.

Exactly one file conflicted, twice — scripts/forge/gitea/pr-view.sh.

⚠️ Behaviour change from the conflict resolution: pr-view now emits url

While this branch sat, PIR #1179 landed on main and gave gitea pr-view a url field mapped from Gitea's html_url:

tea pulls view "$CODEV_PR_NUMBER" --output json | jq '.url = (.html_url // .url)'

This PR rewrites that same script onto tea api with an explicit normalizer — which emitted no url at all. Taking either side of the conflict wholesale loses something: take ours and #1179 is silently reverted, take theirs and the tea api fix is lost.

Resolution: both. The script keeps this PR's tea api routing and re-adds url: (.html_url // .url).

So, stated plainly rather than left in the diff: gitea pr-view now returns a url field that the pre-rebase branch did not return. That is a restoration of main's behaviour, not a new invention — forge-contracts.ts documents the Gitea mapping by name ("Gitea html_url — Gitea's url is the API endpoint, do not use it") — but it is a real change to this concept's output versus what this PR previously proposed, so it should not be discovered from the diff.

bugfix-1137-gitea-tea-api.test.ts was updated accordingly: the pulls/42 fixture now carries both html_url and url, and the assertion pins that the browser page, not the API endpoint, is what reaches the contract.

Two smaller deliberate deviations

• _lib.sh is committed 100755, not 100644.scripts/postinstall.mjs chmods every scripts/forge/**/*.sh to 755 unconditionally, so 644 is a mode that never survives an install and leaves a permanently dirty worktree for anyone who runs pnpm install. The file is sourced, not executed; the bit is inert.
• The test-fixture update was applied inside the test commit (via an interactive rebase stop) rather than as a trailing fixup, so every commit is green in isolation — verified by checking out and testing all 5 individually.

Relationship to #1458

#1458 (pr-create as a forge concept) landed while this PR was open, and its gitea pr-create.sh looked the new PR up with tea pulls list --limit 200 — the exact call this PR proves silently truncates. That has been fixed on #1458's branch, not here: it now creates via tea api -X POST …/pulls, which returns the created PR directly, so the lookup is gone rather than paginated.

Re-confirmed live against Forgejo 15.0.2 while doing so: settings/api reports max_response_items: 50, and a ?limit=200 request returns exactly 50 items on a list where paging at 50 returns 53. The premise behind this PR's pagination work holds.

Merge-order implications are spelled out in full at the end of this description.

Verification

• All 5 commits pass the forge suites individually (bugfix-1137-gitea-tea-api, bugfix-568-pr-exists-state-all, forge, bugfix-693-forge-exec-bit).
• Full @cluesmith/codev unit suite, rebased tip: 3193 passed, 126 failed (67 files).
• Baseline run of the same suite on unmodified upstream/main in the same worktree: 3176 passed, 126 failed (67 files) — the same 67 files and the same 126 tests.
• So: zero regressions; this branch adds 17 passing tests and breaks nothing. The pre-existing failures are all agent-farm / terminal / consolidate (attach, session-manager, shellper sockets, SQLite state), environment-dependent — this worktree has no built dist/, which those tests spawn from, and a live Tower is running against the same state. None is in a file this PR touches, and every forge suite passes.

Merge order with the sibling PR — verified, not assumed

#1146 and #1458 come from the same fork and both touch packages/codev/scripts/forge/gitea/, so the ordering question is fair. The answer:

Either order is safe. There is no dependency and no conflict.

Question	Answer	How it was checked
Do they conflict?	No.	git merge-tree on the two branch tips merges cleanly. The only file both touch is the builder thread log, which is the identical blob on both branches and auto-merges.
Must one merge first?	No.	#1458's pr-create.sh does not source _lib.sh and does not call gitea_repo or tea_api_paged. Nothing in it resolves against #1146.
Does the merged result hold together?	Yes.	In the merged tree, _lib.sh and pr-view.sh are byte-identical to #1146's versions and pr-create.sh byte-identical to #1458's — no silent blending. The bugfix-693 invariant (every entry under each provider dir is a *.sh) still holds with _lib.sh present.

Does #1458 duplicate something #1146 makes shared?

The paginator: no, and it shouldn't._lib.sh#tea_api_paged exists to walk a truncating list endpoint. pr-create no longer lists anything — it reads the new PR out of the create response — so there is no pagination for it to share. That is the point of the reconcile rather than an oversight.

Repo resolution: yes, there are two paths, and this is worth a follow-up.

• [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146's read concepts: . _lib.sh → gitea_repo(), which honours CODEV_REPO, else derives owner/repo from the origin remote, and fails fast naming CODEV_REPO as the remedy.
• [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458's pr-create: tea's own {owner}/{repo} placeholders, with CODEV_PR_REPO forwarded as tea --repo.

They were kept separate deliberately, for two reasons rather than by omission:

1. Different contract.pr-create takes CODEV_PR_REPO; the read concepts take CODEV_REPO. gitea_repo() reads the latter and takes no argument, so pr-create could not call it without changing its signature — which would mean editing a [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146 file from [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 and creating exactly the merge-order coupling this avoids.
2. --repo does more than fill a path. It also supplies tea's repo/login context, verified working from a cwd whose remote is not a Gitea host. A path-only helper does not do that.

Recommended follow-up (not done here, deliberately): once both PRs have landed, unify the two behind one helper that takes the override variable as a parameter — e.g. gitea_repo "$CODEV_PR_REPO" — so there is one repo-resolution path with one error message. Doing it now would couple two independent PRs; doing it never leaves two paths that will drift. It is a small, mechanical change against a tree where both are already present.

The one ergonomic gap that split created has been closed in the meantime: an unresolvable repo used to surface from pr-create as a bare 404 page not found, and now names CODEV_PR_REPO as the remedy, matching gitea_repo()'s fail-fast message.

[waleedkadous]

Excellent work — thank you for the disciplined re-do, and apologies for the review latency. This is what a model bugfix PR looks like: every tea-CLI deficiency documented in-script with reasoning, the REST passthrough returning exactly the shape forge-contracts.ts expects, and a genuinely well-built regression suite (fake tea on PATH serving captured REST fixtures, the real scripts executed, contract-shape assertions, the comments-as-int crash and null-login team reviewers both covered). We verified every output mapping field-by-field against the contracts — all conform — and the switch from string-interpolated jq to --arg in pr-exists is a quiet security improvement worth crediting.

One substantive question before merge, and two optional polish items:

1. Pagination cap (the one we'd like addressed or answered). Gitea servers cap page size at max_response_items (default 50), so ?limit=200 likely returns 50 items with no client-side pagination in the raw passthrough. That means pr-exists?state=all can false-negative for a branch whose PR isn't in the most recent ~50 (which would block a porch pr_exists gate), and recently-merged (previously --limit 1000) can miss on a busy repo. A pagination loop (page=1..N until a short page) would settle it — or at minimum a comment documenting the server-side cap and the false-negative window, so the next debugger isn't blind. Happy with either; we'd just like the behavior to be chosen rather than inherited.

2. (Polish, optional) With no origin remote or an unusual URL, REPO silently becomes empty/garbage and tea api "repos//…" fails with a confusing 404. An explicit [ -n "$REPO" ] || { echo "…set CODEV_REPO" >&2; exit 1; } naming the remedy would fit this repo's fail-fast convention — ideally factored once since the derivation appears in five scripts.

3. (Polish, optional) A failed comments fetch silently yields comments: [] — indistinguishable from "no comments" for consumers reading issue discussion. A stderr warning on the degraded path would keep the graceful behavior while leaving a trace.

Verdict: approve once item 1 is addressed (fix or documented caveat — your choice). Items 2–3 are welcome in this PR or a follow-up, contributor's choice.

[pseudoseed]

Thanks for the thorough review — all three items addressed in 3c2e3c2b.

1. Pagination — fixed (real page loop, not a comment). You're right that ?limit=200 inherited Gitea's max_response_items cap (default 50) and silently truncated. Added a shared tea_api_paged helper in a new scripts/forge/gitea/_lib.sh that requests page=1,2,3… at an explicit limit=50, concatenates each page's array (jq -s add), and stops when a page comes back shorter than the limit (or empty). Chosen behavior: it paginates, with a hard ceiling of 100 pages (100 × 50 = 5000 items) so a misbehaving server can't spin forever — documented in the helper. Wired into all three list reads: pr-exists (state=all), pr-list (state=open), recently-merged (state=closed). Output shape is unchanged — the concatenated array feeds the existing jq normalizers untouched. New tests serve a full 50-item page 1 + a short page 2 and assert an item that exists only on page 2 is found by each of the three scripts (pr-exists returns true for it, pr-list/recently-merged include it).

2. REPO fail-fast, factored once — done. The CODEV_REPO/origin-derivation line (duplicated in five scripts) now lives in _lib.sh#gitea_repo, sourced via . "$(dirname "$0")/_lib.sh" by issue-view, pr-exists, pr-list, pr-view, and recently-merged. It validates the result is a clean owner/repo; if not (no origin, unusual URL), it prints set CODEV_REPO=owner/repo to stderr and exits non-zero instead of letting tea api "repos//…" 404. Verified before factoring: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist (a leading-underscore file is never registered as a concept), package.jsonfiles ships scripts/forge so _lib.sh is packaged, it's POSIX sh (no bashisms), and $0-relative sourcing works when the script is invoked by absolute path (how forge runs it via sh -c). Tests cover missing-origin and garbage-URL → non-zero exit + the stderr remedy.

3. Degraded comments warn — done.issue-view still degrades a failed comments fetch to [], but now writes gitea forge: comments fetch failed for issue N; reporting 0 comments to stderr while stdout stays pure JSON. Test asserts both (comments: [] on stdout and the stderr warning).

Full suite green in the worktree: 3449 passed | 48 skipped, 0 failures (pnpm build + pnpm test). The #568pr-existsstate=all assertion stays green (the helper is still called with state=all).

[pseudoseed]

@waleedkadous let me know if there's anything else that needs to be addressed with this one :)

[pseudoseed]

Verified against a real Forgejo + tea — all six concepts pass

The PR notes that tea wasn't available in the authoring environment and the preset was never run end to end. It has now been. I ran this branch's scripts against a live Forgejo instance with tea 0.14.2, on a repo with ~355 issues and ~350 PRs.

Environment: Forgejo, tea 0.14.2 (go-sdk v1.1.0), single configured login, scripts invoked directly with CODEV_REPO set.

Before — released version, same environment

concept	result
user-identity	FAILIncorrect Usage: flag provided but not defined: -output
issue-view	FAILjq: Cannot index array with string "html_url"
pr-list	FAIL, exit 0 — prints Error: invalid field 'description' and still returns success
recently-merged	FAIL, exit 0 — same
pr-view	returns a list, not the requested PR
issue-list, issue-search, pr-exists, recently-closed, auth-status	OK

The two exit-0 cases are the nastiest: a caller checking the exit status sees success and gets an error string where JSON should be.

After — this branch, same environment

concept	result
user-identity	OK — user
issue-view	OK — object with title, body, state, url, comments[]
pr-list	OK — normalized PrListItem[]
pr-view	OK — single PR object, correct one
pr-exists	OK — true
recently-merged	OK — merged-only, correct merged_at ordering

All six previously-broken concepts now work. No regressions in the five that already worked.

Two notes

The comments-as-int catch is real and would have bitten immediately. Gitea returns comments as an integer count on the issue object; our issue-view on the released version failed exactly there. The second call for the comments array is necessary, not defensive.

One nearly-false report from me, worth stating so nobody repeats it. My first run of this branch's issue-view failed with Cannot index array with string "title". That was my harness, not your code — I had exported CODEV_ISSUE_NUMBER where the contract is CODEV_ISSUE_ID, so the path resolved to the issue list endpoint. With the correct variable it works. Flagging it because the failure mode is plausible-looking and someone else testing this could draw the wrong conclusion.

Unrelated gap this surfaced

pr-create is not a forge concept at all, so gh pr create stays hardcoded in the skeleton prompts (porch/prompts/pr.md, protocols/{air,spir,pir,bugfix,maintain}/…). That means a Gitea/Forgejo user still needs a gh shim on PATH no matter how complete this preset becomes. Not this PR's problem — filing separately — but relevant if anyone assumes a working gitea preset makes gh unnecessary.

Happy to re-run against any further revisions.

[amrmelsayed]

Reviewer Integration Review (CMAP-3)

Three-lane consultation (Gemini, GPT-5.6 Sol via Codex, Claude Opus) plus an independent architect pass. Every finding below was re-verified by the reviewing architect against the actual source, and the tea-CLI claims against the installed release binary, before being credited.

Verdict: REQUEST CHANGES (light). The core fix is correct, honestly documented, and the best-evidenced community PR this repo has received: the tea api rerouting, the pagination premise, the #1179 conflict resolution, and the merge-order analysis vs #1458 all check out. Lane split: Gemini APPROVE; Codex and Claude REQUEST_CHANGES. Two items are blocking; the rest are tiered below so nothing has to be rediscovered later.

Verified solid (no action)

• _lib.sh is safely inert as a concept: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist, so a leading-underscore file is never registered. Verified at forge.ts:64.
• $(dirname "$0") sourcing holds in the real call path: executeForgeCommand runs the absolute script path via sh -c.
• package.jsonfiles ships scripts/forge, and the bugfix-693 invariant (every provider-dir entry matches *.sh) still holds with _lib.sh present. The 755-mode argument is correct (postinstall chmods unconditionally).
• All four emitted shapes conform exactly to forge-contracts.ts (PrViewResult, PrListItem, MergedPrItem, IssueViewResult), and the --arg branch switch in pr-exists is a real injection fix.
• Pagination premise re-confirmed: issue gitea forge preset is broken against the real tea CLI (0.14.2) #1137 is still open, no forge-script drift on main since your 08-14 rebase, branch is MERGEABLE.

Blocking

1. issue-comment.sh breaks on the current released tea (0.14.1).tea comments add only exists from tea 0.14.2; on 0.14.1 (current Homebrew release) it exits with No help topic for 'comments'. Verified against the installed 0.14.1 binary and the tea source at both tags: tea comment "$CODEV_ISSUE_ID" "$CODEV_COMMENT_BODY" exists on 0.14.1 and is explicitly preserved as a shorthand in 0.14.2+, so it works on every version. This slipped through because issue-comment is the one concept absent from the live-verification tables (that run used tea 0.14.2), and the fake-tea stub implements comments add by fiat, pinning the assumption rather than testing it. One-word fix plus updating the stub to answer comment instead.

2. Paginator failure exits 0 with empty stdout, which reads as a false-negative pr_exists gate.tea_api_paged's return 1 sits on the left of a pipe in POSIX sh (no pipefail), so the script's exit status is jq's (0) and stdout is empty. Porch's pr-exists check (checks.ts:365) maps anything that isn't "true" to passed: false, so a transient failure mid-walk reports "no PR exists": the exact failure mode pagination was added to prevent. Fix in all three list scripts by capturing first:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

This also converts the jq -s add raw-type-error wart you flagged in the thread log into a clean non-zero exit.

Strongly recommended in this PR (both small, both introduced here)

3. codev doctor regression for gitea users.extractExecutable (forge.ts:192) skips comments, if, and assignments, but not dot-sourcing: the first substantive token in the five sourced scripts is ., and which . fails, so doctor shows five false "not found" rows and stops verifying tea for those concepts. Note the fix is not just skipping .: after the source line and the REPO= assignment are skipped, the next token in the three list scripts is tea_api_paged (a shell function), which also fails the which check. The extraction needs to resolve through sourced-helper calls (or the gitea preset needs declared executables), plus a test; no existing test covers this path, which is why the suite stayed green.

4. The stop condition trusts that the server honored limit=50.max_response_items is admin-tunable; on a server capped below 50, every page is "short", the loop breaks after page 1, and silent truncation returns on exactly the servers that tuned the cap. Derive the effective page size from page 1's item count and break when a page is shorter than that (or stop only on an empty page, at the cost of one extra request per walk). Worth a test with a sub-50 cap.

Maintainer's call: in-PR or filed as follow-ups

• recently-merged ignores CODEV_SINCE_DATE and now walks the full closed-PR history (up to 100 sequential requests, 2 jq spawns per page) inside forge's 30s timeout (forge.ts:323). On a large Gitea repo that risks timeout, and a timeout yields null: a worse dashboard outcome than truncation was. An early-exit on the since-date or a tighter page bound for this concept would cover it.
• Non-paged reads don't validate tea api's exit-0-on-error responses. An HTTP error body piped into the pr-view/issue-view/user-identity normalizers emits a structurally valid all-null contract object at exit 0. [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 guards this exact mode explicitly, so the two halves of the preset currently disagree about a documented behavior. Same class: issue-view's comments degrade path only handles a blank response, not an error-object one (--argjson then fails with a raw jq error instead of the warned [] degrade).

Follow-up issues to file after merge (none blocking)

• The preset is now two idioms: issue-list / issue-search / recently-closed still use tea pulls|issues list --fields … --limit 200/1000 with the same truncation premise this PR disproves. Migrate them onto tea api + tea_api_paged.
• Repo-resolution unification (already proposed in the PR body) should absorb a third path: repo-archive.sh uses bare ${CODEV_REPO} with no fail-fast.
• forge-contracts.ts doc drift: the reviewRequests comment still says "GitLab/Gitea emit []", but gitea now populates real reviewer logins.
• Test gaps: no 3+ page walk, no mid-walk failure, no sub-50 server cap.
• _lib.sh creates a sibling-file dependency for hand-copied .codev/scripts/forge/gitea/ overrides; worth a line in the header.

Process notes

• The rebase documentation is exemplary: the vscode: one-step 'view issue N' / 'view pr N' from QuickPick + Cmd+K P for direct PR-by-ID open #1179url restoration, the 755 mode rationale, and the per-commit green verification were all stated up front and all verified true.
• Merge order vs [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 confirmed independent; either order is safe. The [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 reconcile (dropping list-and-search in favor of reading the create response) is the right shape.

Merge authority rests with the maintainer; this review is the reviewing architect's recommendation, not a gate approval.

[amrmelsayed]

Follow-up from the reviewing architect: finding 3 just got smaller

Merge order has been ruled by the maintainer: #1458 first, then this PR.

That changes the shape of one item in the review above. #1458 ships a # forge-executable: <tool> declaration that extractExecutable honours ahead of its first-substantive-line heuristic. With #1458 merged first, the "strongly recommended" finding 3 (the codev doctor regression) collapses to adding one line to each of the five sourced scripts:

#!/bin/sh# Forge concept: pr-exists (Gitea via tea CLI)# forge-executable: tea

The deeper extraction work the review asked for (resolving through sourced-helper calls, plus a test) is not required of you — that burden moved to #1458's mechanism, and a hardening addition to its builtin skip list is being pressed on that PR separately.

Everything else stands as written, and none of it waits on #1458: the two blockers (tea comment on 0.14.1, and capture-first in the three paginated scripts so a mid-walk failure can't read as a false-negative pr_exists gate) can be fixed now in either order. Finding 4 (the sub-50 max_response_items stop condition) is likewise independent.

[pseudoseed]

Review follow-up (2026-08-20)

Addressed both blocking items and the strongly-recommended item from the 2026-08-17 review, pushed as c9f55a537 (+ 481956e12 for the builder thread log):

1. (blocking) issue-comment.sh — tea comments add doesn't exist on 0.14.1
tea comments add is a 0.14.2+-only subcommand and fails on the still-current 0.14.1 release ("No help topic for comments"). Switched to the top-level tea comment <id> <body> shorthand, which works on both 0.14.1 and 0.14.2+.

2. (blocking) masked pipe failures in the paginated scripts
pr-exists.sh, pr-list.sh, and recently-merged.sh piped tea_api_paged | jq directly. POSIX sh has no pipefail, so a mid-walk pagination failure (tea_api_paged returning 1) was masked by jq's exit status — jq exits 0 on empty stdin, so pr-exists in particular would print "false" for a real API failure instead of erroring. That's a silent false-negative that could pass a porch pr_exists gate on a genuine error rather than an absent PR.

Fixed by capturing the paginator's output into a variable and checking its exit status before piping to jq:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

3. (strongly recommended, done) sub-limit server cap
tea_api_paged's stop condition compared each page's item count against the requested limit (50). A server whose max_response_items is tuned below that requested limit truncates every page — including non-last pages — to its own cap, so every page looked "short" against 50 and the loop broke after page 1, silently missing pages 2+. Now compares against the size actually observed on page 1 instead, so it keeps walking until a page is genuinely shorter than what the server has been returning.

4. (deferred, not done in this PR)
The # forge-executable: tea header convention depends on #1458 landing extractExecutable's header-parsing support first. Checked — #1458 is still open/unmerged, so this isn't actionable yet. Left as a follow-up once #1458 merges, matching the merge order already noted in the PR description (#1458 first, then this PR).

Testing

Added regression coverage for all three fixes in bugfix-1137-gitea-tea-api.test.ts:

• Updated the fake-tea stub to answer comment (not comments add).
• A mid-walk pagination failure fixture (full page 1, erroring page 2) exercised against all three paginated scripts — asserts non-zero exit and empty stdout rather than a silently wrong/empty result.
• A 3-page sub-50-per-page-cap fixture (30 + 30 + 6 items) proving pr-list keeps walking past a page that's full-but-capped rather than stopping because it's short relative to the requested limit.

Full local suite: 3197 passed, 126 failed (67 files) — the same pre-existing environment-dependent failures (agent-farm/terminal/consolidate; no built dist/ in this worktree) as the unmodified baseline reported earlier in this PR. Zero regressions, +4 new passing tests over the prior 3193.

[waleedkadous]

First — apologies for how long this sat; two months without a review is not how we want to treat a contribution, and this one is good: the real-script fake-CLI suite (contract normalization, pagination past page one, sub-50 server caps, mid-walk failures, tea 0.14.1 comment compatibility) is exactly the evidence this kind of fix needs, and moving branch input through jq --arg is a security improvement. Both integration reviews (codex + claude) agree the core mapping is right. Four things I'd like fixed before merge, all in the same spirit as the fix itself — fail loudly, never silently:

1. codev doctor regression. The five scripts that now source _lib.sh make doctor's executable extractor report . (and later tea_api_paged) instead of tea — verified, which . fails under /bin/sh. #1458 introduces a # forge-executable: tea header declaration for exactly this; please add those five lines here regardless of merge order so the regression can't ship.
2. Silent truncation at GITEA_MAX_PAGES. Reaching 100 pages without seeing a terminal short/empty page returns a partial array at exit 0 — the same false-negative pr-exists class the paginator exists to prevent. Fail explicitly instead.
3. Error bodies normalized into valid-looking output.tea api exits 0 on HTTP errors, and pr-view/user-identity/issue-view normalize without validating the response shape — an error object becomes an all-null PR (pr-view even leaks the error body's url into the contract) or the username null, at exit 0. Validate required fields/types before normalizing; the paginated scripts already fail loudly, so this brings the rest in line.
4. recently-merged.sh ignores CODEV_SINCE_DATE and can issue up to 100 sequential requests inside forge's 30-second timeout — on an established repo that turns the analytics path into null. Honoring the since-date bounds it.

Smaller, take-or-leave: CODEV_REPO is now overloaded (repo-archive's foreign-repo input vs. gitea read targeting) — a line in forge.md and both SKILL.md copies would help; and forge-contracts.ts's reviewRequests/isDraft comments go stale with this PR.

Merge order: #1458 first (it brings the # forge-executable mechanism), then this. Happy to turn the two around quickly once these land — and thank you for sticking with it.

[waleedkadous]

Given how long this waited on us, we'll take the last mile ourselves rather than hand you a list: a builder will push the review items directly onto this branch (you enabled maintainer edits — thank you), your commits and authorship stay as they are, and I'll re-review and merge once green. If you'd rather make the changes yourself, just say so and we'll hold off.

[waleedkadous]

Pushed the review items onto this branch as we offered — four commits on top of yours, nothing rebased or squashed, all ten of your commits and their authorship untouched. Thank you again for the contribution and for the patience; the real-script fake-CLI suite you built is what made all of this cheap to do, and every fix below is a test in your harness.

Also merged main in: #1458 landed, so the # forge-executable: mechanism is live.

The four required items

1. # forge-executable: tea headers. On six scripts, not five. The five that source _lib.sh are the ones the review named, but fixing item 3 in user-identity.sh required capturing tea api user before the jq pipe, which moves tea off the first substantive line — so without a header of its own, that fix would have caused the regression this item closes. Verified against the merged extractExecutable, not a simulation of it: all fourteen gitea concepts now resolve to tea.

2. The page ceiling fails loudly. Reaching GITEA_MAX_PAGES with every page full means we don't know we have the whole list, so it errors rather than returning the partial array at exit 0. One wrinkle worth naming: a list whose length is an exact multiple of the page size hits the ceiling with nothing missing, so it probes one page past before failing — a hard error on a complete result would be its own bug.

3. Shape validation before normalizing. The nastiest part of this one is that Gitea's error bodies carry a url (the swagger link), so url: (.html_url // .url)succeeded on them and shipped that link as the PR's browser page inside an otherwise all-null contract object. Required fields are now type-checked and failures carry the server's own .message on stderr. issue-view is validated before its comments are fetched, so a bad id reports only its own error instead of also warning about degraded comments on an issue that isn't there.

4. recently-merged honors CODEV_SINCE_DATE — it asks for sort=recentupdate and stops at the first page reaching past the cutoff. Details below, because this is where the reviewers earned their keep.

Plus the take-or-leave items: CODEV_REPO's two meanings documented in forge.md and both SKILL.md copies, and the reviewRequests/isDraft comments in forge-contracts.ts corrected — they claimed GitLab and Gitea emit empty/false, but all three presets populate them for real.

What the consultation caught, because it's the interesting part

I first wrote the since-date bound to fire when the current page was non-increasing in updated_at, reasoning that proved the server had honored sort=recentupdate. Both reviewers broke that, and they were right. Gitea's default order is index/created-DESC, and on a repo where PRs are opened and merged in order, index-DESC is non-increasing in updated_at. A long-lived PR opened in January and merged after the cutoff then sits on page 2, and we stop at page 1 and drop it — a silent loss in exactly the analytics path the bound was meant to protect.

The fix is to check for the property we actually need — the ordering — rather than for evidence that we asked for it. A stop now requires the order to survive a page boundary (previous page descending too, its oldest no older than this page's newest) and never fires on page 1, where there's nothing to compare against. A server that ignores the parameter falls back to your full walk: slower, never wrong. Costs exactly one extra request on an honest server.

The other finding I'm glad we ran: passing a page to the stop filter through jq --argjson blows up on Linux. MAX_ARG_STRLEN caps a single argv string at 128KiB regardless of ARG_MAX, and a 50-item Gitea pulls page — every object embedding full base.repo and head.repo — measures ~90KiB before anyone writes a long PR body. macOS has no per-argument cap, so it passed locally and would have failed on CI and for every Linux adopter. Both pages go in on stdin now.

Smaller ones from the same pass: jq length is 0 for both null and {}, so an error body mid-walk looked exactly like an exhausted list; jq on empty stdin emits nothing and exits 0, so two scripts were "succeeding" with empty stdout and never running their validators at all; a non-string .message threw a raw jq error instead of the legible one; and the test env inherited CODEV_* from the developer's shell, so the "no CODEV_SINCE_DATE" test was asserting the absence of a variable it didn't control.

Testing

41 tests in bugfix-1137-gitea-tea-api.test.ts, +20 on what you had. Your fake tea grew error bodies at exit 0 for pulls/issues/user, a comments endpoint answering with an error object and one answering with non-objects, a repo whose pages never end, one whose length is an exact multiple of the page size, ~150KB pages for the argv cap, and the sorted/lagging pair for the since-date bound — acme/lagging is the reviewer's counterexample verbatim.

Full suite after merging main: 5549 passed | 48 skipped, 0 failures. Every script also exercised under dash, which is what /bin/sh is on the CI runner, rather than only bash.

Two follow-ups from the earlier reviews are still unfiled and still worth doing, neither in scope here: migrating issue-list/issue-search/recently-closed off tea <entity> list --limit onto tea_api_paged (same truncation premise this PR disproved), and repo-archive.sh's bare ${CODEV_REPO} with no fail-fast.

Over to @waleedkadous for the re-review.

[waleedkadous]

Re-reviewed after the maintainer-side commits: six # forge-executable: tea headers (verified against the merged extractExecutable — all fourteen gitea concepts resolve to tea), the paginator now fails loudly at the page ceiling with a one-page probe so exact-multiple lists don't false-alarm, non-array error bodies are refused instead of normalized to null, recently-merged honors CODEV_SINCE_DATE with the stop filter fed via stdin (Linux argv cap), plus the docs and stale comments. 41 tests in the contributor's own fake-CLI harness; CI 7/7 green on a6eddb6. Approving and merging — thank you, @pseudoseed, for the contribution and the patience.

[pseudoseed]

Fixes#1137.

Bugfix-protocol re-do of the earlier SPIR-style PR #1138 (now closed), per maintainer request. Same root cause, plus a real regression test.

Problem

The gitea forge preset was authored against the Gitea REST API JSON shape, but the scripts invoke the tea CLI, whose output shape differs — and several concepts referenced flags/fields/subcommands tea doesn't have. Per the in-repo #920 note, tea wasn't available in the authoring environment, so the preset was never run end-to-end.

Fix

Route the read concepts through tea api (raw REST passthrough returning the shape forge-contracts.ts + the jq normalizers expect):

• user-identity: tea api user | jq .login (tea whoami has no --output json)
• pr-view: tea api repos/<repo>/pulls/N → PrViewResult (incl. additions/deletions)
• pr-list: tea api repos/<repo>/pulls?state=open → PrListItem[]
• pr-exists: tea api repos/<repo>/pulls?state=all with nested .head.ref / .merged
• issue-view: tea api repos/<repo>/issues/N + a second call for the comments array (Gitea reports comments as an int count, which would crash .comments.filter(...))
• recently-merged: tea api repos/<repo>/pulls?state=closed, filter .merged, using real .merged_at
• issue-comment: tea comments add (tea issues has no comment subcommand)

tea api needs an explicit owner/repo path segment, so each api-based script derives owner/repo from the origin remote (honoring CODEV_REPO when set).

Testing

• New regression test stubs a fake tea on PATH answering api <endpoint> with captured Gitea REST fixtures (tea isn't in CI, per vscode: editor-tab webview for rich backlog search #920), runs each real script, and asserts the normalized output conforms to forge-contracts.ts — incl. comments-as-array, merged-only filtering, open/merged/closed pr-exists, and CODEV_REPO override.
• Updates the pr_exists porch check fails when PR is merged before gate approval #568pr-exists assertion for the new state=all query param.
• Full suite green locally: build ✓, 3443 tests pass.

🤖 Generated with Claude Code

---

Rebased onto main (2026-08-14)

This branch was 2063 commits behind and mergeable=CONFLICTING. Rebased onto upstream/main; force-pushed to the fork. All 5 original commits preserved.

Exactly one file conflicted, twice — scripts/forge/gitea/pr-view.sh.

⚠️ Behaviour change from the conflict resolution: pr-view now emits url

While this branch sat, PIR #1179 landed on main and gave gitea pr-view a url field mapped from Gitea's html_url:

tea pulls view "$CODEV_PR_NUMBER" --output json | jq '.url = (.html_url // .url)'

This PR rewrites that same script onto tea api with an explicit normalizer — which emitted no url at all. Taking either side of the conflict wholesale loses something: take ours and #1179 is silently reverted, take theirs and the tea api fix is lost.

Resolution: both. The script keeps this PR's tea api routing and re-adds url: (.html_url // .url).

So, stated plainly rather than left in the diff: gitea pr-view now returns a url field that the pre-rebase branch did not return. That is a restoration of main's behaviour, not a new invention — forge-contracts.ts documents the Gitea mapping by name ("Gitea html_url — Gitea's url is the API endpoint, do not use it") — but it is a real change to this concept's output versus what this PR previously proposed, so it should not be discovered from the diff.

bugfix-1137-gitea-tea-api.test.ts was updated accordingly: the pulls/42 fixture now carries both html_url and url, and the assertion pins that the browser page, not the API endpoint, is what reaches the contract.

Two smaller deliberate deviations

• _lib.sh is committed 100755, not 100644.scripts/postinstall.mjs chmods every scripts/forge/**/*.sh to 755 unconditionally, so 644 is a mode that never survives an install and leaves a permanently dirty worktree for anyone who runs pnpm install. The file is sourced, not executed; the bit is inert.
• The test-fixture update was applied inside the test commit (via an interactive rebase stop) rather than as a trailing fixup, so every commit is green in isolation — verified by checking out and testing all 5 individually.

Relationship to #1458

#1458 (pr-create as a forge concept) landed while this PR was open, and its gitea pr-create.sh looked the new PR up with tea pulls list --limit 200 — the exact call this PR proves silently truncates. That has been fixed on #1458's branch, not here: it now creates via tea api -X POST …/pulls, which returns the created PR directly, so the lookup is gone rather than paginated.

Re-confirmed live against Forgejo 15.0.2 while doing so: settings/api reports max_response_items: 50, and a ?limit=200 request returns exactly 50 items on a list where paging at 50 returns 53. The premise behind this PR's pagination work holds.

Merge-order implications are spelled out in full at the end of this description.

Verification

• All 5 commits pass the forge suites individually (bugfix-1137-gitea-tea-api, bugfix-568-pr-exists-state-all, forge, bugfix-693-forge-exec-bit).
• Full @cluesmith/codev unit suite, rebased tip: 3193 passed, 126 failed (67 files).
• Baseline run of the same suite on unmodified upstream/main in the same worktree: 3176 passed, 126 failed (67 files) — the same 67 files and the same 126 tests.
• So: zero regressions; this branch adds 17 passing tests and breaks nothing. The pre-existing failures are all agent-farm / terminal / consolidate (attach, session-manager, shellper sockets, SQLite state), environment-dependent — this worktree has no built dist/, which those tests spawn from, and a live Tower is running against the same state. None is in a file this PR touches, and every forge suite passes.

Merge order with the sibling PR — verified, not assumed

#1146 and #1458 come from the same fork and both touch packages/codev/scripts/forge/gitea/, so the ordering question is fair. The answer:

Either order is safe. There is no dependency and no conflict.

Question	Answer	How it was checked
Do they conflict?	No.	git merge-tree on the two branch tips merges cleanly. The only file both touch is the builder thread log, which is the identical blob on both branches and auto-merges.
Must one merge first?	No.	#1458's pr-create.sh does not source _lib.sh and does not call gitea_repo or tea_api_paged. Nothing in it resolves against #1146.
Does the merged result hold together?	Yes.	In the merged tree, _lib.sh and pr-view.sh are byte-identical to #1146's versions and pr-create.sh byte-identical to #1458's — no silent blending. The bugfix-693 invariant (every entry under each provider dir is a *.sh) still holds with _lib.sh present.

Does #1458 duplicate something #1146 makes shared?

The paginator: no, and it shouldn't._lib.sh#tea_api_paged exists to walk a truncating list endpoint. pr-create no longer lists anything — it reads the new PR out of the create response — so there is no pagination for it to share. That is the point of the reconcile rather than an oversight.

Repo resolution: yes, there are two paths, and this is worth a follow-up.

• [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146's read concepts: . _lib.sh → gitea_repo(), which honours CODEV_REPO, else derives owner/repo from the origin remote, and fails fast naming CODEV_REPO as the remedy.
• [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458's pr-create: tea's own {owner}/{repo} placeholders, with CODEV_PR_REPO forwarded as tea --repo.

They were kept separate deliberately, for two reasons rather than by omission:

1. Different contract.pr-create takes CODEV_PR_REPO; the read concepts take CODEV_REPO. gitea_repo() reads the latter and takes no argument, so pr-create could not call it without changing its signature — which would mean editing a [Bugfix #1137] Fix gitea forge preset against the real tea CLI #1146 file from [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 and creating exactly the merge-order coupling this avoids.
2. --repo does more than fill a path. It also supplies tea's repo/login context, verified working from a cwd whose remote is not a Gitea host. A path-only helper does not do that.

Recommended follow-up (not done here, deliberately): once both PRs have landed, unify the two behind one helper that takes the override variable as a parameter — e.g. gitea_repo "$CODEV_PR_REPO" — so there is one repo-resolution path with one error message. Doing it now would couple two independent PRs; doing it never leaves two paths that will drift. It is a small, mechanical change against a tree where both are already present.

The one ergonomic gap that split created has been closed in the meantime: an unresolvable repo used to surface from pr-create as a bare 404 page not found, and now names CODEV_PR_REPO as the remedy, matching gitea_repo()'s fail-fast message.

[waleedkadous]

Excellent work — thank you for the disciplined re-do, and apologies for the review latency. This is what a model bugfix PR looks like: every tea-CLI deficiency documented in-script with reasoning, the REST passthrough returning exactly the shape forge-contracts.ts expects, and a genuinely well-built regression suite (fake tea on PATH serving captured REST fixtures, the real scripts executed, contract-shape assertions, the comments-as-int crash and null-login team reviewers both covered). We verified every output mapping field-by-field against the contracts — all conform — and the switch from string-interpolated jq to --arg in pr-exists is a quiet security improvement worth crediting.

One substantive question before merge, and two optional polish items:

1. Pagination cap (the one we'd like addressed or answered). Gitea servers cap page size at max_response_items (default 50), so ?limit=200 likely returns 50 items with no client-side pagination in the raw passthrough. That means pr-exists?state=all can false-negative for a branch whose PR isn't in the most recent ~50 (which would block a porch pr_exists gate), and recently-merged (previously --limit 1000) can miss on a busy repo. A pagination loop (page=1..N until a short page) would settle it — or at minimum a comment documenting the server-side cap and the false-negative window, so the next debugger isn't blind. Happy with either; we'd just like the behavior to be chosen rather than inherited.

2. (Polish, optional) With no origin remote or an unusual URL, REPO silently becomes empty/garbage and tea api "repos//…" fails with a confusing 404. An explicit [ -n "$REPO" ] || { echo "…set CODEV_REPO" >&2; exit 1; } naming the remedy would fit this repo's fail-fast convention — ideally factored once since the derivation appears in five scripts.

3. (Polish, optional) A failed comments fetch silently yields comments: [] — indistinguishable from "no comments" for consumers reading issue discussion. A stderr warning on the degraded path would keep the graceful behavior while leaving a trace.

Verdict: approve once item 1 is addressed (fix or documented caveat — your choice). Items 2–3 are welcome in this PR or a follow-up, contributor's choice.

[pseudoseed]

Thanks for the thorough review — all three items addressed in 3c2e3c2b.

1. Pagination — fixed (real page loop, not a comment). You're right that ?limit=200 inherited Gitea's max_response_items cap (default 50) and silently truncated. Added a shared tea_api_paged helper in a new scripts/forge/gitea/_lib.sh that requests page=1,2,3… at an explicit limit=50, concatenates each page's array (jq -s add), and stops when a page comes back shorter than the limit (or empty). Chosen behavior: it paginates, with a hard ceiling of 100 pages (100 × 50 = 5000 items) so a misbehaving server can't spin forever — documented in the helper. Wired into all three list reads: pr-exists (state=all), pr-list (state=open), recently-merged (state=closed). Output shape is unchanged — the concatenated array feeds the existing jq normalizers untouched. New tests serve a full 50-item page 1 + a short page 2 and assert an item that exists only on page 2 is found by each of the three scripts (pr-exists returns true for it, pr-list/recently-merged include it).

2. REPO fail-fast, factored once — done. The CODEV_REPO/origin-derivation line (duplicated in five scripts) now lives in _lib.sh#gitea_repo, sourced via . "$(dirname "$0")/_lib.sh" by issue-view, pr-exists, pr-list, pr-view, and recently-merged. It validates the result is a clean owner/repo; if not (no origin, unusual URL), it prints set CODEV_REPO=owner/repo to stderr and exits non-zero instead of letting tea api "repos//…" 404. Verified before factoring: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist (a leading-underscore file is never registered as a concept), package.jsonfiles ships scripts/forge so _lib.sh is packaged, it's POSIX sh (no bashisms), and $0-relative sourcing works when the script is invoked by absolute path (how forge runs it via sh -c). Tests cover missing-origin and garbage-URL → non-zero exit + the stderr remedy.

3. Degraded comments warn — done.issue-view still degrades a failed comments fetch to [], but now writes gitea forge: comments fetch failed for issue N; reporting 0 comments to stderr while stdout stays pure JSON. Test asserts both (comments: [] on stdout and the stderr warning).

Full suite green in the worktree: 3449 passed | 48 skipped, 0 failures (pnpm build + pnpm test). The #568pr-existsstate=all assertion stays green (the helper is still called with state=all).

[pseudoseed]

@waleedkadous let me know if there's anything else that needs to be addressed with this one :)

[pseudoseed]

Verified against a real Forgejo + tea — all six concepts pass

The PR notes that tea wasn't available in the authoring environment and the preset was never run end to end. It has now been. I ran this branch's scripts against a live Forgejo instance with tea 0.14.2, on a repo with ~355 issues and ~350 PRs.

Environment: Forgejo, tea 0.14.2 (go-sdk v1.1.0), single configured login, scripts invoked directly with CODEV_REPO set.

Before — released version, same environment

concept	result
user-identity	FAILIncorrect Usage: flag provided but not defined: -output
issue-view	FAILjq: Cannot index array with string "html_url"
pr-list	FAIL, exit 0 — prints Error: invalid field 'description' and still returns success
recently-merged	FAIL, exit 0 — same
pr-view	returns a list, not the requested PR
issue-list, issue-search, pr-exists, recently-closed, auth-status	OK

The two exit-0 cases are the nastiest: a caller checking the exit status sees success and gets an error string where JSON should be.

After — this branch, same environment

concept	result
user-identity	OK — user
issue-view	OK — object with title, body, state, url, comments[]
pr-list	OK — normalized PrListItem[]
pr-view	OK — single PR object, correct one
pr-exists	OK — true
recently-merged	OK — merged-only, correct merged_at ordering

All six previously-broken concepts now work. No regressions in the five that already worked.

Two notes

The comments-as-int catch is real and would have bitten immediately. Gitea returns comments as an integer count on the issue object; our issue-view on the released version failed exactly there. The second call for the comments array is necessary, not defensive.

One nearly-false report from me, worth stating so nobody repeats it. My first run of this branch's issue-view failed with Cannot index array with string "title". That was my harness, not your code — I had exported CODEV_ISSUE_NUMBER where the contract is CODEV_ISSUE_ID, so the path resolved to the issue list endpoint. With the correct variable it works. Flagging it because the failure mode is plausible-looking and someone else testing this could draw the wrong conclusion.

Unrelated gap this surfaced

pr-create is not a forge concept at all, so gh pr create stays hardcoded in the skeleton prompts (porch/prompts/pr.md, protocols/{air,spir,pir,bugfix,maintain}/…). That means a Gitea/Forgejo user still needs a gh shim on PATH no matter how complete this preset becomes. Not this PR's problem — filing separately — but relevant if anyone assumes a working gitea preset makes gh unnecessary.

Happy to re-run against any further revisions.

[amrmelsayed]

Reviewer Integration Review (CMAP-3)

Three-lane consultation (Gemini, GPT-5.6 Sol via Codex, Claude Opus) plus an independent architect pass. Every finding below was re-verified by the reviewing architect against the actual source, and the tea-CLI claims against the installed release binary, before being credited.

Verdict: REQUEST CHANGES (light). The core fix is correct, honestly documented, and the best-evidenced community PR this repo has received: the tea api rerouting, the pagination premise, the #1179 conflict resolution, and the merge-order analysis vs #1458 all check out. Lane split: Gemini APPROVE; Codex and Claude REQUEST_CHANGES. Two items are blocking; the rest are tiered below so nothing has to be rediscovered later.

Verified solid (no action)

• _lib.sh is safely inert as a concept: forge.ts builds presets from the explicit KNOWN_CONCEPTS allowlist, so a leading-underscore file is never registered. Verified at forge.ts:64.
• $(dirname "$0") sourcing holds in the real call path: executeForgeCommand runs the absolute script path via sh -c.
• package.jsonfiles ships scripts/forge, and the bugfix-693 invariant (every provider-dir entry matches *.sh) still holds with _lib.sh present. The 755-mode argument is correct (postinstall chmods unconditionally).
• All four emitted shapes conform exactly to forge-contracts.ts (PrViewResult, PrListItem, MergedPrItem, IssueViewResult), and the --arg branch switch in pr-exists is a real injection fix.
• Pagination premise re-confirmed: issue gitea forge preset is broken against the real tea CLI (0.14.2) #1137 is still open, no forge-script drift on main since your 08-14 rebase, branch is MERGEABLE.

Blocking

1. issue-comment.sh breaks on the current released tea (0.14.1).tea comments add only exists from tea 0.14.2; on 0.14.1 (current Homebrew release) it exits with No help topic for 'comments'. Verified against the installed 0.14.1 binary and the tea source at both tags: tea comment "$CODEV_ISSUE_ID" "$CODEV_COMMENT_BODY" exists on 0.14.1 and is explicitly preserved as a shorthand in 0.14.2+, so it works on every version. This slipped through because issue-comment is the one concept absent from the live-verification tables (that run used tea 0.14.2), and the fake-tea stub implements comments add by fiat, pinning the assumption rather than testing it. One-word fix plus updating the stub to answer comment instead.

2. Paginator failure exits 0 with empty stdout, which reads as a false-negative pr_exists gate.tea_api_paged's return 1 sits on the left of a pipe in POSIX sh (no pipefail), so the script's exit status is jq's (0) and stdout is empty. Porch's pr-exists check (checks.ts:365) maps anything that isn't "true" to passed: false, so a transient failure mid-walk reports "no PR exists": the exact failure mode pagination was added to prevent. Fix in all three list scripts by capturing first:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

This also converts the jq -s add raw-type-error wart you flagged in the thread log into a clean non-zero exit.

Strongly recommended in this PR (both small, both introduced here)

3. codev doctor regression for gitea users.extractExecutable (forge.ts:192) skips comments, if, and assignments, but not dot-sourcing: the first substantive token in the five sourced scripts is ., and which . fails, so doctor shows five false "not found" rows and stops verifying tea for those concepts. Note the fix is not just skipping .: after the source line and the REPO= assignment are skipped, the next token in the three list scripts is tea_api_paged (a shell function), which also fails the which check. The extraction needs to resolve through sourced-helper calls (or the gitea preset needs declared executables), plus a test; no existing test covers this path, which is why the suite stayed green.

4. The stop condition trusts that the server honored limit=50.max_response_items is admin-tunable; on a server capped below 50, every page is "short", the loop breaks after page 1, and silent truncation returns on exactly the servers that tuned the cap. Derive the effective page size from page 1's item count and break when a page is shorter than that (or stop only on an empty page, at the cost of one extra request per walk). Worth a test with a sub-50 cap.

Maintainer's call: in-PR or filed as follow-ups

• recently-merged ignores CODEV_SINCE_DATE and now walks the full closed-PR history (up to 100 sequential requests, 2 jq spawns per page) inside forge's 30s timeout (forge.ts:323). On a large Gitea repo that risks timeout, and a timeout yields null: a worse dashboard outcome than truncation was. An early-exit on the since-date or a tighter page bound for this concept would cover it.
• Non-paged reads don't validate tea api's exit-0-on-error responses. An HTTP error body piped into the pr-view/issue-view/user-identity normalizers emits a structurally valid all-null contract object at exit 0. [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 guards this exact mode explicitly, so the two halves of the preset currently disagree about a documented behavior. Same class: issue-view's comments degrade path only handles a blank response, not an error-object one (--argjson then fails with a raw jq error instead of the warned [] degrade).

Follow-up issues to file after merge (none blocking)

• The preset is now two idioms: issue-list / issue-search / recently-closed still use tea pulls|issues list --fields … --limit 200/1000 with the same truncation premise this PR disproves. Migrate them onto tea api + tea_api_paged.
• Repo-resolution unification (already proposed in the PR body) should absorb a third path: repo-archive.sh uses bare ${CODEV_REPO} with no fail-fast.
• forge-contracts.ts doc drift: the reviewRequests comment still says "GitLab/Gitea emit []", but gitea now populates real reviewer logins.
• Test gaps: no 3+ page walk, no mid-walk failure, no sub-50 server cap.
• _lib.sh creates a sibling-file dependency for hand-copied .codev/scripts/forge/gitea/ overrides; worth a line in the header.

Process notes

• The rebase documentation is exemplary: the vscode: one-step 'view issue N' / 'view pr N' from QuickPick + Cmd+K P for direct PR-by-ID open #1179url restoration, the 755 mode rationale, and the per-commit green verification were all stated up front and all verified true.
• Merge order vs [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 confirmed independent; either order is safe. The [Bugfix #1455] Add a pr-create forge concept so non-GitHub forges can open PRs #1458 reconcile (dropping list-and-search in favor of reading the create response) is the right shape.

Merge authority rests with the maintainer; this review is the reviewing architect's recommendation, not a gate approval.

[amrmelsayed]

Follow-up from the reviewing architect: finding 3 just got smaller

Merge order has been ruled by the maintainer: #1458 first, then this PR.

That changes the shape of one item in the review above. #1458 ships a # forge-executable: <tool> declaration that extractExecutable honours ahead of its first-substantive-line heuristic. With #1458 merged first, the "strongly recommended" finding 3 (the codev doctor regression) collapses to adding one line to each of the five sourced scripts:

#!/bin/sh# Forge concept: pr-exists (Gitea via tea CLI)# forge-executable: tea

The deeper extraction work the review asked for (resolving through sourced-helper calls, plus a test) is not required of you — that burden moved to #1458's mechanism, and a hardening addition to its builtin skip list is being pressed on that PR separately.

Everything else stands as written, and none of it waits on #1458: the two blockers (tea comment on 0.14.1, and capture-first in the three paginated scripts so a mid-walk failure can't read as a false-negative pr_exists gate) can be fixed now in either order. Finding 4 (the sub-50 max_response_items stop condition) is likewise independent.

[pseudoseed]

Review follow-up (2026-08-20)

Addressed both blocking items and the strongly-recommended item from the 2026-08-17 review, pushed as c9f55a537 (+ 481956e12 for the builder thread log):

1. (blocking) issue-comment.sh — tea comments add doesn't exist on 0.14.1
tea comments add is a 0.14.2+-only subcommand and fails on the still-current 0.14.1 release ("No help topic for comments"). Switched to the top-level tea comment <id> <body> shorthand, which works on both 0.14.1 and 0.14.2+.

2. (blocking) masked pipe failures in the paginated scripts
pr-exists.sh, pr-list.sh, and recently-merged.sh piped tea_api_paged | jq directly. POSIX sh has no pipefail, so a mid-walk pagination failure (tea_api_paged returning 1) was masked by jq's exit status — jq exits 0 on empty stdin, so pr-exists in particular would print "false" for a real API failure instead of erroring. That's a silent false-negative that could pass a porch pr_exists gate on a genuine error rather than an absent PR.

Fixed by capturing the paginator's output into a variable and checking its exit status before piping to jq:

PULLS="$(tea_api_paged "repos/${REPO}/pulls""state=all")"||exit 1
printf'%s'"$PULLS"| jq …

3. (strongly recommended, done) sub-limit server cap
tea_api_paged's stop condition compared each page's item count against the requested limit (50). A server whose max_response_items is tuned below that requested limit truncates every page — including non-last pages — to its own cap, so every page looked "short" against 50 and the loop broke after page 1, silently missing pages 2+. Now compares against the size actually observed on page 1 instead, so it keeps walking until a page is genuinely shorter than what the server has been returning.

4. (deferred, not done in this PR)
The # forge-executable: tea header convention depends on #1458 landing extractExecutable's header-parsing support first. Checked — #1458 is still open/unmerged, so this isn't actionable yet. Left as a follow-up once #1458 merges, matching the merge order already noted in the PR description (#1458 first, then this PR).

Testing

Added regression coverage for all three fixes in bugfix-1137-gitea-tea-api.test.ts:

• Updated the fake-tea stub to answer comment (not comments add).
• A mid-walk pagination failure fixture (full page 1, erroring page 2) exercised against all three paginated scripts — asserts non-zero exit and empty stdout rather than a silently wrong/empty result.
• A 3-page sub-50-per-page-cap fixture (30 + 30 + 6 items) proving pr-list keeps walking past a page that's full-but-capped rather than stopping because it's short relative to the requested limit.

Full local suite: 3197 passed, 126 failed (67 files) — the same pre-existing environment-dependent failures (agent-farm/terminal/consolidate; no built dist/ in this worktree) as the unmodified baseline reported earlier in this PR. Zero regressions, +4 new passing tests over the prior 3193.

[waleedkadous]

First — apologies for how long this sat; two months without a review is not how we want to treat a contribution, and this one is good: the real-script fake-CLI suite (contract normalization, pagination past page one, sub-50 server caps, mid-walk failures, tea 0.14.1 comment compatibility) is exactly the evidence this kind of fix needs, and moving branch input through jq --arg is a security improvement. Both integration reviews (codex + claude) agree the core mapping is right. Four things I'd like fixed before merge, all in the same spirit as the fix itself — fail loudly, never silently:

1. codev doctor regression. The five scripts that now source _lib.sh make doctor's executable extractor report . (and later tea_api_paged) instead of tea — verified, which . fails under /bin/sh. #1458 introduces a # forge-executable: tea header declaration for exactly this; please add those five lines here regardless of merge order so the regression can't ship.
2. Silent truncation at GITEA_MAX_PAGES. Reaching 100 pages without seeing a terminal short/empty page returns a partial array at exit 0 — the same false-negative pr-exists class the paginator exists to prevent. Fail explicitly instead.
3. Error bodies normalized into valid-looking output.tea api exits 0 on HTTP errors, and pr-view/user-identity/issue-view normalize without validating the response shape — an error object becomes an all-null PR (pr-view even leaks the error body's url into the contract) or the username null, at exit 0. Validate required fields/types before normalizing; the paginated scripts already fail loudly, so this brings the rest in line.
4. recently-merged.sh ignores CODEV_SINCE_DATE and can issue up to 100 sequential requests inside forge's 30-second timeout — on an established repo that turns the analytics path into null. Honoring the since-date bounds it.

Smaller, take-or-leave: CODEV_REPO is now overloaded (repo-archive's foreign-repo input vs. gitea read targeting) — a line in forge.md and both SKILL.md copies would help; and forge-contracts.ts's reviewRequests/isDraft comments go stale with this PR.

Merge order: #1458 first (it brings the # forge-executable mechanism), then this. Happy to turn the two around quickly once these land — and thank you for sticking with it.

[waleedkadous]

Given how long this waited on us, we'll take the last mile ourselves rather than hand you a list: a builder will push the review items directly onto this branch (you enabled maintainer edits — thank you), your commits and authorship stay as they are, and I'll re-review and merge once green. If you'd rather make the changes yourself, just say so and we'll hold off.

[waleedkadous]

Pushed the review items onto this branch as we offered — four commits on top of yours, nothing rebased or squashed, all ten of your commits and their authorship untouched. Thank you again for the contribution and for the patience; the real-script fake-CLI suite you built is what made all of this cheap to do, and every fix below is a test in your harness.

Also merged main in: #1458 landed, so the # forge-executable: mechanism is live.

The four required items

1. # forge-executable: tea headers. On six scripts, not five. The five that source _lib.sh are the ones the review named, but fixing item 3 in user-identity.sh required capturing tea api user before the jq pipe, which moves tea off the first substantive line — so without a header of its own, that fix would have caused the regression this item closes. Verified against the merged extractExecutable, not a simulation of it: all fourteen gitea concepts now resolve to tea.

2. The page ceiling fails loudly. Reaching GITEA_MAX_PAGES with every page full means we don't know we have the whole list, so it errors rather than returning the partial array at exit 0. One wrinkle worth naming: a list whose length is an exact multiple of the page size hits the ceiling with nothing missing, so it probes one page past before failing — a hard error on a complete result would be its own bug.

3. Shape validation before normalizing. The nastiest part of this one is that Gitea's error bodies carry a url (the swagger link), so url: (.html_url // .url)succeeded on them and shipped that link as the PR's browser page inside an otherwise all-null contract object. Required fields are now type-checked and failures carry the server's own .message on stderr. issue-view is validated before its comments are fetched, so a bad id reports only its own error instead of also warning about degraded comments on an issue that isn't there.

4. recently-merged honors CODEV_SINCE_DATE — it asks for sort=recentupdate and stops at the first page reaching past the cutoff. Details below, because this is where the reviewers earned their keep.

Plus the take-or-leave items: CODEV_REPO's two meanings documented in forge.md and both SKILL.md copies, and the reviewRequests/isDraft comments in forge-contracts.ts corrected — they claimed GitLab and Gitea emit empty/false, but all three presets populate them for real.

What the consultation caught, because it's the interesting part

I first wrote the since-date bound to fire when the current page was non-increasing in updated_at, reasoning that proved the server had honored sort=recentupdate. Both reviewers broke that, and they were right. Gitea's default order is index/created-DESC, and on a repo where PRs are opened and merged in order, index-DESC is non-increasing in updated_at. A long-lived PR opened in January and merged after the cutoff then sits on page 2, and we stop at page 1 and drop it — a silent loss in exactly the analytics path the bound was meant to protect.

The fix is to check for the property we actually need — the ordering — rather than for evidence that we asked for it. A stop now requires the order to survive a page boundary (previous page descending too, its oldest no older than this page's newest) and never fires on page 1, where there's nothing to compare against. A server that ignores the parameter falls back to your full walk: slower, never wrong. Costs exactly one extra request on an honest server.

The other finding I'm glad we ran: passing a page to the stop filter through jq --argjson blows up on Linux. MAX_ARG_STRLEN caps a single argv string at 128KiB regardless of ARG_MAX, and a 50-item Gitea pulls page — every object embedding full base.repo and head.repo — measures ~90KiB before anyone writes a long PR body. macOS has no per-argument cap, so it passed locally and would have failed on CI and for every Linux adopter. Both pages go in on stdin now.

Smaller ones from the same pass: jq length is 0 for both null and {}, so an error body mid-walk looked exactly like an exhausted list; jq on empty stdin emits nothing and exits 0, so two scripts were "succeeding" with empty stdout and never running their validators at all; a non-string .message threw a raw jq error instead of the legible one; and the test env inherited CODEV_* from the developer's shell, so the "no CODEV_SINCE_DATE" test was asserting the absence of a variable it didn't control.

Testing

41 tests in bugfix-1137-gitea-tea-api.test.ts, +20 on what you had. Your fake tea grew error bodies at exit 0 for pulls/issues/user, a comments endpoint answering with an error object and one answering with non-objects, a repo whose pages never end, one whose length is an exact multiple of the page size, ~150KB pages for the argv cap, and the sorted/lagging pair for the since-date bound — acme/lagging is the reviewer's counterexample verbatim.

Full suite after merging main: 5549 passed | 48 skipped, 0 failures. Every script also exercised under dash, which is what /bin/sh is on the CI runner, rather than only bash.

Two follow-ups from the earlier reviews are still unfiled and still worth doing, neither in scope here: migrating issue-list/issue-search/recently-closed off tea <entity> list --limit onto tea_api_paged (same truncation premise this PR disproved), and repo-archive.sh's bare ${CODEV_REPO} with no fail-fast.

Over to @waleedkadous for the re-review.

[waleedkadous]

Re-reviewed after the maintainer-side commits: six # forge-executable: tea headers (verified against the merged extractExecutable — all fourteen gitea concepts resolve to tea), the paginator now fails loudly at the page ceiling with a one-page probe so exact-multiple lists don't false-alarm, non-array error bodies are refused instead of normalized to null, recently-merged honors CODEV_SINCE_DATE with the stop filter fed via stdin (Linux argv cap), plus the docs and stale comments. 41 tests in the contributor's own fake-CLI harness; CI 7/7 green on a6eddb6. Approving and merging — thank you, @pseudoseed, for the contribution and the patience.