@volter/twin-github 0.1.0 → 0.1.1

package/src/github-connector.ts

@@ -18,8 +18,17 @@
 // text it didn't receive; the one excluded thing is the Non-goal — actual repository
 // file CONTENTS (git blob bytes) — which the pull does not fetch. Content-bearing twin
 // state thus comes from BOTH the observed fold and LOCAL writes, which push reconciles.
-import { appendEvent, confirmAction, pendingActions, syncPull } from '@volter/twin';
-import type { SyncResource, WorldServiceEvent } from '@volter/twin';
+//
+// THE CONVERSATION IS A SET OF SUBJECTS (not a fold on the PR): every review and every issue
+// comment pulls as its OWN SyncResource, because the shadow diff emits one delta per SUBJECT.
+// Folded onto the PR as `reviewCount`/`latestReview`, two reviews between two polls collapsed
+// into one delta (the second overwrote the first), and nothing said WHO reviewed. A review
+// carries its inline (diff-anchored) comments, since GitHub wraps every inline comment in a
+// review — `pull_request_review_id` on each `/pulls/{n}/comments` row is the join.
+import { appendEvent, assertBudgetGuardIntact, buildShadowState, confirmAction, pendingActions, syncPull } from '@volter/twin';
+import type { RemoteExecute, SyncResource, WorldServiceEvent } from '@volter/twin';
+import { GithubBudget, githubCallWeight, type GithubBudgetOptions } from './github-budget.ts';
+import { githubState } from './github-twin.ts';
 
 const SERVICE = 'github';
 
@@ -41,14 +50,61 @@ export interface GithubExecute {
   ): Promise<{ status: number; data: any }>;
 }
 
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveGithubOptions = {
+  /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+  budget?: GithubBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: GithubBudgetOptions;
+};
+
 /**
  * A live executor against the real GitHub REST API (token = the user's own PAT).
  * Constructed with the real @octokit/rest in PROD by the CALLER and passed in; this
  * helper shows the shape without importing the SDK. Kept tiny + dependency-free: it
  * uses `fetch`, so the pack pulls in no network client. Live runs may instead pass a
  * real `new Octokit({ auth }).request` bound into a `{ request }` object.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.github.com` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the
+ * request goes out (`checkBudget`, which THROWS `GithubBudgetError` instead of returning when the
+ * ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a `Retry-After` /
+ * 403-or-429 / `x-ratelimit-remaining: 0` signal becomes a persisted cooldown that makes every
+ * later call fail fast WITHOUT touching GitHub. The weights ARE GitHub's own published point costs
+ * (1 for a read, 5 for a write) — see `github-budget.ts`. There is deliberately NO option to
+ * disable the guard, and no value a caller can pass for `budget` that yields an unguarded client —
+ * but NOT immunity from a caller who WANTS one (a fresh `budgetOptions.path` or an injected clock
+ * restores the allowance; the kernel header states that limit and this does not upgrade it).
  */
-export function liveGithubExecute(token: string, baseUrl = 'https://api.github.com'): GithubExecute {
+export function liveGithubExecute(
+  token: string,
+  baseUrl = 'https://api.github.com',
+  opts: LiveGithubOptions = {},
+): GithubExecute {
+  // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
+  // UNMODIFIED GithubBudget: a duck-typed stand-in, a SUBCLASS that overrides `checkBudget`, and a
+  // Proxy that traps it are all refused, because all three are one-liners that would otherwise
+  // hand back a client with no ceiling at all (§9 finding, 2026-07-26 — `instanceof` alone was
+  // not a check). What this cannot stop is deliberate sabotage from inside the process (an
+  // injected clock, a throwaway ledger path); the kernel's header says so rather than pretending
+  // otherwise, and this guards the accident and the one-liner, which are the shapes that happen.
+  const doFetch = opts.fetchImpl ?? fetch;
+  // The default ledger is keyed by a hash of THIS PAT — GitHub's primary limit is per token, so a
+  // cwd-scoped ledger would hand it a fresh allowance per checkout/worktree/CI matrix leg.
+  // ONE expression decides which budget is used, so there is no second, weaker test that could
+  // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+  // must be an UNMODIFIED GithubBudget — a duck-typed stand-in, a SUBCLASS overriding
+  // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
+  // would otherwise hand back a client with no ceiling (§9 finding, 2026-07-26: `instanceof`
+  // alone was not a check — a subclass satisfied it). What this cannot stop is deliberate
+  // sabotage from inside the process (an injected clock, a throwaway ledger path); the kernel
+  // header states that limit rather than pretending otherwise. This closes the accident and the
+  // one-liner, which are the shapes that actually happen.
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, GithubBudget, 'liveGithubExecute')
+    : new GithubBudget({ token, ...(opts.budgetOptions ?? {}) });
   return {
     async request(route, params = {}) {
       const sp = route.indexOf(' ');
@@ -71,7 +127,12 @@ export function liveGithubExecute(token: string, baseUrl = 'https://api.github.c
         for (const [k, v] of Object.entries(rest)) qs.set(k, String(v));
         path += `${path.includes('?') ? '&' : '?'}${qs.toString()}`;
       }
-      const res = await fetch(`${baseUrl}${path}`, {
+      // Priced by the ROUTE (`"GET /repos/{owner}/{repo}/pulls"`), which is what GitHub's own docs
+      // and point table name endpoints by — stable across owners and repos.
+      const weight = githubCallWeight(route);
+      // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+      const reservation = budget.checkBudget(weight);
+      const res = await doFetch(`${baseUrl}${path}`, {
         method,
         headers: {
           Authorization: `Bearer ${token}`,
@@ -80,7 +141,16 @@ export function liveGithubExecute(token: string, baseUrl = 'https://api.github.c
         },
         ...(isRead ? {} : { body: JSON.stringify(rest) }),
       });
-      return { status: res.status, data: res.status === 204 ? undefined : await res.json() };
+      const resHeaders: Record<string, string> = {};
+      res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
+      const data = res.status === 204 ? undefined : await res.json();
+      // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+      // `Retry-After` beyond the cap is not something to sleep off) — the cooldown is persisted
+      // first either way, so the refusal survives the throw. GitHub answers a tripped SECONDARY
+      // limit with 403 + `Retry-After` rather than 429, which is why the header is read on every
+      // response and not only on a 429.
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+      return { status: res.status, data };
     },
   };
 }
@@ -92,8 +162,56 @@ export function liveGithubExecute(token: string, baseUrl = 'https://api.github.c
 // The shape of an observed PR. Carries the CONTENT the REST PR object returns (title/
 // body/state) plus metadata (counts + refs) and the BODIES of reviews/comments. The
 // only excluded thing is the Non-goal: actual repository file CONTENTS are never pulled.
-type ObservedReview = { state?: string; body?: string; submittedAt?: string };
-type ObservedComment = { body?: string; createdAt?: string };
+
+// One INLINE (diff-anchored) review comment, as it rides its review. `position` and the
+// outdated flag are deliberately NOT carried: GitHub recomputes both on every push, so
+// folding them would make each push a delta on every review that ever touched the file.
+type ObservedReviewComment = {
+  id: string;
+  /** WHO wrote THIS finding, from the comment's own `user` — the row the vendor sent, not
+   *  the review that wraps it. A review is a join key, not an authorship claim: a scanner
+   *  App's finding rides a review a human submitted, a threaded reply rides the root's
+   *  review, and the phantom bucket has no author at all. The pull BOUGHT this field and
+   *  used to throw it away, so a bot finding was served under the human reviewer's login —
+   *  the exact fact a consumer triaging findings reads. Absent when the vendor named nobody
+   *  (`user: null`, a deleted account); the wrapper's author is then the only evidence
+   *  there is, and the fold falls back to it rather than inventing one. */
+  authorLogin?: string;
+  authorType?: 'bot' | 'user';
+  path?: string;
+  line?: number;
+  body?: string;
+  inReplyTo?: string;
+  createdAt?: string;
+};
+// One review: a verdict, its words, WHO said them, and the inline comments it wrapped.
+type ObservedReview = {
+  id?: string;
+  /** True for a review NOBODY SHOWED US — one the reviews page never returned. Two shapes
+   *  wear it: the PHANTOM bucket (`unattached`), holding inline comments whose review id was
+   *  missing, and a NAMED orphan, whose id an inline comment gave us but whose row never
+   *  arrived (a review deleted between the two reads, a page boundary). Both carry comments
+   *  and NOTHING ELSE — no state, no author, no verdict — and a consumer must be able to tell
+   *  either from a real review it merely has no state for yet, so both say so. */
+  partial?: boolean;
+  authorLogin?: string;
+  authorType?: 'bot' | 'user';
+  state?: string;
+  body?: string;
+  submittedAt?: string;
+  commitId?: string;
+  comments: ObservedReviewComment[];
+};
+// One issue comment (the PR's conversation tab). `updatedAt` distinguishes an EDIT — same
+// author, same position, new words — from the comment that was already there.
+type ObservedComment = {
+  id?: string;
+  authorLogin?: string;
+  authorType?: 'bot' | 'user';
+  body?: string;
+  createdAt?: string;
+  updatedAt?: string;
+};
 type ObservedPr = {
   id: string; // owner/repo#number
   number: number;
@@ -108,12 +226,49 @@ type ObservedPr = {
   headSha?: string;
   changedFiles?: number;
   commitsCount?: number;
-  reviewCount: number;
-  commentCount: number;
-  reviews: ObservedReview[];
-  comments: ObservedComment[];
+  authorLogin?: string;
+  /** The PR's own `updated_at` — the provider instant that dates its delta AND the stamp
+   *  the next pull compares against to decide whether its conversation is worth buying. */
+  updatedAt?: string;
+  /** False when the budget skipped this PR's reviews/comments (its `updated_at` had not
+   *  moved). The counts and the conversation subjects are then OMITTED rather than
+   *  reported as zero — an unbought fact is not an observation of absence. */
+  detailsFetched: boolean;
+  /** How many reviews this PR has — counted over exactly the set `latestReview` is drawn
+   *  from (submitted, non-PENDING), so the count and the newest verdict can never disagree. */
+  reviewCount?: number;
+  /** How many issue comments the conversation read bought. Emitted onto the subject beside
+   *  `reviewCount` (it used to be computed here and dropped on the floor). */
+  commentCount?: number;
+  reviews?: ObservedReview[];
+  comments?: ObservedComment[];
 };
 
+// GitHub says a machine wrote something two ways: `user.type === 'Bot'` on the App-authored
+// row, and the `[bot]` login suffix every GitHub App account carries. A consumer triaging a
+// review feed sorts bot findings from human ones, so read both rather than trusting either.
+//
+// READ THE ASYMMETRY BEFORE YOU GATE ON THIS. `bot` ⇒ a machine wrote it is RELIABLE: only a
+// GitHub App account is typed `Bot` or suffixed `[bot]`. The converse is NOT: `user` does not
+// mean a human. A GitHub App acting through a USER token, a service/machine account, and an
+// Organization all come back typed `User` (or `Organization`) with an ordinary login — and a
+// review by a DELETED account answers `user: null`, so neither field exists and no author
+// type is emitted at all. So `authorType === 'bot'` is safe to act on; `authorType === 'user'`
+// is "not identified as a bot", never "a person did this".
+function authorTypeOf(user: any): 'bot' | 'user' {
+  const type = user?.type === undefined || user?.type === null ? '' : String(user.type);
+  const login = user?.login === undefined || user?.login === null ? '' : String(user.login);
+  return type.toLowerCase() === 'bot' || login.endsWith('[bot]') ? 'bot' : 'user';
+}
+
+// The author fields as they ride a review/comment subject: the login when GitHub gave one
+// (a deleted account answers `user: null`), and the human/bot split derived from it.
+function authorFields(user: any): { authorLogin?: string; authorType?: 'bot' | 'user' } {
+  if (user === undefined || user === null) return {};
+  const login = user.login === undefined || user.login === null ? undefined : String(user.login);
+  return { ...(login === undefined ? {} : { authorLogin: login }), authorType: authorTypeOf(user) };
+}
+
 // The shape of an observed ISSUE (GET .../issues with PRs excluded). Carries content
 // (title/body/state) — issues exist on pull as first-class objects, not just via local
 // writes. Numbers share the per-repo PR/issue space (real GitHub).
@@ -129,49 +284,199 @@ type ObservedIssue = {
 /**
  * Pull OBSERVED PRs for a repo via the injected executor. Folds the CONTENT the REST
  * PR object returns (title/body/state) plus metadata (counts/refs) and the BODIES of
- * each review + issue comment. The ONLY thing not pulled is the Non-goal — actual
- * repository file CONTENTS (per-file diffs/blob bytes are not fetched here).
+ * each review + issue comment + INLINE (diff-anchored) review comment. The ONLY thing not
+ * pulled is the Non-goal — actual repository file CONTENTS (per-file diffs/blob bytes are
+ * not fetched here).
+ *
+ * Three reads per PR buy the conversation: the reviews, the issue comments, and
+ * `/pulls/{n}/comments` — the inline comments, where every bot finding lives and which
+ * this pull never fetched before. They are fetched ONCE per PR and joined to their review
+ * by `pull_request_review_id` rather than per review, because GitHub has no
+ * comments-of-one-review route worth N more calls.
+ *
+ * `lastUpdatedAt` is the budget: a PR whose `updated_at` has not moved since the last
+ * observation has no new conversation to buy, so those three reads are skipped entirely
+ * (`detailsFetched: false`) and N unchanged PRs cost only the list call.
+ */
+/** The subject suffix for the PHANTOM review — the bucket an inline comment lands in when
+ *  nothing names the review that wrapped it. A fixed word, not a mint: it is the SAME
+ *  bucket every pull, so a consumer's feed sees one growing subject rather than a new one
+ *  per poll. */
+const UNATTACHED_REVIEW = 'unattached';
+
+/**
+ * The reviews that COUNT as reviews: submitted, and not a PENDING draft. GitHub returns a
+ * reviewer's unsubmitted draft on the reviews page with `state: 'PENDING'` and no
+ * `submitted_at` — nobody has said anything yet — and this pull also carries a PHANTOM
+ * review holding orphaned inline comments, which is a bucket, not a verdict. Both belong in
+ * the `reviews` list (they are real rows) and NEITHER may be the PR's "latest review" or be
+ * counted as one, so exactly one predicate decides both and they can never disagree.
  */
+function submittedReviews(reviews: ObservedReview[]): ObservedReview[] {
+  return reviews.filter((r) => r.submittedAt !== undefined && (r.state ?? '').toUpperCase() !== 'PENDING');
+}
+
+/** GitHub's page ceiling for these list reads. */
+const GITHUB_MAX_PER_PAGE = 100;
+/** How many pages one conversation read will walk before it stops asking. 100×10 = 1000
+ *  reviews or inline comments on a single PR — past that the pull is buying a pathological
+ *  outlier at real rate cost, and the bound is what keeps a poll's spend knowable. */
+const MAX_CONVERSATION_PAGES = 10;
+
+/**
+ * Read EVERY page of a list route, not just the first. GitHub's default page is 30 rows, so
+ * a busy PR's 31st review — or its 31st inline comment, where a scanner's findings pile up
+ * fastest — simply did not exist as far as the pull was concerned, and the missing rows read
+ * downstream as an absence rather than a page boundary. Asks for the vendor's maximum page
+ * (100, the same as `observeRepositoryAndBranches`) and stops on the first short page.
+ */
+async function readAllPages(
+  execute: GithubExecute,
+  route: string,
+  params: Record<string, unknown>,
+): Promise<any[]> {
+  const out: any[] = [];
+  for (let page = 1; page <= MAX_CONVERSATION_PAGES; page++) {
+    const res = await execute.request(route, { ...params, per_page: GITHUB_MAX_PER_PAGE, page });
+    const rows: any[] = Array.isArray(res.data) ? res.data : [];
+    out.push(...rows);
+    if (rows.length < GITHUB_MAX_PER_PAGE) break;
+  }
+  return out;
+}
+
 export async function pullGithubPrs(
   execute: GithubExecute,
-  opts: { owner: string; repo: string; state?: 'open' | 'closed' | 'all'; perPage?: number },
+  opts: {
+    owner: string;
+    repo: string;
+    state?: 'open' | 'closed' | 'all';
+    perPage?: number;
+    /** How many recently-updated CLOSED PRs an open-only pull also sweeps (default 20). */
+    closedPerPage?: number;
+    /** `owner/repo#n` → the `updated_at` last observed for it. */
+    lastUpdatedAt?: Record<string, string>;
+  },
 ): Promise<ObservedPr[]> {
   const { owner, repo } = opts;
   const repository = `${owner}/${repo}`;
+  const state = opts.state ?? 'open';
+  // Same ordering as the closed sweep below: newest-updated first. The two pages are read
+  // against ONE budget of rows, so an open list that came back in the vendor's default order
+  // (by number, descending) would spend that budget on whatever happened to be numbered
+  // highest rather than on what actually moved since the last poll.
   const list = await execute.request('GET /repos/{owner}/{repo}/pulls', {
-    owner, repo, state: opts.state ?? 'open', per_page: opts.perPage ?? 30,
+    owner, repo, state, sort: 'updated', direction: 'desc', per_page: opts.perPage ?? 30,
   });
   if (list.status >= 400) throw new Error(`github pull failed (list pulls): HTTP ${list.status}`);
   const nodes: any[] = Array.isArray(list.data) ? list.data : [];
+  // A MERGE IS A CLOSED PR: an open-only list never observes the event that ends a job —
+  // the PR simply vanishes from the next pull. `state: 'all'` (what syncGithubFromRemote
+  // asks for) already covers it; an open-only caller gets a BOUNDED second page of the
+  // most recently updated closed PRs instead, so the merge folds without a pull walking
+  // the repo's whole closed history.
+  const closedPerPage = opts.closedPerPage ?? 20;
+  if (state === 'open' && closedPerPage > 0) {
+    const closed = await execute.request('GET /repos/{owner}/{repo}/pulls', {
+      owner, repo, state: 'closed', sort: 'updated', direction: 'desc', per_page: closedPerPage,
+    });
+    if (closed.status < 400 && Array.isArray(closed.data)) nodes.push(...closed.data);
+  }
   const out: ObservedPr[] = [];
+  // The two list pages can name the same PR — one that closed BETWEEN the two reads appears
+  // open on the first page and closed on the second. Keeping the page that named it first
+  // kept the STALE row and reported a merged PR as still open. Keep the row whose
+  // `updated_at` is LATER instead (a stampless row never displaces a stamped one), which is
+  // the vendor's own answer to "which of these two observations is the newer".
+  const byNumber = new Map<number, any>();
   for (const n of nodes) {
     const number = Number(n.number);
-    // Reviews + comments: fold the BODIES (content) and count. A real connector would
-    // page these; the fake returns the list, which we map to body-bearing entries.
-    const reviewsRes = await execute.request('GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews', { owner, repo, pull_number: number });
-    const commentsRes = await execute.request('GET /repos/{owner}/{repo}/issues/{issue_number}/comments', { owner, repo, issue_number: number });
-    const reviewNodes: any[] = Array.isArray(reviewsRes.data) ? reviewsRes.data : [];
-    const commentNodes: any[] = Array.isArray(commentsRes.data) ? commentsRes.data : [];
-    const pr: ObservedPr = {
-      id: `${repository}#${number}`,
-      number,
-      repository,
-      reviewCount: reviewNodes.length,
-      commentCount: commentNodes.length,
-      reviews: reviewNodes.map((r) => {
-        const review: ObservedReview = {};
+    // A row with no usable number is not a PR we can address: `Number(undefined)` is NaN and
+    // every such row collapsed onto ONE key, so the second one silently replaced the first.
+    if (!Number.isFinite(number)) continue;
+    const prev = byNumber.get(number);
+    if (prev === undefined) { byNumber.set(number, n); continue; }
+    const a = prev.updated_at === undefined || prev.updated_at === null ? '' : String(prev.updated_at);
+    const b = n.updated_at === undefined || n.updated_at === null ? '' : String(n.updated_at);
+    if (b > a) byNumber.set(number, n);
+  }
+  for (const n of byNumber.values()) {
+    const number = Number(n.number);
+    const updatedAt = n.updated_at === undefined || n.updated_at === null ? undefined : String(n.updated_at);
+    // BUDGET: GitHub moves a PR's `updated_at` on every review, comment, edit and push, so
+    // an unmoved stamp means there is no conversation to buy. A PR that reports no stamp at
+    // all is always fetched — silence is not evidence of stillness.
+    const detailsFetched = updatedAt === undefined || opts.lastUpdatedAt?.[`${repository}#${number}`] !== updatedAt;
+    const pr: ObservedPr = { id: `${repository}#${number}`, number, repository, detailsFetched };
+    if (updatedAt !== undefined) pr.updatedAt = updatedAt;
+    if (detailsFetched) {
+      // ALL THREE conversation reads are PAGED (see readAllPages): a review page boundary
+      // orphaned inline comments from their reviews, an inline page boundary simply lost
+      // findings, and the issue-comment read — which `commentCount` publishes — stopped at
+      // the vendor's default 30, so a busy conversation reported a truncated count as if it
+      // were the whole tab.
+      const reviewNodes = await readAllPages(execute, 'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews', { owner, repo, pull_number: number });
+      const commentNodes = await readAllPages(execute, 'GET /repos/{owner}/{repo}/issues/{issue_number}/comments', { owner, repo, issue_number: number });
+      const inlineNodes = await readAllPages(execute, 'GET /repos/{owner}/{repo}/pulls/{pull_number}/comments', { owner, repo, pull_number: number });
+      // The review is the unit: every inline comment names the review that wrapped it.
+      const inlineByReview = new Map<string, ObservedReviewComment[]>();
+      for (const c of inlineNodes) {
+        if (c.id === undefined || c.id === null) continue; // no id, no stable place in a thread
+        const reviewId = c.pull_request_review_id === undefined || c.pull_request_review_id === null ? '' : String(c.pull_request_review_id);
+        // The row's OWN author rides with it. The review is the join, never the byline.
+        const comment: ObservedReviewComment = { id: String(c.id), ...authorFields(c.user) };
+        if (c.path !== undefined && c.path !== null) comment.path = String(c.path);
+        if (c.line !== undefined && c.line !== null) comment.line = Number(c.line);
+        if (c.body !== undefined && c.body !== null) comment.body = String(c.body);
+        if (c.in_reply_to_id !== undefined && c.in_reply_to_id !== null) comment.inReplyTo = String(c.in_reply_to_id);
+        if (c.created_at !== undefined && c.created_at !== null) comment.createdAt = String(c.created_at);
+        const bucket = inlineByReview.get(reviewId);
+        if (bucket) bucket.push(comment);
+        else inlineByReview.set(reviewId, [comment]);
+      }
+      const reviews: ObservedReview[] = reviewNodes.map((r) => {
+        const id = r.id === undefined || r.id === null ? undefined : String(r.id);
+        const review: ObservedReview = { ...(id === undefined ? {} : { id }), ...authorFields(r.user), comments: id === undefined ? [] : (inlineByReview.get(id) ?? []) };
         if (r.state !== undefined && r.state !== null) review.state = String(r.state);
         if (r.body !== undefined && r.body !== null) review.body = String(r.body);
         if (r.submitted_at !== undefined && r.submitted_at !== null) review.submittedAt = String(r.submitted_at);
+        if (r.commit_id !== undefined && r.commit_id !== null) review.commitId = String(r.commit_id);
+        if (id !== undefined) inlineByReview.delete(id);
         return review;
-      }),
-      comments: commentNodes.map((c) => {
-        const comment: ObservedComment = {};
+      });
+      // An inline comment whose review the reviews page did not name (a page boundary, a
+      // review deleted between the two reads) still EXISTS — it rides a review carrying its
+      // id, the `partial` flag and its comments, and nothing else, rather than being dropped.
+      // Inventing a state or an author for a review nobody showed us would be the worse lie.
+      const unattached: ObservedReviewComment[] = [];
+      for (const [reviewId, comments] of inlineByReview) {
+        // NO review id at all. This used to `continue` — the comment was OBSERVED and then
+        // silently discarded, which is the one thing a pull may never do with a fact it
+        // bought. It hangs off a fixed phantom subject per PR instead, flagged `partial` so
+        // nothing mistakes it for a review whose verdict simply has not arrived.
+        if (reviewId === '') { unattached.push(...comments); continue; }
+        // A review whose id we know but whose ROW never arrived is just as unshown as the
+        // phantom: state, author and verdict are all absent because nobody sent them. It
+        // carries `partial` for the same reason the phantom does — without it a consumer
+        // reads a stateless orphan as a review whose fields merely have not landed yet.
+        reviews.push({ id: reviewId, partial: true, comments });
+      }
+      if (unattached.length > 0) reviews.push({ id: UNATTACHED_REVIEW, partial: true, comments: unattached });
+      pr.reviews = reviews;
+      // Counted over the SAME set the newest verdict is drawn from — a raw row count included
+      // PENDING drafts and the phantom bucket, so `reviewCount` and `latestReview` described
+      // different populations of the same PR.
+      pr.reviewCount = submittedReviews(reviews).length;
+      pr.comments = commentNodes.map((c) => {
+        const comment: ObservedComment = { ...(c.id === undefined || c.id === null ? {} : { id: String(c.id) }), ...authorFields(c.user) };
         if (c.body !== undefined && c.body !== null) comment.body = String(c.body);
         if (c.created_at !== undefined && c.created_at !== null) comment.createdAt = String(c.created_at);
+        if (c.updated_at !== undefined && c.updated_at !== null) comment.updatedAt = String(c.updated_at);
         return comment;
-      }),
-    };
+      });
+      pr.commentCount = commentNodes.length;
+    }
+    if (n.user?.login !== undefined && n.user?.login !== null) pr.authorLogin = String(n.user.login);
     // CONTENT: title/body/state are real text the REST PR object returns — fold them.
     if (n.title !== undefined && n.title !== null) pr.title = String(n.title);
     if (n.body !== undefined && n.body !== null) pr.body = String(n.body);
@@ -230,8 +535,15 @@ export async function pullGithubIssues(
 // contract). Carries CONTENT (title/body/state) now that pull is a content mirror, plus
 // the refs. baseRef/headSha ride under their twin names so the github fold (which reads
 // data.changed.baseRef.after / .headSha.after) picks them up.
+//
+// The PR is one subject and its CONVERSATION is many: each review (`…#<n>:review:<id>`,
+// carrying the inline comments it wrapped) and each issue comment (`…#<n>:ic:<id>`) rides
+// as its own resource, so two reviews between two polls are two deltas and a consumer can
+// say who reviewed. Each dates its own delta — a review by `submitted_at`, a comment by
+// `updated_at ?? created_at` — because a feed ordering a conversation wants the moment it
+// was said, not the moment the poll happened to look.
 export function observedPrsToResources(prs: ObservedPr[]): SyncResource[] {
-  return prs.map((p) => {
+  return prs.flatMap((p) => {
     const fields: SyncResource['fields'] = { number: p.number, repository: p.repository };
     if (p.title !== undefined) fields.title = p.title;
     if (p.body !== undefined) fields.body = p.body;
@@ -244,10 +556,109 @@ export function observedPrsToResources(prs: ObservedPr[]): SyncResource[] {
     if (p.mergeCommit !== undefined) fields.mergeCommit = p.mergeCommit;
     if (p.baseRef !== undefined) fields.baseRef = p.baseRef;
     if (p.headSha !== undefined) fields.headSha = p.headSha;
-    return { type: 'pull_request', id: p.id, fields };
+    // WHO opened it, and when GitHub last saw it change — the stamp the next pull's budget
+    // compares against, kept on the subject rather than in a cache beside it.
+    if (p.authorLogin !== undefined) fields.authorLogin = p.authorLogin;
+    if (p.updatedAt !== undefined) fields.updatedAt = p.updatedAt;
+    // The reviewers' WORDS ride the observation: how many reviews, and the newest one's
+    // verdict and body, so a delta on the feed says what a reviewer said (a consumer decides
+    // from the words, never from a bare count moving). The reviews themselves are subjects
+    // below; this summary stays for a consumer that reads only pull_request. A pull whose
+    // budget skipped the conversation OMITS both — the shadow keeps what it already holds,
+    // because not buying a fact is not observing its absence.
+    if (p.reviewCount !== undefined) fields.reviewCount = p.reviewCount;
+    if (p.commentCount !== undefined) fields.commentCount = p.commentCount;
+    if (p.reviews !== undefined) {
+      // THE NEWEST VERDICT, by the vendor's clock — not `reviews.at(-1)`, which was list
+      // ORDER with the phantom bucket appended after it: the last element was routinely a
+      // review with no state and no body at all (`{}` on the feed), and a reviewer's unsent
+      // PENDING draft could take the slot from the approval that actually landed. The latest
+      // review is the one with the greatest `submitted_at` among the reviews that HAVE one
+      // and are not PENDING — the same set `reviewCount` counts.
+      const submitted = submittedReviews(p.reviews);
+      const latest = submitted.reduce<ObservedReview | undefined>((best, r) => (best === undefined || r.submittedAt! >= best.submittedAt! ? r : best), undefined);
+      fields.latestReview = latest === undefined ? null : { ...(latest.state === undefined ? {} : { state: latest.state }), ...(latest.body === undefined ? {} : { body: latest.body }), ...(latest.submittedAt === undefined ? {} : { submittedAt: latest.submittedAt }) };
+    }
+    const out: SyncResource[] = [{ type: 'pull_request', id: p.id, fields, ...(p.updatedAt === undefined ? {} : { occurredAt: p.updatedAt }) }];
+    for (const r of p.reviews ?? []) {
+      // No review id, no subject: an id minted from a position would move under the next
+      // review and thread a consumer's feed onto the wrong conversation.
+      if (r.id === undefined) continue;
+      const reviewFields: SyncResource['fields'] = { pr: p.number, repository: p.repository };
+      if (r.authorLogin !== undefined) reviewFields.authorLogin = r.authorLogin;
+      if (r.authorType !== undefined) reviewFields.authorType = r.authorType;
+      if (r.state !== undefined) reviewFields.state = r.state;
+      if (r.body !== undefined) reviewFields.body = r.body;
+      if (r.submittedAt !== undefined) reviewFields.submittedAt = r.submittedAt;
+      if (r.commitId !== undefined) reviewFields.commitId = r.commitId;
+      // The PHANTOM bucket says so on the wire. It holds inline comments nothing named a
+      // review for, so it has no state, no author and no verdict — and without this flag a
+      // consumer could not tell it from a real review whose fields simply had not arrived.
+      if (r.partial === true) reviewFields.partial = true;
+      // Always present, even empty: a review that later grows an inline comment is then a
+      // delta on THIS field rather than a field appearing from nowhere. SORTED BY ID, because
+      // the vendor is free to hand the same comments back in a different order and a
+      // reordered array is a field change — a delta on a conversation nobody touched.
+      reviewFields.comments = [...r.comments].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).map((c) => {
+        // EACH FINDING'S OWN AUTHOR rides with it, not the wrapping review's. A consumer
+        // grading a finding reads the FINDING's author: a scanner App's comment inside a
+        // human's review is a bot finding, and serving the wrapper's login called it a
+        // human's. The wrapper is the fallback only for a row that named nobody at all.
+        const authorLogin = c.authorLogin ?? r.authorLogin;
+        const authorType = c.authorType ?? r.authorType;
+        return {
+          id: c.id,
+          ...(authorLogin === undefined ? {} : { authorLogin }),
+          ...(authorType === undefined ? {} : { authorType }),
+          ...(c.path === undefined ? {} : { path: c.path }),
+          ...(c.line === undefined ? {} : { line: c.line }),
+          ...(c.body === undefined ? {} : { body: c.body }),
+          ...(c.inReplyTo === undefined ? {} : { inReplyTo: c.inReplyTo }),
+          ...(c.createdAt === undefined ? {} : { createdAt: c.createdAt }),
+        };
+      });
+      // WHEN it was said. A PENDING draft and the phantom bucket have no `submitted_at`, and
+      // with no occurredAt the delta falls back to the POLL clock — which dates a finding by
+      // when the poller happened to look. The earliest comment it carries is the closest
+      // thing the vendor actually told us about when this subject started existing.
+      const reviewAt = r.submittedAt ?? r.comments.map((c) => c.createdAt).filter((d): d is string => d !== undefined).sort()[0];
+      out.push({ type: 'review', id: `${p.id}:review:${r.id}`, fields: reviewFields, ...(reviewAt === undefined ? {} : { occurredAt: reviewAt }) });
+    }
+    for (const c of p.comments ?? []) {
+      if (c.id === undefined) continue; // same rule as a review: no id, no subject
+      const commentFields: SyncResource['fields'] = { pr: p.number, repository: p.repository };
+      if (c.authorLogin !== undefined) commentFields.authorLogin = c.authorLogin;
+      if (c.authorType !== undefined) commentFields.authorType = c.authorType;
+      if (c.body !== undefined) commentFields.body = c.body;
+      if (c.createdAt !== undefined) commentFields.createdAt = c.createdAt;
+      if (c.updatedAt !== undefined) commentFields.updatedAt = c.updatedAt;
+      // An EDIT moves `updated_at` and nothing else, so it dates the delta ahead of the
+      // moment the comment was first written.
+      const at = c.updatedAt ?? c.createdAt;
+      out.push({ type: 'issue_comment', id: `${p.id}:ic:${c.id}`, fields: commentFields, ...(at === undefined ? {} : { occurredAt: at }) });
+    }
+    return out;
   });
 }
 
+/**
+ * The `updated_at` this world last observed per PR — the budget's memory, read from the
+ * SHADOW (the fold of the world's own event log) rather than a cache beside it, so it
+ * survives a restart, is per-world like every other pulled fact, and cannot disagree with
+ * what was actually folded. A PR nobody has pulled yet is simply absent, and its
+ * conversation gets bought.
+ */
+export function lastObservedPrUpdates(root?: string): Record<string, string> {
+  const shadow = buildShadowState(SERVICE, () => null, root);
+  const out: Record<string, string> = {};
+  for (const subject of Object.values(shadow.subjects)) {
+    if (subject.subject.type !== 'pull_request') continue;
+    const updatedAt = subject.fields.updatedAt;
+    if (typeof updatedAt === 'string' && updatedAt !== '') out[subject.subject.id] = updatedAt;
+  }
+  return out;
+}
+
 // Map observed issues to SyncResource[] (content-bearing: title/body/state).
 export function observedIssuesToResources(issues: ObservedIssue[]): SyncResource[] {
   return issues.map((i) => {
@@ -259,6 +670,44 @@ export function observedIssuesToResources(issues: ObservedIssue[]): SyncResource
   });
 }
 
+/**
+ * A push this connector DECLINES to make, as opposed to one the vendor rejected. It is
+ * raised when enacting the local write faithfully is impossible — the only case today is a
+ * threaded reply whose root has no id on the real repo — and the alternative (posting it
+ * somewhere else, or forwarding a twin-minted id) would write the wrong thing to a real
+ * account. A refusal is ledgered and the sweep continues; the action stays PENDING, so it
+ * pushes on a later sweep once the root is known.
+ */
+export class GithubPushRefused extends Error {
+  constructor(message: string) {
+    super(`github push refused: ${message}`);
+    this.name = 'GithubPushRefused';
+  }
+}
+
+// The outcome of a tolerant append: whether a new event was written, and — when the
+// store already holds a DIVERGENT row under the same id — the stable id of the row that
+// conflicted. See `appendTolerant`.
+type AppendOutcome = { appended: boolean; conflictId?: string };
+
+// Append ONE folded event, tolerating a per-row `Conflicting duplicate` the way the slack
+// connector does (`slack-connector.ts` `fold`). `appendEventLocked` throws this when the
+// store already holds a row with the SAME id/idempotencyKey but DIVERGENT content — e.g.
+// a post-append line mutation raced the live writer (the peak-internal PH-216 incident).
+// That divergence is a single row's integrity question and says nothing about the other
+// resources in the same pull, so it must NOT abort the whole repo's fold: skip the row,
+// surface its stable id, keep folding. Every OTHER error stays fatal (re-thrown).
+function appendTolerant(event: WorldServiceEvent, root?: string): AppendOutcome {
+  try {
+    return { appended: appendEvent(event, root).appended };
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('Conflicting duplicate')) {
+      return { appended: false, conflictId: (event as unknown as { id: string }).id };
+    }
+    throw error;
+  }
+}
+
 // A content-hashed, deterministic id for a folded evidence snapshot — never random,
 // never Date.now. Re-folding the SAME observed evidence yields the same id, so
 // appendEvent dedups it (idempotent pull). A changed observation yields a new id.
@@ -277,7 +726,7 @@ function evidenceHash(parts: unknown[]): string {
 // top-level) and the CONTENT (title/body/state) the pull now mirrors. Idempotent via a
 // content hash in the event id + idempotencyKey: a re-pull of identical observation
 // appends nothing; a changed observation appends a new event.
-function foldObservedPr(pr: ObservedPr, occurredAt: string, root?: string): boolean {
+function foldObservedPr(pr: ObservedPr, occurredAt: string, root?: string): AppendOutcome {
   const data: Record<string, unknown> = {
     number: pr.number,
     repository: pr.repository,
@@ -310,15 +759,16 @@ function foldObservedPr(pr: ObservedPr, occurredAt: string, root?: string): bool
     subject: { type: 'pull_request', id: pr.id },
     data,
   } as unknown as WorldServiceEvent;
-  return appendEvent(event, root).appended;
+  return appendTolerant(event, root);
 }
 
 // Fold each review/comment as its own event, now CARRYING CONTENT (review state/body,
 // comment body) — githubState() reads these to derive review_count/comment_count AND to
 // surface the real text. The event id hashes the content so a changed body re-folds and
 // an unchanged one is idempotent (a deterministic id per (pr, kind, index, content)).
-function foldObservedExistence(pr: ObservedPr, occurredAt: string, root?: string): number {
+function foldObservedExistence(pr: ObservedPr, occurredAt: string, root?: string): { appended: number; conflictIds: string[] } {
   let appended = 0;
+  const conflictIds: string[] = [];
   const emit = (type: string, key: string, extra: Record<string, unknown>): void => {
     const hash = evidenceHash([type, key, extra]);
     const id = `github:${type}:${pr.id}:${key}:${hash}`;
@@ -334,24 +784,65 @@ function foldObservedExistence(pr: ObservedPr, occurredAt: string, root?: string
       subject: { type, id: `${pr.id}:${key}` },
       data: { repository: pr.repository, number: pr.number, ...extra },
     } as unknown as WorldServiceEvent;
-    if (appendEvent(event, root).appended) appended += 1;
+    const outcome = appendTolerant(event, root);
+    if (outcome.appended) appended += 1;
+    else if (outcome.conflictId !== undefined) conflictIds.push(outcome.conflictId);
   };
-  pr.reviews.forEach((r, i) => emit('pull_request_review', `rev${i}`, {
-    ...(r.state !== undefined ? { state: r.state } : {}),
-    ...(r.body !== undefined ? { body: r.body } : {}),
-    ...(r.submittedAt !== undefined ? { submitted_at: r.submittedAt } : {}),
-  }));
-  pr.comments.forEach((c, i) => emit('issue_comment', `c${i}`, {
+  // A PR whose conversation the budget did not buy emits nothing here: the events already
+  // in the log stand, and githubState keeps counting them. `reviews`/`comments` are absent
+  // in that case, NOT empty — the difference is exactly "unknown" versus "none".
+  if (!pr.detailsFetched) return { appended, conflictIds };
+  // The review's key is the VENDOR's review id, not its index on the page: an index moves
+  // when a review is deleted, which re-keys every later review onto a subject that already
+  // means something else. The inline comments it wrapped name that same key, so the join
+  // the pull made survives into the twin's own state.
+  (pr.reviews ?? []).forEach((r, i) => {
+    const key = r.id === undefined ? `rev${i}` : `rev:${r.id}`;
+    emit('pull_request_review', key, {
+      ...(r.state !== undefined ? { state: r.state } : {}),
+      ...(r.body !== undefined ? { body: r.body } : {}),
+      ...(r.submittedAt !== undefined ? { submitted_at: r.submittedAt } : {}),
+      ...(r.authorLogin !== undefined ? { user_login: r.authorLogin } : {}),
+      ...(r.authorType !== undefined ? { user_type: r.authorType === 'bot' ? 'Bot' : 'User' } : {}),
+    });
+    // THE INLINE COMMENTS REACH THE TWIN'S OWN STATE. The pull bought them and the census
+    // claims `pull_request_review_comment` is pulled, but nothing was emitted for them — so
+    // `GET /pulls/:n/comments` on the twin answered [] for a PR whose findings the pull was
+    // holding. Each rides its own subject, keyed by the vendor's comment id, carrying its
+    // anchor, its thread position, and the review that wraps it.
+    for (const c of r.comments) {
+      // WHO WROTE THE FINDING is the comment's own `user`, not the review's. The review is
+      // the join (`pull_request_review_id`), never the byline: a scanner App's comment can
+      // ride a review a human submitted, and emitting the wrapper's login served that bot
+      // finding to the twin as the human's. The wrapper is the fallback ONLY when the
+      // comment row named nobody (`user: null`), and when neither names anyone the twin
+      // serves no author rather than guessing one.
+      const userLogin = c.authorLogin ?? r.authorLogin;
+      const userType = c.authorType ?? r.authorType;
+      emit('pull_request_review_comment', `rc:${c.id}`, {
+        external_id: c.id,
+        review_key: `${pr.id}:${key}`,
+        ...(c.body !== undefined ? { body: c.body } : {}),
+        ...(c.createdAt !== undefined ? { created_at: c.createdAt } : {}),
+        ...(c.path !== undefined ? { path: c.path } : {}),
+        ...(c.line !== undefined ? { line: c.line } : {}),
+        ...(c.inReplyTo !== undefined ? { in_reply_to: `${pr.id}:rc:${c.inReplyTo}` } : {}),
+        ...(userLogin !== undefined ? { user_login: userLogin } : {}),
+        ...(userType !== undefined ? { user_type: userType === 'bot' ? 'Bot' : 'User' } : {}),
+      });
+    }
+  });
+  (pr.comments ?? []).forEach((c, i) => emit('issue_comment', `c${i}`, {
     ...(c.body !== undefined ? { body: c.body } : {}),
     ...(c.createdAt !== undefined ? { created_at: c.createdAt } : {}),
   }));
-  return appended;
+  return { appended, conflictIds };
 }
 
 // Fold ONE observed issue as a `github.issue` event carrying its content (title/body/
 // state). githubState()'s observed fold reads these into a first-class issue. Idempotent
 // via a content hash in the id: a re-pull of identical content appends nothing.
-function foldObservedIssue(iss: ObservedIssue, occurredAt: string, root?: string): boolean {
+function foldObservedIssue(iss: ObservedIssue, occurredAt: string, root?: string): AppendOutcome {
   const data: Record<string, unknown> = { number: iss.number, repository: iss.repository };
   if (iss.title !== undefined) data.title = iss.title;
   if (iss.body !== undefined) data.body = iss.body;
@@ -370,7 +861,7 @@ function foldObservedIssue(iss: ObservedIssue, occurredAt: string, root?: string
     subject: { type: 'issue', id: iss.id },
     data,
   } as unknown as WorldServiceEvent;
-  return appendEvent(event, root).appended;
+  return appendTolerant(event, root);
 }
 
 /**
@@ -381,36 +872,62 @@ function foldObservedIssue(iss: ObservedIssue, occurredAt: string, root?: string
  * shadow-diff dedup path is exercised (the Linear/Slack-shared contract); the github fold
  * carries the counts/content the generic delta path drops. PRs and issues share ONE
  * per-repo number space (real GitHub). Re-pulling identical observations appends nothing.
+ *
+ * Per-row conflict tolerance: if a stored event has DIVERGED from what a resource now
+ * folds to (a `Conflicting duplicate` — e.g. a post-append line mutation raced the live
+ * writer), that ONE row is skipped and its stable id recorded, rather than aborting the
+ * whole repo's fold — one row's integrity question must not become a total observation
+ * outage for the ~dozens of other resources in the same pull (peak-internal PH-216). The
+ * result exposes `conflictsSkipped` + `conflictingIds` so a poller can log the integrity
+ * problem loudly instead of it being swallowed. Every OTHER append error stays fatal.
  */
 export async function syncGithubFromReal(
   execute: GithubExecute,
   opts: { owner: string; repo: string; root?: string; occurredAt: string; state?: 'open' | 'closed' | 'all'; perPage?: number },
-): Promise<{ observed: number; deltasAppended: number; eventsAppended: number; issues: number }> {
+): Promise<{ observed: number; deltasAppended: number; eventsAppended: number; issues: number; conflictsSkipped: number; conflictingIds: string[] }> {
   const pullOpts = {
     owner: opts.owner,
     repo: opts.repo,
     ...(opts.state ? { state: opts.state } : {}),
     ...(opts.perPage ? { perPage: opts.perPage } : {}),
   };
-  const prs = await pullGithubPrs(execute, pullOpts);
+  // The budget's memory rides the world, not the process: the shadow already holds the
+  // `updated_at` of every PR this world has folded, so a poller restarted between two pulls
+  // still declines to re-buy a conversation nothing has touched.
+  const prs = await pullGithubPrs(execute, { ...pullOpts, lastUpdatedAt: lastObservedPrUpdates(opts.root) });
   const issues = await pullGithubIssues(execute, pullOpts);
   // Generic shadow-diff fold (content-bearing resources: title/body/state + refs).
   const pull = syncPull({
     service: SERVICE,
-    resources: [...observedPrsToResources(prs), ...observedIssuesToResources(issues)],
+    resources: [...observedPrsToResources(prs), ...observedIssuesToResources(issues), ...(await observeRepositoryAndBranches(execute, opts.owner, opts.repo))],
     occurredAt: opts.occurredAt,
     ...(opts.root !== undefined ? { root: opts.root } : {}),
   });
   // GitHub fold (carries counts + review/comment content the delta drops, plus issues).
+  // A per-row `Conflicting duplicate` is tolerated (skipped + recorded), never fatal, so a
+  // single diverged row can't stop later resources in the same pull from folding.
   let eventsAppended = 0;
+  let conflictsSkipped = 0;
+  const conflictingIds: string[] = [];
+  const recordConflict = (id: string | undefined): void => {
+    if (id === undefined) return;
+    conflictsSkipped += 1;
+    conflictingIds.push(id);
+  };
   for (const pr of prs) {
-    if (foldObservedPr(pr, opts.occurredAt, opts.root)) eventsAppended += 1;
-    eventsAppended += foldObservedExistence(pr, opts.occurredAt, opts.root);
+    const prOutcome = foldObservedPr(pr, opts.occurredAt, opts.root);
+    if (prOutcome.appended) eventsAppended += 1;
+    else recordConflict(prOutcome.conflictId);
+    const existence = foldObservedExistence(pr, opts.occurredAt, opts.root);
+    eventsAppended += existence.appended;
+    for (const id of existence.conflictIds) recordConflict(id);
   }
   for (const iss of issues) {
-    if (foldObservedIssue(iss, opts.occurredAt, opts.root)) eventsAppended += 1;
+    const issOutcome = foldObservedIssue(iss, opts.occurredAt, opts.root);
+    if (issOutcome.appended) eventsAppended += 1;
+    else recordConflict(issOutcome.conflictId);
   }
-  return { observed: pull.observed, deltasAppended: pull.deltasAppended, eventsAppended, issues: issues.length };
+  return { observed: pull.observed, deltasAppended: pull.deltasAppended, eventsAppended, issues: issues.length, conflictsSkipped, conflictingIds };
 }
 
 // ---------------------------------------------------------------------------
@@ -448,6 +965,11 @@ export async function syncGithubFromReal(
 export async function pushGithubAction(
   execute: GithubExecute,
   action: { operation?: string; subject: { type: string; id: string }; fields?: Record<string, unknown> },
+  opts: {
+    /** Twin comment id → the id that row has on the REAL repo (pulled from GitHub, or
+     *  returned by an earlier push in this sweep). A reply resolves its root here. */
+    externalIds?: Record<string, string>;
+  } = {},
 ): Promise<{ externalId: string }> {
   const f = action.fields ?? {};
   const repository = String(f.repository ?? action.subject.id.split('#')[0]);
@@ -459,8 +981,9 @@ export async function pushGithubAction(
   };
 
   if (op === 'pull_request.create') {
+    // A draft stays a draft on the remote: the flag rides the create.
     const res = await execute.request('POST /repos/{owner}/{repo}/pulls', {
-      owner, repo, title: f.title, body: f.body, head: f.head_sha, base: f.base_ref,
+      owner, repo, title: f.title, body: f.body, head: f.head_ref ?? f.head_sha, base: f.base_ref, ...(f.draft === undefined ? {} : { draft: Boolean(f.draft) }),
     });
     ensureOk(res, 'pulls.create');
     return { externalId: String(res.data?.number ?? '') };
@@ -527,6 +1050,24 @@ export async function pushGithubAction(
   }
   if (op === 'pull_request_review_comment.create') {
     const number = Number(f.number);
+    // A REPLY IS NOT A NEW ROOT COMMENT. `in_reply_to` says the local write answered an
+    // existing thread; POSTing it to `.../pulls/{n}/comments` started a SECOND thread on the
+    // real repo, unanchored to the finding it was answering. GitHub has a dedicated reply
+    // route, and it addresses the root by the VENDOR's comment id — which is never the id the
+    // twin minted for its own storage. Forwarding a minted id raw is how a push lands on a
+    // stranger's row (the groq incident, §9), so the root is resolved through the known
+    // external ids and the push REFUSES when there is no answer.
+    if (f.in_reply_to !== undefined && f.in_reply_to !== null) {
+      const rootKey = String(f.in_reply_to);
+      const rootExternal = opts.externalIds?.[rootKey];
+      if (rootExternal === undefined || rootExternal === '') {
+        throw new GithubPushRefused(`reply to comment ${rootKey}: the root comment has no known GitHub id (it was never pushed or pulled), and the twin's own id is not addressable on the real repo`);
+      }
+      const replyParams: Record<string, unknown> = { owner, repo, pull_number: number, comment_id: rootExternal, body: f.body };
+      const res = await execute.request('POST /repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies', replyParams);
+      ensureOk(res, 'pulls.review_comment.reply');
+      return { externalId: String(res.data?.id ?? '') };
+    }
     const params: Record<string, unknown> = {
       owner, repo, pull_number: number, body: f.body,
     };
@@ -536,7 +1077,11 @@ export async function pushGithubAction(
     if (f.line !== undefined) params.line = f.line;
     if (f.side !== undefined) params.side = f.side;
     if (f.start_line !== undefined) params.start_line = f.start_line;
-    if (f.head_sha !== undefined) params.commit_id = f.head_sha;
+    // GitHub REFUSES a diff-anchored comment without the commit it anchors to. The local
+    // write carries the PR head it was authored against; fall back to the PR's head sha so an
+    // anchored comment authored without one is not rejected at the vendor.
+    const commitId = f.head_sha ?? f.commit_id;
+    if (commitId !== undefined) params.commit_id = commitId;
     const res = await execute.request('POST /repos/{owner}/{repo}/pulls/{pull_number}/comments', params);
     ensureOk(res, 'pulls.review_comment.create');
     return { externalId: String(res.data?.id ?? '') };
@@ -610,9 +1155,71 @@ export async function pushGithubAction(
     ensureOk(res, 'milestones.update');
     return { externalId: String(res.data?.number ?? number) };
   }
+  // A repository the working copy declared: reality already holds it (the link names it) —
+  // it is confirmed as-is, and created only where it truly is absent.
+  if (op === 'repository.create') {
+    // The record names owner and name as fields (its subject is a sequence id, not a slug).
+    const repoOwner = String(f.owner ?? owner);
+    const repoName = String(f.name ?? repo);
+    const probe = await execute.request('GET /repos/{owner}/{repo}', { owner: repoOwner, repo: repoName }).catch(() => undefined);
+    if (probe !== undefined && probe.status < 300) return { externalId: `${repoOwner}/${repoName}` };
+    const res = await execute.request('POST /orgs/{org}/repos', { org: repoOwner, name: repoName, ...(f.private === undefined ? {} : { private: f.private }), ...(f.default_branch === undefined ? {} : { default_branch: f.default_branch }) });
+    ensureOk(res, 'repos.create');
+    return { externalId: `${repoOwner}/${repoName}` };
+  }
+  // THE BRANCH AND ITS FILES cross too (an API-plane implementation: a seat that writes through
+  // the Contents API, never git). A ref that already exists on the remote is the same ref.
+  const alreadyThere = (e: unknown): boolean => /already exists/iu.test(e instanceof Error ? e.message : String(e));
+  if (op === 'git_ref.create' || op === 'branch.create') {
+    const ref = op === 'git_ref.create' ? String(f.ref) : `refs/heads/${String(f.name)}`;
+    const sha = String(op === 'git_ref.create' ? f.object_sha : f.commit_sha);
+    try {
+      const res = await execute.request('POST /repos/{owner}/{repo}/git/refs', { owner, repo, ref, sha });
+      ensureOk(res, 'git.refs.create');
+    } catch (e) {
+      if (!alreadyThere(e)) throw e;
+    }
+    return { externalId: ref };
+  }
+  if (op === 'content_file.create' || op === 'content_file.update' || op === 'content_file.delete') {
+    const path = String(f.path);
+    const branch = f.branch === undefined ? undefined : String(f.branch);
+    // GitHub demands the current blob sha to update or delete; the remote is asked, not guessed.
+    let currentSha: string | undefined;
+    try {
+      const current = await execute.request('GET /repos/{owner}/{repo}/contents/{path}', { owner, repo, path, ...(branch === undefined ? {} : { ref: branch }) });
+      const data = current.data as { sha?: unknown } | undefined;
+      if (typeof data?.sha === 'string') currentSha = data.sha;
+    } catch {
+      currentSha = undefined;
+    }
+    if (op === 'content_file.delete') {
+      const res = await execute.request('DELETE /repos/{owner}/{repo}/contents/{path}', { owner, repo, path, message: `Delete ${path}`, ...(currentSha === undefined ? {} : { sha: currentSha }), ...(branch === undefined ? {} : { branch }) });
+      ensureOk(res, 'contents.delete');
+      return { externalId: path };
+    }
+    const res = await execute.request('PUT /repos/{owner}/{repo}/contents/{path}', { owner, repo, path, message: `${op === 'content_file.create' ? 'Add' : 'Update'} ${path}`, content: String(f.content_b64 ?? ''), ...(currentSha === undefined ? {} : { sha: currentSha }), ...(branch === undefined ? {} : { branch }) });
+    ensureOk(res, 'contents.put');
+    const data = res.data as { content?: { sha?: unknown } } | undefined;
+    return { externalId: typeof data?.content?.sha === 'string' ? data.content.sha : path };
+  }
   throw new Error(`github push: unsupported operation "${op}" for subject ${action.subject.type}`);
 }
 
+/**
+ * The REAL-GitHub id of every review comment this world can address: the vendor id a PULL
+ * observed for it. A locally-minted comment id means nothing on the real repo, so this is
+ * what a threaded reply resolves its root through — and a root that is absent here is a
+ * root the push must refuse rather than guess at.
+ */
+function knownReviewCommentExternalIds(root?: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const c of githubState(root).comments) {
+    if (c.kind === 'review' && c.external_id !== undefined && c.external_id !== '') out[String(c.id)] = c.external_id;
+  }
+  return out;
+}
+
 /**
  * PUSH (all): push every pending LOCAL GitHub action to real GitHub via the injected
  * executor and CONFIRM each on success — `confirmAction` records the confirmed fields
@@ -620,15 +1227,32 @@ export async function pushGithubAction(
  * projection (the fact now lives in the observed log; counted exactly once). Closes
  * the action → push → observed loop (R18). Idempotency: a confirmed action is no
  * longer pending, so a re-push calls the executor for it again ZERO times.
+ *
+ * PER-ACTION TOLERANCE, the same doctrine the pull's per-row conflict skip follows: one
+ * action the connector cannot enact (a reply whose root has no id on the real repo) or that
+ * the vendor rejected must NOT abort the other pending writes in the sweep — it is skipped
+ * with its reason, left PENDING so a later sweep retries it, and REPORTED in `skipped` so a
+ * poller can log it loudly instead of it being swallowed. Nothing is confirmed on a failure,
+ * so a skipped action is never mistaken for a written one.
  */
 export async function pushPendingGithubActions(
   execute: GithubExecute,
   opts: { root?: string; occurredAt: string },
-): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
+): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string>; skipped: Array<{ actionId: string; operation: string; reason: string }> }> {
   const confirmed: string[] = [];
   const externalIds: Record<string, string> = {};
+  const skipped: Array<{ actionId: string; operation: string; reason: string }> = [];
+  // Seeded from what the world already knows, then GROWN as the sweep confirms writes — a
+  // root comment created and replied to between two pushes resolves within one sweep.
+  const commentExternalIds = knownReviewCommentExternalIds(opts.root);
   for (const action of pendingActions(SERVICE, opts.root)) {
-    const { externalId } = await pushGithubAction(execute, action);
+    let externalId: string;
+    try {
+      ({ externalId } = await pushGithubAction(execute, action, { externalIds: commentExternalIds }));
+    } catch (error) {
+      skipped.push({ actionId: action.id, operation: action.operation ?? '', reason: error instanceof Error ? error.message : String(error) });
+      continue;
+    }
     confirmAction({
       service: SERVICE,
       actionId: action.id,
@@ -639,6 +1263,153 @@ export async function pushPendingGithubActions(
     });
     confirmed.push(action.id);
     externalIds[action.id] = externalId;
+    // A review comment the vendor just accepted is now addressable, so a reply LATER in this
+    // same sweep can name it. Keyed by the twin's own comment id, which is what the reply's
+    // `in_reply_to` carries.
+    const local = /^comment:(\d+)$/.exec(action.subject.id);
+    if (local !== null && action.operation === 'pull_request_review_comment.create' && externalId !== '') commentExternalIds[local[1]!] = externalId;
   }
-  return { pushed: confirmed.length, confirmed, externalIds };
+  return { pushed: confirmed.length, confirmed, externalIds, skipped };
+}
+
+/**
+ * THE R14 PUSH ADAPTER for github (jira's `pushJiraToRemote` is the reference; this
+ * transcribes its METHOD): pending local actions cross to the remote through the kernel's
+ * ONE RemoteExecute seam under a sealed credential the pack never sees, and each pushed
+ * action is confirmed in the local log. Anchored naming: `createGithubTwinFetch` pairs
+ * with `syncGithubFromRemote` and `pushGithubToRemote`. Push-plane only — a read refuses
+ * loudly. The route grammar is the one `pushGithubAction` speaks (`METHOD /path/{param}`,
+ * templated params in the path, the rest as the JSON body).
+ */
+export async function pushGithubToRemote(
+  execute: RemoteExecute,
+  opts: { root?: string; origin?: string } = {},
+): Promise<{ pushed: number; confirmed: string[]; skipped: Array<{ actionId: string; operation: string; reason: string }> }> {
+  const executor: GithubExecute = {
+    async request(route, params = {}) {
+      const sp = route.indexOf(' ');
+      const method = route.slice(0, sp);
+      // The push plane writes; the one read it makes is the current blob sha a Contents write
+      // needs (GitHub refuses an update without it) — a read that serves the push, never a pull.
+      let path = route.slice(sp + 1);
+      const body: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(params)) {
+        const token = `{${key}}`;
+        if (path.includes(token)) path = path.replace(token, encodeURIComponent(String(value)));
+        else if (value !== undefined) body[key] = value;
+      }
+      const read = method === 'GET' || method === 'HEAD';
+      if (read && Object.keys(body).length > 0) {
+        const qs = new URLSearchParams();
+        for (const [key, value] of Object.entries(body)) qs.set(key, String(value));
+        path += `${path.includes('?') ? '&' : '?'}${qs.toString()}`;
+      }
+      const res = await execute({
+        method,
+        path,
+        headers: { accept: 'application/vnd.github+json', 'user-agent': 'volter-twin-push', ...(read ? {} : { 'content-type': 'application/json' }) },
+        ...(read ? {} : { body: JSON.stringify(body) }),
+      });
+      // The vendor's own words ride the error: push health on the link must say WHY reality
+      // refused (a bare status is a guess), bounded so a page never lands in a ledger.
+      if (res.status >= 300) throw new Error(`github remote push: ${route} answered ${res.status}${res.body === '' ? '' : ` — ${res.body.slice(0, 300)}`}`);
+      return { status: res.status, data: res.body === '' ? undefined : JSON.parse(res.body) };
+    },
+  };
+  const pushed = await pushPendingGithubActions(executor, { ...(opts.root === undefined ? {} : { root: opts.root }), occurredAt: new Date().toISOString() });
+  // The refusals ride out with the successes: a link that pushed nothing because every action
+  // was refused must not read as a clean sweep.
+  return { pushed: pushed.pushed, confirmed: pushed.confirmed, skipped: pushed.skipped };
+}
+
+/**
+ * THE REPOSITORY AND ITS BRANCHES are observed with the PRs and issues: a working copy's
+ * confirmed writes (a branch it cut, the repo it declared) survive only as what reality
+ * shows back, so the pull says what reality holds — the repo and every branch head.
+ */
+export async function observeRepositoryAndBranches(execute: GithubExecute, owner: string, repo: string): Promise<SyncResource[]> {
+  const full = `${owner}/${repo}`;
+  const out: SyncResource[] = [];
+  const repoRes = await execute.request('GET /repos/{owner}/{repo}', { owner, repo }).catch(() => undefined);
+  const r = repoRes?.data as { default_branch?: unknown; private?: unknown; description?: unknown } | undefined;
+  if (repoRes !== undefined && repoRes.status < 300 && r !== undefined) {
+    out.push({ type: 'repository', id: `repo:${full}`, fields: { owner, name: repo, full_name: full, default_branch: String(r.default_branch ?? 'main'), private: r.private === true, description: r.description ?? null } });
+  }
+  const branchesRes = await execute.request('GET /repos/{owner}/{repo}/branches', { owner, repo, per_page: 100 }).catch(() => undefined);
+  const list = Array.isArray(branchesRes?.data) ? (branchesRes!.data as Array<{ name?: unknown; commit?: { sha?: unknown } }>) : [];
+  for (const b of list) {
+    if (typeof b.name !== 'string') continue;
+    out.push({ type: 'branch', id: `branch:${full}#${b.name}`, fields: { repository: full, name: b.name, commit_sha: String(b.commit?.sha ?? '') } });
+  }
+  return out;
+}
+
+/**
+ * THE R14 SCHEDULED-PULL ADAPTER (jira is the reference; this transcribes its METHOD):
+ * adapts this pack's executor onto the kernel's ONE RemoteExecute seam, so the twins
+ * service can schedule pulls with a sealed credential the pack never sees. Anchored
+ * naming: `createGithubTwinFetch` pairs with `syncGithubFromRemote`.
+ *
+ * The link's origin names the REPO, not just the API host — a link is a git remote:
+ *   https://api.github.com/repos/{owner}/{repo}
+ * Egress still anchors at the origin's HOST (the service's RemoteExecute discards the
+ * path when routing), so the path here is pure identity. Pull-plane only — every
+ * non-read request refuses loudly.
+ *
+ * Rate note, counted over the routes this pull actually calls: 2 list reads (the repo and
+ * its branches) + 1 PR list + 1 issue list, and then, per PR whose `updated_at` MOVED since
+ * the last pull, three PAGED conversation reads — the reviews, the issue comments and the
+ * inline comments — at 1 request each for a PR under 100 rows and up to 10 each beyond
+ * that. So a poll costs 4 + 3·CHANGED at the floor and 4 + 30·CHANGED at the ceiling; an
+ * unchanged PR costs nothing beyond the list. The link's sync interval still carries the
+ * budget — 60s at the default page floods a PAT's 5000/hr the first time it walks a busy
+ * repo; schedule github links at ≥120s.
+ */
+export async function syncGithubFromRemote(
+  execute: RemoteExecute,
+  opts: { root?: string; origin?: string; state?: 'open' | 'closed' | 'all'; perPage?: number } = {},
+): Promise<{ observed: number; deltasAppended: number; eventsAppended: number; issues: number; conflictsSkipped: number; conflictingIds: string[] }> {
+  const match = /^\/repos\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(opts.origin === undefined ? '' : new URL(opts.origin).pathname);
+  if (match === null) {
+    throw new Error('github remote pull: the link origin must name the repo — https://api.github.com/repos/{owner}/{repo}');
+  }
+  const [, owner, repo] = match as unknown as [string, string, string];
+  const executor: GithubExecute = {
+    async request(route, params = {}) {
+      const sp = route.indexOf(' ');
+      const method = route.slice(0, sp);
+      if (method !== 'GET' && method !== 'HEAD') {
+        throw new Error(`syncGithubFromRemote is the PULL plane: ${route} is a push-side operation and never runs here`);
+      }
+      // Same route grammar liveGithubExecute speaks: substitute {param} templates,
+      // remaining params become the query string (a read has no body).
+      let path = route.slice(sp + 1);
+      const rest: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(params)) {
+        const token = `{${key}}`;
+        if (path.includes(token)) path = path.replace(token, encodeURIComponent(String(value)));
+        else rest[key] = value;
+      }
+      if (Object.keys(rest).length > 0) {
+        const qs = new URLSearchParams();
+        for (const [key, value] of Object.entries(rest)) qs.set(key, String(value));
+        path += `${path.includes('?') ? '&' : '?'}${qs.toString()}`;
+      }
+      // GitHub answers 403 to any request without a User-Agent (its documented rule);
+      // workerd's fetch sends none, so the adapter names itself.
+      const res = await execute({ method, path, headers: { accept: 'application/vnd.github+json', 'user-agent': 'volter-twin-pull' } });
+      if (res.status >= 300) throw new Error(`github remote pull: ${route} answered ${res.status}`);
+      return { status: res.status, data: res.body === '' ? undefined : JSON.parse(res.body) };
+    },
+  };
+  // The pull plane's instant is observation time — fetch metadata, never served content
+  // (R9 governs the serve path; this is the freshness half of the git model). `all`
+  // because the merge IS the observation that ends a job — closed PRs must fold.
+  return await syncGithubFromReal(executor, {
+    owner, repo,
+    occurredAt: new Date().toISOString(),
+    state: opts.state ?? 'all',
+    perPage: opts.perPage ?? 20,
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+  });
 }