@volter/twin-github 0.1.0 → 0.1.1

package/src/github-twin.ts

@@ -10,12 +10,56 @@
 // declared scope rather than fabricated. The shapes match GitHub's REST objects (R1).
 import { createHash } from 'node:crypto';
 import { applyTwinWrite, isEgressEventType, listEvents, pendingActions } from '@volter/twin';
+// The REAL git plane (bare repos + spawned git — see github-git-plane.ts). Git Data writes
+// materialize REAL objects there (real shas); reads fall back to it for objects that only
+// exist in the plane (a `git push` via smart HTTP); ref writes materialize whenever the
+// target object exists. One object store, not two.
+import {
+  deleteBareRepo, deleteGitRefInPlane, diffFilesInPlane, ensureBareRepo, forkBareRepo,
+  isAncestorInPlane, isValidBranchName, listGitPlaneRefs, mergeIntoBranchInPlane, objectExistsInPlane, objectTypeInPlane,
+  readGitBlobFromPlane, readGitCommitFromPlane, readGitTagFromPlane, readGitTreeFromPlane,
+  setBareRepoHead, updateGitRefInPlane, writeGitBlobToPlane, writeGitCommitToPlane, writeGitTagToPlane, writeGitTreeToPlane,
+} from './github-git-plane.ts';
 
 const SERVICE = 'github';
 
 // Deterministic 40-hex merge-commit sha derived from repo+number — NEVER random
 // (repo forbids Math.random/Date.now in non-runtime code). Stable per repo+number,
 // and a PR can only merge once (a second attempt 405s), so this is unique per merge.
+// ── Landing a pull request: the gates, then the merge ───────────────────────────────────────
+// The base branch's protection names required status checks; each must be a successful check run or
+// commit status on the pull request's head sha (real GitHub: 405 "Required status check … is expected.").
+function requiredChecksMissing(st: GithubState, repo: string, baseRef: string, headSha: string): string[] {
+  const branch = st.branches.find((b) => b.repository === repo && b.name === baseRef);
+  const contexts = branch?.protection_config?.required_status_checks?.contexts ?? [];
+  return contexts.filter((ctx) =>
+    !st.checkRuns.some((c) => c.repository === repo && c.head_sha === headSha && c.name === ctx && c.conclusion === 'success')
+    && !st.statuses.some((c) => c.repository === repo && c.sha === headSha && c.context === ctx && c.state === 'success'));
+}
+// Merge = the gates, then a REAL merge commit on the git plane when the repository has one (main moves
+// on the git wire, as it does on GitHub — a REST merge that left the clone behind was a fake success),
+// then the pull request folded closed+merged. Without a plane the merge sha is the deterministic one.
+async function mergePullRequest(repo: string, pr: GithubPr, method: 'merge' | 'squash' | 'rebase', occurredAt: string, root?: string): Promise<{ ok: true; sha: string } | { ok: false; status: number; message: string }> {
+  const missing = requiredChecksMissing(githubState(root), repo, pr.base_ref ?? 'main', pr.head_sha ?? '');
+  if (missing.length) return { ok: false, status: 405, message: `Required status check "${missing[0]}" is expected.` };
+  let sha = mergeCommitSha(repo, pr.number);
+  if (pr.head_sha) {
+    const landed = mergeIntoBranchInPlane(repo, pr.base_ref ?? 'main', pr.head_sha, `Merge pull request #${pr.number} from ${pr.head_ref ?? 'head'}\n\n${pr.title ?? ''}`, method, occurredAt, root);
+    if (landed && 'conflict' in landed) return { ok: false, status: 405, message: 'Pull Request is not mergeable' };
+    if (landed) sha = landed.sha;
+  }
+  const fields = { number: pr.number, repository: repo, state: 'closed', merged: true, merged_at: occurredAt, merge_commit_sha: sha, merge_method: method };
+  await applyTwinWrite(SERVICE, { operation: 'pull_request.merge', subjectType: 'pull_request', subjectId: pr.id, fields, occurredAt, actor: { kind: 'agent' } }, root);
+  return { ok: true, sha };
+}
+// Auto-merge: a pull request armed with a merge method lands the moment its required checks are all
+// green — evaluated when a check run or commit status on its head sha succeeds. A merge that still fails
+// a gate simply waits for the next signal, as on GitHub.
+async function landArmedPullRequests(repo: string, headSha: string, occurredAt: string, root?: string): Promise<void> {
+  const armed = githubState(root).prs.filter((p) => p.repository === repo && p.head_sha === headSha && p.state === 'open' && !p.merged && p.auto_merge_method);
+  for (const pr of armed) await mergePullRequest(repo, pr, (pr.auto_merge_method as 'merge' | 'squash' | 'rebase') ?? 'merge', occurredAt, root);
+}
+
 function mergeCommitSha(repo: string, number: number): string {
   return createHash('sha256').update(`${repo}#${number}`).digest('hex').slice(0, 40);
 }
@@ -30,6 +74,15 @@ export type GithubReview = {
   state?: string;
   body?: string;
   submitted_at?: string;
+  // The PR head sha the review was submitted AGAINST (real GitHub's `commit_id`) — the
+  // exact-head binding merge gates re-earn per push (a review's commit_id never moves).
+  commit_id?: string;
+  // WHO reviewed. A twin-authored review carries the twin's own writer login (`twin`); a
+  // PULLED one carries the login real GitHub named, with `user_type: 'Bot'` when GitHub
+  // said a machine wrote it. Absent = genuinely unknown (a legacy row, a deleted account),
+  // and the serve then answers `user: null` rather than inventing an account.
+  user_login?: string;
+  user_type?: 'User' | 'Bot';
 };
 // A review overlay (LOCAL) — a dismiss or a body-edit applied to an already-submitted review,
 // keyed by the review id. Overlaid onto the folded review array (last write per field wins).
@@ -54,6 +107,17 @@ export type GithubComment = {
   diff_hunk?: string;
   // in_reply_to: the root review-comment id this comment replies to (threaded review reply).
   in_reply_to?: number;
+  // THE REVIEW THAT WRAPS THIS COMMENT (real GitHub's `pull_request_review_id`). Every
+  // inline comment has one: the review it was submitted under, or the PR's implicit review
+  // when it was posted on its own (see `implicitReviewId`). It is the join a consumer does
+  // to read a review's findings, so it is served, never nulled.
+  review_id?: number;
+  // WHO wrote it — same rule as a review's (see GithubReview.user_login).
+  user_login?: string;
+  user_type?: 'User' | 'Bot';
+  // The REAL vendor id of this comment when the row came from real GitHub (pulled), so a
+  // push can address the vendor's own comment instead of forwarding a twin-minted id.
+  external_id?: string;
 };
 // A per-file diff carried on a LOCAL PR write (real GitHub's pull-request file object).
 // Observed PR evidence carries a changed-files COUNT only, never per-file diffs, so this
@@ -276,6 +340,16 @@ export type GithubBranch = {
   name: string;
   commit_sha: string;
   protected?: boolean;
+  // The PERSISTED classic branch-protection config (PUT .../protection body, normalized):
+  // required_status_checks {strict, contexts, checks}, enforce_admins, required_pull_request_reviews.
+  // This is what merge gates read back (required-check contexts, enforce_admins) — a
+  // protection PUT that forgets its own body is a fake success.
+  protection_config?: {
+    required_status_checks?: { strict: boolean; contexts: string[]; checks: Array<{ context: string; app_id: number | null }> } | null;
+    enforce_admins?: boolean;
+    required_pull_request_reviews?: Record<string, unknown> | null;
+    restrictions?: Record<string, unknown> | null;
+  };
 };
 // A repo collaborator (LOCAL). permission is GitHub's role enum (pull|triage|push|maintain|admin).
 export type GithubCollaborator = {
@@ -658,6 +732,9 @@ export function githubState(root?: string): GithubState {
   const deletedRepos = new Set<string>();
   const branchesById = new Map<string, GithubBranch>();
   const deletedBranches = new Set<string>();
+  // Protection survives a branch tombstone (GitHub's pattern-rule semantics) — keyed by the
+  // branch subject id, consumed (and cleared) by the next branch.create for that id.
+  const branchProtectionMemory = new Map<string, { protected?: boolean; protection_config?: GithubBranch['protection_config'] }>();
   const collaboratorsById = new Map<string, GithubCollaborator>();
   const deletedCollaborators = new Set<string>();
   const webhooksById = new Map<string, GithubWebhook>();
@@ -779,6 +856,35 @@ export function githubState(root?: string): GithubState {
     if (isEgressEventType(ev.type)) continue; // egress write intent/result are not GitHub objects
     const data = (ev.data ?? {}) as Record<string, any>;
     const t = ev.subject.type;
+    // A pulled field rides flat on first observation and under `changed.<field>.after` on a
+    // delta; read either.
+    const observed = (field: string): unknown => data[field] !== undefined ? data[field] : (data.changed as Record<string, { after?: unknown }> | undefined)?.[field]?.after;
+    if (t === 'repository') {
+      // The client's repository, as reality shows it (observeRepositoryAndBranches).
+      const prev = reposById.get(ev.subject.id);
+      const owner = String(observed('owner') ?? prev?.owner ?? ev.subject.id.replace(/^repo:/, '').split('/')[0] ?? '');
+      const name = String(observed('name') ?? prev?.name ?? ev.subject.id.replace(/^repo:/, '').split('/')[1] ?? '');
+      if (owner !== '' && name !== '') {
+        reposById.set(ev.subject.id, {
+          ...(prev ?? {}), id: prev?.id ?? reposById.size + 1, owner, name, full_name: `${owner}/${name}`,
+          description: observed('description') !== undefined ? (observed('description') as string | null) : prev?.description,
+          private: observed('private') !== undefined ? Boolean(observed('private')) : prev?.private,
+          default_branch: String(observed('default_branch') ?? prev?.default_branch ?? 'main'),
+        } as GithubRepo);
+        deletedRepos.delete(ev.subject.id);
+      }
+      continue;
+    }
+    if (t === 'branch') {
+      const prev = branchesById.get(ev.subject.id);
+      const repository = String(observed('repository') ?? prev?.repository ?? ev.subject.id.replace(/^branch:/, '').split('#')[0] ?? '');
+      const name = String(observed('name') ?? prev?.name ?? ev.subject.id.split('#').pop() ?? '');
+      if (repository !== '' && name !== '') {
+        branchesById.set(ev.subject.id, { ...(prev ?? {}), repository, name, commit_sha: String(observed('commit_sha') ?? prev?.commit_sha ?? '') } as GithubBranch);
+        deletedBranches.delete(ev.subject.id);
+      }
+      continue;
+    }
     if (t === 'pull_request') {
       const id = ev.subject.id;
       const number = Number(data.number ?? id.split('#').pop());
@@ -831,11 +937,27 @@ export function githubState(root?: string): GithubState {
         if (data.state !== undefined) review.state = String(data.state);
         if (data.body !== undefined && data.body !== null) review.body = String(data.body);
         if (data.submitted_at !== undefined) review.submitted_at = String(data.submitted_at);
+        // WHO reviewed, as the pull observed it — the login and the bot/human split real
+        // GitHub gave. Absent when the vendor named nobody (a deleted account).
+        if (data.user_login !== undefined && data.user_login !== null) review.user_login = String(data.user_login);
+        if (data.user_type === 'Bot' || data.user_type === 'User') review.user_type = data.user_type;
         reviews.push(review);
       } else {
         const comment: GithubComment = { id, repository, number, kind: t === 'pull_request_review_comment' ? 'review' : 'issue' };
         if (data.body !== undefined && data.body !== null) comment.body = String(data.body);
         if (data.created_at !== undefined) comment.created_at = String(data.created_at);
+        if (data.user_login !== undefined && data.user_login !== null) comment.user_login = String(data.user_login);
+        if (data.user_type === 'Bot' || data.user_type === 'User') comment.user_type = data.user_type;
+        // A PULLED inline comment carries its diff anchor and its thread position — the pull
+        // fetched all of it, so the twin serves all of it rather than dropping it on the floor.
+        if (data.path !== undefined && data.path !== null) comment.path = String(data.path);
+        if (data.line !== undefined && data.line !== null) comment.line = Number(data.line);
+        if (data.in_reply_to !== undefined && data.in_reply_to !== null) comment.in_reply_to = observedId(String(data.in_reply_to));
+        // THE JOIN, preserved across the fold: the pull names the review's own SUBJECT id,
+        // which hashes to the same twin-side review id the review row got.
+        if (data.review_key !== undefined && data.review_key !== null) comment.review_id = observedId(String(data.review_key));
+        // The vendor's real id, so a push can address the vendor's comment (never a minted id).
+        if (data.external_id !== undefined && data.external_id !== null) comment.external_id = String(data.external_id);
         comments.push(comment);
       }
     }
@@ -1061,7 +1183,17 @@ export function githubState(root?: string): GithubState {
         resolved: f.resolved !== undefined ? Boolean(f.resolved) : prev?.resolved,
       });
     } else if (a.subject.type === 'repository') {
-      if (a.operation === 'repository.delete') { deletedRepos.add(a.subject.id); continue; }
+      if (a.operation === 'repository.delete') {
+        deletedRepos.add(a.subject.id);
+        // Cascade: the repo's refs/branches die WITH it (the bare repo is removed too), so a
+        // re-created repo starts truly empty on BOTH planes — REST must not serve dead refs.
+        const dyingRepo = reposById.get(a.subject.id);
+        const dyingFull = dyingRepo ? `${dyingRepo.owner}/${dyingRepo.name}` : `${String(f.owner ?? '')}/${String(f.name ?? '')}`;
+        for (const [k, v] of [...gitRefsById]) if (v.repository === dyingFull) { gitRefsById.delete(k); deletedGitRefs.delete(k); }
+        for (const [k, v] of [...branchesById]) if (v.repository === dyingFull) { branchesById.delete(k); deletedBranches.delete(k); }
+        for (const k of [...branchProtectionMemory.keys()]) if (k.startsWith(`branch:${dyingFull}#`)) branchProtectionMemory.delete(k);
+        continue;
+      }
       const m = /^repo:(\d+)$/.exec(a.subject.id);
       const id = m ? Number(m[1]) : observedId(a.subject.id);
       const prev = reposById.get(a.subject.id);
@@ -1084,12 +1216,26 @@ export function githubState(root?: string): GithubState {
         created_at: f.created_at ?? prev?.created_at, updated_at: f.updated_at ?? prev?.updated_at,
       });
     } else if (a.subject.type === 'branch') {
-      if (a.operation === 'branch.delete') { deletedBranches.add(a.subject.id); continue; }
-      const prev = branchesById.get(a.subject.id);
+      if (a.operation === 'branch.delete') {
+        // The row dies, but PROTECTION does not: real GitHub's classic protection is a
+        // repo-level pattern rule, so deleting `main` and re-pushing it comes back
+        // protected. Remember the protection across the tombstone.
+        const dying = branchesById.get(a.subject.id);
+        if (dying && (dying.protected || dying.protection_config)) {
+          branchProtectionMemory.set(a.subject.id, { protected: dying.protected, protection_config: dying.protection_config });
+        }
+        deletedBranches.add(a.subject.id); branchesById.delete(a.subject.id); continue;
+      }
+      deletedBranches.delete(a.subject.id); // delete→re-create resurrects (see git_ref fold below)
+      const prev = branchesById.get(a.subject.id) ?? branchProtectionMemory.get(a.subject.id) as GithubBranch | undefined;
+      if (branchesById.get(a.subject.id) === undefined && branchProtectionMemory.has(a.subject.id)) branchProtectionMemory.delete(a.subject.id);
       branchesById.set(a.subject.id, {
         repository: String(f.repository ?? prev?.repository ?? ''), name: String(f.name ?? prev?.name ?? ''),
         commit_sha: String(f.commit_sha ?? prev?.commit_sha ?? ''),
         protected: f.protected !== undefined ? Boolean(f.protected) : prev?.protected,
+        ...(f.protection_config !== undefined
+          ? (f.protection_config === null ? {} : { protection_config: f.protection_config as GithubBranch['protection_config'] })
+          : (prev?.protection_config !== undefined ? { protection_config: prev.protection_config } : {})),
       });
     } else if (a.subject.type === 'collaborator') {
       if (a.operation === 'collaborator.remove') { deletedCollaborators.add(a.subject.id); continue; }
@@ -1141,7 +1287,8 @@ export function githubState(root?: string): GithubState {
         updated_at: f.updated_at ?? prev?.updated_at,
       });
     } else if (a.subject.type === 'git_ref') {
-      if (a.operation === 'git_ref.delete') { deletedGitRefs.add(a.subject.id); continue; }
+      if (a.operation === 'git_ref.delete') { deletedGitRefs.add(a.subject.id); gitRefsById.delete(a.subject.id); continue; }
+      deletedGitRefs.delete(a.subject.id); // a later create RESURRECTS a deleted ref (delete→re-push must not be tombstoned forever)
       const prev = gitRefsById.get(a.subject.id);
       gitRefsById.set(a.subject.id, {
         repository: String(f.repository ?? prev?.repository ?? ''), ref: String(f.ref ?? prev?.ref ?? ''),
@@ -1602,7 +1749,7 @@ export function githubState(root?: string): GithubState {
       if (!repository || !number) continue;
       ensure(`${repository}#${number}`, number, repository);
       const m = /^review:(\d+)$/.exec(a.subject.id);
-      reviews.push({ id: m ? Number(m[1]) : observedId(a.subject.id), repository, number, state: f.state, body: f.body, submitted_at: f.submitted_at });
+      reviews.push({ id: m ? Number(m[1]) : observedId(a.subject.id), repository, number, state: f.state, body: f.body, submitted_at: f.submitted_at, ...(f.commit_id !== undefined ? { commit_id: String(f.commit_id) } : {}), ...(f.user_login !== undefined ? { user_login: String(f.user_login) } : {}) });
     } else if (a.subject.type === 'pull_request_review_overlay') {
       // A dismiss / body-edit on a submitted review (keyed by review id). Overlaid below.
       const rid = Number(f.review_id ?? 0);
@@ -1627,6 +1774,10 @@ export function githubState(root?: string): GithubState {
       if (f.start_line !== undefined) comment.start_line = Number(f.start_line);
       if (f.diff_hunk !== undefined) comment.diff_hunk = String(f.diff_hunk);
       if (f.in_reply_to !== undefined) comment.in_reply_to = Number(f.in_reply_to);
+      // The review this comment was submitted under (an explicit one when the write named it,
+      // otherwise the PR's implicit review) and WHO wrote it — both recorded at write time.
+      if (f.review_id !== undefined) comment.review_id = Number(f.review_id);
+      if (f.user_login !== undefined) comment.user_login = String(f.user_login);
       comments.push(comment);
     }
   }
@@ -1639,6 +1790,20 @@ export function githubState(root?: string): GithubState {
   }
   // Derive the evidence counts the _twin block still reports from the folded objects.
   for (const r of reviews) ensure(`${r.repository}#${r.number}`, r.number, r.repository).review_count += 1;
+  // THE IMPLICIT REVIEW IS ONE OF THEM. `GET /pulls/:n/reviews` synthesizes the wrapper from
+  // the comments that name it and SERVES it, exactly as real GitHub does — and real GitHub
+  // counts it. The count read only the STORED rows, so a PR whose reviews page answers one
+  // review reported `review_count: 0` and the mirror rendered "Review count 0" over it. The
+  // condition here is the handler's, verbatim, so the count and the list can never describe
+  // different populations: one wrapper per PR that has at least one comment naming it.
+  const wrappedPrs = new Set<string>();
+  for (const c of comments) {
+    if (c.kind !== 'review' || c.review_id !== implicitReviewId(c.repository, c.number)) continue;
+    const key = `${c.repository}#${c.number}`;
+    if (wrappedPrs.has(key)) continue;
+    wrappedPrs.add(key);
+    ensure(key, c.number, c.repository).review_count += 1;
+  }
   for (const c of comments) ensure(`${c.repository}#${c.number}`, c.number, c.repository).comment_count += 1;
   const byRepoNum = <T extends { repository: string; number: number }>(a: T, b: T): number =>
     a.repository === b.repository ? a.number - b.number : a.repository < b.repository ? -1 : 1;
@@ -1962,17 +2127,74 @@ export function toGithubRest(pr: GithubPr, milestones?: GithubMilestone[]): Reco
   return out;
 }
 
+// ── WHO the twin says wrote a review or a review comment ─────────────────────────────────
+// A review the twin serves used to answer `user: null`, so a twin-written review folded with
+// no author at all — the one fact a review feed is FOR. The twin ledgers exactly one caller
+// identity for a local write (`actor: { kind: 'agent' }`, which carries no login), so the
+// login it serves for its own writes is the stable `twin` — the same name the jira twin gives
+// a local writer. A rehearsal reviewer's REAL login rides in the review/comment BODY by
+// convention; the twin invents no header for it and never guesses a human's account from an
+// unauthenticated write. A PULLED review carries the login real GitHub named instead.
+export const GITHUB_TWIN_LOGIN = 'twin';
+// Deterministic account id per login (never random, never Date.now), in its own id band so it
+// cannot collide with an observed subject id (0x40000000…) or a check-suite id (0x70000000…).
+function twinUserId(login: string): number {
+  return 0x10000000 + (parseInt(createHash('sha256').update(`user:${login}`).digest('hex').slice(0, 8), 16) % 0x0fffffff);
+}
+// GitHub's simple-user object for a login the twin actually knows. Only `login` and `type`
+// are FACTS; the URLs are derived shape and the unmodeled remainder is declared scope
+// (`user.*` in github-known-deviations.json), exactly like `toAssignees`.
+function toSimpleUser(login: string, type: 'User' | 'Bot' = 'User'): Record<string, unknown> {
+  // `node_id` is OMITTED, not nulled: GitHub declares it a non-nullable string, so a null
+  // there is a type violation rather than a declared gap — the twin omits what it does not
+  // know instead of faking it.
+  return {
+    login,
+    id: twinUserId(login),
+    type,
+    site_admin: false,
+    url: `https://api.github.com/users/${login}`,
+    html_url: `https://github.com/${login}`,
+  };
+}
+// THE IMPLICIT REVIEW. Real GitHub wraps EVERY inline comment in a review: a comment posted
+// through `POST .../pulls/:n/comments` with no review of its own still comes back naming a
+// `pull_request_review_id`, and that wrapper review appears on `GET .../pulls/:n/reviews`.
+// The twin used to serve `pull_request_review_id: null` on every review comment, which made
+// the join a consumer does (comment → its review) DEAD against the twin's own data. So the
+// wrapper is minted DETERMINISTICALLY per (repo, PR): one implicit review per PR, the same id
+// every time. It is synthesized on the reviews READ from the comments that name it — never
+// stored as a review of its own, because it is a wrapper, not a verdict — and `githubState`
+// counts it into `_twin.review_count` under exactly the condition the read uses, so the count
+// and the list describe one population.
+//
+// WHY IT CANNOT COLLIDE, precisely — the band is NOT the reason. Its offset (0x80000000…)
+// separates it from the twin's own two id spaces, the local sequence (small integers) and
+// `observedId`'s hash band (0x40000000…), and that is all it does: real GitHub's own review
+// ids have been in the 0x80000000 range since ~2024, so a band argument against VENDOR ids
+// would be false. The actual invariant is that a vendor id is never a twin id: every pulled
+// review and comment is REHASHED through `observedId` before it is served (nothing arrives
+// carrying its raw GitHub id), and no review id is ever sent back OUT — a push addresses a
+// vendor comment by the `external_id` the pull recorded, never by a minted one.
+export function implicitReviewId(repository: string, number: number): number {
+  return 0x80000000 + (parseInt(createHash('sha256').update(`implicit-review:${repository}#${number}`).digest('hex').slice(0, 8), 16) % 0x3fffffff);
+}
+
 // Map a submitted review to GitHub's pull-request-review shape. `id` is an INTEGER
 // (real GitHub ids are integers; the twin's internal subject id stays `review:N`).
 // node_id/_links/author_association are declared evidence-twin scope (not fabricated).
-export function toGithubReview(a: { id: number; repository: string; number: number; state?: string; body?: string; submitted_at?: string }): Record<string, unknown> {
+export function toGithubReview(a: { id: number; repository: string; number: number; state?: string; body?: string; submitted_at?: string; commit_id?: string; user_login?: string; user_type?: 'User' | 'Bot' }): Record<string, unknown> {
   const api = `https://api.github.com/repos/${a.repository}`;
   const out: Record<string, unknown> = {
     id: a.id,
-    user: null,
+    // WHO reviewed — the twin's own login on a local write, the vendor's on a pulled one,
+    // and `null` only when the author is genuinely unknown.
+    user: a.user_login === undefined ? null : toSimpleUser(a.user_login, a.user_type ?? 'User'),
     body: a.body ?? '',
     state: a.state ?? 'COMMENTED',
-    commit_id: null,
+    // The head sha the review bound to at submission (exact-head re-earn); null only for
+    // legacy/observed reviews whose submission head was never recorded.
+    commit_id: a.commit_id ?? null,
     html_url: `https://github.com/${a.repository}/pull/${a.number}#pullrequestreview-${a.id}`,
     pull_request_url: `${api}/pulls/${a.number}`,
   };
@@ -2003,19 +2225,25 @@ export function toGithubComment(a: { id: number; repository: string; number: num
 // diff-position fields (path/line/side/start_line/diff_hunk) are emitted for LOCAL writes
 // that anchored the comment to the diff; for OBSERVED review comments (no diff evidence)
 // they are omitted and stay declared scope (reviewComment.*). `id` is an INTEGER.
-export function toGithubReviewComment(a: { id: number; repository: string; number: number; body?: string; at?: string; path?: string; line?: number; side?: string; start_line?: number; diff_hunk?: string }): Record<string, unknown> {
+export function toGithubReviewComment(a: { id: number; repository: string; number: number; body?: string; at?: string; path?: string; line?: number; side?: string; start_line?: number; diff_hunk?: string; in_reply_to?: number; review_id?: number; user_login?: string; user_type?: 'User' | 'Bot' }): Record<string, unknown> {
   const api = `https://api.github.com/repos/${a.repository}`;
   const out: Record<string, unknown> = {
     id: a.id,
-    user: null,
+    user: a.user_login === undefined ? null : toSimpleUser(a.user_login, a.user_type ?? 'User'),
     body: a.body ?? '',
     url: `${api}/pulls/comments/${a.id}`,
     html_url: `https://github.com/${a.repository}/pull/${a.number}#discussion_r${a.id}`,
     pull_request_url: `${api}/pulls/${a.number}`,
-    pull_request_review_id: null,
+    // THE JOIN. Every inline comment names the review that wraps it — the review it was
+    // submitted under, or the PR's implicit review when it was posted on its own. `null`
+    // only for a row whose review is genuinely unknown; it is no longer the constant answer.
+    pull_request_review_id: a.review_id ?? null,
   };
   // Observed review comments carry no timestamp — omit rather than fake an empty date.
   if (a.at !== undefined) { out.created_at = a.at; out.updated_at = a.at; }
+  // A threaded reply names the comment it answers — the field a client (and this pack's own
+  // pull) threads a review conversation by. Absent on a root comment, exactly as GitHub.
+  if (a.in_reply_to !== undefined) out.in_reply_to_id = a.in_reply_to;
   // Diff anchoring — present only when a LOCAL write supplied it. diff_hunk defaults to ''
   // (the real API always returns the string) once a path is anchored; line/side per write.
   if (a.path !== undefined) {
@@ -2281,18 +2509,68 @@ export function toGithubRepo(r: GithubRepo): Record<string, unknown> {
   };
 }
 
-// Map a branch to GitHub's branch shape (GET .../branches[/:name]).
+// Map a branch to GitHub's branch shape (GET .../branches[/:name]). The protection summary
+// carries the PERSISTED required-check contexts + the real enforcement_level semantics
+// (everyone when enforce_admins, non_admins otherwise, off when unprotected) — this summary
+// is what merge-gate scripts read their required contexts from.
 export function toGithubBranch(b: GithubBranch): Record<string, unknown> {
   const api = `https://api.github.com/repos/${b.repository}`;
+  const rsc = b.protection_config?.required_status_checks;
+  // enforcement_level is about REQUIRED STATUS CHECKS: 'off' when the branch has none
+  // configured (even while otherwise protected), 'everyone' under enforce_admins,
+  // 'non_admins' otherwise — real GitHub's branch-summary semantics.
+  const enforcement = !(b.protected ?? false) || !rsc ? 'off' : (b.protection_config?.enforce_admins ? 'everyone' : 'non_admins');
   return {
     name: b.name,
     commit: { sha: b.commit_sha, url: `${api}/commits/${b.commit_sha}` },
     protected: b.protected ?? false,
-    protection: { enabled: b.protected ?? false, required_status_checks: { enforcement_level: b.protected ? 'everyone' : 'off', contexts: [] } },
+    protection: {
+      enabled: b.protected ?? false,
+      required_status_checks: { enforcement_level: enforcement, contexts: rsc?.contexts ?? [], checks: rsc?.checks ?? [] },
+    },
     protection_url: `${api}/branches/${encodeURIComponent(b.name)}/protection`,
   };
 }
 
+// Render the FULL classic protection object (GET/PUT .../branches/:b/protection).
+export function toGithubBranchProtection(b: GithubBranch): Record<string, unknown> {
+  const base = `https://api.github.com/repos/${b.repository}/branches/${encodeURIComponent(b.name)}/protection`;
+  const cfg = b.protection_config ?? {};
+  const out: Record<string, unknown> = { url: base, enabled: true };
+  if (cfg.required_status_checks) {
+    out.required_status_checks = {
+      url: `${base}/required_status_checks`,
+      strict: cfg.required_status_checks.strict,
+      contexts: cfg.required_status_checks.contexts,
+      contexts_url: `${base}/required_status_checks/contexts`,
+      checks: cfg.required_status_checks.checks,
+    };
+  }
+  out.enforce_admins = { url: `${base}/enforce_admins`, enabled: cfg.enforce_admins ?? false };
+  if (cfg.required_pull_request_reviews) {
+    out.required_pull_request_reviews = { url: `${base}/required_pull_request_reviews`, ...cfg.required_pull_request_reviews };
+  }
+  if (cfg.restrictions) {
+    out.restrictions = { url: `${base}/restrictions`, ...cfg.restrictions };
+  }
+  return out;
+}
+
+// Normalize a PUT .../protection body's required_status_checks into the persisted shape.
+// Real GitHub accepts `contexts` (deprecated) or `checks` [{context, app_id}]; both are kept
+// in sync so either read-back form answers.
+export function normalizeRequiredStatusChecks(v: unknown): { strict: boolean; contexts: string[]; checks: Array<{ context: string; app_id: number | null }> } | null {
+  if (v === null || v === undefined || typeof v !== 'object') return null;
+  const o = v as Record<string, unknown>;
+  const checksIn = Array.isArray(o.checks) ? (o.checks as Array<Record<string, unknown>>) : undefined;
+  const contextsIn = Array.isArray(o.contexts) ? (o.contexts as unknown[]).map(String) : undefined;
+  const checks = checksIn
+    ? checksIn.map((c) => ({ context: String(c.context ?? ''), app_id: c.app_id === undefined || c.app_id === null || Number(c.app_id) === -1 ? null : Number(c.app_id) }))
+    : (contextsIn ?? []).map((context) => ({ context, app_id: null }));
+  const contexts = contextsIn ?? checks.map((c) => c.context);
+  return { strict: o.strict === true, contexts, checks };
+}
+
 // Map a collaborator to GitHub's collaborator simple-user shape (with a permissions block).
 export function toGithubCollaborator(c: GithubCollaborator): Record<string, unknown> {
   const perm = c.permission;
@@ -2335,6 +2613,75 @@ export function toGithubWebhook(h: GithubWebhook): Record<string, unknown> {
 // Map a contents file to GitHub's contents shape (GET/PUT .../contents/:path). The twin
 // honors small content the caller PUT (base64), and serves it back; raw bytes for large
 // blobs remain the declared Non-goal.
+
+// ── Git-plane-backed READS for the content surfaces real GitHub serves from the same objects a
+// `git push` wrote: GET contents/*, GET readme, GET commits/:ref. A connector-pulled (REST-stored)
+// file wins when present; otherwise the bare repo is the truth — one object store, not two.
+function planeQueryRef(query: string | undefined): string | undefined {
+  if (!query) return undefined;
+  const v = new URLSearchParams(query.startsWith('?') ? query.slice(1) : query).get('ref');
+  return v && v.length ? v : undefined;
+}
+function resolvePlaneRef(repo: string, ref: string | undefined, defaultBranch: string, root?: string): string | null {
+  const want = ref && ref.length ? ref : defaultBranch;
+  if (/^[0-9a-f]{40}$/.test(want) && objectExistsInPlane(repo, want, root)) return want;
+  const refs = listGitPlaneRefs(repo, root);
+  const hit = refs.find((r) => r.ref === want || r.ref === `refs/heads/${want}` || r.ref === `refs/tags/${want}`);
+  if (!hit) return null;
+  if (hit.object_type === 'tag') return readGitTagFromPlane(repo, hit.object_sha, root)?.object_sha ?? null;
+  return hit.object_sha;
+}
+type PlaneLookup = { kind: 'file'; entry: { path: string; mode: string; type: string; sha: string; size?: number } } | { kind: 'dir'; entries: Array<{ path: string; mode: string; type: string; sha: string; size?: number }> };
+function planeEntryAt(repo: string, commitSha: string, path: string, root?: string): PlaneLookup | null {
+  const commit = readGitCommitFromPlane(repo, commitSha, root);
+  if (!commit) return null;
+  let treeSha = commit.tree_sha;
+  const segs = path ? path.split('/').filter(Boolean) : [];
+  for (let i = 0; i < segs.length; i += 1) {
+    const entries = readGitTreeFromPlane(repo, treeSha, root);
+    const e = entries?.find((x) => x.path === segs[i]);
+    if (!e) return null;
+    if (e.type === 'blob') return i === segs.length - 1 ? { kind: 'file', entry: e } : null;
+    if (e.type !== 'tree') return null;
+    treeSha = e.sha;
+  }
+  const entries = readGitTreeFromPlane(repo, treeSha, root);
+  return entries ? { kind: 'dir', entries } : null;
+}
+function planeFileContent(repo: string, ref: string, path: string, entry: { sha: string; size?: number }, root?: string): Record<string, unknown> | null {
+  const blob = readGitBlobFromPlane(repo, entry.sha, root);
+  if (!blob) return null;
+  return toGithubContent({ repository: repo, path, sha: entry.sha, size: blob.size, content_b64: blob.content_b64, branch: ref } as unknown as GithubContentFile);
+}
+function planeContents(repo: string, ref: string | undefined, path: string, defaultBranch: string, root?: string): { status: number; body: unknown } | null {
+  const sha = resolvePlaneRef(repo, ref, defaultBranch, root);
+  if (!sha) return null;
+  const hit = planeEntryAt(repo, sha, path, root);
+  if (!hit) return null;
+  const shownRef = ref ?? defaultBranch;
+  if (hit.kind === 'file') {
+    const body = planeFileContent(repo, shownRef, path, hit.entry, root);
+    return body ? { status: 200, body } : null;
+  }
+  const prefix = path ? `${path}/` : '';
+  return { status: 200, body: hit.entries.map((e) => ({ type: e.type === 'tree' ? 'dir' : e.type === 'commit' ? 'submodule' : 'file', name: e.path, path: `${prefix}${e.path}`, sha: e.sha, size: e.size ?? 0 })) };
+}
+function planeCommitBody(repo: string, sha: string, root?: string): Record<string, unknown> | null {
+  const c = readGitCommitFromPlane(repo, sha, root);
+  if (!c) return null;
+  const who = { name: c.author_name ?? 'github-twin', email: c.author_email ?? 'github-twin@localhost', date: c.created_at ?? new Date(0).toISOString() };
+  return {
+    sha: c.sha,
+    node_id: `C_${c.sha.slice(0, 12)}`,
+    commit: { author: who, committer: who, message: c.message, tree: { sha: c.tree_sha, url: `https://api.github.com/repos/${repo}/git/trees/${c.tree_sha}` }, comment_count: 0 },
+    url: `https://api.github.com/repos/${repo}/commits/${c.sha}`,
+    html_url: `https://github.com/${repo}/commit/${c.sha}`,
+    author: null,
+    committer: null,
+    parents: c.parents.map((sha) => ({ sha, url: `https://api.github.com/repos/${repo}/commits/${sha}`, html_url: `https://github.com/${repo}/commit/${sha}` })),
+  };
+}
+
 export function toGithubContent(f: GithubContentFile): Record<string, unknown> {
   const api = `https://api.github.com/repos/${f.repository}`;
   const ref = f.branch ?? 'main';
@@ -2686,6 +3033,10 @@ export function toGithubGitCommit(c: GithubGitCommit): Record<string, unknown> {
     parents: c.parents.map((p) => ({ sha: p, url: `${api}/git/commits/${p}`, html_url: `https://github.com/${c.repository}/commit/${p}` })),
     author: { name: c.author_name ?? null, email: c.author_email ?? null, date: c.created_at ?? null },
     committer: { name: c.author_name ?? null, email: c.author_email ?? null, date: c.created_at ?? null },
+    // Real responses always carry a verification block. The twin's objects are unsigned —
+    // reported honestly (never a fabricated "verified": the signing GitHub's API does for
+    // bot-created commits needs GitHub's key, which a local twin cannot have).
+    verification: { verified: false, reason: 'unsigned', signature: null, payload: null },
     html_url: `https://github.com/${c.repository}/commit/${c.sha}`,
   };
 }
@@ -2715,6 +3066,8 @@ export function toGithubGitTagObject(t: GithubGitTagObject): Record<string, unkn
     url: `${api}/git/tags/${t.sha}`,
     tagger: { name: t.tagger_name ?? null, email: null, date: t.created_at ?? null },
     object: { type: t.object_type, sha: t.object_sha, url: `${api}/git/${t.object_type === 'tag' ? 'tags' : 'commits'}/${t.object_sha}` },
+    // Honest unsigned verification block (see toGithubGitCommit).
+    verification: { verified: false, reason: 'unsigned', signature: null, payload: null },
   };
 }
 
@@ -3195,6 +3548,26 @@ export function handleGithubRequest(req: { method: string; path: string; root?:
       const n = Number(decodeURIComponent(seg[4]));
       if (seg[5] === 'reviews') {
         const items = state.reviews.filter((r) => r.repository === repo && r.number === n);
+        // THE IMPLICIT REVIEW rides the list, exactly as real GitHub's does: a review comment
+        // posted on its own is still wrapped in a review, and a consumer that joins
+        // `pull_request_review_id` → this list must find it. It is synthesized FROM the
+        // comments that name it (never stored as a review of its own): submitted at the
+        // earliest of them, authored by the first of them, state COMMENTED like GitHub's.
+        // `githubState` counts it into `_twin.review_count` under this same condition — the
+        // count and this list must describe the same population, or the mirror says "Review
+        // count 0" over a PR whose reviews page answers one.
+        const wrapperId = implicitReviewId(repo, n);
+        const wrapped = state.comments.filter((c) => c.repository === repo && c.number === n && c.kind === 'review' && c.review_id === wrapperId);
+        if (wrapped.length > 0) {
+          const dated = wrapped.map((c) => c.created_at).filter((d): d is string => d !== undefined).sort();
+          const author = wrapped.find((c) => c.user_login !== undefined);
+          items.push({
+            id: wrapperId, repository: repo, number: n, state: 'COMMENTED', body: '',
+            ...(dated[0] !== undefined ? { submitted_at: dated[0] } : {}),
+            ...(author?.user_login !== undefined ? { user_login: author.user_login } : {}),
+            ...(author?.user_type !== undefined ? { user_type: author.user_type } : {}),
+          });
+        }
         return { status: 200, body: paginate(items, query).map(toGithubReview) };
       }
       if (seg[5] === 'comments') {
@@ -3209,15 +3582,30 @@ export function handleGithubRequest(req: { method: string; path: string; root?:
           ...(c.side !== undefined ? { side: c.side } : {}),
           ...(c.start_line !== undefined ? { start_line: c.start_line } : {}),
           ...(c.diff_hunk !== undefined ? { diff_hunk: c.diff_hunk } : {}),
+          // a reply reads back naming the comment it answers, so a thread survives the round-trip
+          ...(c.in_reply_to !== undefined ? { in_reply_to: c.in_reply_to } : {}),
+          // and the review that wraps it, so the join a consumer does is live on twin data
+          ...(c.review_id !== undefined ? { review_id: c.review_id } : {}),
+          ...(c.user_login !== undefined ? { user_login: c.user_login } : {}),
+          ...(c.user_type !== undefined ? { user_type: c.user_type } : {}),
         })) };
       }
       if (seg[5] === 'files') {
-        // LOCAL PR writes can carry per-file diffs (filename/status/additions/deletions/patch),
-        // returned here paginated. OBSERVED PRs carry a changed-files COUNT only (no per-file
-        // diff evidence), so they return [] — never fabricated. Declared scope: pullFile.*.
+        // Three sources, in order of evidence strength: (1) per-file diffs a LOCAL PR write
+        // carried; (2) the REAL diff computed from the git plane when the PR's base+head
+        // commits both exist there (a pushed PR's true changed-file list — what merge-gate
+        // scope classification reads); (3) [] for observed PRs with no diff evidence — never
+        // fabricated. Declared scope: pullFile.*.
         const pr = inRepo.find((p) => p.number === n);
-        const items = pr?.files ?? [];
         const headSha = pr?.head_sha ?? '';
+        let items = pr?.files ?? [];
+        // Guard on changed_files === undefined (like the GraphQL path): an OBSERVED PR
+        // carries a pulled count but no per-file evidence — serving a plane list that could
+        // contradict its own count would be two answers for one object.
+        if (items.length === 0 && pr && pr.changed_files === undefined) {
+          const planeFiles = prPlaneDiffFiles(state, repo, pr, req.root);
+          if (planeFiles) items = planeFiles;
+        }
         return { status: 200, body: paginate(items, query).map((f) => toGithubPullFile(repo, headSha, f)) };
       }
       if (seg[5] === 'commits') {
@@ -3265,6 +3653,14 @@ export function handleGithubRequest(req: { method: string; path: string; root?:
     return { status: 200, body: paginate(filtered, query).map((p) => toGithubRest(p, state.milestones)) };
   }
   // Commit statuses + check runs (keyed by sha/ref).
+  // GET .../commits/:ref — a single commit by sha, branch, or tag, read from the REAL git plane.
+  if (req.method === 'GET' && seg[0] === 'repos' && seg[3] === 'commits' && seg[4] && !seg[5]) {
+    const repo = `${seg[1]}/${seg[2]}`;
+    const defaultBranch = state.repos.find((r) => r.full_name === repo)?.default_branch ?? 'main';
+    const sha = resolvePlaneRef(repo, decodeURIComponent(seg[4]), defaultBranch, req.root);
+    const body = sha ? planeCommitBody(repo, sha, req.root) : null;
+    return body ? { status: 200, body } : githubNotFound();
+  }
   if (req.method === 'GET' && seg[0] === 'repos' && seg[3] === 'commits' && seg[4] && seg[5]) {
     const repo = `${seg[1]}/${seg[2]}`;
     const ref = decodeURIComponent(seg[4]);
@@ -3312,6 +3708,16 @@ export function handleGithubRequest(req: { method: string; path: string; root?:
   if (req.method === 'GET' && seg[0] === 'repos' && seg[3] === 'readme' && !seg[4]) {
     const repo = `${seg[1]}/${seg[2]}`;
     const readme = state.contents.filter((c) => c.repository === repo && /^readme(\.[a-z]+)?$/i.test(c.path)).sort((a, b) => a.path.length - b.path.length)[0];
+    if (!readme) {
+      const defaultBranch = state.repos.find((r) => r.full_name === repo)?.default_branch ?? 'main';
+      const sha = resolvePlaneRef(repo, planeQueryRef(query), defaultBranch, req.root);
+      const top = sha ? planeEntryAt(repo, sha, '', req.root) : null;
+      const entry = top?.kind === 'dir' ? top.entries.find((e) => e.type === 'blob' && /^readme(\.[a-z]+)?$/i.test(e.path)) : undefined;
+      if (entry) {
+        const body = planeFileContent(repo, planeQueryRef(query) ?? defaultBranch, entry.path, entry, req.root);
+        if (body) return { status: 200, body };
+      }
+    }
     if (!readme) return githubNotFound();
     return { status: 200, body: {
       type: 'file', name: readme.path.split('/').pop(), path: readme.path, sha: readme.sha, size: readme.size ?? 0,
@@ -3670,16 +4076,24 @@ export function handleGithubRequest(req: { method: string; path: string; root?:
     const inRepo = state.tags.filter((t) => t.repository === repo);
     return { status: 200, body: paginate(inRepo, query).map(toGithubTag) };
   }
-  // Git refs for tags (GET .../git/refs/tags[/:tag]) — lightweight commit refs.
+  // Git refs for tags (GET .../git/refs/tags[/:tag]) — the UNION of release-derived tag refs
+  // and first-class git refs (REST-created or pushed refs/tags/*). The two used to be served
+  // by disjoint handlers, so a pushed tag was visible at .../git/ref/tags/:t but invisible
+  // here — two answers for one object. First-class refs win a name collision.
   if (req.method === 'GET' && seg[0] === 'repos' && seg[3] === 'git' && seg[4] === 'refs' && seg[5] === 'tags') {
     const repo = `${seg[1]}/${seg[2]}`;
-    const inRepo = state.tags.filter((t) => t.repository === repo);
+    const gitTagRefs = state.gitRefs.filter((x) => x.repository === repo && x.ref.startsWith('refs/tags/'));
+    const gitTagNames = new Set(gitTagRefs.map((x) => x.ref.slice('refs/tags/'.length)));
+    const releaseTags = state.tags.filter((t) => t.repository === repo && !gitTagNames.has(t.name));
     if (seg[6]) {
       const name = decodeURIComponent(seg.slice(6).join('/'));
-      const tag = inRepo.find((t) => t.name === name);
+      const gitRef = gitTagRefs.find((x) => x.ref === `refs/tags/${name}`);
+      if (gitRef) return { status: 200, body: toGithubGitRef(gitRef) };
+      const tag = releaseTags.find((t) => t.name === name);
       return tag ? { status: 200, body: toGithubGitTagRef(tag) } : githubNotFound();
     }
-    return { status: 200, body: paginate(inRepo, query).map(toGithubGitTagRef) };
+    const union = [...releaseTags.map(toGithubGitTagRef), ...gitTagRefs.map(toGithubGitRef)];
+    return { status: 200, body: paginate(union, query) };
   }
   // ── Git Data API reads (refs/commits/trees/blobs/annotated tags). These are LOCAL Git
   //   objects authored via the Git Data write endpoints (distinct from the derived tag refs
@@ -3702,20 +4116,31 @@ export function handleGithubRequest(req: { method: string; path: string; root?:
       if (exact && matches.length === 1) return { status: 200, body: toGithubGitRef(exact) };
       return { status: 200, body: paginate(matches, query).map(toGithubGitRef) };
     }
+    // Object reads consult the kernel row first (REST-authored objects land in BOTH with the
+    // same real sha), then fall back to the REAL git plane — so an object that arrived by
+    // `git push` (receive-pack) is visible through the Git Data REST surface too.
     if (seg[4] === 'commits' && seg[5]) {
-      const c = state.gitCommits.find((x) => x.repository === repo && x.sha === decodeURIComponent(seg[5]!));
+      const sha = decodeURIComponent(seg[5]!);
+      const c = state.gitCommits.find((x) => x.repository === repo && x.sha === sha)
+        ?? (() => { const p = readGitCommitFromPlane(repo, sha, req.root); return p ? { repository: repo, ...p } : undefined; })();
       return c ? { status: 200, body: toGithubGitCommit(c) } : githubNotFound();
     }
     if (seg[4] === 'trees' && seg[5]) {
-      const t = state.gitTrees.find((x) => x.repository === repo && x.sha === decodeURIComponent(seg[5]!));
+      const sha = decodeURIComponent(seg[5]!);
+      const t = state.gitTrees.find((x) => x.repository === repo && x.sha === sha)
+        ?? (() => { const p = readGitTreeFromPlane(repo, sha, req.root); return p ? { repository: repo, sha, tree: p, truncated: false } : undefined; })();
       return t ? { status: 200, body: toGithubGitTree(t) } : githubNotFound();
     }
     if (seg[4] === 'blobs' && seg[5]) {
-      const b = state.gitBlobs.find((x) => x.repository === repo && x.sha === decodeURIComponent(seg[5]!));
+      const sha = decodeURIComponent(seg[5]!);
+      const b = state.gitBlobs.find((x) => x.repository === repo && x.sha === sha)
+        ?? (() => { const p = readGitBlobFromPlane(repo, sha, req.root); return p ? { repository: repo, sha, content_b64: p.content_b64, size: p.size, encoding: 'base64' } : undefined; })();
       return b ? { status: 200, body: toGithubGitBlob(b) } : githubNotFound();
     }
     if (seg[4] === 'tags' && seg[5]) {
-      const t = state.gitTagObjects.find((x) => x.repository === repo && x.sha === decodeURIComponent(seg[5]!));
+      const sha = decodeURIComponent(seg[5]!);
+      const t = state.gitTagObjects.find((x) => x.repository === repo && x.sha === sha)
+        ?? (() => { const p = readGitTagFromPlane(repo, sha, req.root); return p ? { repository: repo, ...p } : undefined; })();
       return t ? { status: 200, body: toGithubGitTagObject(t) } : githubNotFound();
     }
     return githubNotFound();
@@ -3806,6 +4231,24 @@ export function handleGithubRequest(req: { method: string; path: string; root?:
   if (req.method === 'GET' && seg[0] === 'repos' && seg[3] === 'branches') {
     const repo = `${seg[1]}/${seg[2]}`;
     const inRepo = state.branches.filter((b) => b.repository === repo);
+    // Protection reads (GET .../branches/:b/protection[/required_status_checks|enforce_admins])
+    // — the persisted config back out, 404 "Branch not protected" when protection is off.
+    if (seg[4] && seg[5] === 'protection') {
+      const name = decodeURIComponent(seg[4]!);
+      const b = inRepo.find((x) => x.name === name);
+      if (!b?.protected) return { status: 404, body: { message: 'Branch not protected', documentation_url: 'https://docs.github.com/rest/branches/branch-protection' } };
+      const base = `https://api.github.com/repos/${repo}/branches/${encodeURIComponent(name)}/protection`;
+      if (!seg[6]) return { status: 200, body: toGithubBranchProtection(b) };
+      if (seg[6] === 'required_status_checks' && !seg[7]) {
+        const rsc = b.protection_config?.required_status_checks;
+        if (!rsc) return { status: 404, body: { message: 'Required status checks not enabled', documentation_url: 'https://docs.github.com/rest/branches/branch-protection' } };
+        return { status: 200, body: { url: `${base}/required_status_checks`, strict: rsc.strict, contexts: rsc.contexts, contexts_url: `${base}/required_status_checks/contexts`, checks: rsc.checks } };
+      }
+      if (seg[6] === 'enforce_admins' && !seg[7]) {
+        return { status: 200, body: { url: `${base}/enforce_admins`, enabled: b.protection_config?.enforce_admins ?? false } };
+      }
+      return githubNotFound();
+    }
     if (seg[4]) {
       const name = decodeURIComponent(seg.slice(4).join('/'));
       const b = inRepo.find((x) => x.name === name);
@@ -3847,6 +4290,9 @@ export function handleGithubRequest(req: { method: string; path: string; root?:
     const prefix = p ? `${p}/` : '';
     const children = inRepo.filter((c) => c.path.startsWith(prefix) && c.path !== p);
     if (children.length) return { status: 200, body: children.map((c) => ({ type: 'file', name: c.path.slice(prefix.length).split('/')[0], path: c.path, sha: c.sha, size: c.size })) };
+    // Nothing REST-stored at this path: the bare repo (a real `git push`) is the truth.
+    const planeHit = planeContents(repo, planeQueryRef(query), p, state.repos.find((r) => r.full_name === repo)?.default_branch ?? 'main', req.root);
+    if (planeHit) return planeHit;
     return githubNotFound();
   }
   // ── Teams: GET /orgs/:org/teams[/:slug][/...]  (CRUD + membership + repo access + discussions)
@@ -4256,8 +4702,21 @@ export function handleGithubRequest(req: { method: string; path: string; root?:
     const [base, head] = basehead.split('...');
     const pr = state.prs.find((p) => p.repository === repo && (p.head_sha === head || p.base_ref === base));
     const commitsList = pr?.commits_list ?? [];
-    const files = pr?.files ?? [];
+    let files = pr?.files ?? [];
     const headSha = pr?.head_sha ?? head ?? '';
+    // Same evidence order as GET /pulls/:n/files: carried diffs first, then the REAL diff
+    // from the git plane when both sides resolve there (compare is three-dot by definition —
+    // diffFilesInPlane already diffs from the merge base). Never two answers for one object.
+    if (files.length === 0 && base && head) {
+      const resolveRef = (name: string): string | undefined => /^[0-9a-f]{40}$/i.test(name) ? name
+        : (state.gitRefs.find((x) => x.repository === repo && x.ref === `refs/heads/${name}`)?.object_sha
+          ?? state.branches.find((b) => b.repository === repo && b.name === name)?.commit_sha);
+      const baseSha = resolveRef(base); const tipSha = resolveRef(head);
+      if (baseSha && tipSha) {
+        const diff = diffFilesInPlane(repo, baseSha, tipSha, req.root);
+        if (diff) files = diff.map((f) => ({ filename: f.filename, status: f.status, additions: f.additions, deletions: f.deletions, changes: f.additions + f.deletions, ...(f.sha !== undefined ? { sha: f.sha } : {}) }));
+      }
+    }
     return { status: 200, body: {
       status: commitsList.length ? 'ahead' : 'identical',
       ahead_by: commitsList.length,
@@ -4574,8 +5033,18 @@ function nextRunNumber(repo: string, workflowId: number, root?: string): number
   return max + 1;
 }
 
-export type GithubWriteEvent = { event: string; action: string; repository: string; number: number; pr?: Record<string, unknown>; body?: string };
-export type GithubWriteOutcome = { response: GithubResponse; webhook?: GithubWriteEvent };
+export type GithubWriteEvent = {
+  event: string; action: string; repository: string; number: number; pr?: Record<string, unknown>; body?: string;
+  // push events (a git-receive-pack push or a contents write): GitHub's ref/before/after triple.
+  ref?: string; before?: string; after?: string;
+};
+export type GithubWriteOutcome = {
+  response: GithubResponse;
+  webhook?: GithubWriteEvent;
+  // Some writes fire SEVERAL events (a ref write is a push AND may synchronize/close PRs) —
+  // REST and receive-pack converge on the same event stream.
+  webhooks?: GithubWriteEvent[];
+};
 
 /**
  * Handle a GitHub REST WRITE as a local action (R5/R18). Supports:
@@ -4588,6 +5057,60 @@ export type GithubWriteOutcome = { response: GithubResponse; webhook?: GithubWri
  *   POST   /repos/:o/:r/issues/:n/comments → comment (issue_comment)
  * Mirror mode rejects writes (R4). No real GitHub I/O (R16).
  */
+/**
+ * The PR's REAL changed-file list from the git plane: resolve the base branch tip + the PR
+ * head sha; when both commits exist in the bare repo, `git diff-tree` computes the truth.
+ * Null when either side is not in the plane (observed/simulated PRs keep their carried or
+ * empty file lists — never fabricated). This is what merge-gate scope classification reads
+ * (GET /pulls/:n/files + GraphQL changedFiles), so a pushed PR must answer with its actual
+ * paths, not 0 files.
+ */
+export function prPlaneDiffFiles(state: GithubState, repo: string, pr: GithubPr, root?: string): GithubPullFile[] | null {
+  const headSha = pr.head_sha;
+  if (!headSha || !/^[0-9a-f]{40}$/i.test(headSha)) return null;
+  const baseBranch = pr.base_ref;
+  if (!baseBranch) return null;
+  const baseSha = state.gitRefs.find((x) => x.repository === repo && x.ref === `refs/heads/${baseBranch}`)?.object_sha
+    ?? state.branches.find((b) => b.repository === repo && b.name === baseBranch)?.commit_sha;
+  if (!baseSha || !/^[0-9a-f]{40}$/i.test(baseSha)) return null;
+  const diff = diffFilesInPlane(repo, baseSha, headSha, root);
+  if (!diff) return null;
+  // Real post-image blob shas ride along (from --raw); `patch` text stays absent — a filed
+  // todo (github.pulls.files_patch_from_plane), never a fabricated diff body.
+  return diff.map((f) => ({ filename: f.filename, status: f.status, additions: f.additions, deletions: f.deletions, changes: f.additions + f.deletions, ...(f.sha !== undefined ? { sha: f.sha } : {}) }));
+}
+
+/**
+ * GitHub closes open PRs whose HEAD BRANCH is deleted. Shared by the receive-pack reconcile
+ * and the REST ref delete so both paths converge. Returns the closed PR numbers.
+ */
+export async function closePrsForDeletedBranch(repo: string, branch: string, root: string | undefined, occurredAt: string): Promise<number[]> {
+  const closed: number[] = [];
+  for (const pr of githubState(root).prs) {
+    if (pr.repository !== repo || pr.head_ref !== branch || pr.merged || (pr.state ?? 'open') !== 'open') continue;
+    await applyTwinWrite(SERVICE, { operation: 'pull_request.update', subjectType: 'pull_request', subjectId: pr.id, fields: { number: pr.number, repository: repo, state: 'closed' }, occurredAt, actor: { kind: 'agent' } }, root);
+    closed.push(pr.number);
+  }
+  return closed;
+}
+
+/**
+ * Re-point every OPEN PR whose head branch is `branch` at the branch's new tip — GitHub's
+ * `synchronize` semantic: a push (receive-pack or an API ref update) moves the PR head, so
+ * statuses/checks/reviews earned on the old head no longer match. Returns the PR numbers
+ * moved (the receive-pack path emits `pull_request synchronize` webhooks for them).
+ */
+export async function syncPrHeadsToBranchTip(repo: string, branch: string, sha: string, root: string | undefined, occurredAt: string): Promise<number[]> {
+  const moved: number[] = [];
+  for (const pr of githubState(root).prs) {
+    if (pr.repository !== repo || pr.head_ref !== branch || pr.merged) continue;
+    if ((pr.state ?? 'open') !== 'open' || pr.head_sha === sha) continue;
+    await applyTwinWrite(SERVICE, { operation: 'pull_request.update', subjectType: 'pull_request', subjectId: pr.id, fields: { number: pr.number, repository: repo, head_sha: sha }, occurredAt, actor: { kind: 'agent' } }, root);
+    moved.push(pr.number);
+  }
+  return moved;
+}
+
 export async function applyGithubWrite(req: {
   method: string; path: string; body?: string; root?: string; readOnly?: boolean; occurredAt?: string;
 }): Promise<GithubWriteOutcome> {
@@ -4674,12 +5197,35 @@ export async function applyGithubWrite(req: {
     const pr = st.prs.find((p) => p.id === id);
     return { response: { status: 200, body: pr ? toGithubRest(pr, st.milestones) : { number } }, webhook: { event: 'pull_request', action: body.state === 'closed' ? 'closed' : 'edited', repository: repo, number } };
   }
-  // POST /repos/:o/:r/pulls/:n/reviews  → submit review
+  // POST /repos/:o/:r/pulls/:n/reviews  → submit review. The review BINDS to the PR's head
+  // sha at submission (real GitHub's `commit_id`) — a caller may pin it explicitly with
+  // `commit_id` (the real API accepts one); otherwise the CURRENT head is recorded. This is
+  // the exact-head re-earn semantic merge gates depend on: a later push moves the PR head,
+  // the review's commit_id stays where it was.
   if (req.method === 'POST' && seg[3] === 'pulls' && seg[4] && seg[5] === 'reviews') {
     const number = Number(decodeURIComponent(seg[4]!));
     const seq = nextSeq('review', req.root);
-    await applyTwinWrite(SERVICE, { operation: 'pull_request_review.submit', subjectType: 'pull_request_review', subjectId: `review:${seq}`, fields: { repository: repo, number, state: body.event ?? 'COMMENTED', body: body.body, submitted_at: occurredAt }, occurredAt, actor: { kind: 'agent' } }, req.root);
-    return { response: { status: 200, body: toGithubReview({ id: seq, repository: repo, number, state: body.event, body: body.body, submitted_at: occurredAt }) }, webhook: { event: 'pull_request_review', action: 'submitted', repository: repo, number, body: body.body } };
+    const prHead = githubState(req.root).prs.find((p) => p.repository === repo && p.number === number)?.head_sha;
+    const commitId = body.commit_id !== undefined ? String(body.commit_id) : prHead;
+    const fields: Record<string, unknown> = { repository: repo, number, state: body.event ?? 'COMMENTED', body: body.body, submitted_at: occurredAt, user_login: GITHUB_TWIN_LOGIN };
+    if (commitId !== undefined) fields.commit_id = commitId;
+    await applyTwinWrite(SERVICE, { operation: 'pull_request_review.submit', subjectType: 'pull_request_review', subjectId: `review:${seq}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
+    // Real GitHub's review create takes an inline `comments` array — the diff findings the
+    // review is submitting. Each becomes a review comment WRAPPED BY THIS REVIEW (its
+    // `pull_request_review_id` is this review's id, not the PR's implicit wrapper), which is
+    // the one path where the create route knows the review a comment was posted under.
+    if (Array.isArray(body.comments)) {
+      for (const raw of body.comments as Array<Record<string, unknown>>) {
+        const cSeq = nextSeq('comment', req.root);
+        const cFields: Record<string, unknown> = { repository: repo, number, body: raw.body, created_at: occurredAt, updated_at: occurredAt, review_id: seq, user_login: GITHUB_TWIN_LOGIN };
+        if (raw.path !== undefined) cFields.path = String(raw.path);
+        if (raw.line !== undefined) cFields.line = Number(raw.line);
+        if (raw.side !== undefined) cFields.side = String(raw.side);
+        if (raw.start_line !== undefined) cFields.start_line = Number(raw.start_line);
+        await applyTwinWrite(SERVICE, { operation: 'pull_request_review_comment.create', subjectType: 'pull_request_review_comment', subjectId: `comment:${cSeq}`, fields: cFields, occurredAt, actor: { kind: 'agent' } }, req.root);
+      }
+    }
+    return { response: { status: 200, body: toGithubReview({ id: seq, repository: repo, number, state: body.event, body: body.body, submitted_at: occurredAt, user_login: GITHUB_TWIN_LOGIN, ...(commitId !== undefined ? { commit_id: commitId } : {}) }) }, webhook: { event: 'pull_request_review', action: 'submitted', repository: repo, number, body: body.body } };
   }
   // PUT /repos/:o/:r/pulls/:n/reviews/:rid/dismissals → dismiss a review (state → DISMISSED).
   //   Requires a `message` (real GitHub 422s without it). PUT .../reviews/:rid → update body.
@@ -4702,13 +5248,46 @@ export async function applyGithubWrite(req: {
       return { response: { status: 200, body: toGithubReview(r) } };
     }
   }
+  // POST /repos/:o/:r/pulls/:n/comments/:cid/replies → reply IN a review thread.
+  // GitHub's dedicated reply route, and the one a seat answering a bot's finding can
+  // actually use: it read the finding from `GET .../pulls/:n/comments` and knows the
+  // comment id, not the diff anchor — so the reply inherits the root comment's anchor and
+  // `in_reply_to_id` is what threads it. Matched BEFORE the create route below, whose
+  // `seg[5] === 'comments'` test would otherwise swallow this path and lose the thread.
+  if (req.method === 'POST' && seg[3] === 'pulls' && seg[4] && seg[5] === 'comments' && seg[6] && seg[7] === 'replies') {
+    const number = Number(decodeURIComponent(seg[4]!));
+    const rootId = Number(decodeURIComponent(seg[6]!));
+    const parent = githubState(req.root).comments.find((c) => c.repository === repo && c.number === number && c.kind === 'review' && c.id === rootId);
+    // Real GitHub 404s a reply to a comment that isn't there rather than starting a thread.
+    if (!parent) return { response: githubNotFound() };
+    // Real GitHub refuses an EMPTY body the same way it refuses a missing one — a blank reply
+    // is not a reply. (`missing_field` is the code its validator returns for both.)
+    if (body.body === undefined || String(body.body) === '') return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'PullRequestReviewComment', field: 'body', code: 'missing_field' }] } } };
+    const seq = nextSeq('comment', req.root);
+    const anchor: Record<string, unknown> = {};
+    if (parent.path !== undefined) anchor.path = parent.path;
+    if (parent.line !== undefined) anchor.line = parent.line;
+    if (parent.side !== undefined) anchor.side = parent.side;
+    if (parent.diff_hunk !== undefined) anchor.diff_hunk = parent.diff_hunk;
+    // The reply is the TWIN's own comment, so it rides the PR's implicit review — not the
+    // parent's, which would claim the answer was part of the reviewer's verdict. Real GitHub
+    // does the same: a reply is wrapped in a fresh review belonging to the replier.
+    const wrapperId = implicitReviewId(repo, number);
+    const fields: Record<string, unknown> = { repository: repo, number, body: body.body, created_at: occurredAt, updated_at: occurredAt, in_reply_to: rootId, review_id: wrapperId, user_login: GITHUB_TWIN_LOGIN, ...anchor };
+    await applyTwinWrite(SERVICE, { operation: 'pull_request_review_comment.create', subjectType: 'pull_request_review_comment', subjectId: `comment:${seq}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
+    return { response: { status: 201, body: toGithubReviewComment({ id: seq, repository: repo, number, body: body.body, at: occurredAt, in_reply_to: rootId, review_id: wrapperId, user_login: GITHUB_TWIN_LOGIN, ...anchor }) }, webhook: { event: 'pull_request_review_comment', action: 'created', repository: repo, number, body: body.body } };
+  }
   // POST /repos/:o/:r/pulls/:n/comments  → create a review (diff-thread) comment.
   // LOCAL writes may anchor the comment to the diff via path + line + side (+ start_line),
   // like real GitHub — those fields ride on the stored comment and the read-back.
   if (req.method === 'POST' && seg[3] === 'pulls' && seg[4] && seg[5] === 'comments') {
     const number = Number(decodeURIComponent(seg[4]!));
     const seq = nextSeq('comment', req.root);
-    const fields: Record<string, unknown> = { repository: repo, number, body: body.body, created_at: occurredAt, updated_at: occurredAt };
+    // A comment posted with no review of its own is still WRAPPED in one on real GitHub —
+    // the PR's implicit review (deterministic per repo+PR), so the id this route serves back
+    // as `pull_request_review_id` resolves on `GET .../pulls/:n/reviews`.
+    const wrapperId = implicitReviewId(repo, number);
+    const fields: Record<string, unknown> = { repository: repo, number, body: body.body, created_at: occurredAt, updated_at: occurredAt, review_id: wrapperId, user_login: GITHUB_TWIN_LOGIN };
     if (body.path !== undefined) fields.path = String(body.path);
     if (body.line !== undefined) fields.line = Number(body.line);
     if (body.side !== undefined) fields.side = String(body.side);
@@ -4719,11 +5298,15 @@ export async function applyGithubWrite(req: {
     await applyTwinWrite(SERVICE, { operation: 'pull_request_review_comment.create', subjectType: 'pull_request_review_comment', subjectId: `comment:${seq}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
     return { response: { status: 201, body: toGithubReviewComment({
       id: seq, repository: repo, number, body: body.body, at: occurredAt,
+      review_id: wrapperId, user_login: GITHUB_TWIN_LOGIN,
       ...(body.path !== undefined ? { path: String(body.path) } : {}),
       ...(body.line !== undefined ? { line: Number(body.line) } : {}),
       ...(body.side !== undefined ? { side: String(body.side) } : {}),
       ...(body.start_line !== undefined ? { start_line: Number(body.start_line) } : {}),
       ...(body.diff_hunk !== undefined ? { diff_hunk: String(body.diff_hunk) } : {}),
+      // The create accepted `in_reply_to` but answered without it, so a client that threads
+      // by the response alone lost the thread it had just joined. It rides the 201 now.
+      ...(body.in_reply_to !== undefined ? { in_reply_to: Number(body.in_reply_to) } : {}),
     }) }, webhook: { event: 'pull_request_review_comment', action: 'created', repository: repo, number, body: body.body } };
   }
   // PUT /repos/:o/:r/pulls/:n/merge  → merge a pull request
@@ -4736,15 +5319,20 @@ export async function applyGithubWrite(req: {
     if (pr.merged || pr.state === 'closed') return { response: { status: 405, body: { message: 'Pull Request is not mergeable' } } };
     // A draft PR cannot be merged (real GitHub 405s).
     if (pr.draft) return { response: { status: 405, body: { message: 'Draft pull requests cannot be merged.' } } };
+    // GitHub's optional `sha` is an optimistic-concurrency precondition: callers that reviewed
+    // one exact head can refuse to merge if the branch advanced between their read and this
+    // write. Ignoring it turns every external merge gate into a check-then-act race.
+    if (body.sha !== undefined && String(body.sha) !== pr.head_sha) {
+      return { response: { status: 409, body: { message: 'Head branch was modified. Review and try the merge again.' } } };
+    }
     // merge_method (merge|squash|rebase) selects how the merge commit is produced; default 'merge'.
     const allowedMethods = ['merge', 'squash', 'rebase'];
     const method = body.merge_method ? String(body.merge_method) : 'merge';
     if (!allowedMethods.includes(method)) return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'PullRequest', field: 'merge_method', code: 'invalid' }] } } };
-    const sha = mergeCommitSha(repo, number);
-    const fields = { number, repository: repo, state: 'closed', merged: true, merged_at: occurredAt, merge_commit_sha: sha, merge_method: method };
-    await applyTwinWrite(SERVICE, { operation: 'pull_request.merge', subjectType: 'pull_request', subjectId: id, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
+    const landed = await mergePullRequest(repo, pr, method as 'merge' | 'squash' | 'rebase', occurredAt, req.root);
+    if (!landed.ok) return { response: { status: landed.status, body: { message: landed.message } } };
     return {
-      response: { status: 200, body: { sha, merged: true, message: 'Pull Request successfully merged' } },
+      response: { status: 200, body: { sha: landed.sha, merged: true, message: 'Pull Request successfully merged' } },
       webhook: { event: 'pull_request', action: 'closed', repository: repo, number },
     };
   }
@@ -4814,6 +5402,7 @@ export async function applyGithubWrite(req: {
     const seq = nextSeq('status', req.root);
     const fields = { repository: repo, sha, state: body.state, context: body.context ?? 'default', description: body.description, target_url: body.target_url, created_at: occurredAt, updated_at: occurredAt };
     await applyTwinWrite(SERVICE, { operation: 'commit_status.create', subjectType: 'commit_status', subjectId: `status:${seq}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
+    if (body.state === 'success') await landArmedPullRequests(repo, sha, occurredAt, req.root);
     return { response: { status: 201, body: toGithubStatus({ id: seq, repository: repo, sha, state: body.state, context: body.context ?? 'default', description: body.description, target_url: body.target_url, created_at: occurredAt, updated_at: occurredAt }) } };
   }
   // POST /repos/:o/:r/check-runs  → create a check run (LOCAL CI construct)
@@ -4826,6 +5415,7 @@ export async function applyGithubWrite(req: {
     const fields: Record<string, unknown> = { repository: repo, head_sha: body.head_sha, name: body.name, status, conclusion: body.conclusion, details_url: body.details_url, started_at: body.started_at ?? occurredAt };
     if (completed_at !== undefined) fields.completed_at = completed_at;
     await applyTwinWrite(SERVICE, { operation: 'check_run.create', subjectType: 'check_run', subjectId: `check:${seq}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
+    if (body.conclusion === 'success') await landArmedPullRequests(repo, String(body.head_sha), occurredAt, req.root);
     return { response: { status: 201, body: toGithubCheckRun({ id: seq, repository: repo, head_sha: body.head_sha, name: body.name, status, conclusion: body.conclusion, details_url: body.details_url, started_at: body.started_at ?? occurredAt, ...(completed_at !== undefined ? { completed_at } : {}) }) } };
   }
   // POST /repos/:o/:r/pulls/:n/requested_reviewers  → request reviewers (body {reviewers:[login]})
@@ -5334,6 +5924,7 @@ export async function applyGithubWrite(req: {
       }));
     } else if (existing.annotations) { fields.annotations = existing.annotations; }
     await applyTwinWrite(SERVICE, { operation: 'check_run.update', subjectType: 'check_run', subjectId: `check:${id}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
+    if (fields.conclusion === 'success') await landArmedPullRequests(repo, existing.head_sha, occurredAt, req.root);
     const updated = githubState(req.root).checkRuns.find((c) => c.id === id)!;
     return { response: { status: 200, body: toGithubCheckRun(updated) } };
   }
@@ -5366,7 +5957,14 @@ export async function applyGithubWrite(req: {
       if (body[k] !== undefined) fields[k] = body[k];
     }
     if (body.name !== undefined) fields.name = String(body.name);
+    // Validate BEFORE the kernel write (never half-apply): a branch name symbolic-ref would
+    // refuse is GitHub's 422, not a thrown 500.
+    if (body.default_branch !== undefined && !isValidBranchName(String(body.default_branch))) {
+      return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'Repository', field: 'default_branch', code: 'invalid' }] } } };
+    }
     await applyTwinWrite(SERVICE, { operation: 'repository.update', subjectType: 'repository', subjectId: `repo:${r0.id}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
+    // A default_branch change re-points the bare repo's HEAD too (clone checks out the new one).
+    if (body.default_branch !== undefined) setBareRepoHead(repo, String(body.default_branch), req.root);
     const r = githubState(req.root).repos.find((x) => x.id === r0.id)!;
     return { response: { status: 200, body: toGithubRepo(r) }, webhook: { event: 'repository', action: 'edited', repository: repo, number: 0 } };
   }
@@ -5374,6 +5972,8 @@ export async function applyGithubWrite(req: {
     const r0 = githubState(req.root).repos.find((x) => x.full_name === repo);
     if (!r0) return { response: githubNotFound() };
     await applyTwinWrite(SERVICE, { operation: 'repository.delete', subjectType: 'repository', subjectId: `repo:${r0.id}`, fields: { owner: r0.owner, name: r0.name }, occurredAt, actor: { kind: 'agent' } }, req.root);
+    // The bare repo dies with the repo — a later re-create must NOT inherit its history.
+    deleteBareRepo(repo, req.root);
     return { response: { status: 204, body: undefined }, webhook: { event: 'repository', action: 'deleted', repository: repo, number: 0 } };
   }
   // POST /repos/:o/:r/forks → create a fork (a new repo with fork:true + parent).
@@ -5381,10 +5981,25 @@ export async function applyGithubWrite(req: {
     const parent = githubState(req.root).repos.find((x) => x.full_name === repo);
     const owner = String(body.organization ?? 'octocat');
     const name = String(body.name ?? seg[2]);
+    if (!/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(name) || ['.', '..'].includes(owner) || ['.', '..'].includes(name)) {
+      return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'Repository', field: 'name', code: 'invalid' }] } } };
+    }
     const full = `${owner}/${name}`;
     const seq = nextSeq('repo', req.root);
     const fields = { owner, name, fork: true, parent_full_name: repo, description: parent?.description ?? null, default_branch: parent?.default_branch ?? 'main', created_at: occurredAt, updated_at: occurredAt };
     await applyTwinWrite(SERVICE, { operation: 'repository.fork', subjectType: 'repository', subjectId: `repo:${seq}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
+    // A fork copies the parent's OBJECT STORE + refs (what GitHub does server-side) — cloning
+    // the fork must serve the parent's history, not an empty repo — AND the copied refs get
+    // control-plane rows (else REST refs/branches would answer empty while clone serves
+    // history: two answers for one object).
+    forkBareRepo(repo, full, req.root, String(fields.default_branch));
+    for (const planeRef of listGitPlaneRefs(full, req.root)) {
+      await applyTwinWrite(SERVICE, { operation: 'git_ref.create', subjectType: 'git_ref', subjectId: `gitref:${full}#${planeRef.ref}`, fields: { repository: full, ref: planeRef.ref, object_sha: planeRef.object_sha, object_type: planeRef.object_type === 'tag' ? 'tag' : 'commit' }, occurredAt, actor: { kind: 'agent' } }, req.root);
+      if (planeRef.ref.startsWith('refs/heads/')) {
+        const bn = planeRef.ref.slice('refs/heads/'.length);
+        await applyTwinWrite(SERVICE, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${full}#${bn}`, fields: { repository: full, name: bn, commit_sha: planeRef.object_sha }, occurredAt, actor: { kind: 'agent' } }, req.root);
+      }
+    }
     const r = githubState(req.root).repos.find((x) => x.full_name === full)!;
     return { response: { status: 202, body: toGithubRepo(r) }, webhook: { event: 'fork', action: 'created', repository: repo, number: 0 } };
   }
@@ -5396,9 +6011,11 @@ export async function applyGithubWrite(req: {
     await applyTwinWrite(SERVICE, { operation: 'repository.set_topics', subjectType: 'repository', subjectId: `repo:${r0.id}`, fields: { owner: r0.owner, name: r0.name, topics: names, updated_at: occurredAt }, occurredAt, actor: { kind: 'agent' } }, req.root);
     return { response: { status: 200, body: { names } } };
   }
-  // ── Branches: create/delete via git refs is below; protection toggles here ───────────────
-  // PUT /repos/:o/:r/branches/:branch/protection → mark protected. DELETE → unmark.
-  if (seg[3] === 'branches' && seg[4] && seg[5] === 'protection' && (req.method === 'PUT' || req.method === 'DELETE')) {
+  // ── Branches: create/delete via git refs is below; protection lives here ─────────────────
+  // PUT /repos/:o/:r/branches/:branch/protection → protect + PERSIST the config (required
+  // status-check contexts, enforce_admins, required PR reviews — what merge gates read back).
+  // DELETE → unprotect (204). Sub-resources (required_status_checks / enforce_admins) below.
+  if (seg[3] === 'branches' && seg[4] && seg[5] === 'protection' && !seg[6] && (req.method === 'PUT' || req.method === 'DELETE')) {
     const name = decodeURIComponent(seg[4]!);
     const st0 = githubState(req.root);
     let b = st0.branches.find((x) => x.repository === repo && x.name === name);
@@ -5409,9 +6026,53 @@ export async function applyGithubWrite(req: {
       b = githubState(req.root).branches.find((x) => x.repository === repo && x.name === name)!;
     }
     const protect = req.method === 'PUT';
-    await applyTwinWrite(SERVICE, { operation: protect ? 'branch.protect' : 'branch.unprotect', subjectType: 'branch', subjectId: `branch:${repo}#${name}`, fields: { repository: repo, name, commit_sha: b.commit_sha, protected: protect }, occurredAt, actor: { kind: 'agent' } }, req.root);
+    // Fidelity: real GitHub 422s a protection PUT unless ALL FOUR keys are present
+    // (required_status_checks / enforce_admins / required_pull_request_reviews /
+    // restrictions — each nullable, but never omittable).
+    if (protect) {
+      const missingKeys = (['required_status_checks', 'enforce_admins', 'required_pull_request_reviews', 'restrictions'] as const)
+        .filter((k) => !(k in body));
+      if (missingKeys.length) {
+        return { response: { status: 422, body: { message: 'Validation Failed', errors: missingKeys.map((field) => ({ resource: 'BranchProtection', field, code: 'missing_field' })) } } };
+      }
+    }
+    const protection_config = protect
+      ? {
+          required_status_checks: normalizeRequiredStatusChecks(body.required_status_checks),
+          enforce_admins: body.enforce_admins === true,
+          required_pull_request_reviews: body.required_pull_request_reviews && typeof body.required_pull_request_reviews === 'object' ? (body.required_pull_request_reviews as Record<string, unknown>) : null,
+          restrictions: body.restrictions && typeof body.restrictions === 'object' ? (body.restrictions as Record<string, unknown>) : null,
+        }
+      : null;
+    await applyTwinWrite(SERVICE, { operation: protect ? 'branch.protect' : 'branch.unprotect', subjectType: 'branch', subjectId: `branch:${repo}#${name}`, fields: { repository: repo, name, commit_sha: b.commit_sha, protected: protect, protection_config }, occurredAt, actor: { kind: 'agent' } }, req.root);
     if (!protect) return { response: { status: 204, body: undefined } };
-    return { response: { status: 200, body: { url: `https://api.github.com/repos/${repo}/branches/${encodeURIComponent(name)}/protection`, enabled: true, required_status_checks: { enforcement_level: 'everyone', contexts: [] } } } };
+    const after = githubState(req.root).branches.find((x) => x.repository === repo && x.name === name)!;
+    return { response: { status: 200, body: toGithubBranchProtection(after) } };
+  }
+  // PATCH /repos/:o/:r/branches/:branch/protection/required_status_checks → update the
+  // required-check config on an already-protected branch (404 when not protected, like GitHub).
+  if (req.method === 'PATCH' && seg[3] === 'branches' && seg[4] && seg[5] === 'protection' && seg[6] === 'required_status_checks' && !seg[7]) {
+    const name = decodeURIComponent(seg[4]!);
+    const b = githubState(req.root).branches.find((x) => x.repository === repo && x.name === name);
+    if (!b?.protected) return { response: githubNotFound() };
+    const prev = b.protection_config?.required_status_checks ?? { strict: false, contexts: [], checks: [] };
+    const next = normalizeRequiredStatusChecks({ strict: body.strict ?? prev.strict, contexts: body.contexts ?? (body.checks === undefined ? prev.contexts : undefined), checks: body.checks })!;
+    const protection_config = { ...(b.protection_config ?? {}), required_status_checks: next };
+    await applyTwinWrite(SERVICE, { operation: 'branch.protect', subjectType: 'branch', subjectId: `branch:${repo}#${name}`, fields: { repository: repo, name, commit_sha: b.commit_sha, protected: true, protection_config }, occurredAt, actor: { kind: 'agent' } }, req.root);
+    const base = `https://api.github.com/repos/${repo}/branches/${encodeURIComponent(name)}/protection`;
+    return { response: { status: 200, body: { url: `${base}/required_status_checks`, strict: next.strict, contexts: next.contexts, contexts_url: `${base}/required_status_checks/contexts`, checks: next.checks } } };
+  }
+  // POST/DELETE /repos/:o/:r/branches/:branch/protection/enforce_admins → toggle admin
+  // enforcement on a protected branch (the enforce_admins:true the twin-sdlc gate provisions).
+  if (seg[3] === 'branches' && seg[4] && seg[5] === 'protection' && seg[6] === 'enforce_admins' && !seg[7] && (req.method === 'POST' || req.method === 'DELETE')) {
+    const name = decodeURIComponent(seg[4]!);
+    const b = githubState(req.root).branches.find((x) => x.repository === repo && x.name === name);
+    if (!b?.protected) return { response: githubNotFound() };
+    const enabled = req.method === 'POST';
+    const protection_config = { ...(b.protection_config ?? {}), enforce_admins: enabled };
+    await applyTwinWrite(SERVICE, { operation: 'branch.protect', subjectType: 'branch', subjectId: `branch:${repo}#${name}`, fields: { repository: repo, name, commit_sha: b.commit_sha, protected: true, protection_config }, occurredAt, actor: { kind: 'agent' } }, req.root);
+    if (!enabled) return { response: { status: 204, body: undefined } };
+    return { response: { status: 200, body: { url: `https://api.github.com/repos/${repo}/branches/${encodeURIComponent(name)}/protection/enforce_admins`, enabled } } };
   }
   // ── Collaborators: PUT/DELETE /repos/:o/:r/collaborators/:login ──────────────────────────
   if (seg[3] === 'collaborators' && seg[4] && (req.method === 'PUT' || req.method === 'DELETE')) {
@@ -5486,25 +6147,48 @@ export async function applyGithubWrite(req: {
   }
 
   // ── Git Data API writes (refs/commits/trees/blobs/annotated tags) ──────────────────────────
+  // Re-backed by the REAL git plane (github-git-plane.ts): each create writes a REAL git
+  // object into the repo's bare repo and returns the REAL git sha, so a REST-authored chain
+  // (blob → tree → commit → ref) is byte-for-byte fetchable by an unmodified `git` client.
+  // The kernel event log still records every write (the control-plane ledger the projection,
+  // mirror and webhooks fold), but the OBJECT store is the bare repo — one store, not two.
+  // An owner/name the plane's path validation rejects can never name a twin repo: answer the
+  // vendor-shaped 404 up front rather than letting bareRepoDir throw into a 500.
+  if (seg[3] === 'git' && (!/^[A-Za-z0-9_.-]+$/.test(seg[1]!) || !/^[A-Za-z0-9_.-]+$/.test(seg[2]!) || ['.', '..'].includes(seg[1]!) || ['.', '..'].includes(seg[2]!))) {
+    return { response: githubNotFound() };
+  }
   // POST .../git/blobs  → create a blob object (content base64). Returns {sha,url}.
   if (req.method === 'POST' && seg[3] === 'git' && seg[4] === 'blobs' && !seg[5]) {
     if (body.content === undefined) return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'Blob', field: 'content', code: 'missing_field' }] } } };
     const encoding = String(body.encoding ?? 'utf-8');
     const content_b64 = encoding === 'base64' ? String(body.content) : Buffer.from(String(body.content), 'utf-8').toString('base64');
     let size = 0; try { size = Buffer.from(content_b64, 'base64').length; } catch { size = content_b64.length; }
-    const sha = createHash('sha256').update(`${repo}:blob:${content_b64}`).digest('hex').slice(0, 40);
+    const sha = writeGitBlobToPlane(repo, content_b64, req.root); // REAL git sha (hash-object -w)
     await applyTwinWrite(SERVICE, { operation: 'git_blob.create', subjectType: 'git_blob', subjectId: `gitblob:${repo}#${sha}`, fields: { repository: repo, sha, content_b64, size, encoding: 'base64' }, occurredAt, actor: { kind: 'agent' } }, req.root);
     return { response: { status: 201, body: { sha, url: `https://api.github.com/repos/${repo}/git/blobs/${sha}` } } };
   }
-  // POST .../git/trees  → create a tree object from {tree:[{path,mode,type,sha}]}.
+  // POST .../git/trees  → create a tree object from {tree:[{path,mode,type,sha}]}, with
+  //   base_tree overlay semantics (an entry with sha:null deletes its path) like real GitHub.
   if (req.method === 'POST' && seg[3] === 'git' && seg[4] === 'trees' && !seg[5]) {
     if (!Array.isArray(body.tree)) return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'Tree', field: 'tree', code: 'missing_field' }] } } };
     const entries: GithubGitTreeEntry[] = (body.tree as Array<Record<string, unknown>>).map((e) => ({
-      path: String(e.path ?? ''), mode: String(e.mode ?? '100644'), type: String(e.type ?? 'blob'), sha: String(e.sha ?? ''),
+      path: String(e.path ?? ''), mode: String(e.mode ?? '100644'), type: String(e.type ?? 'blob'), sha: e.sha === null ? '' : String(e.sha ?? ''),
       ...(e.size !== undefined ? { size: Number(e.size) } : {}),
     }));
-    const sha = createHash('sha256').update(`${repo}:tree:${JSON.stringify(entries)}:${body.base_tree ?? ''}`).digest('hex').slice(0, 40);
-    await applyTwinWrite(SERVICE, { operation: 'git_tree.create', subjectType: 'git_tree', subjectId: `gittree:${repo}#${sha}`, fields: { repository: repo, sha, tree: entries, truncated: false }, occurredAt, actor: { kind: 'agent' } }, req.root);
+    // Fidelity: entry shas must be 40-hex (sha:null deletes a base_tree path; both real).
+    if (entries.some((e) => e.sha !== '' && !/^[0-9a-f]{40}$/i.test(e.sha))) {
+      return { response: { status: 422, body: { message: 'The sha parameter must be exactly 40 characters and contain only [0-9a-f]' } } };
+    }
+    // Fidelity: a base_tree naming a tree the store does not hold is a 422 (real GitHub) —
+    // silently dropping the base would LOSE the base's entries in the produced tree.
+    if (body.base_tree !== undefined
+      && (!/^[0-9a-f]{40}$/i.test(String(body.base_tree)) || objectTypeInPlane(repo, String(body.base_tree), req.root) !== 'tree')) {
+      return { response: { status: 422, body: { message: `The base tree parameter (${String(body.base_tree)}) is not a valid tree` } } };
+    }
+    const sha = writeGitTreeToPlane(repo, entries, body.base_tree !== undefined ? String(body.base_tree) : undefined, req.root); // REAL git sha (mktree)
+    // The kernel row records the REAL tree listing the plane now holds (post-overlay).
+    const planeTree = readGitTreeFromPlane(repo, sha, req.root) ?? entries.filter((e) => e.sha);
+    await applyTwinWrite(SERVICE, { operation: 'git_tree.create', subjectType: 'git_tree', subjectId: `gittree:${repo}#${sha}`, fields: { repository: repo, sha, tree: planeTree, truncated: false }, occurredAt, actor: { kind: 'agent' } }, req.root);
     const t = githubState(req.root).gitTrees.find((x) => x.repository === repo && x.sha === sha)!;
     return { response: { status: 201, body: toGithubGitTree(t) } };
   }
@@ -5513,8 +6197,27 @@ export async function applyGithubWrite(req: {
     const missing = (['message', 'tree'] as const).filter((k) => body[k] === undefined);
     if (missing.length) return { response: { status: 422, body: { message: 'Validation Failed', errors: missing.map((field) => ({ resource: 'Commit', field, code: 'missing_field' })) } } };
     const parents = Array.isArray(body.parents) ? (body.parents as unknown[]).map(String) : [];
-    const sha = createHash('sha256').update(`${repo}:commit:${body.message}:${body.tree}:${parents.join(',')}`).digest('hex').slice(0, 40);
-    const fields = { repository: repo, sha, message: String(body.message), tree_sha: String(body.tree), parents, author_name: body.author?.name, author_email: body.author?.email, created_at: occurredAt };
+    // Fidelity: a git sha is 40 hex chars — real GitHub 422s a malformed tree/parent sha
+    // (and real git refuses to frame a commit around one).
+    if (!/^[0-9a-f]{40}$/i.test(String(body.tree)) || parents.some((p) => !/^[0-9a-f]{40}$/i.test(p))) {
+      return { response: { status: 422, body: { message: 'The tree and parent parameters must be exactly 40 characters and contain only [0-9a-f]' } } };
+    }
+    const author = body.author?.name !== undefined || body.author?.email !== undefined
+      ? { name: String(body.author?.name ?? 'github-twin'), email: String(body.author?.email ?? 'github-twin@localhost') }
+      : undefined;
+    const committer = body.committer?.name !== undefined || body.committer?.email !== undefined
+      ? { name: String(body.committer?.name ?? 'github-twin'), email: String(body.committer?.email ?? 'github-twin@localhost') }
+      : undefined;
+    // REAL git sha: the commit object is framed and stored by git itself. author.date (when
+    // given) pins the sha exactly as real GitHub honors it; otherwise the write time does.
+    const sha = writeGitCommitToPlane(repo, {
+      message: String(body.message), treeSha: String(body.tree), parents,
+      ...(author !== undefined ? { author } : {}), ...(committer !== undefined ? { committer } : {}),
+      occurredAt: String(body.author?.date ?? body.committer?.date ?? occurredAt),
+    }, req.root);
+    // The kernel row records the SAME identity the object bytes carry (the twin ident when
+    // the caller supplied none) — REST rendering and `git cat-file` must agree.
+    const fields = { repository: repo, sha, message: String(body.message), tree_sha: String(body.tree), parents, author_name: body.author?.name ?? 'github-twin', author_email: body.author?.email ?? 'github-twin@localhost', created_at: occurredAt };
     await applyTwinWrite(SERVICE, { operation: 'git_commit.create', subjectType: 'git_commit', subjectId: `gitcommit:${repo}#${sha}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
     const c = githubState(req.root).gitCommits.find((x) => x.repository === repo && x.sha === sha)!;
     return { response: { status: 201, body: toGithubGitCommit(c) } };
@@ -5523,7 +6226,14 @@ export async function applyGithubWrite(req: {
   if (req.method === 'POST' && seg[3] === 'git' && seg[4] === 'tags' && !seg[5]) {
     const missing = (['tag', 'message', 'object'] as const).filter((k) => body[k] === undefined);
     if (missing.length) return { response: { status: 422, body: { message: 'Validation Failed', errors: missing.map((field) => ({ resource: 'Tag', field, code: 'missing_field' })) } } };
-    const sha = createHash('sha256').update(`${repo}:tagobj:${body.tag}:${body.object}`).digest('hex').slice(0, 40);
+    if (!/^[0-9a-f]{40}$/i.test(String(body.object))) return { response: { status: 422, body: { message: 'The object parameter must be exactly 40 characters and contain only [0-9a-f]' } } };
+    const tagger = body.tagger?.name !== undefined || body.tagger?.email !== undefined
+      ? { name: String(body.tagger?.name ?? 'github-twin'), email: String(body.tagger?.email ?? 'github-twin@localhost') }
+      : undefined;
+    const sha = writeGitTagToPlane(repo, {
+      tag: String(body.tag), message: String(body.message), objectSha: String(body.object), objectType: String(body.type ?? 'commit'),
+      ...(tagger !== undefined ? { tagger } : {}), occurredAt: String(body.tagger?.date ?? occurredAt),
+    }, req.root); // REAL git sha
     const fields = { repository: repo, sha, tag: String(body.tag), message: String(body.message), object_sha: String(body.object), object_type: String(body.type ?? 'commit'), tagger_name: body.tagger?.name, created_at: occurredAt };
     await applyTwinWrite(SERVICE, { operation: 'git_tag_object.create', subjectType: 'git_tag_object', subjectId: `gittag:${repo}#${sha}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
     const t = githubState(req.root).gitTagObjects.find((x) => x.repository === repo && x.sha === sha)!;
@@ -5537,10 +6247,26 @@ export async function applyGithubWrite(req: {
     const refName = String(body.ref);
     if (!refName.startsWith('refs/')) return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'Reference', field: 'ref', code: 'invalid' }] } } };
     if (githubState(req.root).gitRefs.some((x) => x.repository === repo && x.ref === refName)) return { response: { status: 422, body: { message: 'Reference already exists' } } };
-    const object_type = refName.startsWith('refs/tags/') && githubState(req.root).gitTagObjects.some((t) => t.repository === repo && t.sha === String(body.sha)) ? 'tag' : 'commit';
+    const planeType = objectTypeInPlane(repo, String(body.sha), req.root);
+    const object_type = planeType === 'tag' || (refName.startsWith('refs/tags/') && githubState(req.root).gitTagObjects.some((t) => t.repository === repo && t.sha === String(body.sha))) ? 'tag' : 'commit';
     await applyTwinWrite(SERVICE, { operation: 'git_ref.create', subjectType: 'git_ref', subjectId: `gitref:${repo}#${refName}`, fields: { repository: repo, ref: refName, object_sha: String(body.sha), object_type }, occurredAt, actor: { kind: 'agent' } }, req.root);
+    // Materialize into the git plane when the object exists there — the REST-created ref is
+    // then FETCHABLE by a real git client (git plane ↔ control plane agreement). A ref minted
+    // against a sha the plane has never seen stays control-plane-only (lenient legacy surface).
+    updateGitRefInPlane(repo, refName, String(body.sha), req.root);
+    // REST and receive-pack CONVERGE: a branch ref create also lands the branch row (so
+    // GET /branches sees it), re-points any open PR riding the branch, and fires the SAME
+    // event stream a push does (an API ref write IS a push on real GitHub).
+    const createEvents: GithubWriteEvent[] = [{ event: 'push', action: '', repository: repo, number: 0, ref: refName, before: '0'.repeat(40), after: String(body.sha) }];
+    if (refName.startsWith('refs/heads/')) {
+      const branchNm = refName.slice('refs/heads/'.length);
+      await applyTwinWrite(SERVICE, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${repo}#${branchNm}`, fields: { repository: repo, name: branchNm, commit_sha: String(body.sha) }, occurredAt, actor: { kind: 'agent' } }, req.root);
+      for (const n of await syncPrHeadsToBranchTip(repo, branchNm, String(body.sha), req.root, occurredAt)) {
+        createEvents.push({ event: 'pull_request', action: 'synchronize', repository: repo, number: n });
+      }
+    }
     const r = githubState(req.root).gitRefs.find((x) => x.repository === repo && x.ref === refName)!;
-    return { response: { status: 201, body: toGithubGitRef(r) } };
+    return { response: { status: 201, body: toGithubGitRef(r) }, webhooks: createEvents };
   }
   // PATCH .../git/refs/:ref  → fast-forward/force-update a ref's sha. 404 if absent.
   if (req.method === 'PATCH' && seg[3] === 'git' && seg[4] === 'refs' && seg[5]) {
@@ -5548,9 +6274,30 @@ export async function applyGithubWrite(req: {
     const existing = githubState(req.root).gitRefs.find((x) => x.repository === repo && x.ref === refName);
     if (!existing) return { response: githubNotFound() };
     if (body.sha === undefined) return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'Reference', field: 'sha', code: 'missing_field' }] } } };
+    // Fidelity: a non-fast-forward update needs force:true (GitHub 422s it). Decidable only
+    // when BOTH commits exist in the plane; control-plane-only shas keep the lenient surface.
+    // gh -f sends the STRING "true"; -F sends boolean true. GitHub accepts both.
+    const forceRequested = body.force === true || body.force === 'true';
+    if (!forceRequested
+      && objectExistsInPlane(repo, existing.object_sha, req.root) && objectExistsInPlane(repo, String(body.sha), req.root)
+      && !isAncestorInPlane(repo, existing.object_sha, String(body.sha), req.root)) {
+      return { response: { status: 422, body: { message: 'Update is not a fast forward' } } };
+    }
     await applyTwinWrite(SERVICE, { operation: 'git_ref.update', subjectType: 'git_ref', subjectId: `gitref:${repo}#${refName}`, fields: { repository: repo, ref: refName, object_sha: String(body.sha), object_type: existing.object_type }, occurredAt, actor: { kind: 'agent' } }, req.root);
+    updateGitRefInPlane(repo, refName, String(body.sha), req.root); // fetchable when the object exists in the plane
+    // A head-branch move re-points every open PR riding it (real GitHub: an API ref update IS
+    // a push — the PR head follows and the old head's reviews/approvals stop matching), and
+    // fires the same push/synchronize event stream a receive-pack push does.
+    const updateEvents: GithubWriteEvent[] = [{ event: 'push', action: '', repository: repo, number: 0, ref: refName, before: existing.object_sha, after: String(body.sha) }];
+    if (refName.startsWith('refs/heads/')) {
+      const branchNm = refName.slice('refs/heads/'.length);
+      await applyTwinWrite(SERVICE, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${repo}#${branchNm}`, fields: { repository: repo, name: branchNm, commit_sha: String(body.sha) }, occurredAt, actor: { kind: 'agent' } }, req.root);
+      for (const n of await syncPrHeadsToBranchTip(repo, branchNm, String(body.sha), req.root, occurredAt)) {
+        updateEvents.push({ event: 'pull_request', action: 'synchronize', repository: repo, number: n });
+      }
+    }
     const r = githubState(req.root).gitRefs.find((x) => x.repository === repo && x.ref === refName)!;
-    return { response: { status: 200, body: toGithubGitRef(r) } };
+    return { response: { status: 200, body: toGithubGitRef(r) }, webhooks: updateEvents };
   }
   // DELETE .../git/refs/:ref  → delete a branch/tag ref (204). 404 if absent.
   if (req.method === 'DELETE' && seg[3] === 'git' && seg[4] === 'refs' && seg[5]) {
@@ -5558,7 +6305,20 @@ export async function applyGithubWrite(req: {
     const existing = githubState(req.root).gitRefs.find((x) => x.repository === repo && x.ref === refName);
     if (!existing) return { response: githubNotFound() };
     await applyTwinWrite(SERVICE, { operation: 'git_ref.delete', subjectType: 'git_ref', subjectId: `gitref:${repo}#${refName}`, fields: { repository: repo, ref: refName }, occurredAt, actor: { kind: 'agent' } }, req.root);
-    return { response: { status: 204, body: undefined } };
+    deleteGitRefInPlane(repo, refName, req.root); // keep the plane in agreement
+    // Deleting a branch ref removes the branch row, CLOSES open PRs riding it, and fires the
+    // push(deleted)/closed events — full REST ↔ receive-pack convergence.
+    const deleteEvents: GithubWriteEvent[] = [{ event: 'push', action: '', repository: repo, number: 0, ref: refName, before: existing.object_sha, after: '0'.repeat(40) }];
+    if (refName.startsWith('refs/heads/')) {
+      const branchNm = refName.slice('refs/heads/'.length);
+      if (githubState(req.root).branches.some((b) => b.repository === repo && b.name === branchNm)) {
+        await applyTwinWrite(SERVICE, { operation: 'branch.delete', subjectType: 'branch', subjectId: `branch:${repo}#${branchNm}`, fields: { repository: repo, name: branchNm }, occurredAt, actor: { kind: 'agent' } }, req.root);
+      }
+      for (const n of await closePrsForDeletedBranch(repo, branchNm, req.root, occurredAt)) {
+        deleteEvents.push({ event: 'pull_request', action: 'closed', repository: repo, number: n });
+      }
+    }
+    return { response: { status: 204, body: undefined }, webhooks: deleteEvents };
   }
 
   // ── Deployments writes ─────────────────────────────────────────────────────────────────────
@@ -6355,11 +7115,19 @@ async function applyGithubNonRepoWrite(req: {
     if (!body.name) return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'Repository', field: 'name', code: 'missing_field' }] } } };
     const owner = seg[0] === 'orgs' ? String(seg[1]) : 'octocat';
     const name = String(body.name);
+    // Fidelity: GitHub 422s a repo name outside [A-Za-z0-9_.-] (it would also be unservable
+    // as a bare-repo path).
+    if (!/^[A-Za-z0-9_.-]+$/.test(name) || name === '.' || name === '..' || !/^[A-Za-z0-9_.-]+$/.test(owner)) {
+      return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'Repository', field: 'name', code: 'invalid' }] } } };
+    }
     const full = `${owner}/${name}`;
     if (githubState(req.root).repos.some((r) => r.full_name === full)) return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'Repository', code: 'already_exists', field: 'name' }] } } };
     const seq = nextSeq('repo', req.root);
     const fields = { owner, name, description: body.description ?? null, private: body.private === true, default_branch: body.default_branch ?? 'main', has_issues: body.has_issues ?? true, has_projects: body.has_projects ?? true, has_wiki: body.has_wiki ?? true, has_discussions: body.has_discussions ?? false, homepage: body.homepage ?? null, created_at: occurredAt, updated_at: occurredAt };
     await applyTwinWrite(SERVICE, { operation: 'repository.create', subjectType: 'repository', subjectId: `repo:${seq}`, fields, occurredAt, actor: { kind: 'agent' } }, req.root);
+    // Creating a repo via REST initializes its REAL bare repo (the git plane): the new repo
+    // is immediately clonable (empty) and pushable by an unmodified `git` client.
+    ensureBareRepo(full, req.root, String(fields.default_branch));
     const sha = createHash('sha256').update(`${full}:${fields.default_branch}`).digest('hex').slice(0, 40);
     await applyTwinWrite(SERVICE, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${full}#${fields.default_branch}`, fields: { repository: full, name: fields.default_branch, commit_sha: sha }, occurredAt, actor: { kind: 'agent' } }, req.root);
     const r = githubState(req.root).repos.find((x) => x.full_name === full)!;