Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

A verdict reads the pull request's current head, so a Yes at it counts (#3628) (#3337)

harness-for-autonomous[bot]8af654f7857c
diff --git a/backend/integration/superTabPullRequestEvents.test.ts b/backend/integration/superTabPullRequestEvents.test.ts
index 70c236296..1a9ef7ba7 100644
--- a/backend/integration/superTabPullRequestEvents.test.ts
+++ b/backend/integration/superTabPullRequestEvents.test.ts
@@ -64,12 +64,14 @@ function fakeReader() {
let pullNumbers = 100
/** A Swarm with a Lead and a task, "Ship the parser", assigned to a worker that linked [PR] in its status. */
-async function swarm() {
+/** [reads]: the store reads GitHub through the same fake when a verdict or a Ready needs the head now (#3628). */
+async function swarm({ reads = false } = {}) {
const number = ++pullNumbers, PR = `https://github.com/acme/app/pull/${number}`
const pull = (patch: Partial<PullRequestWatch> = {}): PullRequestWatch => ({ url: PR, number, state: 'open', draft: false, head: HEAD, base: 'main',
mergeable: true, checkRuns: [], checkSuites: [], reviews: [], comments: [], ...patch })
let now = Date.parse('2026-11-03T08:00:00.000Z')
- const store = new SuperTabStore(db, () => now)
+ const { pulls, asked, patches, patchReads, merges, reader } = fakeReader()
+ const store = new SuperTabStore(db, () => now, undefined, reads ? { pullRequestReader: () => reader } : {})
const tab = (await store.create(owner, randomUUID(), 'Events', 'public')).id
const execute = (command: Command, user = owner, asAgentId?: string) => store.execute(user, tab, { operationId: randomUUID(), command }, asAgentId)
const invitation = await execute({ type: 'invite.create', email: host.email, role: 'collaborator', conversationId: 'lead' })
@@ -85,7 +87,6 @@ async function swarm() {
const worker = await add(task, 'test-host', 'Worker')
const assignment = String((await execute({ type: 'work.assign', conversationId: task, agentId: worker })).result.assignmentId)
await execute({ type: 'work.status', conversationId: task, assignmentId: assignment, status: 'working', result: `Draft ${PR}` }, host, worker)
- const { pulls, asked, patches, patchReads, merges, reader } = fakeReader()
const pass = async () => { now += MINUTE; return watchPullRequests(db, store, reader, now) }
/** The rows this feature wrote in [conversationId], oldest first. */
const told = async (conversationId = task) => (await db.superTabMessage.findMany({ where: { tabId: tab, conversationId }, orderBy: { sequence: 'asc' } }))
@@ -453,4 +454,80 @@ describe('pull request events', () => {
for (const check of await read()) expect(check.passedBy).toBeNull()
})
})
+
+ // Task #3628: on #3561 a Yes at the pull request's real head did not count, twice, as the watch had not read the push yet. A
+ // verdict naming a head the record does not have reads GitHub first; a Ready reads it too.
+ describe('a head the record does not have yet', () => {
+ const HEAD2 = 'bbbbbbb2222222bbbbbbb2222222bbbbbbb22222', HEAD3 = 'ccccccc3333333ccccccc3333333ccccccc33333'
+ /** The watch read HEAD; GitHub is at HEAD3 now, unread. A Reviewer on the task and a Tester on its step. */
+ const pushed = async () => {
+ const f = await swarm({ reads: true })
+ f.patches.set(HEAD, 'p1').set(HEAD2, 'p2').set(HEAD3, 'p3')
+ f.pulls.set(f.PR, f.pull())
+ await f.pass()
+ const reviewer = await f.add(f.task, 'test-host', 'Reviewer'), tester = await f.add(f.task, 'test-host', 'Tester')
+ const step = String((await f.execute({ type: 'conversation.create', title: 'Test', reviewOf: f.task, step: 'Test', brief: 'Test it',
+ checks: [{ description: 'Signs in', independent: true }] } as Command, host, f.worker)).result.conversationId)
+ await f.execute({ type: 'conversation.agent', conversationId: step, agentId: tester, present: true, lead: false })
+ const stepWork = String((await f.execute({ type: 'work.assign', conversationId: step, agentId: tester }, host, f.worker)).result.assignmentId)
+ const data = async (key: string) => (await db.swarmGroup.findFirstOrThrow({ where: { tabId: f.tab, key } })).data as unknown as
+ { checks: Array<{ id: string; passedBy: string | null; verdicts?: Array<{ head?: string; stale?: string }> }>; pullRequestHeads?: Record<string, { head: string; patch: string | null }> }
+ const taskCheck = (await data(f.task)).checks[0]!.id, stepCheck = (await data(step)).checks[0]!.id
+ f.pulls.set(f.PR, f.pull({ head: HEAD3 }))
+ const review = async (head: string) => (await f.execute({ type: 'work.check', conversationId: f.task, assignmentId: f.assignment, checkId: taskCheck,
+ passed: true, evidence: 'Reads right', head, base: 'main' } as Command, host, reviewer)).result
+ const test = async (head: string) => (await f.execute({ type: 'work.check', conversationId: step, assignmentId: stepWork, checkId: stepCheck,
+ passed: true, evidence: 'Signs in', head, base: 'main' } as Command, host, tester)).result
+ const recorded = async () => (await data(f.task)).pullRequestHeads?.[f.PR]
+ const checks = async () => [(await data(f.task)).checks[0]!, (await data(step)).checks[0]!]
+ return { f, review, test, recorded, checks }
+ }
+
+ it('a Yes at the real head counts on the task and its step, and the record is that head', async () => {
+ const { review, test, recorded, checks } = await pushed()
+ expect(await review(HEAD3)).toMatchObject({ counts: true })
+ expect(await test(HEAD3)).toMatchObject({ counts: true })
+ expect(await recorded()).toMatchObject({ head: HEAD3, patch: 'p3' })
+ for (const check of await checks()) {
+ expect(check.passedBy).not.toBeNull()
+ expect(check.verdicts!.at(-1)).toMatchObject({ head: HEAD3 })
+ expect(check.verdicts!.at(-1)!.stale).toBeUndefined()
+ }
+ })
+
+ it('a Yes at an older head does not count, and the record moves to GitHub\'s head', async () => {
+ const { review, test, recorded, checks } = await pushed()
+ expect(await review(HEAD2)).toMatchObject({ counts: false })
+ expect(await test(HEAD2)).toMatchObject({ counts: false })
+ expect(await recorded()).toMatchObject({ head: HEAD3 })
+ for (const check of await checks()) {
+ expect(check.passedBy).toBeNull()
+ expect(check.verdicts!.at(-1)).toMatchObject({ head: HEAD2, stale: HEAD3 })
+ }
+ })
+
+ it('a Yes at the recorded head stops counting once GitHub\'s newer head is read', async () => {
+ const { f, review, recorded, checks } = await pushed()
+ // The record still says HEAD, so a Yes there reads nothing and counts, as before; the read for HEAD3 then stales it.
+ expect(await review(HEAD)).toMatchObject({ counts: true })
+ expect(await review(HEAD3)).toMatchObject({ counts: true })
+ f.pulls.set(f.PR, f.pull({ head: HEAD2 }))
+ expect(await review(HEAD)).toMatchObject({ counts: false })
+ expect(await recorded()).toMatchObject({ head: HEAD2 })
+ expect((await checks())[0]!.passedBy).toBeNull()
+ })
+
+ it('GitHub unreadable: the verdict is judged on the record, as before', async () => {
+ const { f, review, recorded } = await pushed()
+ f.pulls.delete(f.PR)
+ expect(await review(HEAD3)).toMatchObject({ counts: false })
+ expect(await recorded()).toMatchObject({ head: HEAD })
+ })
+
+ it('a Ready reads the head of the pull request it names', async () => {
+ const { f, recorded } = await pushed()
+ await f.execute({ type: 'work.status', conversationId: f.task, assignmentId: f.assignment, status: 'review', result: `Ready for review: ${f.PR}` }, host, f.worker)
+ expect(await recorded()).toMatchObject({ head: HEAD3, patch: 'p3' })
+ })
+ })
})
diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.ts
index f6ddf9b0d..5617aa7a6 100644
--- a/backend/src/routes/superTabs.ts
+++ b/backend/src/routes/superTabs.ts
@@ -27,6 +27,7 @@ import { projectGitHubAccess } from '../github/projectAccess.js'
import { projectCiLoad } from '../github/ciLoad.js'
import { projectBranchOrigin, projectPushOrigin } from '../github/pushOrigin.js'
import { projectPullRequestFiles } from '../superTabs/pullRequestFiles.js'
+import { appPullRequestWatch } from '../superTabs/pullRequestEvents.js'
import { githubSignIn, PrismaApprovals, readState, signState, stateSecret, type Approvals, type GitHubSignIn } from '../github/approvals.js'
import type { GitHubRepository } from '../github/repository.js'
import { githubRepository } from '../github/repository.js'
@@ -280,6 +281,8 @@ async function productionStore(github: GitHubTokens | null, approvals: Approvals
...(github ? { pullRequestMerges: (_env: string, _tab: string, _project: string, urls: string[]) => appPullRequestMerges(github.app)(urls) } : {}),
// A task's Ready reads the files its pull requests change, and the server opens its review steps from them (task #3401).
...(github ? { pullRequestFiles: projectPullRequestFiles(github.app) } : {}),
+ // A verdict naming a head the record does not have, and a Ready, read the pull request's head now (task #3628).
+ ...(github ? { pullRequestReader: () => appPullRequestWatch(github.app) } : {}),
// A start or assignment its account cannot reach the repository from is refused at once, by the read Project details
// shows (task #3266): the token endpoint below would refuse it on the machine, after the start was queued.
...(github ? { repositoryReach: async (autonomousEnv: string, tabId: string, projectId: string, repositoryUrl: string) =>
diff --git a/backend/src/superTabs/pullRequestEvents.ts b/backend/src/superTabs/pullRequestEvents.ts
index 3d205b128..f97133d05 100644
--- a/backend/src/superTabs/pullRequestEvents.ts
+++ b/backend/src/superTabs/pullRequestEvents.ts
@@ -136,6 +136,11 @@ export const WATCH_DONE_GROUPS = 100
/** A head whose patch GitHub could not give is asked again after this long, not every pass. */
export const PATCH_RETRY_MS = 15 * 60_000
+/** Whether a pass reads [watch]'s patch id: a head new to the task, or one GitHub could not give a patch for PATCH_RETRY_MS ago.
+ * A new base branch is read again like a new head (security review of #3218, round 3): the id names the branch. */
+const patchNeeded = (known: PullRequestHead | undefined, watch: PullRequestWatch, now: number) =>
+ known?.head !== watch.head || known.base !== watch.base || (known.patch === null && now - known.at >= PATCH_RETRY_MS)
+
/** Reads with the Harness GitHub App: one read-only token per repository for the whole pass, revoked when it is done (as the
* archive pass's, archive.ts). A repository the app is not installed on, or any GitHub failure, reads as null. */
export function appPullRequestWatch(app: GitHubApp): PullRequestReader {
@@ -215,9 +220,6 @@ export async function watchPullRequests(db: PrismaClient, store: Pick<SuperTabSt
if (!patches.has(key)) patches.set(key, reader.patch(url, head, base).catch(() => null))
return patches.get(key)!
}
- // A new base branch is read again like a new head (security review of #3218, round 3): the id names the branch.
- const patchNeeded = (known: PullRequestHead | undefined, watch: PullRequestWatch) =>
- known?.head !== watch.head || known.base !== watch.base || (known.patch === null && now - known.at >= PATCH_RETRY_MS)
// Each task's newest links (watchedLinks), with their pull request as GitHub has it now and a patch where one is needed.
// A head new to a task is asked whether it is git's own merge of another head and main (#3553), once a pass.
const merges = new Map<string, Promise<string | null>>()
@@ -232,7 +234,7 @@ export async function watchPullRequests(db: PrismaClient, store: Pick<SuperTabSt
const watch = await watchOf(url)
if (watch?.state !== 'open') continue
const known = row.heads?.[url] ?? undefined, newHead = known?.head !== watch.head || known.base !== watch.base
- seen.push({ row, watch, patch: patchNeeded(known, watch) ? await patchOf(url, watch.head, watch.base) : undefined,
+ seen.push({ row, watch, patch: patchNeeded(known, watch, now) ? await patchOf(url, watch.head, watch.base) : undefined,
merged: newHead ? await mergeOf(url, watch.head, watch.base) : undefined })
}
}
@@ -272,6 +274,37 @@ export async function watchPullRequests(db: PrismaClient, store: Pick<SuperTabSt
} finally { await reader.done() }
}
+/** A task whose pull requests a command needs read now (store.ts headsReadNow): its key, its heads as recorded, its steps. */
+export interface TaskHeads { key: string; heads?: Record<string, PullRequestHead> | null; steps?: string[] | null }
+
+/**
+ * Reads [urls], pull requests the task [task] links, now, as a pass reads them, and records what GitHub says (store.ts
+ * pullRequestSeen) before the command that needs it is judged (task #3628): a verdict at the pull request's real head was not
+ * counted while the minute's pass had not read the push yet (#3561). The pass's own reads, its own write: the head, its patch
+ * when new, whether it is git's own main merge, and the events, each posted once whichever read sees it first. A closed pull
+ * request is left to the pass. The pull requests GitHub could not say anything of.
+ */
+export async function readPullRequestsNow(db: PrismaClient, store: Pick<SuperTabStore, 'pullRequestSeen'>, reader: PullRequestReader, tabId: string,
+ task: TaskHeads, urls: readonly string[], now: number): Promise<string[]> {
+ try {
+ const unread: string[] = []
+ let bot: string | null | undefined, listed: string[] | undefined
+ for (const url of urls) {
+ const watch = await reader.watch(url).catch(() => null)
+ if (!watch) unread.push(url)
+ if (watch?.state !== 'open') continue
+ const known = task.heads?.[url] ?? undefined, newHead = known?.head !== watch.head || known.base !== watch.base
+ const patch = patchNeeded(known, watch, now) ? await reader.patch(url, watch.head, watch.base).catch(() => null) : undefined
+ const merged = newHead ? await reader.merge(url, watch.head, watch.base).catch(() => null) : null
+ // A task from before steps were listed looks its dormant steps up once, as the pass does at a new head.
+ if (patch !== undefined && !Array.isArray(task.steps) && listed === undefined) listed = (await listedSteps(db, [{ tabId, key: task.key }])).get(`${tabId}:${task.key}`)
+ if (bot === undefined) bot = await reader.botLogin().catch(() => null)
+ await store.pullRequestSeen(tabId, task.key, watch, bot, patch, task.steps ?? listed ?? [], listed !== undefined, merged)
+ }
+ return unread
+ } finally { await reader.done() }
+}
+
/** The dormant steps of [tasks] that list none (Conversation.stepIds absent: tasks from before steps were listed), by
* `tabId:key`, an empty list for one with none: one read for the pass, by the awake-groups index's tabId, dormant and
* deleted, examining a Swarm's dormant groups once (production's largest Swarm had 3,060 groups, 2026-11-05). Each task then
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index 067b79236..81eebbcbb 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -89,7 +89,7 @@ import { activeMachineKeysOf } from '../lib/deviceKeyLog.js'
import { commitParts, indexesOf, machineContentChanged, numberMessages, type Touch, type Written } from './parts/commit.js'
import { loadDeliveryParts, ms } from './parts/light.js'
import { endSteps, ownerOf, stepEndedRows, stepsOf } from './steps.js'
-import { pullRequestEvents, type PullRequestWatch } from './pullRequestEvents.js'
+import { pullRequestEvents, readPullRequestsNow, type PullRequestReader, type PullRequestWatch, type TaskHeads } from './pullRequestEvents.js'
import { deriveCheck, keepHead, refreshChecks, watchedLinks } from './checkVerdicts.js'
import { reopenOnEvents } from './handed.js'
import type { TrainTask } from './mergeTrain/plan.js'
@@ -428,6 +428,9 @@ export interface SuperTabStoreHooks {
* instructions save that may drop a person's rule kept in a code task (ruleMoves.ts, task #3463). Absent with no GitHub App:
* such a line then stays. */
pullRequestMerges?: (autonomousEnv: string, tabId: string, projectId: string, pullRequestUrls: string[]) => Promise<Record<string, number | null>>
+ /** A reader of pull requests as the minute PR watch reads them (pullRequestEvents.ts appPullRequestWatch), for a verdict naming
+ * a head the record does not have and for a Ready, which read the head now (task #3628). Absent with no GitHub App. */
+ pullRequestReader?: () => PullRequestReader
/** The same for a branch a start names: its open pull request's answer, clean for the default branch, unknown with no pull request. */
branchPushOrigin?: (repositoryUrl: string | null, branch: string) => Promise<PushOrigin>
/** Whether the Harness GitHub App reaches a project's GitHub repository for this Swarm (github/projectAccess.ts), read before
@@ -1714,7 +1717,8 @@ export class SuperTabStore {
workspaceLeave = false, only: { overdue?: boolean; defaulted?: boolean; movedTo?: { machineId: string; ownerId: string }; asProjectPm?: string } = {}) {
const { operationId, command } = operationSchema.parse(input)
const [pushOrigin, repositoryReach, pullRequestFiles, pullRequestMerges] = await Promise.all([this.pushOriginFor(user, tabId, command),
- this.repositoryReachFor(user, tabId, command), this.pullRequestFilesFor(user, tabId, command), this.pullRequestMergesFor(user, tabId, command)])
+ this.repositoryReachFor(user, tabId, command), this.pullRequestFilesFor(user, tabId, command), this.pullRequestMergesFor(user, tabId, command),
+ this.verdictHeadRead(user, tabId, command)])
let ended: WorkHold[] = [], started: WorkHold[] = []
// With only PMs and Buddies, no dispatch pass can hand out work.
let hasWorkers = false
@@ -2362,9 +2366,71 @@ export class SuperTabStore {
this.startWork(tabId, started)
// A write that may free a worker or open a task hands out work at once, not at the next 30-second sweep (dispatch.ts).
if (hasWorkers && freesOrOpens(command)) this.dispatchSoon(tabId)
+ // A task's Ready records its pull request's head as GitHub has it now, for the Reviewers it hands over to (task #3628).
+ if (command.type === 'work.status' && command.status === 'review') await this.readyHeadRead(user, tabId, command)
return done
}
+ /**
+ * Before a work.check naming a head (or base) its pull request's record does not have, that pull request's head as GitHub has
+ * it now, recorded as the PR watch records it (task #3628): the verdict is then judged on it. On #3561 a Yes at the real head
+ * did not count, twice, while the minute's pass had not read the push. A head the record has, carried ones too, reads nothing:
+ * the record never moves but to the head GitHub gives, so a verdict at an older head still counts at none.
+ */
+ private async verdictHeadRead(user: AuthUser, tabId: string, command: Command): Promise<void> {
+ if (!this.hooks.pullRequestReader || command.type !== 'work.check' || !command.head) return
+ const { head, base } = command
+ await this.headsReadNow(user, tabId, command, (state) => {
+ const group = state.conversations.find(c => c.id === command.conversationId)
+ const task = group?.reviewOf ? state.conversations.find(c => c.id === group.reviewOf) : group
+ const urls = task?.pullRequestUrls ?? [], heads = task?.pullRequestHeads
+ // The pull request the command records the verdict on (commands.ts work.check).
+ const url = urls.findLast(u => heads?.[u]) ?? urls.at(-1)
+ const known = url ? heads?.[url] : undefined
+ const same = (sha: string) => sha.toLowerCase() === head.toLowerCase()
+ if (!task || !url || (known && (same(known.head) || known.carries?.some(same)) && (base === undefined || base === known.base))) return null
+ return { task, urls: [url] }
+ }, [command.conversationId])
+ }
+
+ /** After a task's Ready, the heads of the pull requests it names that the task links, else its newest link (task #3628). */
+ private async readyHeadRead(user: AuthUser, tabId: string, command: Extract<Command, { type: 'work.status' }>): Promise<void> {
+ if (!this.hooks.pullRequestReader) return
+ await this.headsReadNow(user, tabId, command, (state) => {
+ const task = state.conversations.find(c => c.id === command.conversationId)
+ if (!task || task.reviewOf || !task.pullRequestUrls?.length) return null
+ const linked = watchedLinks(task.pullRequestUrls)
+ const named = typeof command.result === 'string' ? pullRequestsIn(command.result, groupProject(state, task).repository?.repositoryUrl ?? null) : []
+ const urls = linked.filter(url => named.includes(url))
+ return { task, urls: urls.length ? urls : linked.slice(-1) }
+ }, [])
+ }
+
+ /** [pick]'s pull requests of a task read from GitHub now and recorded (pullRequestEvents.ts readPullRequestsNow), outside any
+ * command's transaction, as GitHub may take seconds. A failure leaves the record as it was and is logged: the command is
+ * judged on the record then, as before. [groups]: the command's groups whose task, when they are a step, is loaded too. */
+ private async headsReadNow(user: AuthUser, tabId: string, command: Command,
+ pick: (state: SuperTabState) => { task: Conversation; urls: string[] } | null, groups: string[]): Promise<void> {
+ let picked: { task: TaskHeads; urls: string[] } | null = null
+ try {
+ picked = await transaction(this.db, async tx => {
+ const loaded = await this.load(tx, user, tabId, namedFor(command))
+ // A step's task may be dormant: loaded by its id.
+ const reviewOf = groups.map(id => loaded.state.conversations.find(c => c.id === id)?.reviewOf).filter((id): id is string => !!id)
+ const { state } = reviewOf.length ? await this.ensure(tx, loaded, { groupIds: [...groups, ...reviewOf] }) : loaded
+ const chosen = pick(state)
+ return chosen && chosen.urls.length ? { task: { key: chosen.task.id, heads: chosen.task.pullRequestHeads ?? null,
+ steps: chosen.task.stepIds ?? null }, urls: chosen.urls } : null
+ })
+ if (!picked) return
+ const unread = await readPullRequestsNow(this.db, this, this.hooks.pullRequestReader!(), tabId, picked.task, picked.urls, this.now())
+ if (unread.length) logger.warn('[swarm-pr-head] not read', { tabId, group: picked.task.key, pulls: unread.length })
+ } catch (error) {
+ if (error instanceof SuperTabError) return
+ logger.warn('[swarm-pr-head] not read', { tabId, group: picked?.task.key, error: error instanceof Error ? error.message : String(error) })
+ }
+ }
+
/**
* The project PM the crew dispatch speaks as (dispatchCrew), checked inside the write as the agent path checks an agent:
* it still leads the task's own project and is not stopping, its grant holds (Workspace, machine, share: grantHolds), a
diff --git a/docs/plans/2026-11-06-verdict-reads-pr-head-plan.md b/docs/plans/2026-11-06-verdict-reads-pr-head-plan.md
new file mode 100644
index 000000000..7186d2345
--- /dev/null
+++ b/docs/plans/2026-11-06-verdict-reads-pr-head-plan.md
@@ -0,0 +1,75 @@
+# A verdict reads the pull request's current head: implementation plan
+
+> Written by the project's Engineer way of working (project instructions, Engineer): plan first, then each task test first,
+> the failing test committed before its code. No Execution Handoff.
+
+**Goal:** A check verdict at the pull request's real head counts even when the Swarm's recorded head is stale; a verdict at
+an older head still does not (task #3628, requested by Dee through Harness). On #3561 (PR #3293) a Yes at 316d374, the real
+head, did not count twice because the record still said 3a82e08, then 189afb1: the minute PR watch had not read the push yet.
+
+**Architecture:** The PR watch (pullRequestEvents.ts) stays the one writer of `Conversation.pullRequestHeads`
+(store.ts `pullRequestSeen`). A new function, `readPullRequestsNow`, runs the watch's read for one task's chosen pull
+requests at once: GitHub's pull request, its patch id when the head is new, whether it is git's own main merge, then
+`pullRequestSeen`, which records the head and re-derives the checks of the task and its steps. The store calls it:
+
+- before a `work.check` whose `head` (or `base`) is not the record's for the verdict's pull request, outside the command's
+ transaction, as `pullRequestFilesFor` reads GitHub; the command then judges against the fresh record;
+- after a task's Ready (`work.status` review) commits, for the pull requests the Ready names that the task links (else its
+ newest link), so the record is current when its Reviewers start.
+
+A new store hook, `pullRequestReader`, gives it the GitHub App reader the worker's watch uses (`appPullRequestWatch`).
+
+GitHub sends the backend no push webhook (pullRequestEvents.ts header): "the GitHub push event" is the watch's minute read
+of a new head, which already records it. The verdict-time read covers the minute between.
+
+**Tech Stack:** TypeScript backend (vitest, Mongo integration suite).
+
+**Spec:** task #3628 brief.
+
+## Global Constraints
+
+- Verdicts count only at the exact head on the base they name, or the same patch, or a carried main merge (#3218): unchanged.
+ The read only makes the record GitHub's head; it never makes a head count that GitHub does not show.
+- A read that fails, or no GitHub App, leaves the record as it is and the command runs as before; it is logged.
+- No new refusal. Swarm code stays out of cli/src/core. Owns backend/src/superTabs/ and backend/src/github/.
+
+## Design
+
+- growth: N/A because nothing new is stored: the read writes the same `pullRequestHeads` the watch writes (kept by `keepHead`).
+- concurrency: `pullRequestSeen` is its own transaction on the task, as the watch's; the command's transaction loads after it.
+- read cost: one pull request read per `work.check` whose head differs from the record (none when it matches), plus a
+ patch and merge read only for a new head; a Ready reads the pull requests it names (ETag reads, as the watch).
+- scale: 10x checks means 10x reads only for mismatched heads; the warn line counts failed reads first.
+- compatibility: old clients send no head: no read, as before. The hook is optional.
+- migration + rollback: none; reverting the code returns to minute-only reads.
+- audience: the read runs for a caller the Swarm load admits; the command still checks who may record a verdict.
+- identity: the Harness GitHub App's read-only token per read, revoked after, as the watch's.
+- failure: a failed read is logged (`[swarm-pr-head] not read`) and the verdict is judged on the record, as before.
+- platforms: backend only.
+
+## Review Focus
+
+- A verdict at an old head never counts after the read (GitHub's head is newer).
+- The read cannot move the record to a head GitHub does not report.
+- Steps' checks are re-derived with the task's (dormant steps load).
+
+## Task 1: a verdict at the real head counts when the record is stale
+
+**Files:** backend/integration/superTabPullRequestEvents.test.ts, backend/src/superTabs/pullRequestEvents.ts,
+backend/src/superTabs/store.ts, backend/src/routes/superTabs.ts
+
+**Interfaces:** `readPullRequestsNow(db, store, reader, tabId, task, urls, now)`; hook `pullRequestReader?: () => PullRequestReader`.
+
+- [x] Test: record at HEAD, GitHub at HEAD3, a Yes at HEAD3 counts on the task and its step, and the record is HEAD3.
+- [x] Test: record at HEAD, GitHub at HEAD3, a Yes at HEAD2 (older, never recorded) does not count; the record is HEAD3.
+- [x] Test: a failed read leaves the record and judges as before.
+- [x] Watch them fail; commit.
+- [x] Implement the read before `work.check`; watch them pass; commit.
+
+## Task 2: Ready reads the head
+
+**Files:** same.
+
+- [x] Test: record at HEAD, GitHub at HEAD3, the Engineer's Ready leaves the record at HEAD3.
+- [x] Watch it fail; commit (with Task 1's tests, same file).
+- [x] Implement the read after Ready commits; watch it pass; commit.