Appearance
API changelog
Consumer-visible changes to the public HTTP surfaces, /api/* including the browser-managed /api/auth/* management routes, keyed to the server version (GET /api/version; surfaced by mergebrief auth status). Entries name the version that shipped them, NOT a git SHA: releases are what adopters deploy, and the version string is what a skewed client can actually see. (Within this monorepo, pre-release "versions" are the SERVER_VERSION the operator sets; dev means an untagged build; key such entries to the merge date instead.)
The contract discipline: response shapes change additively within a major; removals/renames ship expand/contract: new field first, deprecation note here, removal only at a major.
dev (2026-11-14)
No server change; the CLI reads the same route.
- Added
mergebrief product-diff <n>: theproductDiffofread-briefalone, as{"productDiff":{…}}, and{}when the brief has none. It takes--revision <headIndex>likegroups.
dev (2026-11-13)
- Added
jiratointentCheck.primaryTicket.trackeronread-brief: the primary ticket is a key of a Jira project the repository lists. Clients that treat the tracker set as closed must accept the new value. - Changed which reference becomes
intentCheck.primaryTicketonread-brief: a ticket the title names outranks one the branch names, which outranks one the description names, closing keyword or not. The keyword now only puts its reference first among the description's own. A ticket named in several places reports the first of them infoundIn. Briefs already stored keep their ticket until regenerated.
dev (2026-11-04)
No server change; the CLI reads the same routes.
- Changed
mergebrief sessionandcontextwith no span flags: exit 0 on the latest revision with a finished brief, instead of exit 2. A lone--baseor--headstays exit 2. - Changed
mergebrief groupsanddiffwhen the head has no brief but an older one exists: exit 0 on that older one, naming it on stderr, instead of exit 4. No finished brief at all stays exit 4. - Changed session writes with no span flags: exit 0 on the revision you are on, instead of exit 2. A lone
--baseor--headstays exit 2. - Changed
mergebrief submitwith no span flags: exit 0 on the revision you are on when it is the newest code, otherwise exit 5, instead of exit 2. - Added
--revision <headIndex>onsession,context,groups,diffand every session write.
dev (2026-11-01)
- Added
deltaUnchanged: trueon an availablecomparisons.lastReviewofread-pull: the pull request's own change did not move since the checkpoint (a rebase, a base merge or a rewrite only), so no delta is owed.deltaAvailableisfalseon such a view; the field is absent otherwise.read-deltaanswers such a span 404, as it does a skipped one. - Added
unchanged: trueon an availablecomparisons.previousBriefofread-pull: the same, since the previous brief.read-narrativeserves the span's no-change record (artifactKind: "revisionNarrativeUnchanged", noovervieworchunks) in place of a narrative. - Added an unavailable arm to
comparisons.previousBriefonread-pull:{baselineSha, baselineIndex, unavailable}where a previous brief exists but its span has no marks, with thelastReviewreasons (pending,baseline-unavailable,span-too-large). Such a revision previously carried nopreviousBrief. Clients that readnarrativeAvailablemust branch onunavailablefirst.
dev (2026-10-27)
- Added two optional fields to each card's counts on
read-brief-layout:rowRuns, the card's rows as runs of one kind (<kind><length>, kindshhunk header,ccontext,aadded,rremoved,nnote,ean expand control's own row), andsplitLineWidths, the split view's rows bucketed by their wider side, absent where it equalslineWidths. A layout stored before them is removed, so the brief reads as one with no layout until a run over it stores a new one; clients that read the counts alone are unaffected. - Added optional
packageSourceFileson theread-deltabody (GET /api/repos/:repoId/pulls/:prNumber/delta): head paths of the span's files thatchanges-package-sourcefires on but no delta chunk carries (a rename, a mode change or a binary file). Absent when there are none. - Added
read-brief-layout(GET /api/repos/:repoId/pulls/:prNumber/brief-layout?base=&head=): the per-chunk row counts stored beside the brief for the span, as{"layout":{"chunks":{...},"files":{...}}}keyed by chunk id and by unattributed file path. A brief stored without them answers{"layout":null}; a span no brief covers answers 404. - Added
deltaSkipped: trueon an availablecomparisons.lastReviewofread-pull: the worker stored a skip record for the span (too large for one delta call, or the call was cut at its output cap), so no delta will come.deltaAvailableisfalseon such a view; the field is absent otherwise. Clients keyed ondeltaAvailablealone are unaffected.read-deltaanswers such a span 404, as it does a span with no delta. - Added
span-too-largetocomparisons.lastReview.unavailableonread-pull: GitHub would not render the span, so it has no marks, and the worker stored a skip record for it. Clients that treat the reason set as closed must accept the new value. - Added
504 diff-fetch-timeouttoread-diff(GET /api/repos/:repoId/pulls/:prNumber/diff): GitHub did not render the span's diff within the read's 25 s deadline; a later retry may succeed.read-diffnow retries GitHub's 422 and 5xx inside that deadline, and keeps a diff of up to 64 MB per viewer for 10 minutes. No response shape changes. - Added
{ needed, left, cap }as a second shape ofgeneration.errorParamsonread-pull,list-inboxandread-generation-claims: acappedrow whose large pull request needed more runs than the day had left carries the runs it needed, the runs left and the daily cap it ran against. Every othercappedrow keepserrorParamsnull. Clients that readerrorParams.detailalone are unaffected. - Added
output-cuttogeneration.errorCode: the model's output reached its token cap before it finished. A rerun is cut the same way, soregenerate-briefrefuses it as409 generation-not-regenerable. Clients that treat the code set as closed must accept the new value. - Added
provider-spend-limittogeneration.errorCode: the model provider refused the request because its account reached a spend limit, either one the operator set or the account tier's monthly cap. The run fails without a retry; generating again helps once the limit is raised or resets. Clients that treat the code set as closed must accept the new value. - Added
largeRuns { runs, units }toread-spend, present on a day with a run that took more than one unit.startedRunsnow counts units: one per run, plus one per part of a large pull request briefed in parts. - Added
generation.startedAtandgeneration.parts { done, total }toread-pull, present only while a run holds the row: when the run's attempt started (ISO 8601), and, once a large pull request's run planned its parts, how many of them are done. The Inbox never fills either.
dev (2026-10-26)
- Renamed the env var
MERGEBRIEF_URL_BOX_TOKENtoMERGEBRIEF_URL_FALLBACK_TOKEN, and the api and worker log eventevt: "url-box-token.owner.fail"toevt: "url-fallback-token.owner.fail"(same level and fields). The old key, set and non-empty, logs one warning naming the new key and is ignored. No response shape changes.
dev (2026-10-24)
Added
regenerate-brief,POST /api/repos/:repoId/pulls/:prNumber/regenerate, classifiedexternal-write: queues a fresh run of the pull request's current head when it failed in a way a rerun can help, and answers202with no body. The run spends model budget and ends in a PR comment. It needs push access, which it confirms with GitHub at the request (502 github-unavailablewhen GitHub cannot answer), and a repository in an App installation (404 otherwise), and answers409 generation-heldwhile a run holds the head and409 generation-not-regenerablewhen the pull request is closed or merged, the head neither failed nor waits for its trigger approval, failed withdiff-too-large,output-secretorprovider-refusal, or already has a stored brief.Added
awaiting-triggertogeneration.statusonread-pull,list-inboxandread-generation-claims: a pull request whose author the repository does not trust waits for a collaborator with push access to approve its runs, and no brief generates until then. Not a failure:errorCodeis null onread-pullandlist-inbox, absent onread-generation-claims, and no attempt is consumed. Clients that treat the status set as closed must accept the new value.Changed
regenerate-briefalso acts on anawaiting-triggerhead, a pull request whose author's pushes wait for a collaborator. From a browser session it confirms the caller's push access with GitHub at the click (404without it,502 github-unavailablewhen GitHub cannot answer), records the caller as the pull request's trigger approval and queues the run, after which every push is briefed as usual. A Bearer token on such a head gets403 human-onlyand writes nothing; a failed head still accepts a token.Added
viewerCanPushonread-pull(GET /api/repos/:repoId/pulls/:prNumber): the viewer's push access alone, whereviewerCanResolveis push or authorship. A client gatesregenerate-briefon it together withappInstalled.Added
headBriefStoredonread-pull: the latest brief is forheadSha, on any base, which is whatbriefAvailablemeant before.Changed
briefAvailableonread-pullnow means a brief is stored for the pull request's current base andheadSha, the testregenerate-briefapplies (was: the latest brief is forheadSha, on any base). On a pull request retargeted after its head was briefed, a client that still readsbriefAvailablereports no brief while the brief exists;headBriefStoredkeeps the old meaning.Added
stalledtogeneration.waitReasononread-pull: the head ispendingbut its queued job used every attempt and no takeover is queued, so nothing runs it until a new trigger. A client that does not know the value shows its generic pending line.Changed
generation.waitReasononread-pullis absent while a spent job's takeover is scheduled or running (waswaiting-for-slot).
dev (2026-10-23)
- Changed an instance config with no
spend.maxGenerationsPerDaycaps the Instance at 300 generations a day (was uncapped), soGET /api/spendreportscap: 300there.maxGenerationsPerDay: unlimitedkeeps the old uncapped behaviour and leavescapout. - Changed a token rotation GitHub does not answer (no answer within 10 seconds, a network error or a 5xx) answers
502 github-unavailableon any route that reads with the viewer's token (was401 unauthorized, and a browser session was deleted). Every session and API token is kept, so a retry can succeed. A request that waits more than 2 seconds behind another refresh of the same sign-in answers the same 502. - Changed a token rotation GitHub refuses deletes every browser session from that sign-in and revokes every API token minted from it, then answers
401 unauthorized(was: only the browser session making the request was deleted). The CLI's existing answer to a 401 asks for a fresh token. - Changed a stored GitHub token the instance's session key cannot open or seal, on any request or rotation, answers
500 internal-errorand keeps the session (was401 unauthorizedwith the browser session deleted). - Changed a rotation GitHub refuses for the App's own credentials or settings (a wrong client secret, any other client-config OAuth error, or tokens that do not expire) answers
500 internal-errorand keeps every session and API token (was401 unauthorizedwith the browser session deleted). Only GitHub refusing the refresh token itself (bad_refresh_token) ends the sign-in.
dev (2026-10-20)
- Added
search-mention-suggestions,GET /api/repos/:repoId/mention-suggestions?q=<text>: the users and teams the viewer can mention in the repository, as{users:[{login, name?, avatarUrl}], teams:[{combinedSlug, name}]}.qis at most 140 characters. - Added
resolve-mention-targets,GET /api/repos/:repoId/mention-targets?targets=<login,org/slug,...>: which of up to 50 targets GitHub shows the viewer, as{users:[login], teams:[org/slug]}in GitHub's casing.
dev (2026-10-19)
Added
read-spend,GET /api/spend, for the Instance's Operators (403operator-onlyotherwise): the UTC day'sstartedRuns, the dailycap(absent when uncapped),dayStartedAtandresetsAt.Added
read-generation-claims,GET /api/repos/:repoId/pulls/:prNumber/generation: the current head'sclaimsagainstclaimLimit,exhausted, the storederrorCodeanderrorParams, and thetakeoverjob (scheduledwithrunsAt,runningorspent). Nogenerationbefore the first brief is queued.Added the wire code
operator-only(403): an operation for the Instance's Operators refuses any other principal, session or API token.Added
operator(boolean) onGET /api/auth/session: whether the config'soperatorslist names the viewer.Changed
GET /api/inboxandGET /api/repos/:repoId/pulls/:prNumberread installation pull requests live too, on the viewer's token, as a backstop for a webhook that never arrived: an open installation row'sdraft,state,titleand author can change on read, and itsbehindcan now be true. Url rows are still read first, for up to two seconds across both. A live read never queues a generation.Changed
GET /api/inboxandGET /api/repos/:repoId/pulls/:prNumberpick a pull request's currentgenerationby when a trigger last named its head, not by its last status write: an older head's run that finishes after a newer push no longer shows as the pull request's brief.
dev (2026-10-12)
- Changed every
/api/*request body is capped at 1 MiB: a larger one, declared or streamed, answers413 request-too-largebefore the session layer runs, so no credential is checked. Before, an oversized unauthenticated POST answered 401 and an oversized signed-in write was parsed or answered 400.POST /api/repos/:repoId/pulls/:prNumber/attachmentsis exempt and keeps its own larger upload cap. - Removed
catalogFingerprintfromGET /api/capabilities, andserverCatalogFingerprint,cliCatalogFingerprintandfingerprintMatchfrommergebrief capabilities --json. Removed before the first release, so no shipped client reads them. The version number is the skew signal;--requirestill checks the operations an agent needs. - Removed the error codes
app-not-installed,generation-failed,generation-unavailableandgeneration-config, which no route emitted, and theparamsfield of the error body: every/api/*error body is now{ error, code }. Removed before the first release, so no shipped client reads them. - Changed archive to
POST /api/repos/:repoId/pulls/:prNumber/archive(wasPUTon the same path) and unarchive toPOST /api/repos/:repoId/pulls/:prNumber/unarchive(wasDELETEon.../archive). Both answer204with no body (was200 { ok: true }). The oldPUTandDELETEon.../archiveare removed before the first release and now answer404. - Changed
DELETE /api/repos/:repoId/pulls/:prNumber,DELETE /api/inbox/:repoId/:prNumberandDELETE /api/repos/:repoId/attachmentsto answer204with no body (was200 { ok: true }). Methods, paths and error answers are unchanged. - Changed the Review Session writes that echoed their request to answer
204with no body:PATCHandDELETE/api/repos/:repoId/pulls/:prNumber/session/comments/:draftIdandPUT .../session/comments/:draftId/anchor(were200 { draftId }), andPUT .../session/groups/:groupId/classification(was200 { changeGroupId, category }). Removed before the first release.mergebrief draft update|reanchor|deleteandreclassifynow print nothing on success and exit 0. - Changed
POST .../session/risks/dismiss,.../risks/addressand.../risks/reopento answer200 { count }(was200 { flags }, the same number under a new name). Removed before the first release;mergebrief risk dismiss|address|reopenrelays{"count":n}. - Removed the
set-chunk-readoperation,PUT /api/repos/:repoId/pulls/:prNumber/session/chunks/:chunkId/readwith body{ read }answering200 { chunkId, read }. Removed before the first release; the oldPUTnow answers404. - Added
mark-chunk-read,POST .../session/chunks/:chunkId/read, andmark-chunk-unread,POST .../session/chunks/:chunkId/unread. Neither takes a body; both answer204with no body and keep the old operation'sprivate-writeclassification and policy.mergebrief chunk-readsends the first,--unreadthe second, and prints nothing on success. POST .../session/comments(201 { draftId }) andPUT .../session/outcome(200 { outcome }, read back off the stored session) are unchanged.- Changed
POST /api/repos/:repoId/pulls/:prNumber/readyto answer204with no body (was200 { draft: false }, an echo of the request). Removed before the first release.mergebrief readynow prints nothing on success and exits 0. - Changed
POST /api/generateto answer202 { repoId, prNumber }(was200with the same body): the request queues generation in the worker.mergebrief generaterelays the body verbatim. Aurllonger than 500 characters is still a deterministic400 invalid-request. POST /api/repos/:repoId/pulls/:prNumber/review(201 { reviewId, commentsDegraded, commentsFolded, commentsTotal }) is unchanged.- Changed
DELETE /api/auth/tokens/:idto answer200 { apiToken }(was200 { ok: true, apiToken }) andDELETE /api/auth/sessionsto answer200 { revoked }(was200 { ok: true, revoked }). Removed before the first release. - Changed
POST /api/version/dismissandPOST /api/auth/logoutto answer204with no body (were200 { ok: true }). Logout now also sendscache-control: no-store. Removed before the first release. - Changed
GET /api/auth/sessionto answer200 { viewer }(was200 { ok: true, viewer }). Removed before the first release. - Changed
POST /api/auth/tokensto refuse a whitespace-onlynamewith400 invalid-request, and to store the name trimmed; the 100-character cap counts the trimmed name.DELETE /api/auth/tokens/:idwith an id past theint8range answers404(was500). POST /api/auth/tokens(201 { token, apiToken }) andGET /api/auth/tokens(200 { tokens }) are unchanged.
dev (2026-10-11)
- Added
authorLogin(string | null) onGET /api/repos/:repoId/pulls/:prNumberand on eachGET /api/inboxitem: the PR author's GitHub login,nullwhen the stored row has none. A client that predates it ignores the field. - Added the api and worker log event
evt: "url-box-token.owner.fail"(levelerror, fieldsstatus,code): GitHub refusedMERGEBRIEF_URL_BOX_TOKENat boot, so it serves nobody until the token is replaced and the process restarts. The token now serves only the GitHub account that owns it;MERGEBRIEF_URL_BOX_TOKEN_REVIEWERSis no longer read. No response shape changes. - Added the wire code
signed-out(401): a cookie request with no session cookie, an unknown session or an expired one answers401 signed-out(was401 unauthorized), so a browser can tell a session that is gone from a live one GitHub refused. A refused Bearer token and every other 401 still answerunauthorized. - Changed the check order under
/api/repos/:repoId/pulls/:prNumber: a pull request this instance holds no row for answers404 not-foundbefore the body or query is read (a malformed body was400), and a malformed:prNumberanswers 404 like a malformed repo id (was400).DELETE .../pulls/:prNumberanswers 404 for a missing row before the admin check (a non-admin got403 repo-admin-only). - Changed a Bearer token on a human-only operation answers
403 human-onlybefore its input is validated (a malformed body or PR number answered400first). Human-only: deleting a pull request's briefs on either route, editing a draft's anchor, deleting a draft, dismissing, addressing or reopening a risk, purging attachments, and dismissing the version notice. - Changed the per-repo gate in front of every
/api/repos/:repoId/*route: a GitHub outage, rate limit or failed request at the access check answers502 github-unavailable(was 404). It is never cached and never tried on the operator token. A 404 there now always means GitHub refused access or the repository is gone, so a client can tell "try again" from "you lost access". - Changed a GitHub 401 that survives the request's token refresh answers
401 unauthorized(was 404 at the gate, 502 on the reads below). The refreshed token is the one GitHub rejected, so signing in again is the fix. Affects the gate andGET .../pulls/:prNumber/diff,.../stack,.../file-rangeand.../attachments/:assetId. The session is kept. - Changed a GitHub 403 on
GET .../pulls/:prNumber/diffandGET .../pulls/:prNumber/conversationanswers404 not-found(was 502), and onGET /api/repos/:repoId/collaboratorsthe same (was 502). A read collapses a refusal to absence like the gate does; only an outage is 502. The conversation read on an App-installed repository still answers an App credential 401 as502 github-unavailable: a sign-in cannot repair the instance's own credential. - Changed a GitHub 403 on
POST .../pulls/:prNumber/comments(publish a draft now) answers403 github-permission(was 404), as a review submit already does. The viewer proved access at the gate and the fresh re-resolve, so the refusal is their permission to comment, not absence. The draft's claim is released as before. - Changed a GitHub 403 whose message names a secondary rate limit, with no
retry-afterand budget left inx-ratelimit-remaining, answers502 github-unavailablelike any other rate limit (it was read as a permission refusal:404 not-foundor403 github-permission). - Changed the
errorline ofgithub-unavailablereadsgithub is unavailable or rate limited(wasupstream error). The code and status are unchanged.
dev (2026-10-06)
- Added
attempts-exhaustedto the generation failure codes a generation'serrorCodecarries: the head used all its claims since its last trigger and will not retry until a new trigger arrives. It carries nodetail. A client that predates it renders the generic failed line. - Added
maxAttemptsto the worker log eventjob.retries.exhausted, which now also fires when a head's claims are spent.
dev (2026-10-04)
- Added
429 attachment-limit-reachedonPOST /api/repos/:repoId/pulls/:prNumber/attachments: each reviewer may upload 10 files or 30 MB per 10 minutes by default (operator-set through theattachmentsblock ofmergebrief.config.yaml), cookie and Bearer counted together, per api replica. The answer isno-storeand carriesRetry-Afterin whole seconds until the reviewer's window ends. A client that attaches in bulk should stop on it and retry after that delay.
dev (2026-09-27)
- Added
POST /api/repos/:repoId/pulls/:prNumber/attachments(upload-attachment), behind the per-PR gate, App-installed repositories only: the raw bytes of one PNG, JPEG, GIF or WebP image (10 MB cap,content-typedeclares the type and the bytes must agree) are committed to the repository'smergebrief/attachmentsbranch on the App's token, and the answer is201 { url }, the GitHub blob URL a comment carries. External write: a Bearer principal atexternal-writemay call it. Two wire codes ride with it:403 attachments-disabledwhen a rule on the branch refuses the push, and400 attachment-unsupported-type; an App that may not push at all (Contents left read-only, an archived repository) answers the existing403 github-permission. - Added
GET /api/repos/:repoId/pulls/:prNumber/attachments/:assetIdaccepts<uuid>.<ext>as well as a bare asset id, serving a file from the attachments branch with the viewer's token.
dev (2026-09-24)
- Added
PUTandDELETE /api/repos/:repoId/pulls/:prNumber/archive(archive-pull,unarchive-pull), behind the per-PR gate: the viewer's own archive of one inbox row, per reviewer, anchored on the latest brief's head. A brief at a new head lifts it; a brief at the same head, a retarget, does not. Private writes: a Bearer principal atprivate-writeor above may call them. - Added
archivedonGET /api/inbox:hide(the default) leaves the viewer's archived rows out of the page, the total and the repositories;onlylists nothing else.countsnever includes an archived row in either view. The response carriesarchivedTotal, the viewer's archived rows whatever the filters or the view, besidetotal. - Added
DELETE /api/repos/:repoId/pulls/:prNumber(delete-pull), behind the per-PR gate: erases one pull request's briefs and everything hanging off them. Cookie only (human-onlyfor a Bearer principal). An installation row needspermissions.adminon a fresh read of the repository with the viewer's token, else 403repo-admin-only. The route is App-only: an owner world, the operator-PAT rung included, is a 404, and a pasted-URL row isdelete-own-pull's. When an admin deletes an installation row and also holds a pasted-URL row for the same pull request, both go. The purge's audit row names the reviewer. - Added the wire code
repo-admin-only(403). - Changed
DELETE /api/inbox/:repoId/:prNumber: the operation isdelete-own-pull(wasdelete-inbox-item), so an audit or access ledger query on the old id stops at this release; cookie only now (human-onlyfor a Bearer principal, which could call it before); and the purge's audit row names the reviewer (was the App). The path, the owner-only scope and the absence of any GitHub call are unchanged: a pasted row whose repository nobody can read any more still goes, and a row in any installation, or another reviewer's paste, is an indistinguishable 404. - Added
viewerCanDeleteonGET /api/inboxitems: true on the viewer's own pasted-URL rows, and on an installation row when the viewer administers its repository as GitHub listed it. - Added
asOfonGET /api/repos/:repoId/pulls/:prNumber/stack: for a merged or closed pull request the live open list no longer resolves a stack for,stackis the last one recorded on the row andasOfis the ISO time it was recorded. An open pull request without live neighbours still answersstack: nulland noasOf; open or closed is GitHub's answer on the read, not the stored row state. Every live resolve is folded into the row's record, and the worker folds in the stack it sees at generation too: a chain that lost merged ancestors gets them grafted back, so a closed pull request answers the full chain it was part of, andasOfis when the record last changed, not the last read. - Changed the stored fallback for
stackonGET /api/inboxitems: a merged or closed row the live open list no longer holds now keeps the last stack recorded on the pull request row rather than the snapshot inside its latest brief body. An open row without a live entry, including one whose list GitHub refused, isnull: the same rule the brief header applies, since an open pull request the list does not place has no stack. Rows never read since the column landed reportnulluntil the next brief read or generation records one. - Changed the reviewer session cookie is
__Host-mergebrief_session(wasrs_session) and the OAuth state cookie__Host-mergebrief_oauth_state. Both areSecureunconditionally, and the prefix forbids aDomainattribute, so a sibling subdomain on the same apex can no longer shadow them. Every signed-in reviewer signs in again once after upgrading; the old session rows fall to the expiry sweep. Bearer clients are unaffected. - Changed a cookie-authenticated
POST,PUT,PATCHorDELETE(POST /api/auth/logoutincluded) now needsSec-Fetch-Site: same-originor anOriginequal toPUBLIC_BASE_URL's origin, and answers 403forbiddenotherwise. Browsers send one of the two on every such request, so a page served fromPUBLIC_BASE_URLis unaffected; a script driving the API with a session cookie sets one of them. Bearer requests are exempt.PUBLIC_BASE_URLmust now parse as an absolutehttp(s)URL, checked at boot. - Added
DELETE /api/auth/sessions(revoke-sessions, private-write): revokes every session of the signed-in reviewer, the caller's own included, clears the cookie and answers{ ok: true, revoked }. Cookie-only like the token surface, so a Bearer token cannot sign its owner out; a token minted off one of the revoked sessions keeps working.
dev (2026-09-22)
- Added
layoutquery onGET /api/inbox:folded(the default) leads with the rows that need the viewer before the sort;mixedorders the page by the sort alone. Numbered pages follow the layout, so a layout change is read from page one.
dev (2026-09-21)
- Changed
countsonGET /api/inbox: the four review-state totals now cover only the open, non-draft rows the viewer can see. A merged, closed or draft pull request no longer counts as new or changed, whatever the status filter shows. The viewer's own rows carried no state before and still carry none. - Fixed
viewerIsAuthorandreviewStateonGET /api/inboxitems andviewerIsAuthoronGET /api/repos/:repoId/pulls/:prNumberfor a url row ingested before its author was recorded: the live read now writes the author GitHub names, so the viewer's own row stops reading as new to them once it is read again. - Changed
stackonGET /api/inboxitems: for a pull request GitHub still lists as open, the position now comes from the repository's live open-PR list, read with the viewer's token and cached per session for a minute, the same readGET /api/repos/:repoId/pulls/:prNumber/stackmakes. A row the list no longer holds, or whose list GitHub refused, keeps the position stored with its latest brief, as before; a row the list holds as a fork or on its own isnulleven when a stored position said otherwise. A url row's list is read under the name its last successful live read recorded after matching the repository id; a row GitHub no longer shows the viewer keeps its stored position.
dev (2026-09-20)
- Added
vieweronGET /api/auth/session:{ login, avatarUrl }for the signed-in reviewer, the same shape the Inbox response carries, so a header can show who is signed in without listing anything. - Added
GET /api/inbox(list-inbox): the viewer's pull requests across every installation they reach plus their own pasted-URL rows, as numbered pages of 25 (items,page,pageSize,total, nohasNext; a page past the end returns no items with the true total). Query keyspage,sort(updated|generated),state(repeatable:open,draft,merged,closed; default open and draft),repo,review(new,in-progress,reviewed,updated),author(mine,others,all),installation. Each item carriesreviewState,behind,unreachable,generation,latestBriefAt,githubUpdatedAtandstack; the response carriescounts,viewer,reachableInstallationsandrepositories(every repository the viewer's rows name, unfiltered, sorted by slug, at most 100: the Repository filter's vocabulary) andinstallUrl(the App's new-installation page, or null when the instance set noGITHUB_APP_SLUG). A GitHub failure on the installations check fails the list withgithub-unavailable. Pasted-URL rows are read live first, for up to two seconds. - Added
DELETE /api/inbox/:repoId/:prNumber(delete-inbox-item), the owner-delete of a pasted-URL row. - Removed
GET /api/pulls(list-pulls),GET /api/briefs(list-url-briefs) andDELETE /api/briefs/:repoId/:prNumber(delete-url-brief): the Inbox and its delete replace all three, andmergebrief pralready readsGET /api/inbox. - Removed
GET /api/auth/installationsandPOST /api/auth/installationswith their operation idslist-installationsandselect-installation. No credential holds a current installation: every gated request resolves the installation from the repository it names, among the installations the viewer can reach, and an API token reaches every one of them. - Changed
POST /api/auth/tokensno longer takesinstallationId; a body carrying it is accepted and the field ignored. Token views on the mint and list responses no longer carryinstallationId. A pre-release change with no compatibility value: a cached web bundle shows its generic token-list failure until it reloads.
dev (2026-09-18)
- Added an optional
generation.waitReasononGET /api/repos/:repoId/pulls/:prNumber:debouncingwhile the queued job's start time is still ahead,waiting-for-slotonce it is due and no worker slot has claimed it. Present only while the generation ispendingand its job is unclaimed; absent otherwise, and never onGET /api/pullsorGET /api/briefsrows. No timestamp is exposed. A client that does not know the field, or a value in it, shows its generic pending line.
dev (2026-09-17)
- Added
GET /api/auth/session: answers{ "ok": true }for a request carrying a live session cookie, otherwise the session gate's hint-free 401. Cookie-only like the rest of/api/auth/*; a Bearer token is ignored. The web app's development-only file-brief readers gate on it.
dev (2026-09-15)
- Changed the instance config key
spend.dailyGenerationCapis nowspend.maxGenerationsPerDay, and the cap counts generations across every repo the instance serves instead of per repo.spend.perRepois removed; a file still carrying either old key refuses boot (the block is strict). Thecappedstatus and thespend.cap.tripevent are unchanged,repofield included. Pre-release rename with no compatibility value.
dev (2026-09-14)
- Changed the
generation.statuswire valuequeuedis nowpending: a Job is queued, a Generation is pending. Pre-release rename with no compatibility value, so a client matching onqueuedmust be updated.
dev (2026-09-11)
- Added
GET /api/repos/:repoId/pulls/:prNumber/file-range?ref&path&from&to→{path, ref, from, to, lines, totalLines}: one file's line window at a ref, read live with the viewer's token behind the per-PR gate,no-store. Backs hunk-edge expansion in the diff view.from/toare 1-based inclusive and both ends clamp to the file, solinesalways holdsto - from + 1entries and a window past the end answersfrom = totalLines + 1,to = totalLines. A span wider than 400 lines is a 400invalid-request.refis a 40-hex commit SHA, never a branch name, so a push cannot serve newer lines at the old line numbers;pathmust be repo-relative with no empty,.or..segment and no control character. A path absent at that commit is 404file-not-found(told apart from the gate's bare 404 for a repo the reader may not see); a blob over 1 MB is 413file-too-large; a blob that is not text is 400file-not-text. - Added wire error codes
file-not-found(404),file-too-large(413) andfile-not-text(400).
dev (2026-08-21)
- Added
GET /api/capabilities→{operations:[{id, kind, classification, endpoint}], catalogFingerprint}: the registered product-operation catalog served as data (id-sorted,no-store, session-gated on both presentation channels).catalogFingerprintis the sha256 hex of the committedproduct-operations.manifest.jsonbytes, so a client can detect catalog skew without diffing descriptor lists. Backs themergebrief capabilitiesfail-closed compatibility check (exit 6).
dev (2026-08-16)
- BREAKING: the installation-switch endpoint renamed
POST /api/auth/installation→POST /api/auth/installations, so both multi-org operations share one prefix (GET /api/auth/installationsis unchanged). The request body, response shape, status codes, and cookie-only presentation rule are all unchanged; only the path moved. The old singular path now 404s. Before the first release, with no adopters, so it ships as a straight rename rather than expand/contract.
dev (2026-08-03)
- Added
cappedtogeneration.statuson the PR-view/list responses (generation.status): the repo hit the instance's daily generation cap (spend.dailyGenerationCap) and the run was skipped. Terminal, and NOT a failure:erroris null and no attempt is consumed. Clients that treat the status set as closed must accept the new value; clients that only branch onsucceeded/failedsee it as "neither", which is correct. - Added the worker log event
evt: "spend.cap.trip"(levelwarn, fieldsrepo,prId,headSha,cap,dayUtc), one line per capped skip. The event name was reserved by the logging design; it ships atwarn, not the reservederror.
dev (2026-07-21)
- BREAKING: the per-request access-log line renamed
evt: "read"→evt: "api.access"(before the first release, with no adopters). The line also gainsreqIdand amsgfield, and levels render as string labels ("level":"info"). Anything scripted againstevt:"read"must move toevt:"api.access". - BREAKING: the compose web healthcheck moved
/→/healthz. Operator probes pointed at/still work (it serves the app) but the documented health endpoint is now/healthz. - Added
GET /healthz(static liveness) andGET /readyz(readiness: app composition +SELECT 1), bare top-level paths outside/api, unauthenticated, constant{"ok":bool}JSON./readyzanswers 503 when the database is unreachable; compose and orchestrators must probe/healthz, never/readyz. - Added
X-Request-Idhandling on/api/*: a valid inbound id (charset/length-guarded) is accepted and echoed on the response; a UUID is minted and echoed otherwise. - BREAKING: all
/auth/*routes moved under/api/auth/*so the app registers ONE external path namespace:/auth/github→/api/auth/github,/auth/github/callback→/api/auth/github/callback,/auth/logout→/api/auth/logout,/auth/tokens[/:id]→/api/auth/tokens[/:id],/auth/installation[s]→/api/auth/installation[s]. Old paths now 404 (SSR page router). Every registered GitHub App must update its OAuth callback URL to<PUBLIC_BASE_URL>/api/auth/github/callback. - Bearer presentation rule adjusted with the move: Bearer is accepted on
/api/*except/api/auth/*; auth management stays cookie-only, as before.
dev (2026-07-09)
- Added
GET /api/version→{version}(session-gated, both presentation channels). - Added
GET /api/repos→{repos:[{repoId, fullName}]}: the installation ∩ user-access intersection; flat, unpaginated,no-store; GitHub failure is a 401/502, never a DB-derived listing. - Added Bearer-token presentation on
/api/*(Authorization: Bearer mergebrief_...), a second channel over the same session machinery./auth/*stays browser-only. - Added
POST /auth/tokens,GET /auth/tokens, andDELETE /auth/tokens/:id(browser-only token management).