@volter/twin-github 0.1.0 → 0.1.1

package/src/github-capabilities.ts

@@ -16,9 +16,34 @@
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { checkCapabilities, uiDataCoupled, type CapabilityReport, type CapabilitySpec } from '@volter/twin-tooling';
-import { githubMirrorState } from './github-mirror-ui.ts';
+import { checkCapabilities, uiDataCoupled, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/twin-tooling';
+import { githubMirrorState } from './github-mirror-state.ts';
 import { applyGithubWrite, handleGithubRequest } from './github-twin.ts';
+import { handleGithubGitSmartHttp } from './github-git-http.ts';
+import { createGithubTwinServer } from './github-server.ts';
+import { clearGithubWebhooks, registerGithubWebhook } from './github-events.ts';
+
+// ── git-plane helpers: spawn the REAL git CLI (async — verifies that also run the twin's
+// HTTP server must keep the event loop free; a spawnSync would deadlock the clone against
+// the in-process server). Local subprocess + 127.0.0.1 only: offline, deterministic, no
+// rate budget. Proxy env is stripped so an active world proxy can never intercept loopback.
+function gitCliEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) if (v !== undefined) env[k] = v;
+  for (const k of ['http_proxy', 'https_proxy', 'all_proxy', 'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY']) delete env[k];
+  Object.assign(env, {
+    NO_PROXY: '*', GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null', GIT_CONFIG_NOSYSTEM: '1',
+    GIT_TERMINAL_PROMPT: '0', GIT_AUTHOR_NAME: 'Cap Verify', GIT_AUTHOR_EMAIL: 'cap@verify.test',
+    GIT_COMMITTER_NAME: 'Cap Verify', GIT_COMMITTER_EMAIL: 'cap@verify.test',
+    GIT_AUTHOR_DATE: '2026-01-02T03:04:05Z', GIT_COMMITTER_DATE: '2026-01-02T03:04:05Z',
+  });
+  return env;
+}
+async function gitc(cwd: string, ...args: string[]): Promise<{ code: number; stdout: string }> {
+  const proc = Bun.spawn({ cmd: ['git', ...args], cwd, stdout: 'pipe', stderr: 'pipe', env: gitCliEnv() });
+  const [code, stdout] = await Promise.all([proc.exited, new Response(proc.stdout).text()]);
+  return { code, stdout: stdout.trim() };
+}
 
 // ── API predicate: run a real verify() against a fresh temp root (mkdtemp), exercising the
 // twin's handleGithubRequest (GET) + applyGithubWrite (POST/PATCH/PUT). Each verify creates
@@ -30,9 +55,7 @@ import { applyGithubWrite, handleGithubRequest } from './github-twin.ts';
 export async function withRoot(fn: (root: string) => Promise<boolean>): Promise<boolean> {
   const root = mkdtempSync(join(tmpdir(), 'gh-cap-'));
   try {
-    return await fn(root);
-  } catch {
-    return false;
+    return await verifyBoundary('github.withRoot', () => fn(root));
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
@@ -112,12 +135,15 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
       const res = await applyGithubWrite({ method: 'PATCH', path: `/repos/${REPO}/pulls/1`, body: JSON.stringify({ title: 'new' }), root });
       return ok(res.response.status) && (res.response.body as { title?: string }).title === 'new';
     })),
-  done('github.pulls.merge', 'pulls', 'PRs: merge (PUT .../pulls/:n/merge → 200 merged)', 'api', 'core', () =>
+  done('github.pulls.merge', 'pulls', 'PRs: merge (PUT .../pulls/:n/merge → 200; optional exact-head sha precondition → 409 after a push)', 'api', 'core', () =>
     withRoot(async (root) => {
       await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls`, body: JSON.stringify({ title: 'm', head: 'a', base: 'main' }), root });
-      const res = await applyGithubWrite({ method: 'PUT', path: `/repos/${REPO}/pulls/1/merge`, body: '{}', root });
+      const pr = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1`, root });
+      const head = (pr.body as { head?: { sha?: string } }).head?.sha;
+      const stale = await applyGithubWrite({ method: 'PUT', path: `/repos/${REPO}/pulls/1/merge`, body: JSON.stringify({ sha: `${head}-stale` }), root });
+      const res = await applyGithubWrite({ method: 'PUT', path: `/repos/${REPO}/pulls/1/merge`, body: JSON.stringify({ sha: head }), root });
       const merged = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1/merge`, root });
-      return ok(res.response.status) && (res.response.body as { merged?: boolean }).merged === true && merged.status === 204;
+      return stale.response.status === 409 && ok(res.response.status) && (res.response.body as { merged?: boolean }).merged === true && merged.status === 204;
     })),
   done('github.pulls.reviews', 'pulls', 'PRs: reviews submit + list (APPROVE/COMMENT/REQUEST_CHANGES)', 'api', 'core', () =>
     withRoot(async (root) => {
@@ -126,12 +152,81 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
       const list = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1/reviews`, root });
       return ok(sub.response.status) && ok(list.status) && isArr(list.body) && list.body.length === 1;
     })),
-  done('github.pulls.review_comments', 'pulls', 'PRs: diff-anchored review comments (path/line/side)', 'api', 'core', () =>
+  done('github.pulls.files_from_git_plane', 'pulls', 'PRs: files/changedFiles derive from the REAL git diff (base tip…head tip in the plane) when the PR carries no diff evidence — merge-gate scope classification reads actual paths, never 0', 'api', 'common', () =>
+    withRoot(async (root) => {
+      // Author base + head commits purely through Git Data REST (real objects, real diff).
+      const mk = async (path: string, content: string, parent?: string, baseTree?: string) => {
+        const b = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/blobs`, body: JSON.stringify({ content: Buffer.from(content).toString('base64'), encoding: 'base64' }), root });
+        const t = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/trees`, body: JSON.stringify({ ...(baseTree ? { base_tree: baseTree } : {}), tree: [{ path, mode: '100644', type: 'blob', sha: (b.response.body as { sha?: string }).sha }] }), root });
+        const c = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/commits`, body: JSON.stringify({ message: `add ${path}`, tree: (t.response.body as { sha?: string }).sha, parents: parent ? [parent] : [] }), root });
+        return { commit: (c.response.body as { sha?: string }).sha!, tree: (t.response.body as { sha?: string }).sha! };
+      };
+      const base = await mk('README.md', 'base\n');
+      const head = await mk('scripts/gate.ts', 'gate\n', base.commit, base.tree);
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/refs`, body: JSON.stringify({ ref: 'refs/heads/main', sha: base.commit }), root });
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/refs`, body: JSON.stringify({ ref: 'refs/heads/feat', sha: head.commit }), root });
+      const pr = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls`, body: JSON.stringify({ title: 'F', head: 'feat', base: 'main' }), root });
+      if (pr.response.status !== 201) return false;
+      // GET /pulls/:n/files answers the REAL one-file diff with status + counts.
+      const files = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1/files`, root });
+      if (!(ok(files.status) && isArr(files.body) && files.body.length === 1)) return false;
+      const f = files.body[0] as { filename?: string; status?: string; additions?: number };
+      if (!(f.filename === 'scripts/gate.ts' && f.status === 'added' && f.additions === 1)) return false;
+      // GraphQL changedFiles agrees (the field human-approval-gate cross-checks completeness against).
+      const gq = await applyGithubWrite({ method: 'POST', path: '/graphql', body: JSON.stringify({ query: `query { repository(owner: "octo", name: "demo") { pullRequest(number: 1) { changedFiles } } }` }), root });
+      const cf = ((gq.response.body as { data?: { repository?: { pullRequest?: { changedFiles?: number } } } }).data)?.repository?.pullRequest?.changedFiles;
+      if (cf !== 1) return false;
+      // THREE-DOT semantics (the merge-gate load-bearing half): advance the BASE branch past
+      // the PR's branch point — the PR's file list must stay ITS OWN one file, never inherit
+      // the base's new paths as phantom "removed" entries (a two-dot diff would).
+      const advance = await mk('docs/onmain.md', 'later\n', base.commit, base.tree);
+      const ff = await applyGithubWrite({ method: 'PATCH', path: `/repos/${REPO}/git/refs/heads/main`, body: JSON.stringify({ sha: advance.commit }), root });
+      if (ff.response.status !== 200) return false;
+      const after = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1/files`, root });
+      if (!(ok(after.status) && isArr(after.body) && after.body.length === 1)) return false;
+      return (after.body[0] as { filename?: string }).filename === 'scripts/gate.ts';
+    })),
+  done('github.pulls.review_head_sha_binding', 'pulls', 'PRs: a review binds commit_id to the EXACT head sha at submission; a later push moves the PR head, the review stays where it was', 'api', 'core', () =>
+    withRoot(async (root) => {
+      // Register a head-branch tip, open a PR on it, review it: commit_id == that tip.
+      const shaA = 'a'.repeat(40);
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/refs`, body: JSON.stringify({ ref: 'refs/heads/feat', sha: shaA }), root });
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls`, body: JSON.stringify({ title: 'B', head: 'feat', base: 'main' }), root });
+      const r1 = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls/1/reviews`, body: JSON.stringify({ event: 'APPROVE', body: 'lgtm' }), root });
+      if (!(ok(r1.response.status) && (r1.response.body as { commit_id?: string }).commit_id === shaA)) return false;
+      // "Push" (an API ref move IS a push): the PR head follows, the OLD review's commit_id
+      // does NOT — the exact-head re-earn semantics merge gates depend on.
+      const shaB = 'b'.repeat(40);
+      const upd = await applyGithubWrite({ method: 'PATCH', path: `/repos/${REPO}/git/refs/heads/feat`, body: JSON.stringify({ sha: shaB }), root });
+      if (upd.response.status !== 200) return false;
+      const pr = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1`, root });
+      if ((pr.body as { head?: { sha?: string } }).head?.sha !== shaB) return false;
+      const list = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1/reviews`, root });
+      const first = (list.body as Array<{ commit_id?: string }>)[0]!;
+      if (first.commit_id !== shaA) return false; // pinned to the head it judged
+      // A fresh review binds the NEW head; a caller-pinned commit_id is honored verbatim.
+      const r2 = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls/1/reviews`, body: JSON.stringify({ event: 'APPROVE' }), root });
+      if ((r2.response.body as { commit_id?: string }).commit_id !== shaB) return false;
+      const r3 = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls/1/reviews`, body: JSON.stringify({ event: 'COMMENT', commit_id: shaA }), root });
+      return (r3.response.body as { commit_id?: string }).commit_id === shaA;
+    })),
+  done('github.pulls.review_comments', 'pulls', 'PRs: diff-anchored review comments (write, list, reply)', 'api', 'core', () =>
     withRoot(async (root) => {
       await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls`, body: JSON.stringify({ title: 'c', head: 'a', base: 'main' }), root });
       const c = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls/1/comments`, body: JSON.stringify({ body: 'nit', path: 'a.ts', line: 10, side: 'RIGHT' }), root });
       const list = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1/comments`, root });
-      return c.response.status === 201 && ok(list.status) && isArr(list.body) && (list.body[0] as { path?: string }).path === 'a.ts';
+      if (!(c.response.status === 201 && ok(list.status) && isArr(list.body) && (list.body[0] as { path?: string }).path === 'a.ts')) return false;
+      // The READ is how a seat finds a finding, and the REPLY is how it answers one: GitHub's
+      // own reply route takes the comment id alone and inherits the root's diff anchor.
+      const cid = (c.response.body as { id?: number }).id!;
+      const reply = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls/1/comments/${cid}/replies`, body: JSON.stringify({ body: 'fixed in b3f1' }), root });
+      const replied = reply.response.body as { in_reply_to_id?: number; path?: string };
+      if (!(reply.response.status === 201 && replied.in_reply_to_id === cid && replied.path === 'a.ts')) return false;
+      // a reply to a comment that isn't there is a 404, not a new thread
+      const orphan = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls/1/comments/99999/replies`, body: JSON.stringify({ body: 'nobody home' }), root });
+      if (orphan.response.status !== 404) return false;
+      const after = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1/comments`, root });
+      return isArr(after.body) && after.body.length === 2 && (after.body[1] as { in_reply_to_id?: number }).in_reply_to_id === cid;
     })),
   done('github.pulls.requested_reviewers', 'pulls', 'PRs: request/remove reviewers', 'api', 'core', () =>
     withRoot(async (root) => {
@@ -558,7 +653,10 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
   done('github.repos.branch_protection', 'repos', 'Repos: branch protection rules + rulesets', 'api', 'niche', () =>
     withRoot(async (root) => {
       await applyGithubWrite({ method: 'POST', path: `/orgs/octo/repos`, body: JSON.stringify({ name: 'demo' }), root });
-      const p = await applyGithubWrite({ method: 'PUT', path: `/repos/octo/demo/branches/main/protection`, body: JSON.stringify({ required_status_checks: null }), root });
+      // Real GitHub 422s a protection PUT missing any of the four required (nullable) keys.
+      const partial = await applyGithubWrite({ method: 'PUT', path: `/repos/octo/demo/branches/main/protection`, body: JSON.stringify({ required_status_checks: null }), root });
+      if (partial.response.status !== 422) return false;
+      const p = await applyGithubWrite({ method: 'PUT', path: `/repos/octo/demo/branches/main/protection`, body: JSON.stringify({ required_status_checks: null, enforce_admins: false, required_pull_request_reviews: null, restrictions: null }), root });
       if (!(ok(p.response.status) && (p.response.body as { enabled?: boolean }).enabled === true)) return false;
       const b = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main`, root });
       if ((b.body as { protected?: boolean }).protected !== true) return false;
@@ -566,6 +664,50 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
       const after = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main`, root });
       return d.response.status === 204 && (after.body as { protected?: boolean }).protected === false;
     })),
+  done('github.repos.branch_protection_required_checks', 'repos', 'Repos: branch protection PERSISTS its config — required-check contexts, strict, enforce_admins — and serves it back (the merge-gate read path)', 'api', 'common', () =>
+    withRoot(async (root) => {
+      await applyGithubWrite({ method: 'POST', path: `/orgs/octo/repos`, body: JSON.stringify({ name: 'demo' }), root });
+      // GET protection on an unprotected branch → GitHub's 404 "Branch not protected".
+      const bare = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main/protection`, root });
+      if (!(bare.status === 404 && (bare.body as { message?: string }).message === 'Branch not protected')) return false;
+      // PUT the twin-sdlc-shaped config: four required contexts + enforce_admins.
+      const put = await applyGithubWrite({ method: 'PUT', path: `/repos/octo/demo/branches/main/protection`, body: JSON.stringify({
+        required_status_checks: { strict: false, contexts: ['test', 'agent-review', 'security', 'human-approval'] },
+        enforce_admins: true, required_pull_request_reviews: null, restrictions: null,
+      }), root });
+      const putBody = put.response.body as { required_status_checks?: { contexts?: string[] }; enforce_admins?: { enabled?: boolean } };
+      if (!(ok(put.response.status) && putBody.required_status_checks?.contexts?.length === 4 && putBody.enforce_admins?.enabled === true)) return false;
+      // The BRANCH summary carries the persisted contexts + the real enforcement_level
+      // semantics (everyone == enforce_admins) — exactly what review-prerequisites.ts reads.
+      const branch = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main`, root });
+      const prot = (branch.body as { protection?: { required_status_checks?: { contexts?: string[]; enforcement_level?: string } } }).protection;
+      if (!(prot?.required_status_checks?.contexts?.includes('agent-review') && prot.required_status_checks.enforcement_level === 'everyone')) return false;
+      // Sub-resource reads + PATCH round-trip; enforce_admins DELETE flips the level.
+      const rsc = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main/protection/required_status_checks`, root });
+      if (!(ok(rsc.status) && (rsc.body as { contexts?: string[] }).contexts?.length === 4 && (rsc.body as { strict?: boolean }).strict === false)) return false;
+      const patched = await applyGithubWrite({ method: 'PATCH', path: `/repos/octo/demo/branches/main/protection/required_status_checks`, body: JSON.stringify({ strict: true, contexts: ['test'] }), root });
+      if (!(ok(patched.response.status) && (patched.response.body as { strict?: boolean }).strict === true && (patched.response.body as { contexts?: string[] }).contexts?.length === 1)) return false;
+      const dropAdmins = await applyGithubWrite({ method: 'DELETE', path: `/repos/octo/demo/branches/main/protection/enforce_admins`, root });
+      if (dropAdmins.response.status !== 204) return false;
+      const after = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main`, root });
+      const lvl = (after.body as { protection?: { required_status_checks?: { enforcement_level?: string } } }).protection?.required_status_checks?.enforcement_level;
+      if (lvl !== 'non_admins') return false;
+      // Protection SURVIVES a branch delete→re-create (real GitHub: classic protection is a
+      // repo-level pattern rule — deleting `main` and re-pushing it comes back protected).
+      const mainSha = (handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main`, root }).body as { commit?: { sha?: string } }).commit?.sha ?? 'a'.repeat(40);
+      await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/git/refs`, body: JSON.stringify({ ref: 'refs/heads/main', sha: mainSha }), root });
+      const delRef = await applyGithubWrite({ method: 'DELETE', path: `/repos/octo/demo/git/refs/heads/main`, root });
+      if (delRef.response.status !== 204) return false;
+      const recreate = await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/git/refs`, body: JSON.stringify({ ref: 'refs/heads/main', sha: 'b'.repeat(40) }), root });
+      if (recreate.response.status !== 201) return false;
+      const survived = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main/protection`, root });
+      if (!(ok(survived.status) && ((survived.body as { required_status_checks?: { contexts?: string[] } }).required_status_checks?.contexts?.length === 1))) return false;
+      // DELETE protection → the summary reads off again (and protection GET 404s).
+      await applyGithubWrite({ method: 'DELETE', path: `/repos/octo/demo/branches/main/protection`, root });
+      const off = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main/protection`, root });
+      return off.status === 404;
+    })),
+  todo('github.repos.protection_required_reviews_enforced', 'repos', 'Repos: required_pull_request_reviews ENFORCED on merge (config persists; merge does not yet refuse on it)', 'api', 'niche'),
   done('github.repos.collaborators', 'repos', 'Repos: collaborators + permissions', 'api', 'common', () =>
     withRoot(async (root) => {
       const add = await applyGithubWrite({ method: 'PUT', path: `/repos/${REPO}/collaborators/alice`, body: JSON.stringify({ permission: 'maintain' }), root });
@@ -650,17 +792,31 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
       if (!(ok(list.status) && isArr(list.body) && list.body.length === 1)) return false;
       const del = await applyGithubWrite({ method: 'DELETE', path: `/repos/${REPO}/git/refs/heads/feat`, root });
       const gone = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/git/ref/heads/feat`, root });
-      return del.response.status === 204 && gone.status === 404;
-    })),
-  done('github.git.commits', 'git', 'Git Data: commit objects (get/create)', 'api', 'niche', () =>
-    withRoot(async (root) => {
-      const tree = 't'.repeat(40);
-      // missing required fields → 422.
+      if (!(del.response.status === 204 && gone.status === 404)) return false;
+      // Dirty-state pin (§9): delete → RE-CREATE must resurrect, not stay tombstoned forever
+      // (the delete→re-push flow; a permanent tombstone once made recreated refs invisible
+      // to REST while the git plane served them). Re-created at a DIFFERENT sha than the ref
+      // ever held, so a stale row surviving in the fold cannot satisfy this by accident.
+      const sha3 = 'c'.repeat(40);
+      const again = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/refs`, body: JSON.stringify({ ref: 'refs/heads/feat', sha: sha3 }), root });
+      if (again.response.status !== 201) return false;
+      const back = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/git/ref/heads/feat`, root });
+      return ok(back.status) && (back.body as { object?: { sha?: string } }).object?.sha === sha3;
+    })),
+  done('github.git.commits', 'git', 'Git Data: commit objects (get/create; REAL git shas)', 'api', 'niche', () =>
+    withRoot(async (root) => {
+      const tree = 'f'.repeat(40);
+      // missing required fields → 422; a MALFORMED (non-hex) tree sha → 422 like real GitHub
+      // (and like real git, which now frames+stores the object — see github-git-plane.ts).
       const bad = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/commits`, body: JSON.stringify({ message: 'x' }), root });
       if (bad.response.status !== 422) return false;
-      const c = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/commits`, body: JSON.stringify({ message: 'init', tree, parents: ['p'.repeat(40)], author: { name: 'Ann', email: 'a@x' } }), root });
+      const malformed = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/commits`, body: JSON.stringify({ message: 'x', tree: 't'.repeat(40) }), root });
+      if (malformed.response.status !== 422) return false;
+      const c = await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/commits`, body: JSON.stringify({ message: 'init', tree, parents: ['e'.repeat(40)], author: { name: 'Ann', email: 'a@x' } }), root });
       if (!(c.response.status === 201 && (c.response.body as { message?: string }).message === 'init')) return false;
       const sha = (c.response.body as { sha?: string }).sha!;
+      // The sha is a REAL git object id (the plane stored a real commit object under it).
+      if (!/^[0-9a-f]{40}$/.test(sha)) return false;
       const get = handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/git/commits/${sha}`, root });
       const b = get.body as { tree?: { sha?: string }; parents?: unknown[]; author?: { name?: string } };
       return ok(get.status) && b.tree?.sha === tree && b.parents?.length === 1 && b.author?.name === 'Ann';
@@ -705,6 +861,160 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
       return ref.response.status === 201 && (ref.response.body as { object?: { type?: string } }).object?.type === 'tag';
     })),
 
+  // ── Git smart-HTTP (the REAL git plane: bare repos + spawned git, github-git-plane.ts) ───
+  done('github.git.smart_http_discovery', 'git', 'Git smart-HTTP: info/refs service advertisement (pkt-line framing per gitprotocol-http)', 'api', 'core', () =>
+    withRoot(async (root) => {
+      // Unknown repo → the vendor-shaped 404 miss.
+      const missing = await handleGithubGitSmartHttp({ method: 'GET', pathname: '/octo/absent.git/info/refs', query: new URLSearchParams('service=git-upload-pack'), root });
+      if (missing?.status !== 404) return false;
+      // No service param → 403 (dumb HTTP refused — git http-backend's own status for it).
+      await applyGithubWrite({ method: 'POST', path: '/orgs/octo/repos', body: JSON.stringify({ name: 'demo' }), root });
+      const dumb = await handleGithubGitSmartHttp({ method: 'GET', pathname: '/octo/demo/info/refs', root });
+      if (dumb?.status !== 403) return false;
+      // Author a real chain so the advertisement carries a REF (git's own output, not just
+      // the twin-written prefix — a saboteur echoing only the prefix must fail this).
+      const blob = await applyGithubWrite({ method: 'POST', path: '/repos/octo/demo/git/blobs', body: JSON.stringify({ content: 'YWR2', encoding: 'base64' }), root });
+      const tree = await applyGithubWrite({ method: 'POST', path: '/repos/octo/demo/git/trees', body: JSON.stringify({ tree: [{ path: 'a', mode: '100644', type: 'blob', sha: (blob.response.body as { sha?: string }).sha }] }), root });
+      const commit = await applyGithubWrite({ method: 'POST', path: '/repos/octo/demo/git/commits', body: JSON.stringify({ message: 'adv', tree: (tree.response.body as { sha?: string }).sha }), root });
+      const commitSha = (commit.response.body as { sha?: string }).sha!;
+      if ((await applyGithubWrite({ method: 'POST', path: '/repos/octo/demo/git/refs', body: JSON.stringify({ ref: 'refs/heads/main', sha: commitSha }), root })).response.status !== 201) return false;
+      // The advertisement: correct content-type + the DOCUMENTED prefix — one pkt-line
+      // `# service=git-upload-pack\n` (length 001e) then a flush-pkt (0000) — and then GIT'S
+      // OWN payload advertising the materialized ref at its real sha.
+      const adv = await handleGithubGitSmartHttp({ method: 'GET', pathname: '/octo/demo.git/info/refs', query: new URLSearchParams('service=git-upload-pack'), root });
+      if (adv?.status !== 200 || adv.contentType !== 'application/x-git-upload-pack-advertisement') return false;
+      const head = Buffer.from(adv.body.slice(0, 34)).toString('utf8');
+      if (!head.startsWith('001e# service=git-upload-pack\n0000')) return false;
+      const advText = Buffer.from(adv.body).toString('utf8');
+      if (!advText.includes('refs/heads/main') || !advText.includes(commitSha)) return false;
+      // receive-pack advertisement answers too — and a READ-ONLY twin refuses it (403).
+      const rp = await handleGithubGitSmartHttp({ method: 'GET', pathname: '/octo/demo.git/info/refs', query: new URLSearchParams('service=git-receive-pack'), root });
+      if (rp?.status !== 200 || rp.contentType !== 'application/x-git-receive-pack-advertisement') return false;
+      const ro = await handleGithubGitSmartHttp({ method: 'GET', pathname: '/octo/demo.git/info/refs', query: new URLSearchParams('service=git-receive-pack'), root, readOnly: true });
+      return ro?.status === 403;
+    })),
+  done('github.git.smart_http_clone_push', 'git', 'Git smart-HTTP: an UNMODIFIED git CLI clones and pushes; REST refs/commits/branches agree; push fires the push webhook', 'api', 'core', () =>
+    withRoot(async (root) => {
+      const { mkdtempSync: mkTmp, rmSync: rmTmp, writeFileSync: writeTmp } = await import('node:fs');
+      const { tmpdir: osTmp } = await import('node:os');
+      const { join: j } = await import('node:path');
+      const work = mkTmp(j(osTmp(), 'gh-cap-git-'));
+      const server = createGithubTwinServer({ root });
+      const deliveries: Array<Record<string, unknown>> = [];
+      const hook = Bun.serve({ port: 0, async fetch(req) { deliveries.push({ event: req.headers.get('x-github-event'), ...(await req.json() as Record<string, unknown>) }); return new Response('ok'); } });
+      clearGithubWebhooks();
+      registerGithubWebhook(`http://127.0.0.1:${hook.port}/hook`);
+      try {
+        const base = `http://127.0.0.1:${server.port}`;
+        // Creating the repo over REST initializes its REAL bare repo; the clone sees it empty.
+        const created = await fetch(`${base}/orgs/octo/repos`, { method: 'POST', body: JSON.stringify({ name: 'demo' }) });
+        if (created.status !== 201) return false;
+        if ((await gitc(work, 'clone', `${base}/octo/demo.git`, 'c1')).code !== 0) return false;
+        const c1 = j(work, 'c1');
+        writeTmp(j(c1, 'a.txt'), 'clone-push\n');
+        if ((await gitc(c1, 'add', 'a.txt')).code !== 0) return false;
+        if ((await gitc(c1, 'commit', '-m', 'first')).code !== 0) return false;
+        if ((await gitc(c1, 'push', 'origin', 'HEAD:refs/heads/main')).code !== 0) return false;
+        const tip = (await gitc(c1, 'rev-parse', 'HEAD')).stdout;
+        // REST agreement: ref, commit object (plane fallback), branch tip — all the PUSHED sha.
+        const ref = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/git/ref/heads/main`, root });
+        if (!(ok(ref.status) && (ref.body as { object?: { sha?: string } }).object?.sha === tip)) return false;
+        const commit = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/git/commits/${tip}`, root });
+        if (!(ok(commit.status) && (commit.body as { message?: string }).message === 'first')) return false;
+        const branch = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/branches/main`, root });
+        if (!(ok(branch.status) && (branch.body as { commit?: { sha?: string } }).commit?.sha === tip)) return false;
+        // The push rode the EXISTING webhook pipeline: a `push` delivery with ref/before/after.
+        const push = deliveries.find((d) => d.event === 'push' && d.ref === 'refs/heads/main');
+        return push !== undefined && push.before === '0'.repeat(40) && push.after === tip;
+      } finally {
+        server.stop(); hook.stop(true); clearGithubWebhooks(); rmTmp(work, { recursive: true, force: true });
+      }
+    })),
+  done('github.git.rest_authored_chain_fetchable', 'git', 'Git Data REST ↔ protocol agreement: a REST blob→tree→commit→ref chain is fetchable by real git; a dangling ref is NOT advertised', 'api', 'core', () =>
+    withRoot(async (root) => {
+      const { mkdtempSync: mkTmp, rmSync: rmTmp, readFileSync: readTmp } = await import('node:fs');
+      const { tmpdir: osTmp } = await import('node:os');
+      const { join: j } = await import('node:path');
+      const work = mkTmp(j(osTmp(), 'gh-cap-chain-'));
+      const server = createGithubTwinServer({ root });
+      try {
+        const base = `http://127.0.0.1:${server.port}`;
+        await fetch(`${base}/orgs/octo/repos`, { method: 'POST', body: JSON.stringify({ name: 'demo' }) });
+        // Author a commit purely through Git Data REST — REAL git objects, REAL shas.
+        const blob = await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/git/blobs`, body: JSON.stringify({ content: Buffer.from('rest chain\n').toString('base64'), encoding: 'base64' }), root });
+        if (blob.response.status !== 201) return false;
+        const blobSha = (blob.response.body as { sha?: string }).sha!;
+        const tree = await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/git/trees`, body: JSON.stringify({ tree: [{ path: 'chain.txt', mode: '100644', type: 'blob', sha: blobSha }] }), root });
+        if (tree.response.status !== 201) return false;
+        const commit = await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/git/commits`, body: JSON.stringify({ message: 'rest chain', tree: (tree.response.body as { sha?: string }).sha }), root });
+        if (commit.response.status !== 201) return false;
+        const commitSha = (commit.response.body as { sha?: string }).sha!;
+        const mkRef = await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/git/refs`, body: JSON.stringify({ ref: 'refs/heads/feat', sha: commitSha }), root });
+        if (mkRef.response.status !== 201) return false;
+        // A ref minted on a sha NO object backs (lenient legacy surface) stays
+        // control-plane-only: REST serves it, the protocol must NOT advertise it (an
+        // advertised ref must always be clonable).
+        const dangling = await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/git/refs`, body: JSON.stringify({ ref: 'refs/heads/ghost', sha: 'a'.repeat(40) }), root });
+        if (dangling.response.status !== 201) return false;
+        // Sharper still: a commit OBJECT that exists but DANGLES (its tree was never
+        // written — the lenient surface permits it) must also stay un-advertised; existence
+        // alone is not clonability, CONNECTIVITY is (updateGitRefInPlane's rev-list guard).
+        const dCommit = await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/git/commits`, body: JSON.stringify({ message: 'dangling', tree: 'f'.repeat(40) }), root });
+        if (dCommit.response.status !== 201) return false;
+        const ghost2 = await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/git/refs`, body: JSON.stringify({ ref: 'refs/heads/ghost2', sha: (dCommit.response.body as { sha?: string }).sha }), root });
+        if (ghost2.response.status !== 201) return false;
+        const adv = await handleGithubGitSmartHttp({ method: 'GET', pathname: '/octo/demo/info/refs', query: new URLSearchParams('service=git-upload-pack'), root });
+        const advText = Buffer.from(adv!.body).toString('utf8');
+        if (!advText.includes('refs/heads/feat') || advText.includes('refs/heads/ghost')) return false;
+        // Real git clones the REST-authored branch and reads the REST-authored bytes.
+        if ((await gitc(work, 'clone', '--branch', 'feat', `${base}/octo/demo.git`, 'c1')).code !== 0) return false;
+        if ((await gitc(j(work, 'c1'), 'rev-parse', 'HEAD')).stdout !== commitSha) return false;
+        return readTmp(j(work, 'c1', 'chain.txt'), 'utf8') === 'rest chain\n';
+      } finally {
+        server.stop(); rmTmp(work, { recursive: true, force: true });
+      }
+    })),
+  done('github.git.push_synchronizes_pr', 'git', 'Git smart-HTTP: a push to a PR head branch re-points the PR (synchronize) — old-head statuses/reviews stop matching', 'api', 'core', () =>
+    withRoot(async (root) => {
+      const { mkdtempSync: mkTmp, rmSync: rmTmp, writeFileSync: writeTmp } = await import('node:fs');
+      const { tmpdir: osTmp } = await import('node:os');
+      const { join: j } = await import('node:path');
+      const work = mkTmp(j(osTmp(), 'gh-cap-sync-'));
+      const server = createGithubTwinServer({ root });
+      try {
+        const base = `http://127.0.0.1:${server.port}`;
+        await fetch(`${base}/orgs/octo/repos`, { method: 'POST', body: JSON.stringify({ name: 'demo' }) });
+        if ((await gitc(work, 'clone', `${base}/octo/demo.git`, 'c1')).code !== 0) return false;
+        const c1 = j(work, 'c1');
+        writeTmp(j(c1, 'f.txt'), 'one\n');
+        await gitc(c1, 'add', 'f.txt');
+        await gitc(c1, 'commit', '-m', 'one');
+        if ((await gitc(c1, 'push', 'origin', 'HEAD:refs/heads/topic')).code !== 0) return false;
+        const tip1 = (await gitc(c1, 'rev-parse', 'HEAD')).stdout;
+        // Open a PR on the pushed branch — its head is the PUSHED tip.
+        const pr = await applyGithubWrite({ method: 'POST', path: `/repos/octo/demo/pulls`, body: JSON.stringify({ title: 'T', head: 'topic', base: 'main' }), root });
+        if (!(pr.response.status === 201 && (pr.response.body as { head?: { sha?: string } }).head?.sha === tip1)) return false;
+        const n = (pr.response.body as { number?: number }).number!;
+        // Push again: the PR head must FOLLOW (GitHub's synchronize), not stay stale.
+        writeTmp(j(c1, 'f.txt'), 'two\n');
+        await gitc(c1, 'add', 'f.txt');
+        await gitc(c1, 'commit', '-m', 'two');
+        if ((await gitc(c1, 'push', 'origin', 'HEAD:refs/heads/topic')).code !== 0) return false;
+        const tip2 = (await gitc(c1, 'rev-parse', 'HEAD')).stdout;
+        if (tip1 === tip2) return false;
+        const after = handleGithubRequest({ method: 'GET', path: `/repos/octo/demo/pulls/${n}`, root });
+        return ok(after.status) && (after.body as { head?: { sha?: string } }).head?.sha === tip2;
+      } finally {
+        server.stop(); rmTmp(work, { recursive: true, force: true });
+      }
+    })),
+  todo('github.git.protected_branch_push_rules', 'git', 'Git smart-HTTP: receive-pack enforces branch protection (force-push/deletion refusal on protected branches)', 'api', 'niche'),
+  todo('github.repos.contents_backed_by_git_plane', 'repos', 'Repos: the contents API (PUT/DELETE .../contents/:path) writes REAL git objects + moves the branch ref — today it is still a disconnected side-store the git plane never sees', 'api', 'common'),
+  todo('github.git.trees_recursive_param', 'git', 'Git Data: GET .../git/trees/:sha?recursive=1 (full recursive listing)', 'api', 'niche'),
+  todo('github.git.shallow_partial_clone', 'git', 'Git smart-HTTP: shallow (--depth) + partial (--filter) clones asserted end-to-end (upload-pack supports them natively; unasserted)', 'api', 'niche'),
+  todo('github.git.lfs', 'git', 'Git LFS: the batch API + object storage', 'api', 'niche'),
+  todo('github.git.ssh_transport', 'git', 'Git over SSH (port 22 transport + key auth) — smart HTTP is the modeled transport', 'api', 'niche'),
+
   // ── Releases / Tags ──────────────────────────────────────────────────────────────────────
   done('github.releases.crud', 'releases', 'Releases: create/edit/list/get + latest + by-tag', 'api', 'common', () =>
     withRoot(async (root) => {
@@ -1752,6 +2062,76 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
   // ── Next honest gaps (top-down GitHub surface NOT yet modeled — keeps the denominator
   //    honest; a high % against a thin list would be misleading). Each is a real product
   //    area still to close in a future cycle. ─────────────────────────────────────────────────
+  done('github.graphql.pr_view_merge_gate_fields', 'api', 'GraphQL repository.pullRequest(number): the gh pr view --json fields the OA merge-gate scripts read (headRefOid, state, baseRefName, statusCheckRollup, closingIssuesReferences, changedFiles, labels, body)', 'api', 'common', () =>
+    withRoot(async (root) => {
+      // Seed: an issue, a PR whose body closes it, a check run + two commit statuses (the
+      // second supersedes the first — the rollup shows each context ONCE, latest wins).
+      const shaA = 'a'.repeat(40);
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/issues`, body: JSON.stringify({ title: 'bug' }), root });
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/git/refs`, body: JSON.stringify({ ref: 'refs/heads/feat', sha: shaA }), root });
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls`, body: JSON.stringify({ title: 'Fix', head: 'feat', base: 'main', body: 'Closes #1' }), root });
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/check-runs`, body: JSON.stringify({ name: 'test', head_sha: shaA, status: 'completed', conclusion: 'success' }), root });
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/statuses/${shaA}`, body: JSON.stringify({ state: 'pending', context: 'agent-review' }), root });
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/statuses/${shaA}`, body: JSON.stringify({ state: 'success', context: 'agent-review' }), root });
+      await applyGithubWrite({ method: 'PATCH', path: `/repos/${REPO}/pulls/2`, body: JSON.stringify({ labels: ['human-required'] }), root });
+      // The gh-CLI-shaped query (PullRequestByNumber with the --json field selection).
+      const query = `query PullRequestByNumber($owner: String!, $repo: String!, $number: Int!) {
+        repository(owner: $owner, name: $repo) {
+          pullRequest(number: $number) {
+            number state headRefOid baseRefName changedFiles body
+            labels(first: 100) { nodes { name } }
+            closingIssuesReferences(first: 100) { nodes { number } }
+            statusCheckRollup: commits(last: 1) { nodes { commit { statusCheckRollup { state contexts(first: 100) { nodes { __typename ...on StatusContext { context state } ...on CheckRun { name status conclusion } } } } } } }
+          }
+        }
+      }`;
+      const res = await applyGithubWrite({ method: 'POST', path: '/graphql', body: JSON.stringify({ query, variables: { owner: 'octo', repo: 'demo', number: 2 } }), root });
+      const pr = ((res.response.body as { data?: { repository?: { pullRequest?: Record<string, any> } } }).data)?.repository?.pullRequest;
+      if (!pr) return false;
+      if (!(pr.number === 2 && pr.state === 'OPEN' && pr.headRefOid === shaA && pr.baseRefName === 'main' && pr.body === 'Closes #1')) return false;
+      if (pr.labels?.nodes?.[0]?.name !== 'human-required') return false;
+      if (pr.closingIssuesReferences?.nodes?.[0]?.number !== 1) return false;
+      const rollup = pr.statusCheckRollup?.nodes?.[0]?.commit?.statusCheckRollup;
+      if (rollup?.state !== 'SUCCESS') return false; // latest agent-review status won; check run green
+      const ctx = rollup?.contexts?.nodes as Array<Record<string, unknown>>;
+      const run = ctx?.find((c) => c.__typename === 'CheckRun');
+      const st = ctx?.filter((c) => c.__typename === 'StatusContext');
+      if (!(run?.name === 'test' && run.status === 'COMPLETED' && run.conclusion === 'SUCCESS')) return false;
+      if (!(st?.length === 1 && st[0]!.context === 'agent-review' && st[0]!.state === 'SUCCESS')) return false;
+      // An unmodeled PR field stays an HONEST undefinedField error, never a fabricated value.
+      const badQ = `query { repository(owner: "octo", name: "demo") { pullRequest(number: 2) { projectCards { totalCount } } } }`;
+      const bad = await applyGithubWrite({ method: 'POST', path: '/graphql', body: JSON.stringify({ query: badQ }), root });
+      const errs = (bad.response.body as { errors?: Array<{ type?: string }> }).errors;
+      return errs?.[0]?.type === 'undefinedField';
+    })),
+  done('github.graphql.issue_view', 'api', 'GraphQL repository.issue(number): the gh issue view --json fields the gate scripts read (labels for human-approval scope, comments for finalize routing) — and single-node token matching never hijacks a repo NAMED "issue-*"', 'api', 'common', () =>
+    withRoot(async (root) => {
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/issues`, body: JSON.stringify({ title: 'bug', body: 'details' }), root });
+      await applyGithubWrite({ method: 'PATCH', path: `/repos/${REPO}/issues/1`, body: JSON.stringify({ labels: ['agent-develop-only'] }), root });
+      await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/issues/1/comments`, body: JSON.stringify({ body: 'triaged' }), root });
+      const query = `query IssueByNumber($owner: String!, $repo: String!, $number: Int!) {
+        repository(owner: $owner, name: $repo) {
+          issue(number: $number) { number title state body labels(first: 100) { nodes { name } } comments(first: 100) { nodes { body } } }
+        }
+      }`;
+      const res = await applyGithubWrite({ method: 'POST', path: '/graphql', body: JSON.stringify({ query, variables: { owner: 'octo', repo: 'demo', number: 1 } }), root });
+      const issue = ((res.response.body as { data?: { repository?: { issue?: Record<string, any> } } }).data)?.repository?.issue;
+      if (!issue) return false;
+      if (!(issue.number === 1 && issue.title === 'bug' && issue.state === 'OPEN' && issue.body === 'details')) return false;
+      if (issue.labels?.nodes?.[0]?.name !== 'agent-develop-only') return false;
+      if (issue.comments?.nodes?.[0]?.body !== 'triaged') return false;
+      // NOT_FOUND negative — an absent issue is an honest error, never a fabricated node.
+      const missing = await applyGithubWrite({ method: 'POST', path: '/graphql', body: JSON.stringify({ query, variables: { owner: 'octo', repo: 'demo', number: 99 } }), root });
+      if ((missing.response.body as { errors?: Array<{ type?: string }> }).errors?.[0]?.type !== 'NOT_FOUND') return false;
+      // Token-hijack regression pin (§9 round two): a repository whose NAME contains "issue"
+      // resolves ordinary repository fields — the single-issue branch must not capture it.
+      await applyGithubWrite({ method: 'POST', path: '/orgs/octo/repos', body: JSON.stringify({ name: 'issue-tracker' }), root });
+      const repoQ = await applyGithubWrite({ method: 'POST', path: '/graphql', body: JSON.stringify({ query: `query { repository(owner: "octo", name: "issue-tracker") { name nameWithOwner isPrivate } }` }), root });
+      const repoData = (repoQ.response.body as { data?: { repository?: { nameWithOwner?: string } }; errors?: unknown[] });
+      return repoData.errors === undefined && repoData.data?.repository?.nameWithOwner === 'octo/issue-tracker';
+    })),
+  todo('github.graphql.pr_view_full_field_set', 'api', 'GraphQL pullRequest: the rest of gh pr view --json (reviewDecision, mergeable, mergeStateStatus, files, commits detail, reviews connection)', 'api', 'niche'),
+  todo('github.graphql.gh_edit_mutations', 'api', 'GraphQL mutations gh pr/issue edit send (updatePullRequest, addLabelsToLabelable/removeLabels, replaceActorsForAssignable, requestReviews) — finalize-agent-review\'s label routing needs these', 'api', 'common'),
   todo('github.graphql.connections', 'api', 'GraphQL: cursor pagination (pageInfo/edges + after) on connections', 'api', 'niche'),
   todo('github.graphql.search', 'api', 'GraphQL: the search() connection (typed SearchResultItem nodes)', 'api', 'niche'),
   todo('github.security.advisories', 'security', 'Repository security advisories (GHSA drafts + CVE request + credits)', 'api', 'niche'),
@@ -1830,6 +2210,94 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
       return ok(pr.status) && (pr.body as { title?: string }).title === 'Real title'
         && ok(iss.status) && (iss.body as { title?: string }).title === 'Bug';
     })),
+  // THE CONVERSATION, cell by cell. `github.connector.pull` above proves a PR and an issue
+  // fold with their content; it says NOTHING about the review/comment subjects, and its fake
+  // answers [] to every comments route, so the whole conversation feature could be DELETED and
+  // it would stay green (2026-09-03 review finding). This cell is the one that names the
+  // feature: distinct reviews / issue-comment / inline routes, each row shaped the way GitHub
+  // shapes it (a `user`, a `pull_request_review_id`, a `submitted_at`), and it asserts the
+  // exact subject ids, WHO said it, WHEN they said it, the inline finding under its review —
+  // and that a PR whose `updated_at` has not moved costs zero detail calls on the next pull.
+  done('github.connector.pull_conversation', 'connector', "Connector: a PR's conversation pulls as SUBJECTS — every review (with the inline comments it wrapped, joined by pull_request_review_id) and every issue comment, each naming ITS OWN author and dated by the provider, with the unchanged-PR budget skip", 'connector', 'core', () =>
+    withRoot(async (root) => {
+      const { observedPrsToResources, pullGithubPrs, syncGithubFromReal } = await import('./github-connector.ts');
+      const detailRoutes = /\/(reviews|comments)$/;
+      const calls: string[] = [];
+      const pr = { number: 7, title: 'Conversation', state: 'open', updated_at: '2026-03-01T12:00:00Z', user: { login: 'anne', type: 'User' } };
+      const execute = {
+        async request(route: string, params: Record<string, unknown> = {}) {
+          calls.push(route);
+          if (route === 'GET /repos/{owner}/{repo}/pulls') return { status: 200, data: params.state === 'closed' ? [] : [pr] };
+          if (route === 'GET /repos/{owner}/{repo}/issues') return { status: 200, data: [] };
+          // Three DISTINCT routes with three distinct shapes — the reviews page, the issue
+          // (conversation-tab) comments, and the inline diff comments.
+          if (route === 'GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews') {
+            // Chronological, as GitHub returns them — so the LAST row is not the newest
+            // verdict: review 13 is a reviewer's unsubmitted PENDING draft, the most recently
+            // created row and no verdict at all. `latestReview` must still be review 12.
+            return { status: 200, data: [
+              { id: 11, state: 'CHANGES_REQUESTED', body: 'needs a test', submitted_at: '2026-03-01T10:00:00Z', commit_id: 'aaa', user: { login: 'anne', type: 'User' } },
+              { id: 12, state: 'COMMENTED', body: 'scanned', submitted_at: '2026-03-01T11:00:00Z', commit_id: 'aaa', user: { login: 'volter-scanner[bot]', type: 'Bot' } },
+              { id: 13, state: 'PENDING', body: 'draft', user: { login: 'dan', type: 'User' } },
+            ] };
+          }
+          if (route === 'GET /repos/{owner}/{repo}/pulls/{pull_number}/comments') {
+            return { status: 200, data: [
+              { id: 900, pull_request_review_id: 12, path: 'src/a.ts', line: 12, body: 'unchecked index', created_at: '2026-03-01T11:00:00Z', user: { login: 'volter-scanner[bot]', type: 'Bot' } },
+              // A BOT finding inside the HUMAN's review: the join is by review id, and it is
+              // not an authorship claim — this comment is the scanner's, not anne's.
+              { id: 901, pull_request_review_id: 11, path: 'src/b.ts', line: 3, body: 'null deref', created_at: '2026-03-01T10:00:00Z', user: { login: 'volter-scanner[bot]', type: 'Bot' } },
+            ] };
+          }
+          if (route === 'GET /repos/{owner}/{repo}/issues/{issue_number}/comments') {
+            return { status: 200, data: [{ id: 41, body: 'ship it', created_at: '2026-03-01T09:00:00Z', updated_at: '2026-03-01T09:30:00Z', user: { login: 'bob', type: 'User' } }] };
+          }
+          return { status: 404, data: { message: 'not found' } };
+        },
+      };
+      const resources = observedPrsToResources(await pullGithubPrs(execute, { owner: 'octo', repo: 'demo', state: 'all' }));
+      // ONE subject per thing that was said, at the exact ids a consumer threads a feed by.
+      const ids = resources.map((r) => `${r.type} ${r.id}`);
+      if (ids.join('|') !== ['pull_request octo/demo#7', 'review octo/demo#7:review:11', 'review octo/demo#7:review:12', 'review octo/demo#7:review:13', 'issue_comment octo/demo#7:ic:41'].join('|')) return false;
+      const human = resources.find((r) => r.id === 'octo/demo#7:review:11')!;
+      const bot = resources.find((r) => r.id === 'octo/demo#7:review:12')!;
+      const draft = resources.find((r) => r.id === 'octo/demo#7:review:13')!;
+      const issueComment = resources.find((r) => r.id === 'octo/demo#7:ic:41')!;
+      // WHO said it — the bot verdict is separable from the human's changes-requested.
+      if (human.fields.authorLogin !== 'anne' || human.fields.authorType !== 'user') return false;
+      if (bot.fields.authorLogin !== 'volter-scanner[bot]' || bot.fields.authorType !== 'bot') return false;
+      if (issueComment.fields.authorLogin !== 'bob' || issueComment.fields.authorType !== 'user') return false;
+      // WHEN it was said — the provider's own instant, never the poll clock. The unsubmitted
+      // draft has no instant to be dated by, and is given none.
+      if (human.occurredAt !== '2026-03-01T10:00:00Z' || bot.occurredAt !== '2026-03-01T11:00:00Z') return false;
+      if (issueComment.occurredAt !== '2026-03-01T09:30:00Z') return false;
+      if (resources[0]!.occurredAt !== '2026-03-01T12:00:00Z') return false;
+      if (draft.occurredAt !== undefined) return false;
+      // THE JOIN — each inline finding rides the review that wrapped it, and only that one.
+      const botComments = bot.fields.comments as Array<Record<string, unknown>>;
+      const humanComments = human.fields.comments as Array<Record<string, unknown>>;
+      if (!Array.isArray(botComments) || botComments.length !== 1) return false;
+      if (botComments[0]!.id !== '900' || botComments[0]!.path !== 'src/a.ts' || botComments[0]!.line !== 12 || botComments[0]!.body !== 'unchecked index') return false;
+      if (!Array.isArray(humanComments) || humanComments.length !== 1) return false;
+      if (humanComments[0]!.id !== '901' || humanComments[0]!.body !== 'null deref') return false;
+      // ...AUTHORED BY WHOEVER WROTE IT. The scanner's finding inside anne's review is the
+      // scanner's; reading the wrapper's login served a bot finding as a human's.
+      if (humanComments[0]!.authorLogin !== 'volter-scanner[bot]' || humanComments[0]!.authorType !== 'bot') return false;
+      if (botComments[0]!.authorLogin !== 'volter-scanner[bot]' || botComments[0]!.authorType !== 'bot') return false;
+      // The summary a consumer reading only the PR sees agrees with the subjects above: the
+      // count excludes the PENDING draft, and the newest verdict is the newest SUBMITTED one
+      // rather than the last row on the page.
+      if (resources[0]!.fields.reviewCount !== 2) return false;
+      const latest = resources[0]!.fields.latestReview as Record<string, unknown> | null;
+      if (latest === null || latest.state !== 'COMMENTED' || latest.submittedAt !== '2026-03-01T11:00:00Z') return false;
+      // THE BUDGET — a second pull whose `updated_at` has not moved buys the list and nothing
+      // else. Folded through syncGithubFromReal, because the memory is the SHADOW.
+      await syncGithubFromReal(execute, { owner: 'octo', repo: 'demo', root, occurredAt: '2026-03-01T13:00:00Z', state: 'all' });
+      calls.length = 0;
+      await syncGithubFromReal(execute, { owner: 'octo', repo: 'demo', root, occurredAt: '2026-03-01T14:00:00Z', state: 'all' });
+      if (calls.some((route) => detailRoutes.test(route))) return false;
+      return calls.includes('GET /repos/{owner}/{repo}/pulls');
+    })),
   done('github.connector.push', 'connector', 'Connector: push reconcile (apply desired-state writes)', 'connector', 'common', () =>
     withRoot(async (root) => {
       const { pushPendingGithubActions } = await import('./github-connector.ts');
@@ -1874,10 +2342,19 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
       await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls/1/requested_reviewers`, body: JSON.stringify({ reviewers: ['carol'] }), root });
       await applyGithubWrite({ method: 'POST', path: `/repos/${REPO}/pulls/1/comments`, body: JSON.stringify({ body: 'nit', path: 'a.ts', line: 1, side: 'RIGHT' }), root });
     },
-    fetch: async (root) => githubMirrorState(root),
+    // The screen's "Review count" and the reviews the API serves for the same PR are read
+    // TOGETHER: the seed leaves two reviews on the PR — the APPROVE, and the implicit review
+    // wrapping the standalone inline comment, which `GET /pulls/:n/reviews` serves exactly as
+    // real GitHub does. The count used to read only the stored rows, so the mirror rendered
+    // "Review count 1" over a reviews page answering two.
+    fetch: async (root) => ({
+      ...githubMirrorState(root),
+      served: (handleGithubRequest({ method: 'GET', path: `/repos/${REPO}/pulls/1/reviews`, root }).body as unknown[]).length,
+    }),
     assert: (m) => {
       const pr = (m.github as any).pullRequests.find((p: any) => p.title === 'Conversation Probe');
-      return !!pr && pr.reviewCount === 1 && pr.reviewCommentsCount === 1 && (pr.requestedReviewers as string[]).includes('carol');
+      if (!pr || pr.reviewCommentsCount !== 1 || !(pr.requestedReviewers as string[]).includes('carol')) return false;
+      return pr.reviewCount === 2 && pr.reviewCount === m.served;
     },
   })),
   // Issues list: seed an issue with a distinct label + assignee — both must appear on
@@ -2097,9 +2574,9 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
       return !!d && d.state === 'success' && d.environmentUrl === 'https://probe.x' && !!e && e.protected === true;
     },
   })),
-  // ── Pull-surface coverage audit gaps (TWIN-46 / G2) — filed as manifest todos so
-  // scripts/seed-conformance-issues.ts (A1) turns them into real backlog work. See
-  // pull-audit.json (repo root) for the per-pack pull-vs-read-surface evidence.
+  // ── Pull-surface coverage audit gaps (TWIN-46 / G2) — filed as manifest todos, which is
+  // what the demand-ordered build list is drawn from. See pull-audit.json (repo root) for the
+  // per-pack pull-vs-read-surface evidence.
   todo('github.connector.pull_pr_files', 'connector', 'Connector: pull PR files (per-file diff list) from the real vendor', 'connector', 'core'),
   todo('github.connector.pull_repo_metadata', 'connector', 'Connector: pull repo metadata/settings (GET /repos/:owner/:repo) from the real vendor', 'connector', 'common'),
 
@@ -2116,6 +2593,8 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
   todo('github.billing.packages_storage', 'billing', 'Billing: shared storage/packages billing usage', 'api', 'niche'),
   todo('github.migrations.org_export', 'migrations', 'Migrations: start + poll an org migration (data export archive)', 'api', 'niche'),
   todo('github.migrations.repo_import', 'migrations', 'Migrations: source import status (GitHub Importer API)', 'api', 'niche'),
+  todo('github.pulls.merge_gated_by_protection', 'pulls', 'PRs: merge refused (405) while a protected base branch has failing/missing required checks (the config persists; PUT .../merge does not yet consult it)', 'api', 'common'),
+  todo('github.pulls.review_actor_identity', 'pulls', 'PRs: review.user/comment.user reflect the authenticated actor. LOAD-BEARING gap: human-approval-gate.ts reads review.user.login (then checks collaborators/:login/permission), so with user:null a native Approve or /agent-approve comment can NEVER authorize against the twin — hermetic human-approval needs this modeled', 'api', 'common'),
   todo('github.actions.runners_crud', 'actions', 'Actions: self-hosted runners CRUD (repo/org) + registration/removal tokens', 'api', 'niche'),
   todo('github.actions.runner_groups', 'actions', 'Actions: runner groups (org) CRUD + repo/runner assignment', 'api', 'niche'),
   todo('github.interactions.limits', 'interactions', 'Interactions: repo/org temporary interaction limits (collaborators-only restriction)', 'api', 'niche'),