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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.tsindex 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')).idconst 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.tsindex 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.tsindex 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<SuperTabStif (!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<SuperTabStconst watch = await watchOf(url)if (watch?.state !== 'open') continueconst 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 thendiff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex 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), adiff --git a/docs/plans/2026-11-06-verdict-reads-pr-head-plan.md b/docs/plans/2026-11-06-verdict-reads-pr-head-plan.mdnew file mode 100644index 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.