Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
d291012
chore(quest): claim quest/m0/late-signals.md
kixelated Nov 12, 2026
16ad0e5
feat(merge): hold a head an unanswered finding or a newer maintainer …
kixelated Nov 12, 2026
f284a2c
fix(signals): only writers answer, answers target their review, and t…
kixelated Nov 12, 2026
35984ac
fix(signals): a body finding is answered only by a writer's link to i…
kixelated Nov 12, 2026
7989af8
fix(signals): say how to answer a signal in each refusal and comment
kixelated Nov 12, 2026
9c6af83
fix(signals): answer CodeRabbit's threads on the late-signal hold
kixelated Nov 12, 2026
cef3105
Merge origin/main
kixelated Nov 12, 2026
fb1b38f
fix(land-watch): skip a signaled pick retargeted off the watched base
kixelated Nov 12, 2026
1f175cb
Merge remote-tracking branch 'origin/main' into quest/m0/late-signals
kixelated Nov 12, 2026
8ae4bb7
fix(signals): tighten reviewer replies, thread-only passes, fenced de…
kixelated Nov 12, 2026
d813a06
fix(signals): dequeue before commenting and keep a refused comment, s…
kixelated Nov 12, 2026
33e9cb9
fix(signals): mark long-thread pages from a moved head, keep the comm…
kixelated Nov 12, 2026
3d58511
fix(land): count a replaced head's findings and decisions since its p…
kixelated Nov 12, 2026
4bd5446
fix(land): carry a replaced pick's signals to the fixer's head in eve…
kixelated Nov 12, 2026
0aed125
fix(land): carry a prepared head's pin, disarm only the pick read, an…
kixelated Nov 12, 2026
415abaf
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 12, 2026
bb172ff
test(land): pass deps to prepareHead after merging main
kixelated Nov 12, 2026
9ed725a
fix(land): check a queued fixer head, carry gate pins and past handba…
kixelated Nov 12, 2026
d64b996
fix(land): keep a handed-back fix's carry, carry a prepared head's pi…
kixelated Nov 12, 2026
b447a3f
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 13, 2026
75ece8f
fix(land): give the carry its own record, written before the fixer pu…
kixelated Nov 13, 2026
e4776cf
fix(land): chain a gate merge's pin carry, ask contents: write to dis…
kixelated Nov 13, 2026
edc59ab
docs(land): say the non-fixer watcher's token disarms with contents: …
kixelated Nov 13, 2026
33cf3b9
Merge origin/main into quest/m0/late-signals
kixelated Nov 13, 2026
10c1b46
test: adapt the signal tests to main's land request and fixer context
kixelated Nov 13, 2026
9bef64c
fix(land): mark a fixer's signal handback unanswered_signal, reread b…
kixelated Nov 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 44 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -510,6 +510,7 @@ comes last, and a missing value prints as `-`:
| `checkpoint` | Each bot reviewer that approves or requests changes, such as one whose approval the base requires, its round, and its review's URL, when that review is of the head and its latest verdict there, ignoring plain comments, is neither an approval nor a dismissal, at the end of its third, sixth, ... round: [`/quest-review`'s design checkpoint](#review-locally) for an online reviewer. A round is one commit it reviewed; a dismissed review counts as one that approves or requests changes. Only printed when due. |
| `reacted:<content>` | Actor, time, and the PR or review reacted to, as `quest wait` names reactions. |
| `thread` | Node ID, `current` or `outdated`, last commenter, latest comment URL, and `path:line` of each unresolved thread. |
| `signal` | `finding` or `decision`, its URL, who posted it, and its text, for each [signal](#signals-that-hold-a-head) holding the head. |
| `hold` | Label, acquisition token, acquisition time, verified GitHub event API URL, and age; `hold -` when no label holds it. Unknown acquisition facts print as `-` and `unknown age`. |
| `starter-hold` | A draft its starter owns: last activity time, PR URL, and `last active` age. Last activity is not when ownership began. |

Expand All @@ -533,7 +534,7 @@ requirement names one, its app, as GitHub and `quest land` do, and leaves out
same facts as one object with the fields `url`, `state`, `draft`, `head`,
`mergeable`, `mergeState`, `reviewDecision`, `autoMerge`, `mergeQueue`,
`landingStopped`, `checks` (`state`, `passed`, `failing`, `pending`), `reviews`, `checkpoints` (`reviewer`, `round`, `url`), `reactions`,
`threads`, `holds` (`label`, `token`, `takenAt`, `age`, `eventUrl`), and `starterHold` (`lastActive`, `age`, `url`, or null). Ownership uses the state commands' shared reader without changing labels, and event links match the opaque acquisition token against GitHub's event listing. Long lists are paged; reactions are the newest 100 per PR or review,
`threads`, `signals` (`kind`, `url`, `author`, `text`), `holds` (`label`, `token`, `takenAt`, `age`, `eventUrl`), and `starterHold` (`lastActive`, `age`, `url`, or null). Ownership uses the state commands' shared reader without changing labels, and event links match the opaque acquisition token against GitHub's event listing. Long lists are paged; reactions are the newest 100 per PR or review,
as in `quest wait`. Any PR state exits 0, invalid arguments exit 2, and other
failures exit 1.

Expand Down Expand Up @@ -584,7 +585,10 @@ quests skips it. While the base requires an approval the PR lacks, such as an
online reviewer's that a ruleset requires (GitHub's review decision is
`review_required` or `changes_requested`), it only arms auto-merge, which waits
for the approval, and refuses where nothing would wait, since an admin's token
would merge or enqueue past the requirement. It enables auto-merge bound to that SHA, or merges at once when nothing is
would merge or enqueue past the requirement.
It also refuses while a [signal](#signals-that-hold-a-head) holds the head,
naming each.
It enables auto-merge bound to that SHA, or merges at once when nothing is
left to wait for. `--squash` or `--rebase` picks the method, and it refuses one
the repository disallows; otherwise it uses the only method the repository
allows, or else a merge commit, and refuses when merge commits are off and more
Expand Down Expand Up @@ -889,6 +893,35 @@ backoff. Grant the App the base ruleset's bypass and the read permissions needed
to inspect branch protection. The bypass actor's API merge of a pinned PR with
the unreported required `quest land` check must be verified on the live host.

### Signals that hold a head

A signal holds a PR's head from landing until it is fixed or answered, since
the review its pick relied on predates it. `quest merge --land` refuses while
one holds, `quest status` lists each as a `signal` line, and a queue takes a
PR that draws one out, ejecting it as `unanswered_signal`, even while it waits
to merge. Nothing waits for a reviewer: a signal the queue reads before the
merge ends the pick. There are two kinds:

- `finding`: an online reviewer's (a bot's, or a review whose body opens
`Automated review by <name>`) on the head. A review thread it opened holds
until it is resolved or a writer other than the reviewer replies. A `[P<n>]`
line in its latest review over the head, counting one that only opens
threads, holds until a writer's later comment links that review.
- `decision`: a writer's comment that opens with `Maintainer decision`, not in
a quote or code block, posted after the head's commit, which therefore cannot apply it. A
newer commit answers it, as does a writer's later comment that links it.

The land fixer's commit reads neither kind, so it answers none: a head the
fixer put back in the queue still counts the findings on every head its pick's
rounds replaced, and the decisions posted since that pick, wherever the queue
judges it (the fixer's re-enqueue, `quest land watch`'s dequeue, and `quest land
serve`'s queue), however the head got queued. The carry is its own record, written
before the fixer publishes the head and kept through handbacks, holds, removals,
and later picks, so only a writer's push, which moves the head away, ends it.

A writer can push to the repository: an owner, or a member or collaborator
whose permission GitHub reports as write or higher. A bot is never one.

## Watch the merge queue with quest land watch

`quest land watch` runs on a maintainer's host, one process per base branch of a repository,
Expand All @@ -900,7 +933,10 @@ which offers no merge queue. Each pass reads the base's rules
GitHub's queue on a repository switches its watcher with no host change; a
pass that cannot read them does nothing. It reads them with a `contents: read`
token, so an installation granted only one mode's permissions runs it. On GitHub's queue it tells each PR the queue
drops unmerged why. With `--fixer`, it also runs the land fixer on each PR the
drops unmerged why, and takes a queued or armed PR whose head draws a
[signal](#signals-that-hold-a-head) out of the queue, disarming its auto-merge
and saying why, even one another session holds, since GitHub's queue ignores
hold labels. With `--fixer`, it also runs the land fixer on each PR the
queue dropped for a failure or a conflict, and puts it back at the back of the
queue. It polls; the host needs no public endpoint. Its base is resolved once at
startup, from `--base` or the default branch, so a renamed default branch needs a
Expand Down Expand Up @@ -1034,10 +1070,11 @@ pull request GitHub refuses to enqueue says so and waits for a maintainer.

It shares `quest land serve`'s App key, state directory, private repository,
and locks, so the two never run for the same repository at once. Without a
fixer its token asks for `contents: read`, `pull_requests: write`,
`actions: read`, which the App needs for the logs, and `merge_queues: write`,
which `enqueuePullRequest` needs. With one it also asks for `contents: write`,
for arming auto-merge and pushing fixes, and `checks: read` and `statuses: read`,
fixer its token asks for `contents: write`, which disarming a signaled pull
request's auto-merge needs, `pull_requests: write`, `actions: read`, which
the App needs for the logs, and `merge_queues: write`, which
`enqueuePullRequest` needs. With one, which also arms auto-merge and pushes
fixes, it also asks for `checks: read` and `statuses: read`,
for the PR's own checks the fixer reads; a push that carries a workflow change
asks for `workflows: write`.

Expand Down
1 change: 1 addition & 0 deletions assets/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,7 @@ Start each sub-agent in the background with its own isolated worktree, since age
Before starting or resuming one, run `quest agent admit` in the background and go on once it exits 0, handling reports meanwhile: it waits until the host has room for another agent. `quest agent start` and `resume` admit themselves.
A sub-agent reports only when done or blocked, and never waits on GitHub CI, reviews, or merges; stay silent on its interim notifications.
As each reports, explain its result in a few lines: its PR, whether it is still a draft, and its open decisions with recommendations.
Before dispatching a session to apply the user's answers to a PR's decisions, post them on the PR in a comment that opens with `Maintainer decision`: `quest merge` refuses the PR's current head until a newer commit, or a later comment linking the decision, answers it.
Once two agents report the same blocker, such as a check failure that reproduces on the base or a reviewer outage, name it with its evidence in each later agent's brief, and report it once.

A report that is an API error such as a rate limit or overload, or a cancellation the user did not ask for, is not a result.
Expand Down
1 change: 1 addition & 0 deletions assets/skills/iterate.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ Record the settled decisions in this PR description's `## Decisions` section as
Leave the open decisions of its follow-ups to the round that picks it to merge, and record answers your brief or the user gives as the guide's Creation section describes.

Fix merge conflicts, failing CI checks, and the review findings already posted on the head.
Answer each `signal` line of `quest status <pr>` that your push leaves: reply in the finding's thread, link its review in a comment, or link the decision in a comment saying how the head applies it.
If `quest status <pr>` shows auto-merge enabled, disable it with `gh pr merge <pr> --disable-auto` before any push: GitHub keeps it across a writer's push and would land the new head unreviewed.

Once nothing is unfinished and no decision beyond its follow-ups' needs the user, finish with `/quest-review`, passing your token, whether the PR is a draft or already ready for review: it reviews the branch, pushes, and marks it ready.
Expand Down
2 changes: 1 addition & 1 deletion assets/skills/merge.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ The head is landable when:

- the PR is not a draft;
- a review counts for it, as below;
- every review finding posted on it, including automated reviewers' such as CodeRabbit or Codex, is fixed on the head or answered with a refutation, and no decision is open;
- every review finding posted on it, including automated reviewers' such as CodeRabbit or Codex, is fixed on the head or answered with a refutation, no decision is open, and `quest status` prints no `signal` line;
- no check failed on it, required or not, its required checks passed, other than the gate's own `quest land` check, which never reports on a head, and it does not conflict with its base;
- no review requests changes; an approval its base requires may still be to come, since the queue waits for it.

Expand Down
3 changes: 2 additions & 1 deletion assets/skills/run.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ A `/quest-merge` pick covers the PR until it lands or needs the user: when `/que
Order merges that would otherwise conflict.
A PR that left the queue unmerged shows why under `landing-stopped` in `quest status <pr>`.
Where the queue runs a fixer, such as `quest land`, it hands back only a decision: ask the user, with its handback comment's diagnosis and recommendation.
Without one, after `merge_conflict`, `failed_checks`, `changes_requested`, or `unresolved_conversations` the pick holds, even from an earlier session: dispatch `/quest-iterate`. After `checks_timed_out`, run `/quest-merge` again once; a second timeout of the same head is the user's call.
An `unanswered_signal`, which no fixer takes, holds the pick even with one: dispatch `/quest-iterate`.
Without a fixer, after `merge_conflict`, `failed_checks`, `changes_requested`, or `unresolved_conversations` the pick holds, even from an earlier session: dispatch `/quest-iterate`. After `checks_timed_out`, run `/quest-merge` again once; a second timeout of the same head is the user's call.
Any other reason, such as a person removing it, is the user's call.

## Loop
Expand Down
57 changes: 0 additions & 57 deletions quest/m0/late-signals.md

This file was deleted.

4 changes: 2 additions & 2 deletions quest/m0/mistake-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ Check first next run:
[moq-dev/quest#625](https://github.com/moq-dev/quest/pull/625) landed
2026-11-11T18:43Z: no data yet.
- Heads that landed past a finding or decision, after
[late signals](/quest/m0/late-signals.md) lands.
[moq-dev/quest#652](https://github.com/moq-dev/quest/pull/652) lands.
- Whether moq-dev/moq and moq-dev/moq.pro planned the runtime follow-ups
of moq-dev/quest's 2026-11-11 run PR, and whether their escapes recurred.

Expand All @@ -124,7 +124,7 @@ messages 2026-10-26 to 11-11, classed by one sub-agent, approximate):
and 7, with 5 races.
- Landed past an open signal: 3 in moq-dev/moq, 2 catchable and 1
maybe. A review finding posted after enqueue, a recorded decision the
head lacked, and a red platform run. [Late signals](/quest/m0/late-signals.md) takes the
head lacked, and a red platform run. [moq-dev/quest#652](https://github.com/moq-dev/quest/pull/652) takes the
first two; `quest merge`'s refusal of failed checks
([moq-dev/quest#601](https://github.com/moq-dev/quest/pull/601)) covers
none of them.
Expand Down
25 changes: 24 additions & 1 deletion src/cli/hold.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ import { ALLOWS, LAND_CHECK, METHOD_NAMES, contexts, enqueue } from "./land";
import { QUEUE_CHECK } from "./land-queue";
import type { LandingCheck } from "./landed";
import { classifyCheck } from "./status";
import { describe, readSignals } from "./signals";
import { Refusal, ago } from "./start";

export type Method = "merge" | "squash" | "rebase";
Expand Down Expand Up @@ -260,6 +261,7 @@ export async function land(pr: PullRequest, request: LandRequest, deps: GitHubDe
return { ...snapshot, unapproved: fresh.unapproved };
};
await passing(labels.github, pr, snapshot.url, sha);
await unsignaled(labels.github, pr, snapshot.url, sha);
Comment thread
kixelated marked this conversation as resolved.
Resolved
const findings = await request.check({
remote: `https://github.com/${pr.owner}/${pr.repo}.git`,
base: snapshot.base,
Expand All @@ -279,14 +281,18 @@ export async function land(pr: PullRequest, request: LandRequest, deps: GitHubDe
const repository = object(await (await labels.github.request(repositoryPath(pr))).json());
const method = signalMethod(repository, needs.rules, named, snapshot.url, snapshot.base);
await unchanged();
// A finding or decision posted during the quest check above would otherwise ride into the queue.
await unsignaled(labels.github, pr, snapshot.url, sha);
await enqueue(labels.github, snapshot.id, snapshot.head, method);
return;
}
// A merge queue is the repository's own gate: it applies its own method and needs no auto-merge setting.
if (snapshot.queue) {
if (named !== undefined && named !== "merge")
deps.warn(`${snapshot.url} lands through a merge queue, which applies its own merge method`);
await pick(labels, await unchanged(), named ?? "merge");
const fresh = await unchanged();
await unsignaled(labels.github, pr, snapshot.url, sha);
await pick(labels, fresh, named ?? "merge");
return;
}
const repository = object(await (await labels.github.request(repositoryPath(pr))).json());
Expand Down Expand Up @@ -318,6 +324,8 @@ export async function land(pr: PullRequest, request: LandRequest, deps: GitHubDe
);
}
const { unapproved } = await unchanged();
// A decision posted since the check above leaves the head as it was, so `expectedHeadOid` would not refuse it.
await unsignaled(labels.github, pr, snapshot.url, sha);
if (unapproved && repository.allow_auto_merge !== true)
throw new Refusal(
`${snapshot.url} lacks the approval its base requires, which a merge now would bypass; land it once it is approved`,
Expand Down Expand Up @@ -351,6 +359,7 @@ export async function land(pr: PullRequest, request: LandRequest, deps: GitHubDe
(await requirements(labels.github, pr, fresh.base)).checks.some((check) => check.name === LAND_CHECK)
)
throw error;
await unsignaled(labels.github, pr, snapshot.url, sha);
await submit("mergePullRequest");
}
}
Expand All @@ -372,6 +381,20 @@ async function passing(github: GitHub, pr: PullRequest, url: string, sha: string
);
}

/**
* Refuse a head that an online reviewer's unanswered finding or a newer maintainer decision holds, naming each:
* the review a pick relied on predates them, so landing would skip them.
*/
async function unsignaled(github: GitHub, pr: PullRequest, url: string, sha: string): Promise<void> {
const read = (await readSignals(github, pr, [pr.number])).get(pr.number)!;
if (read.head.toLowerCase() !== sha.toLowerCase())
throw new Refusal(`${url} head moved to ${read.head}; check the new head before landing it`);
if (read.signals.length > 0)
throw new Refusal(
`${url} head ${sha} is held by ${describe(read.signals)}; push a fix, or answer each: reply in a finding's thread, or link its review or the decision in a comment that answers it; then land it again`,
);
}

/** GraphQL error types that fault the token or the request, not the PR GitHub would enqueue. */
export const UNREFUSED = ["FORBIDDEN", "NOT_FOUND", "INSUFFICIENT_SCOPES", "INTERNAL"];

Expand Down
Loading
Loading