Repository navigation
feat(forge)!: read PR, claim, and wait state through a forge with a Kixel Quest backend - #753
Conversation
Quest-Claim: a508c71577285b0e
…ixel Quest backend quest status, quest wait, and the claim and draft reads of quest unblocked --unclaimed, quest start, and quest waiting go through a Forge interface. GitHubForge reads GitHub as before; KixelQuestForge reads Kixel Quest's /forge API for a person holding its token, for the repositories it says it serves. The read types and wire parsers move to quest/core. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… keep usage errors Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 32 minutes. View limit details
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. |
There was a problem hiding this comment.
ℹ️ No critical issues. Two rough edges in the Kixel Quest backend, inline, and one wire-design question below.
Reviewed changes
I reviewed the whole PR: the new forge interface and its wire format, the GitHub and Kixel Quest backends, and the commands moved onto them.
- Forge interface in
quest/core:Forge(viewer,status,pulls,held,watch), the read types moved out ofsrc/github,InputErrorin place ofGitHubInputError, and strict parsers that rebuild field order so--jsonstays byte-identical. GitHubForgeandsrc/github/wait.ts: the existing readers behind the interface.quest wait's GitHub logic moves into a Worker-safeWatch, and the viewer is read once and dropped after a failure.- Kixel Quest backend (
src/cli/forge.ts): picks the backend fromrecords.json,QUEST_FORGE, andQUEST_KIXEL_URL.GET /forgeis cached and dropped after a failure. Requests are bounded by the deadline and refuse redirects. A failure namesQUEST_FORGE=github. - Commands:
status,wait, and the claim and draft reads ofunblocked --unclaimed,start,waiting, andmvnow read throughforgeFor.src/cli/wait.tskeeps only the poll schedule and the timeout. - Docs and quests: a README section for reading through Kixel Quest, help text for the affected commands, the finished quest deleted, and follow-up quests repointed.
ℹ️ Strict extra-field rejection makes additive wire changes break across deploys
shape() refuses unknown fields in both requests and answers, and both sides parse with it. The CLI and kixel.quest's pinned quest/core are deployed separately, so any new field breaks every request until both sides upgrade. If Kixel Quest adds a Status field first, older CLIs fail. If a newer CLI sends a field first, the older server returns 400. The error names the override in most cases, so users can recover, but the two sides must upgrade in lockstep for every schema change. That fits "neither side guesses", but it's worth deciding on purpose.
Technical details
# Strict wire parsing vs. independent deploys
## Affected sites
- src/core/forge.ts:318-331 — `shape` fails on any key not in `fields` (`expected no such field`)
- src/cli/forge.ts:106 — CLI parses answers with `parseForgeAnswer` (strict)
- Kixel Quest parses requests with `parseForgeRequest` (strict), per README
## Required outcome
- A deliberate policy for wire evolution between the CLI and kixel.quest's pinned `quest/core`.
## Open questions for the human
- Is lockstep upgrading acceptable (the error names `QUEST_FORGE=github`), or should answers ignore unknown fields while requests stay strict (or carry a version)?
- Determinism of `--json` comes from rebuilding fields in parser order, which stays true if unknown answer fields are dropped instead of refused.claude-opus-5-5 | 𝕏
kixelated
left a comment
There was a problem hiding this comment.
Automated review by review (OpenAI)
Reviewed head: c2556e664e070b4746670894cd28600f04da1472.
Static catch-up review of the forge wire parsers, backend selection and error handling, GitHub watch extraction, CLI wait scheduling, and claim/draft-read routing. No additional actionable finding beyond the existing review threads.
I independently confirmed the timeout-resumption gap already tracked in the existing thread: KixelQuestForge.watch only sets its cursor after a successful answer. With no --since, a first-poll timeout leaves resume undefined, unlike the GitHub backend, which preserves the original head during setup. A retry can therefore start after activity that occurred during the timed-out wait. Preserve a recoverable baseline before that first remote poll, and add a regression covering a first-poll timeout followed by a head change and retry. Please keep the fix/discussion in the existing thread rather than opening a duplicate.
The extracted GitHub Watch does restart from the returned cursor after an eventful poll, and the post-claim race validation remains on GitHub rather than trusting cached remote state. Those boundaries look consistent with the intended design.
Limits: code/diff inspection only; I did not run tests or exercise the deployed Kixel Quest service. This COMMENT is not an approval or merge recommendation.
…nswer, and name the override on a read's 400 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
✅ No new issues found. Both earlier inline findings are fixed.
Reviewed changes
I reviewed the two commits pushed since the last Pullfrog review at c2556e6.
- Limited Kixel Quest 400s that count as usage errors: a 400 from Kixel Quest is now an
InputErroronly on/forge/watch, where it rejects a bad--since. A 400 onstatus,pulls, orheldfails throughfailed(...), and that error namesQUEST_FORGE=github. A new test covers this. - Added a resume point for a Kixel Quest wait before its first answer:
src/cli/wait.tsrecordsstartedbefore it chooses a forge.KixelQuestForge.watchturns that time into its fallbackresume, rounded down to the second. The first poll still sendsfrom: nullwhen--sinceis absent. - Updated docs and tests for the new resume point: the README and
wait --helpnow name the time the wait started as the resume point through Kixel Quest. A new regression test times out the first poll, moves the head within that first second, and checks that the retry reports the push.
claude-opus-5-5 | 𝕏
kixelated
left a comment
There was a problem hiding this comment.
Automated review by review (OpenAI) · 00dfac4a30580b7a9fd9b8d07e4ffa68029fe645
No new blocker in this delta. The first remote watch timeout now returns a resume timestamp from before discovery, rounded down to GitHub’s precision, until a real cursor is received. That preserves a first-second push during a slow discovery, which the fixture covers. The added GitHub fallback guidance is useful; a timeout in discovery itself still has no new resume point, as before. Static re-review only; I did not run the tests.
|
Maintainer decision (from the maintainer's
(Written by Claude Opus 5.5 with high effort) |
Port #754's ETag-cached pager and edits reads into src/github/wait.ts, give the wait fakes a response cache, and drop records-endpoint's Required link to forge-reads, which this branch finishes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Applied the maintainer's decision in #issuecomment-6943118557: head 28dade9 keeps a Kixel Quest wait without (Written by Claude Opus 5.5) |
kixelated
left a comment
There was a problem hiding this comment.
Automated review by review (OpenAI) · 28dade9dee0165cd756c057e27996a583e7e12b5
No new blocker in the wait/ETag merge. The pager still follows the next link and polls from the last page; it now leaves revalidation to the GitHub client, which deliberately rereads a full last page without a next link. The wait’s seen-event checks still discard rows replayed by a cached 304. Edited comments still restart their updated-since scan at page one. Static re-review of the merge resolution only; I did not run the wait tests.
There was a problem hiding this comment.
✅ No new issues found. The merge carries main's ETag cache into the relocated wait logic correctly.
Reviewed changes
I reviewed the merge of origin/main (28dade9) since the last Pullfrog review at 00dfac4.
- Moved the wait pager onto the cached client:
pagerinsrc/github/wait.tsnow reads withgithub.list(path)and no longer runs its own ETag/304 handling. A 304 replays the cached body under the cached headers, so thenextlink still resolves, andfresh()drops rows the wait has already seen. The client'ssettled()declines to cache a full last page that has nonextlink, so a new next page is still found. - Simplified
edits: it usesgithub.all(...), which still restarts the update-filtered comment list from page one on every poll. - Wired the response cache: the CLI's GitHub dependencies get the disk cache, and the wait test fakes now provide an in-memory cache.
src/cli/wait.tskeeps no leftover paging code after the merge. - Updated the records-endpoint quest: it took main's text, including the
Requiredlink to this quest.
bun test test/wait.test.ts test/forge.test.ts passes (93 tests).
claude-opus-5-5 | 𝕏
Main's #753 moved the status types to quest/core behind a strict forge wire parser, so `Duplicate` and `Status.duplicates` move there with a parser entry, and the duplicate fakes move into test/status-fakes.ts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Finishes quest/m0/github-quota/forge-reads.md: quest's polled reads go through one forge interface with a GitHub backend and a Kixel Quest backend, so a person holding a Kixel Quest token stops spending their own GitHub quota on them.
Summary
quest/core(src/core/forge.ts):Forgewithviewer,status,pulls,held, andwatch; every read answers{value, asOf},asOfbeing the time of the newest webhook behind it, or null for a live read. The read types (Status,OpenPull,Holdings,ClaimSources,WaitEvent,WatchPoll,PullRequest,Repository, ...) moved here fromsrc/github, with strict parsers for each request and answer (parseForgeRequest,parseForgeAnswer,parseForgeInfo) andforgeJsonfor maps. Kixel Quest's API:GET /forge→{login, repositories},POST /forge/<read>→{value, asOf}, bearer token.quest/github(GitHubForge): the existing readers, unchanged in behavior.quest wait's GitHub logic moved fromsrc/cli/wait.tsto Worker-safesrc/github/wait.tsbehind aWatchhandle (poll()andresume), so Kixel Quest can serve a read its index cannot answer by falling through to it, as the Plan asks.src/cli/wait.tskeeps only the poll schedule and timeout.src/cli/forge.ts):forgeFor(repository)reads through Kixel Quest when~/.config/quest/records.jsonpairs a token with its URL andGET /forgelists the repository; otherwise GitHub.QUEST_FORGE=githubforces GitHub;QUEST_KIXEL_URLnames another Kixel Quest. Any Kixel Quest failure (network, non-2xx, refused token, malformed answer) fails the command namingQUEST_FORGE=github, except a 400 onwatch, which refuses a bad--sinceand exits 2 as a usage error, as GitHub's backend does. A 400 onstatus,pulls, orheld, which take no free-form argument, means the two sides disagree on the wire, so it names the override like any other failure. Until Kixel Quest first answers a wait, its resume point is--since, else the time the wait started, so a first poll that times out still prints a point a retry reports later pushes from.quest wait --timeoutcovers choosing the forge too, and the viewer read runs on the watch's deadline-bound client.quest status,quest wait, and the claim and open-PR reads ofquest unblocked --unclaimed,quest start,quest waiting, andquest mv. Output is unchanged.Forge.viewer()names the person.quest waitignores that person's own activity whichever credential reads: Kixel Quest's token's person, or on GitHub aviewerpassed in (the installation-token quest's hook) or else read once.kixelQuest(deps)?.serves(repository). Its Plan now points there.status,wait,unblocked,start, andwaitingsays when reads go there.What stays on GitHub, since it's outside the Goal: upstream discovery (
GET /repos/{repo}, one REST call per--unclaimedrun, which #754's ETag cache makes free), write commands and the reads they verify a write with (iterate,ready,release,merge,start's post-claim race check,start --release), and the host'squest landdaemons. forge-writes extends the same interface with the writes.Choices made without asking (reviewable)
records.json, keyed by endpoint URL), the per-person token kixel.quest already issues, rather than a new file or variable.GET /forgeanswering the person and their repositories, read once per command, rather than inferring "not served" from a 404 on each read, which can't tell an unserved repository from a missing PR.watchis one stateless poll per request,{pull, from}→{events, cursor, pollInterval}, where the cursor belongs to the backend. The CLI keeps the poll schedule. Kixel Quest can fall through by runningGitHubForge.watch(...).poll()once per request.asOf: carried by every answer. Onlyquest waituses it: a timeout through Kixel Quest says how current the index's last answer was.quest statusoutput stays unchanged.QUEST_FORGE=githubandQUEST_KIXEL_URL.quest waitingkeeps its existing warn-and-skip for unreadable drafts, so a Kixel Quest failure there warns (naming the override) rather than failing; it spends no GitHub quota either way.GET /forge, since with a token every forge read goes there.Decisions
/forge/watch; elsewhere a failure namingQUEST_FORGE=github(rejected: append the override to every 400 while keeping it a usage error, since a wire mismatch is not the user's argument to fix).statusfirst to resume from its SHA, as GitHub's backend does, since that read can time out too and costs a request per wait). The trade-off: a retry after such a timeout skips activity on the head from before the first wait started, which that wait never reported either.Public API and wire
quest/githubconsumers (kixel-ai/kixel.quest): the read types (Status,Check,Review,Reaction,Thread,ReviewRecord,HoldFact,Signal,OpenPull,Claim,Holdings,Repository,PullRequest) are now exported fromquest/core;Source/Sourcesare renamedClaimSource/ClaimSources, sincequest/corealready exports aSource. Migrate by importing them fromquest/core.quest/githubaddsGitHubForge.quest/m0/read-api.md): described above and in the README.QUEST_FORGEandQUEST_KIXEL_URLvariables; output and exit codes unchanged. Kixel Quest's live site does not serve/forgeyet, and no host holds a token, so nothing changes for anyone until both happen.Validation
just checkandjust testpass (1421 tests) after merging main: feat(github)!: revalidate every REST GET by ETag against an on-disk cache #754's ETag-cachedlist/allreads replace the wait's hand-rolled conditional pager insrc/github/wait.ts, and records-endpoint drops itsRequiredlink to this quest. A regression test times out a wait's first Kixel Quest poll, moves the head, and retries from the printed point, which reports the push; it fails without the fix.test/forge.test.tsruns the same scenarios against a fake GitHub directly and through a fake Kixel Quest that serves each read by runningGitHubForgeon that fake GitHub: three status scenarios (byte-identical--json), open PRs and claims with landed branches, and three wait scenarios (identical lines, cursors, and sleeps). It also covers an unserved repository reading GitHub (case-insensitively), no token orQUEST_FORGE=githubnever contacting Kixel Quest, a 503, a refused token, and a malformed answer each failing with the override named, the timeout'sasOfmessage, the timeout covering forge discovery, a rate-limited GitHub viewer read giving up at the timeout, a Kixel Quest 400 staying a usage error, failed viewer andGET /forgereads being retried rather than cached, and the wire parsers refusing missing, extra, or ill-typed fields.Statusparser fails all three status scenarios, and dropping the tips from theheldrequest fails the claims scenario.dist/quest.jsagainst a local Kixel Quest stand-in (Bun.serveon localhost, serving/forgeby falling through to real GitHub with my token,QUEST_KIXEL_URL=http://localhost:18787):quest status --jsonon feat(audit)!: ship the audit pack, replacing /quest-audit with the tree audit #746 and plainquest statuson feat(github)!: fail at once on a spent GitHub quota outside daemons and waiters #740, quest: plan the GitHub quota epic and forge writes #745, and ci(pullfrog): give reviews the dev shell's tools #751 were byte-identical toQUEST_FORGE=github, withGH_TOKEN=invalidgiven to the CLI, so the CLI itself made no GitHub request.quest unblocked --unclaimed(10 ready, 5 skipped) andquest waitingwere identical both ways.quest waiton ci(pullfrog): give reviews the dev shell's tools #751 printed its activity; resuming from its cursor with--timeout 40exited 3 printing the cursor andtimed out waiting for pull request activity; Kixel Quest's last answer was current to 2026-11-15T18:37:00.987Z.quest statuswithKixel Quest (http://localhost:18788) failed GET /forge: ECONNREFUSED ...; set QUEST_FORGE=github to read GitHub./forgeand hosts to hold tokens. The epic's closing PR records it.Follow-ups
None new. kixel-ai/kixel.quest's
quest/m0/read-api.mdalready owns serving this API; it waits on this PR's types landing in its pinnedquest.Models
Size: L
Implementer: Claude Code, claude-opus-5-5, unknown effort
Implementer: Claude Code, claude-opus-5-5 (iterate, S)
Implementer: Claude Code, claude-opus-5-5 (iterate, XS)
Review
Rewritten by
quest reviewafter each round.Head: 28dade9
Base: origin/main at f293c54
Risk: high,
Removing quest/github exports and routing status and claim reads through a new forge API can break Kixel Code and repository automation; reverting restores the code but cannot undo actions agents already took from incorrect state.Classified: high by Codex, gpt-6.1-sol, low effort, session
01a1e8b0-70de-78b0-a9c7-684df1912c67Reviewer: Codex, gpt-6.1-sol, xhigh effort
Session:
01a1e084-45eb-7a43-93fe-158098bb5956, round 6Score: 10/10,
The merge preserves the reviewed forge behavior and carries main’s ETag changes into the relocated watcher, with no new issues found by code inspection.Rounds: 6; first round 3 (medium 3); findings 6 (medium 6): fixed 6, refuted 0, open 0
Findings: none
Reviewer: Codex, gpt-6.1-sol, high effort, shadow
Session:
01a1e084-45ea-76d0-843b-45185f2098dbRounds: 2; first round 2 (medium 2); findings 2 (medium 2): fixed 2, refuted 0, open 0