feat(server): PR watches no longer wake agents for failures main already has

AGENTS.md

@@ -142,7 +142,7 @@ For authorized mobile verification, a missing or outdated native client is a bui
 - UI changes need before/after images. Motion or timing needs a short video.
 - Upload PR evidence to GitHub. Never commit PR-only screenshots or assets such as `.github/pr-assets/`.
 - One request is one PR. Split it only when the maintainer asks. Outside contributions follow the stricter [one problem per PR](CONTRIBUTING.md#one-problem) rule.
-- When babysitting: call `watch_pull_request` and end your turn. T3 Code wakes you on checks, comments, or conflicts. Do not poll or sleep. Verify each bot finding against the source, fix real ones, dismiss false positives with a written reason. Stay quiet when nothing is new. Stop when the bots are green on the latest commit.
+- When babysitting: call `watch_pull_request` and end your turn. T3 Code wakes you on checks, comments, or conflicts, but not for checks main also fails. Do not poll or sleep. On a CI failure, run `vp run ci:failed` and fix only the jobs tagged [new]. Verify each bot finding against the source, fix real ones, dismiss false positives with a written reason. Stay quiet when nothing is new. Stop when the bots are green on the latest commit.
 
 ## Documentation
 

apps/mobile/src/features/threads/LinkedPullRequestList.tsx

@@ -80,7 +80,7 @@ export const LinkedPullRequestRow = memo(function LinkedPullRequestRow(props: {
   const row = (
     <Pressable
       accessibilityRole="button"
-      accessibilityLabel={`Pull request ${link.number}, ${snapshot?.title ?? "waiting for host state"}${status ? `, ${status.label}` : ""}${conflict ? `, ${conflict.label.toLowerCase()}` : ""}, ${link.repository}${stack ? `, stack of ${stack.size}` : ""}${watching ? ", watching" : ""}${checks ? `, checks ${snapshot?.checksState}` : ""}${review ? `, ${review.accessibleLabel}` : ""}`}
+      accessibilityLabel={`Pull request ${link.number}, ${snapshot?.title ?? "waiting for host state"}${status ? `, ${status.label}` : ""}${conflict ? `, ${conflict.label.toLowerCase()}` : ""}, ${link.repository}${stack ? `, stack of ${stack.size}` : ""}${watching ? `, watching${link.watch?.failingOnBase.length ? `, not waking for checks the base branch fails too: ${link.watch.failingOnBase.join(", ")}` : ""}` : ""}${checks ? `, checks ${snapshot?.checksState}` : ""}${review ? `, ${review.accessibleLabel}` : ""}`}
       accessibilityHint={props.actions ? "Touch and hold for actions." : undefined}
       onPress={() => {
         void props.openPullRequest(link.url).then((opened) => {

apps/server/src/mcp/toolkits/pullRequests/handlers.test.ts

@@ -291,6 +291,7 @@ describe("pull request toolkit handlers", () => {
         failedChecks: [],
         passed: false,
         passedChecks: [],
+        failingOnBase: ["lint"],
         remarksThrough: "2026-08-20T00:00:00.000Z",
         remarkIds: [],
         conflicting: false,
@@ -308,6 +309,11 @@ describe("pull request toolkit handlers", () => {
         .call("watch_pull_request", { repository: "t3tools/t3code", number: 1 })
         .pipe(Effect.flip);
       expect(error).toMatchObject({ _tag: "PullRequestNotOpenError", state: "merged" });
+      // The agent can read why a failed check did not wake it.
+      const listed = yield* harness.call("list_thread_pull_requests", {});
+      expect(listed.pullRequests.find((entry) => entry.number === 3)?.failingOnBase).toEqual([
+        "lint",
+      ]);
       expect(
         yield* harness.call("unwatch_pull_request", { repository: "t3tools/t3code", number: 3 }),
       ).toMatchObject({ wasWatching: true });
@@ -522,6 +528,7 @@ describe("pull request toolkit handlers", () => {
         url: "https://github.com/t3tools/t3code/pull/3",
         source: "agent",
         watching: false,
+        failingOnBase: [],
         state: "open",
         title: "PR 3",
         headBranch: "feat-c",

apps/server/src/mcp/toolkits/pullRequests/handlers.ts

@@ -135,6 +135,7 @@ function entryOf(
     url: link.url,
     source: link.source,
     watching: link.watch !== undefined,
+    failingOnBase: link.watch?.failingOnBase ?? [],
     state: link.snapshot?.state ?? null,
     title: link.snapshot?.title ?? null,
     headBranch: link.snapshot?.headBranch ?? null,
@@ -296,6 +297,7 @@ const make = Effect.gen(function* () {
       url: target.url,
       watching: watchedLink(after)?.watch !== undefined,
       wasWatching: before?.watch !== undefined,
+      failingOnBase: watchedLink(after)?.watch?.failingOnBase ?? [],
     };
   });
 

apps/server/src/mcp/toolkits/pullRequests/tools.ts

@@ -227,6 +227,11 @@ export const UnlinkPullRequestResult = Schema.Struct({
 });
 export type UnlinkPullRequestResult = typeof UnlinkPullRequestResult.Type;
 
+const FailingOnBase = Schema.Array(Schema.String).annotate({
+  description:
+    "Failed checks that the base branch fails too. They are not from this pull request, so T3 Code does not wake you for them. It wakes you if the base branch passes them while they still fail here.",
+});
+
 export const WatchPullRequestResult = Schema.Struct({
   ...PullRequestIdentity,
   watching: Schema.Boolean.annotate({
@@ -235,13 +240,15 @@ export const WatchPullRequestResult = Schema.Struct({
   wasWatching: Schema.Boolean.annotate({
     description: "Whether it was already watched before the call.",
   }),
+  failingOnBase: FailingOnBase,
 });
 export type WatchPullRequestResult = typeof WatchPullRequestResult.Type;
 
 export const ThreadPullRequestEntry = Schema.Struct({
   ...PullRequestIdentity,
   source: ThreadPullRequestLinkSource,
   watching: Schema.Boolean,
+  failingOnBase: FailingOnBase,
   state: Schema.NullOr(PullRequestState),
   title: Schema.NullOr(Schema.String),
   headBranch: Schema.NullOr(Schema.String),
@@ -316,7 +323,7 @@ const ListThreadPullRequestsTool = Tool.make("list_thread_pull_requests", {
 
 const WatchPullRequestTool = Tool.make("watch_pull_request", {
   description:
-    "Have T3 Code watch an open pull request for this thread, linking it first if needed. T3 Code checks it every two minutes and wakes you with a message when a check fails, the required checks pass, someone else comments or reviews, or the branch starts to conflict with its base. Use this to monitor or babysit a pull request instead of polling, sleeping, or running a watcher. Only comments posted after this call wake you, so handle the existing ones first, then end your turn. A wake is news, not a merge decision: check readiness yourself before merging. While T3 Code watches, the thread stays in the user's Working list, not their inbox. When you hand the work back to the user, call unwatch_pull_request first so the thread returns to their inbox. Watching ends when the pull request merges or closes, when its thread settles or is archived, when T3 Code fails to read it 8 times in a row (a host rate limit only delays it), when the user stops this thread, or when you call unwatch_pull_request. Unsettle the thread before starting a new watch. A subagent cannot watch: its parent thread owns the pull request.",
+    "Have T3 Code watch an open pull request for this thread, linking it first if needed. T3 Code checks it every two minutes and wakes you with a message when a check fails, the required checks pass, someone else comments or reviews, or the branch starts to conflict with its base. A failed check that the base branch fails too does not wake you, because it is not from this pull request; T3 Code wakes you if the base branch passes it while it still fails here. Use this to monitor or babysit a pull request instead of polling, sleeping, or running a watcher. Only comments posted after this call wake you, so handle the existing ones first, then end your turn. A wake is news, not a merge decision: check readiness yourself before merging. While T3 Code watches, the thread stays in the user's Working list, not their inbox. When you hand the work back to the user, call unwatch_pull_request first so the thread returns to their inbox. Watching ends when the pull request merges or closes, when its thread settles or is archived, when T3 Code fails to read it 8 times in a row (a host rate limit only delays it), when the user stops this thread, or when you call unwatch_pull_request. Unsettle the thread before starting a new watch. A subagent cannot watch: its parent thread owns the pull request.",
   parameters: PullRequestTargetInput,
   success: WatchPullRequestResult,
   failure: PullRequestToolError,

apps/server/src/orchestration-v2/Orchestrator.ts

@@ -3375,13 +3375,15 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
                     failedChecks: [],
                     passed: false,
                     passedChecks: [],
+                    failingOnBase: [],
                     conflicting: false,
                     // Watching again must not repeat check or conflict news the last watch told.
                     ...(existing.endedWatch && {
                       headSha: existing.endedWatch.headSha,
                       failedChecks: existing.endedWatch.failedChecks,
                       passed: existing.endedWatch.passed,
                       passedChecks: existing.endedWatch.passedChecks,
+                      failingOnBase: existing.endedWatch.failingOnBase,
                       conflicting: existing.endedWatch.conflicting,
                     }),
                     remarksThrough: startedAt,

apps/server/src/orchestration-v2/ProjectionStore.test.ts

@@ -5478,6 +5478,7 @@ it.layer(layerTest)("ProjectionStoreV2", (it) => {
             failedChecks: [],
             passed: false,
             passedChecks: [],
+            failingOnBase: [],
             remarksThrough: DateTime.formatIso(at),
             remarkIds: [],
             conflicting: false,

apps/server/src/orchestration-v2/PullRequestWatchReactor.ts

@@ -34,7 +34,11 @@ import * as PullRequestService from "../pullRequest/PullRequestService.ts";
 import { forkParked } from "../serverActivation.ts";
 import * as Orchestrator from "./Orchestrator.ts";
 import * as ProjectionStore from "./ProjectionStore.ts";
-import { evaluatePullRequestWatch, pullRequestWatchMessage } from "./pullRequestWatch.ts";
+import {
+  evaluatePullRequestWatch,
+  isFailedCheck,
+  pullRequestWatchMessage,
+} from "./pullRequestWatch.ts";
 
 /**
  * Checks take minutes, so a faster pass mostly spends the host's rate limit,
@@ -171,6 +175,7 @@ function watchesEqual(left: ThreadPullRequestWatch, right: ThreadPullRequestWatc
     left.failedChecks.join("\n") === right.failedChecks.join("\n") &&
     left.passed === right.passed &&
     left.passedChecks.join("\n") === right.passedChecks.join("\n") &&
+    left.failingOnBase.join("\n") === right.failingOnBase.join("\n") &&
     left.remarksThrough === right.remarksThrough &&
     left.remarkIds.join("\n") === right.remarkIds.join("\n") &&
     left.conflicting === right.conflicting &&
@@ -524,22 +529,43 @@ export const make = Effect.gen(function* () {
           fingerprint === null ? QUIET_REREAD_MS : FINGERPRINT_REREAD_MS,
         )
       : null;
+    // Only failures are compared with the base branch, so a green pull request costs no read.
+    const base =
+      detail.checks.some(isFailedCheck) ||
+      group.targets.some((target) => target.watch.failingOnBase.length > 0)
+        ? yield* pullRequests.baseChecks({ ...reference, branch: detail.baseBranch }).pipe(
+            Effect.catchCause((cause) =>
+              Cause.hasInterruptsOnly(cause)
+                ? Effect.failCause(cause)
+                : Effect.logDebug("pull request watch base checks failed", {
+                    pullRequest: group.key,
+                    cause,
+                  }).pipe(Effect.as(null)),
+            ),
+          )
+        : null;
+    const waitsOnBase =
+      group.targets.some((target) => target.watch.failingOnBase.length > 0) ||
+      detail.checks.some((check) => isFailedCheck(check) && base?.failing.includes(check.name));
     lastReads.set(group.key, {
       at:
         plan.activity || last === undefined
           ? (threadTails.get(group.key)?.fetchedAt ?? now)
           : last.at,
       fingerprint: group.fingerprint,
+      // A failure the base branch shares waits on news a host fingerprint of this pull request
+      // cannot show, so it is read on every pass, like a pending check.
       inFlight:
         detail.mergeability === "unknown" ||
-        detail.checks.some((check) => check.status === "pending"),
+        detail.checks.some((check) => check.status === "pending") ||
+        waitsOnBase,
       remarksComplete: plan.activity ? remarks !== null : (last?.remarksComplete ?? false),
       watches: new Set(group.targets.map(watchKey)),
       status: fingerprint?.status ?? null,
       remarks: fingerprint?.remarks ?? null,
     });
     yield* eachTarget(group, (target) => {
-      const report = evaluatePullRequestWatch(target.watch, detail, remarks);
+      const report = evaluatePullRequestWatch(target.watch, detail, remarks, base);
       if (report.changes.length > 0) {
         const wake = pullRequestWatchMessage({
           number: target.link.number,

apps/server/src/orchestration-v2/ThreadForkService.test.ts

@@ -168,6 +168,7 @@ it.effect("preserves pull request context without inheriting any watches", () =>
       failedChecks: ["lint"],
       passed: false,
       passedChecks: [],
+      failingOnBase: [],
       remarksThrough: DateTime.formatIso(snoozedAt),
       remarkIds: ["review-1"],
       conflicting: true,

apps/server/src/orchestration-v2/pullRequestWatch.forgejoComments.test.ts

@@ -19,6 +19,7 @@ describe("Forgejo comment watch boundary", () => {
     failedChecks: [],
     passed: false,
     passedChecks: [],
+    failingOnBase: [],
     remarksThrough: "2026-10-10T19:52:40.000Z",
     remarkIds: ["29061"],
     conflicting: false,

apps/server/src/orchestration-v2/pullRequestWatch.test.ts

@@ -5,7 +5,11 @@ import type {
 } from "@t3tools/contracts";
 import { assert, describe, it } from "@effect/vitest";
 
-import { PULL_REQUEST_WATCH_WAKE_LIMIT, evaluatePullRequestWatch } from "./pullRequestWatch.ts";
+import {
+  PULL_REQUEST_WATCH_WAKE_LIMIT,
+  evaluatePullRequestWatch,
+  pullRequestWatchMessage,
+} from "./pullRequestWatch.ts";
 
 const STARTED = "2026-10-02T12:00:00.000Z";
 
@@ -15,6 +19,7 @@ const watch = (overrides: Partial<ThreadPullRequestWatch> = {}): ThreadPullReque
   failedChecks: [],
   passed: false,
   passedChecks: [],
+  failingOnBase: [],
   remarksThrough: STARTED,
   remarkIds: [],
   conflicting: false,
@@ -76,6 +81,47 @@ describe("evaluatePullRequestWatch", () => {
     assert.equal(evaluatePullRequestWatch(test.next, pushed, noRemarks).changes.length, 1);
   });
 
+  it("waits quietly on a failure the base branch has too, until the base branch passes it", () => {
+    const red = detail({ checks: [check("lint", "failure"), check("test", "pending")] });
+    const quiet = evaluatePullRequestWatch(watch(), red, noRemarks, {
+      failing: ["lint"],
+      passing: [],
+    });
+    assert.deepEqual(quiet.changes, []);
+    assert.deepEqual(quiet.next.failingOnBase, ["lint"]);
+
+    // An unread base branch, or one whose lint is still running, says nothing new.
+    assert.deepEqual(evaluatePullRequestWatch(quiet.next, red, noRemarks).changes, []);
+    const running = { failing: [], passing: [] };
+    assert.deepEqual(evaluatePullRequestWatch(quiet.next, red, noRemarks, running).changes, []);
+
+    const green = { failing: [], passing: ["lint"] };
+    const fixed = evaluatePullRequestWatch(quiet.next, red, noRemarks, green);
+    assert.deepEqual(fixed.changes, [{ kind: "base-passes", failed: [check("lint", "failure")] }]);
+    assert.deepEqual(fixed.next.failingOnBase, []);
+    assert.deepEqual(evaluatePullRequestWatch(fixed.next, red, noRemarks, green).changes, []);
+  });
+
+  it("wakes for a new failure next to one the base branch has, and names the shared one", () => {
+    const red = detail({ checks: [check("lint", "failure"), check("test", "failure")] });
+    const report = evaluatePullRequestWatch(watch(), red, noRemarks, {
+      failing: ["lint"],
+      passing: ["test"],
+    });
+    assert.deepEqual(report.changes, [
+      { kind: "checks-failed", failed: [check("test", "failure")] },
+    ]);
+    const { text } = pullRequestWatchMessage({
+      number: 7,
+      url: "https://github.com/o/r/pull/7",
+      baseBranch: "main",
+      headSha: "aaaaaaaaaa",
+      report,
+    });
+    assert.include(text, "Also failing on main, so not from this change");
+    assert.include(text, "does not wake you for them: lint.");
+  });
+
   it("reports passed once the required checks pass, whatever the others do", () => {
     const required = (name: string, status: PullRequestCheck["status"]) => ({
       ...check(name, status),