@volter/twin-github 0.1.0 → 0.1.1

package/src/github-git-plane.ts

@@ -0,0 +1,511 @@
+// GitHub twin git plane — REAL bare git repositories under the twin instance's state dir,
+// driven by the system `git` binary. This is the supabase doctrine applied to GitHub: twin
+// the CONTROL plane (the REST/GraphQL surface), run the REAL engine for the data plane (the
+// git object store). git is its own reference implementation — the object formats, pkt-line
+// framing and smart-HTTP semantics this plane serves are specified by git's own docs
+// (gitformat-pack(5), gitprotocol-common(5), gitprotocol-http(5); recorded in
+// spec-sources.json) and produced/consumed here by real `git` subprocesses, never re-implemented.
+//
+// Layout: one bare repo per twin repository at `<root>/.volter/world/github/git/<owner>/<name>.git`
+// (worldPaths('github').dir — the SAME state dir the kernel event log lives under, so a twin
+// instance's git plane travels with its control-plane state).
+//
+// Reconciliation contract (the heart of the smart-HTTP upgrade — see github-git-http.ts):
+//   • Git Data REST writes (blobs/trees/commits/tags) write REAL git objects here and return
+//     the REAL git sha — so a REST-authored commit chain is byte-for-byte fetchable by any
+//     git client.
+//   • REST ref writes materialize into the bare repo whenever the target object exists
+//     (updateGitRefInPlane); a ref minted against a sha the plane has never seen stays
+//     control-plane-only (the twin's long-standing lenient simulation surface — real GitHub
+//     would 422 "Object does not exist"; the leniency predates this plane and is pinned by
+//     existing capabilities, so it is kept and documented rather than silently changed).
+//   • Pushed refs (git-receive-pack) are folded back into the kernel event log by
+//     reconcileGitPlaneRefs so the REST plane (refs, branches, PR head resolution) sees them.
+//
+// Determinism/offline: every function here shells out to the LOCAL `git` binary over local
+// files — no network, deterministic given the same inputs (commit/tag shas are pinned by the
+// caller-supplied occurredAt). Spawning local git is NOT a live-probe and is outside rate
+// budgets. If `git` itself cannot be spawned we fail LOUDLY with a clear message — never a
+// silent fallback (the gate's absent-capability rule).
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { worldPaths } from '@volter/twin';
+
+// Path-safe owner/name segments (GitHub's own rules are close enough; the point is that a
+// repo name can never traverse out of the plane dir).
+const SEGMENT_RE = /^[A-Za-z0-9_.-]+$/;
+
+/** The git plane root for a twin instance: `<state>/github/git`. */
+export function githubGitPlaneDir(root?: string): string {
+  return join(worldPaths('github', root).dir, 'git');
+}
+
+/** The bare repo dir for `owner/name` (validated — a hostile name cannot escape the plane dir). */
+export function bareRepoDir(repo: string, root?: string): string {
+  const [owner, name, extra] = repo.split('/');
+  if (!owner || !name || extra !== undefined || !SEGMENT_RE.test(owner) || !SEGMENT_RE.test(name) || owner === '..' || name === '..' || owner === '.' || name === '.') {
+    throw new Error(`github twin git plane: invalid repository name ${JSON.stringify(repo)}`);
+  }
+  return join(githubGitPlaneDir(root), owner, `${name}.git`);
+}
+
+export function hasBareRepo(repo: string, root?: string): boolean {
+  return existsSync(join(bareRepoDir(repo, root), 'HEAD'));
+}
+
+// Config hygiene: a spawned git must never read the operator's user/system config (hooks
+// paths, transfer knobs, protocol overrides would make the twin's behavior machine-dependent).
+function gitEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) if (v !== undefined) env[k] = v;
+  env.GIT_CONFIG_GLOBAL = '/dev/null';
+  env.GIT_CONFIG_SYSTEM = '/dev/null';
+  env.GIT_CONFIG_NOSYSTEM = '1';
+  env.GIT_TERMINAL_PROMPT = '0';
+  env.GIT_ATTR_NOSYSTEM = '1';
+  return env;
+}
+
+export type RunGitResult = { code: number; stdout: Buffer; stderr: string };
+
+/**
+ * Run `git <args>` in `dir` (synchronous — the twin's read path is synchronous). Non-zero
+ * exit is returned to the caller (many probes are expected to fail, e.g. cat-file -e); a
+ * FAILED SPAWN (git missing/broken) throws loudly — the git plane cannot exist without git.
+ */
+export function runGit(dir: string, args: string[], opts: { stdin?: Uint8Array; env?: Record<string, string> } = {}): RunGitResult {
+  let proc: ReturnType<typeof Bun.spawnSync>;
+  // A large stdin (a push's packfile) goes through a file, not a pipe: with a pipe, a child that fills its
+  // own stdout before draining stdin deadlocks the synchronous spawn — a push of a real repository hung the
+  // twin for good. A file has no such back-pressure.
+  let stdinFile: string | undefined;
+  let stdin: Uint8Array | ReturnType<typeof Bun.file> | undefined = opts.stdin;
+  if (opts.stdin !== undefined && opts.stdin.length > 65_536) {
+    stdinFile = join(tmpdir(), `twin-git-stdin-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    writeFileSync(stdinFile, opts.stdin);
+    stdin = Bun.file(stdinFile);
+  }
+  try {
+    proc = Bun.spawnSync({
+      cmd: ['git', ...args],
+      cwd: dir,
+      stdin,
+      stdout: 'pipe',
+      stderr: 'pipe',
+      env: { ...gitEnv(), ...(opts.env ?? {}) },
+    });
+  } catch (e) {
+    throw new Error(`github twin git plane: failed to spawn \`git ${args[0] ?? ''}\` — is the git binary on PATH? (${e instanceof Error ? e.message : String(e)})`);
+  } finally {
+    if (stdinFile) rmSync(stdinFile, { force: true });
+  }
+  if (proc.exitCode === null) {
+    throw new Error(`github twin git plane: \`git ${args.join(' ')}\` did not run (killed before exit) — cannot serve the git plane without a working git binary`);
+  }
+  return { code: proc.exitCode, stdout: Buffer.from(proc.stdout ?? new Uint8Array()), stderr: new TextDecoder().decode(proc.stderr ?? new Uint8Array()) };
+}
+
+/** Run git and THROW (loudly, with stderr) on a non-zero exit — for calls that must succeed. */
+function mustGit(dir: string, args: string[], opts: { stdin?: Uint8Array } = {}): RunGitResult {
+  const res = runGit(dir, args, opts);
+  if (res.code !== 0) {
+    throw new Error(`github twin git plane: \`git ${args.join(' ')}\` failed (exit ${res.code}): ${res.stderr.trim() || res.stdout.toString('utf8').trim()}`);
+  }
+  return res;
+}
+
+/** Idempotently create the bare repo for `repo` (HEAD → refs/heads/<defaultBranch>). */
+export function ensureBareRepo(repo: string, root?: string, defaultBranch = 'main'): string {
+  const dir = bareRepoDir(repo, root);
+  if (existsSync(join(dir, 'HEAD'))) return dir;
+  mkdirSync(dir, { recursive: true });
+  mustGit(dir, ['init', '--bare', '--quiet']);
+  // Not `init -b`: symbolic-ref works on every git ≥ 2.x and re-pointing is idempotent.
+  mustGit(dir, ['symbolic-ref', 'HEAD', `refs/heads/${defaultBranch}`]);
+  return dir;
+}
+
+export function objectExistsInPlane(repo: string, sha: string, root?: string): boolean {
+  if (!hasBareRepo(repo, root)) return false;
+  if (!/^[0-9a-f]{40}$/i.test(sha)) return false;
+  return runGit(bareRepoDir(repo, root), ['cat-file', '-e', sha]).code === 0;
+}
+
+export function objectTypeInPlane(repo: string, sha: string, root?: string): string | null {
+  if (!hasBareRepo(repo, root) || !/^[0-9a-f]{40}$/i.test(sha)) return null;
+  const res = runGit(bareRepoDir(repo, root), ['cat-file', '-t', sha]);
+  return res.code === 0 ? res.stdout.toString('utf8').trim() : null;
+}
+
+// ── Objects: blobs ─────────────────────────────────────────────────────────────────────────
+/** Write a REAL blob object; returns the real git sha. */
+export function writeGitBlobToPlane(repo: string, contentB64: string, root?: string): string {
+  const dir = ensureBareRepo(repo, root);
+  const res = mustGit(dir, ['hash-object', '-w', '--stdin'], { stdin: Buffer.from(contentB64, 'base64') });
+  return res.stdout.toString('utf8').trim();
+}
+
+export function readGitBlobFromPlane(repo: string, sha: string, root?: string): { content_b64: string; size: number } | null {
+  if (objectTypeInPlane(repo, sha, root) !== 'blob') return null;
+  const res = mustGit(bareRepoDir(repo, root), ['cat-file', 'blob', sha]);
+  return { content_b64: res.stdout.toString('base64'), size: res.stdout.length };
+}
+
+// ── Objects: trees ─────────────────────────────────────────────────────────────────────────
+export type PlaneTreeEntry = { path: string; mode: string; type: string; sha: string; size?: number };
+
+function lsTreeRecursive(dir: string, sha: string): Map<string, { mode: string; type: string; sha: string }> {
+  // `-r -t` lists blobs AND the intermediate trees; we keep only the LEAF entries (blob /
+  // commit(submodule)) — subtrees are rebuilt from the leaf paths on write.
+  const res = mustGit(dir, ['ls-tree', '-r', '-z', sha]);
+  const out = new Map<string, { mode: string; type: string; sha: string }>();
+  for (const rec of res.stdout.toString('utf8').split('\0')) {
+    if (!rec) continue;
+    const m = /^(\d+) (\w+) ([0-9a-f]{40})\t(.+)$/s.exec(rec);
+    if (m) out.set(m[4]!, { mode: m[1]!, type: m[2]!, sha: m[3]! });
+  }
+  return out;
+}
+
+/** mktree (with `--missing`, matching the twin's lenient legacy surface) one LEVEL of entries. */
+function mktreeLevel(dir: string, entries: Array<{ name: string; mode: string; type: string; sha: string }>): string {
+  const input = entries.map((e) => `${e.mode} ${e.type} ${e.sha}\t${e.name}`).join('\n');
+  const res = mustGit(dir, ['mktree', '--missing'], { stdin: Buffer.from(input.length ? `${input}\n` : '', 'utf8') });
+  return res.stdout.toString('utf8').trim();
+}
+
+/** Build a REAL (possibly nested) tree from flat API entries; returns the real root-tree sha. */
+function buildTreeFromFlat(dir: string, flat: Map<string, { mode: string; type: string; sha: string }>): string {
+  type Node = { entries: Map<string, { mode: string; type: string; sha: string }>; children: Map<string, Node> };
+  const rootNode: Node = { entries: new Map(), children: new Map() };
+  for (const [path, e] of flat) {
+    const parts = path.split('/');
+    let node = rootNode;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const seg = parts[i]!;
+      if (!node.children.has(seg)) node.children.set(seg, { entries: new Map(), children: new Map() });
+      node = node.children.get(seg)!;
+    }
+    node.entries.set(parts[parts.length - 1]!, e);
+  }
+  const write = (node: Node): string => {
+    const level: Array<{ name: string; mode: string; type: string; sha: string }> = [];
+    for (const [name, child] of node.children) level.push({ name, mode: '040000', type: 'tree', sha: write(child) });
+    for (const [name, e] of node.entries) level.push({ name, mode: e.mode, type: e.type, sha: e.sha });
+    return mktreeLevel(dir, level);
+  };
+  return write(rootNode);
+}
+
+/**
+ * Write a REAL tree object from GitHub-API-shaped entries (nested `a/b/c` paths supported,
+ * as real GitHub supports). With `baseTreeSha` (and the base present in the plane), the
+ * entries OVERLAY the base's recursive listing — an entry with an empty/missing sha deletes
+ * its path (GitHub's tree-deletion convention, `sha: null`).
+ */
+export function writeGitTreeToPlane(repo: string, entries: PlaneTreeEntry[], baseTreeSha: string | undefined, root?: string): string {
+  const dir = ensureBareRepo(repo, root);
+  const flat = baseTreeSha && objectTypeInPlane(repo, baseTreeSha, root) === 'tree'
+    ? lsTreeRecursive(dir, baseTreeSha)
+    : new Map<string, { mode: string; type: string; sha: string }>();
+  for (const e of entries) {
+    if (!e.sha) { flat.delete(e.path); continue; }
+    flat.set(e.path, { mode: e.mode, type: e.type, sha: e.sha });
+  }
+  return buildTreeFromFlat(dir, flat);
+}
+
+export function readGitTreeFromPlane(repo: string, sha: string, root?: string): PlaneTreeEntry[] | null {
+  if (objectTypeInPlane(repo, sha, root) !== 'tree') return null;
+  const res = mustGit(bareRepoDir(repo, root), ['ls-tree', '-l', '-z', sha]);
+  const out: PlaneTreeEntry[] = [];
+  for (const rec of res.stdout.toString('utf8').split('\0')) {
+    if (!rec) continue;
+    // size column: bytes for a present blob, `-` for trees, `BAD` for a missing object
+    // (the lenient legacy surface permits tree entries naming unwritten blobs).
+    const m = /^(\d+) (\w+) ([0-9a-f]{40}) +(\S+)\t(.+)$/s.exec(rec);
+    if (!m) continue;
+    const entry: PlaneTreeEntry = { path: m[5]!, mode: m[1]!, type: m[2]!, sha: m[3]! };
+    if (/^\d+$/.test(m[4]!)) entry.size = Number(m[4]);
+    out.push(entry);
+  }
+  return out;
+}
+
+// ── Objects: commits + annotated tags ──────────────────────────────────────────────────────
+export type PlaneIdent = { name: string; email: string };
+const TWIN_IDENT: PlaneIdent = { name: 'github-twin', email: 'github-twin@localhost' };
+
+function identLine(kind: 'author' | 'committer' | 'tagger', ident: PlaneIdent | undefined, occurredAt: string): string {
+  const who = ident ?? TWIN_IDENT;
+  const when = Math.floor((Date.parse(occurredAt) || 0) / 1000);
+  return `${kind} ${who.name} <${who.email}> ${when} +0000`;
+}
+
+/**
+ * Write a REAL commit object (hand-framed per gitformat-commit, hashed+stored by git itself
+ * via `hash-object -t commit -w`); returns the real sha. hash-object validates the object's
+ * FORMAT but not connectivity, so the twin's legacy lenient surface (a commit naming a tree
+ * sha nobody has written) still produces a real, addressable object — exactly the dangling
+ * objects git itself permits.
+ */
+export function writeGitCommitToPlane(
+  repo: string,
+  commit: { message: string; treeSha: string; parents: string[]; author?: PlaneIdent; committer?: PlaneIdent; occurredAt: string },
+  root?: string,
+): string {
+  const dir = ensureBareRepo(repo, root);
+  const lines = [
+    `tree ${commit.treeSha}`,
+    ...commit.parents.map((p) => `parent ${p}`),
+    identLine('author', commit.author, commit.occurredAt),
+    identLine('committer', commit.committer ?? commit.author, commit.occurredAt),
+    '',
+    commit.message,
+  ];
+  const res = mustGit(dir, ['hash-object', '-t', 'commit', '-w', '--stdin'], { stdin: Buffer.from(`${lines.join('\n')}\n`, 'utf8') });
+  return res.stdout.toString('utf8').trim();
+}
+
+export type PlaneCommit = { sha: string; message: string; tree_sha: string; parents: string[]; author_name?: string; author_email?: string; created_at?: string };
+
+export function readGitCommitFromPlane(repo: string, sha: string, root?: string): PlaneCommit | null {
+  if (objectTypeInPlane(repo, sha, root) !== 'commit') return null;
+  const raw = mustGit(bareRepoDir(repo, root), ['cat-file', 'commit', sha]).stdout.toString('utf8');
+  const sep = raw.indexOf('\n\n');
+  const header = sep >= 0 ? raw.slice(0, sep) : raw;
+  const message = sep >= 0 ? raw.slice(sep + 2).replace(/\n$/, '') : '';
+  const tree = /^tree ([0-9a-f]{40})$/m.exec(header)?.[1] ?? '';
+  const parents = [...header.matchAll(/^parent ([0-9a-f]{40})$/gm)].map((m) => m[1]!);
+  const author = /^author (.*) <(.*)> (\d+) ([+-]\d{4})$/m.exec(header);
+  const out: PlaneCommit = { sha, message, tree_sha: tree, parents };
+  if (author) {
+    out.author_name = author[1]!;
+    out.author_email = author[2]!;
+    out.created_at = new Date(Number(author[3]) * 1000).toISOString();
+  }
+  return out;
+}
+
+/** Write a REAL annotated-tag object; returns the real sha. */
+export function writeGitTagToPlane(
+  repo: string,
+  tag: { tag: string; message: string; objectSha: string; objectType: string; tagger?: PlaneIdent; occurredAt: string },
+  root?: string,
+): string {
+  const dir = ensureBareRepo(repo, root);
+  const lines = [
+    `object ${tag.objectSha}`,
+    `type ${tag.objectType}`,
+    `tag ${tag.tag}`,
+    identLine('tagger', tag.tagger, tag.occurredAt),
+    '',
+    tag.message,
+  ];
+  const res = mustGit(dir, ['hash-object', '-t', 'tag', '-w', '--stdin'], { stdin: Buffer.from(`${lines.join('\n')}\n`, 'utf8') });
+  return res.stdout.toString('utf8').trim();
+}
+
+export type PlaneTag = { sha: string; tag: string; message: string; object_sha: string; object_type: string; tagger_name?: string; created_at?: string };
+
+export function readGitTagFromPlane(repo: string, sha: string, root?: string): PlaneTag | null {
+  if (objectTypeInPlane(repo, sha, root) !== 'tag') return null;
+  const raw = mustGit(bareRepoDir(repo, root), ['cat-file', 'tag', sha]).stdout.toString('utf8');
+  const sep = raw.indexOf('\n\n');
+  const header = sep >= 0 ? raw.slice(0, sep) : raw;
+  const message = sep >= 0 ? raw.slice(sep + 2).replace(/\n$/, '') : '';
+  const out: PlaneTag = {
+    sha,
+    tag: /^tag (.*)$/m.exec(header)?.[1] ?? '',
+    message,
+    object_sha: /^object ([0-9a-f]{40})$/m.exec(header)?.[1] ?? '',
+    object_type: /^type (\w+)$/m.exec(header)?.[1] ?? 'commit',
+  };
+  const tagger = /^tagger (.*) <.*> (\d+) ([+-]\d{4})$/m.exec(header);
+  if (tagger) {
+    out.tagger_name = tagger[1]!;
+    out.created_at = new Date(Number(tagger[2]) * 1000).toISOString();
+  }
+  return out;
+}
+
+// ── Refs ───────────────────────────────────────────────────────────────────────────────────
+/**
+ * Materialize a control-plane ref write into the bare repo. Returns true when the ref now
+ * exists in the plane; false when the target object does not exist there OR is not fully
+ * CONNECTED (`rev-list --objects` walks every reachable object) — a ref to a dangling
+ * commit (the twin's lenient legacy surface permits commits naming trees nobody wrote)
+ * stays control-plane-only, so an advertised ref is always actually clonable.
+ */
+export function updateGitRefInPlane(repo: string, ref: string, sha: string, root?: string): boolean {
+  if (!hasBareRepo(repo, root)) return false;
+  if (!objectExistsInPlane(repo, sha, root)) return false;
+  const dir = bareRepoDir(repo, root);
+  if (runGit(dir, ['rev-list', '--objects', sha]).code !== 0) return false; // dangling chain — not clonable
+  return runGit(dir, ['update-ref', ref, sha]).code === 0;
+}
+
+export function deleteGitRefInPlane(repo: string, ref: string, root?: string): void {
+  if (!hasBareRepo(repo, root)) return;
+  runGit(bareRepoDir(repo, root), ['update-ref', '-d', ref]); // non-existence is fine
+}
+
+export type PlaneRef = { ref: string; object_sha: string; object_type: string };
+
+// ── Repo lifecycle + diffs (REST ↔ plane convergence) ──────────────────────────────────────
+/** Re-point the bare repo's HEAD symref (a REST default_branch change IS this operation). */
+export function setBareRepoHead(repo: string, branch: string, root?: string): void {
+  if (!hasBareRepo(repo, root)) return;
+  mustGit(bareRepoDir(repo, root), ['symbolic-ref', 'HEAD', `refs/heads/${branch}`]);
+}
+
+/** Remove a deleted repo's bare repo — a later re-create must NOT inherit its history. */
+export function deleteBareRepo(repo: string, root?: string): void {
+  if (!hasBareRepo(repo, root)) return;
+  rmSync(bareRepoDir(repo, root), { recursive: true, force: true });
+}
+
+/**
+ * Fork = copy the parent's object store + refs (what real GitHub does server-side). A file
+ * copy of a bare repo is a valid bare repo; `cpSync` keeps this synchronous like the rest of
+ * the plane. No parent bare repo → an empty bare repo (the twin's lenient surface).
+ */
+export function forkBareRepo(parentRepo: string, forkRepo: string, root?: string, defaultBranch = 'main'): void {
+  const dst = bareRepoDir(forkRepo, root); // validates the fork name before any copy
+  if (hasBareRepo(forkRepo, root)) return;
+  if (!hasBareRepo(parentRepo, root)) { ensureBareRepo(forkRepo, root, defaultBranch); return; }
+  mkdirSync(dst, { recursive: true });
+  cpSync(bareRepoDir(parentRepo, root), dst, { recursive: true });
+}
+
+/** True when `ancestor` is an ancestor of `descendant` (the fast-forward test). */
+export function isAncestorInPlane(repo: string, ancestor: string, descendant: string, root?: string): boolean {
+  if (!hasBareRepo(repo, root)) return false;
+  return runGit(bareRepoDir(repo, root), ['merge-base', '--is-ancestor', ancestor, descendant]).code === 0;
+}
+
+export type PlaneDiffFile = { filename: string; status: string; additions: number; deletions: number; sha?: string };
+
+/** The merge base of two commits, or null when none exists / either is absent. */
+export function mergeBaseInPlane(repo: string, a: string, b: string, root?: string): string | null {
+  if (!objectExistsInPlane(repo, a, root) || !objectExistsInPlane(repo, b, root)) return null;
+  const res = runGit(bareRepoDir(repo, root), ['merge-base', a, b]);
+  return res.code === 0 ? res.stdout.toString('utf8').trim() : null;
+}
+
+/**
+ * The changed-file list between two commits, from the REAL object store (`diff-tree -r`) —
+ * what backs GET /pulls/:n/files and compare when both sides exist in the plane. THREE-DOT
+ * semantics like real GitHub: the diff runs from merge-base(base,head) to head, so a base
+ * branch that advanced past the PR's branch point never leaks ITS OWN changes into the PR's
+ * file list (merge-gate scope classification depends on exactly this). Unrelated histories
+ * (no merge base) fall back to the plain two-commit diff. Binary files report 0/0 (git
+ * prints `-`) rather than fabricated counts; renames are declared scope (no -M — plumbing
+ * reports adds+deletes, which is honest, never a mis-paired record). `sha` is the REAL
+ * post-image blob sha from --raw (absent for deletions).
+ */
+export function diffFilesInPlane(repo: string, baseSha: string, headSha: string, root?: string): PlaneDiffFile[] | null {
+  if (!objectExistsInPlane(repo, baseSha, root) || !objectExistsInPlane(repo, headSha, root)) return null;
+  const from = mergeBaseInPlane(repo, baseSha, headSha, root) ?? baseSha;
+  const dir = bareRepoDir(repo, root);
+  const num = runGit(dir, ['diff-tree', '-r', '--no-commit-id', '--numstat', '-z', from, headSha]);
+  const nam = runGit(dir, ['diff-tree', '-r', '--no-commit-id', '--name-status', '-z', from, headSha]);
+  const raw = runGit(dir, ['diff-tree', '-r', '--no-commit-id', '--raw', '-z', from, headSha]);
+  if (num.code !== 0 || nam.code !== 0 || raw.code !== 0) return null;
+  const statusByPath = new Map<string, string>();
+  const namParts = nam.stdout.toString('utf8').split('\0');
+  for (let i = 0; i + 1 < namParts.length; i += 2) {
+    const s = namParts[i]!; const p = namParts[i + 1]!;
+    if (!s || !p) continue;
+    const code = s[0];
+    statusByPath.set(p, code === 'A' ? 'added' : code === 'D' ? 'removed' : 'modified');
+  }
+  // --raw -z records: ":oldmode newmode oldsha newsha status\0path\0" — the post-image blob
+  // sha is the REAL object id (all-zeros for a deletion).
+  const shaByPath = new Map<string, string>();
+  const rawParts = raw.stdout.toString('utf8').split('\0');
+  for (let i = 0; i + 1 < rawParts.length; i += 2) {
+    const meta = rawParts[i]!; const p = rawParts[i + 1]!;
+    const m = /^:\d+ \d+ [0-9a-f]{40} ([0-9a-f]{40}) \w+$/.exec(meta);
+    if (m && p && m[1] !== '0'.repeat(40)) shaByPath.set(p, m[1]!);
+  }
+  const out: PlaneDiffFile[] = [];
+  for (const rec of num.stdout.toString('utf8').split('\0')) {
+    if (!rec) continue;
+    const m = /^([0-9-]+)\t([0-9-]+)\t(.*)$/s.exec(rec);
+    if (!m || !m[3]) continue;
+    const filename = m[3];
+    const sha = shaByPath.get(filename);
+    out.push({
+      filename,
+      status: statusByPath.get(filename) ?? 'modified',
+      additions: m[1] === '-' ? 0 : Number(m[1]),
+      deletions: m[2] === '-' ? 0 : Number(m[2]),
+      ...(sha !== undefined ? { sha } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * Conservative git branch-name validation (the load-bearing subset of
+ * git-check-ref-format(1)) — a name this rejects would make `symbolic-ref`/`update-ref`
+ * throw, so callers 422 instead of surfacing a 500.
+ */
+export function isValidBranchName(name: string): boolean {
+  if (!name || name.length > 250) return false;
+  if (/[\s~^:?*[\\\x00-\x1f\x7f]/.test(name)) return false;
+  if (name.includes('..') || name.includes('@{') || name.includes('//')) return false;
+  if (name.startsWith('/') || name.endsWith('/') || name.startsWith('.') || name.endsWith('.') || name.endsWith('.lock')) return false;
+  return true;
+}
+
+/** All refs in the bare repo (`for-each-ref`) — the protocol-visible ref set. */
+export function listGitPlaneRefs(repo: string, root?: string): PlaneRef[] {
+  if (!hasBareRepo(repo, root)) return [];
+  const res = mustGit(bareRepoDir(repo, root), ['for-each-ref', '--format=%(objectname) %(objecttype) %(refname)']);
+  const out: PlaneRef[] = [];
+  for (const line of res.stdout.toString('utf8').split('\n')) {
+    if (!line) continue;
+    const m = /^([0-9a-f]{40}) (\w+) (.+)$/.exec(line);
+    if (m) out.push({ object_sha: m[1]!, object_type: m[2]!, ref: m[3]! });
+  }
+  return out;
+}
+
+// ── Pull-request landing (REST merge ↔ plane convergence) ──────────────────────────────────
+const GITHUB_IDENT: PlaneIdent = { name: 'GitHub', email: 'noreply@github.com' };
+
+/**
+ * Land `headSha` on branch `baseBranch` the way GitHub's merge button does: a REAL merge commit
+ * (git merge-tree, no worktree) whose first parent is the base tip, or a single-parent commit of the
+ * merged tree for the squash/rebase methods (declared deviation: rebase is folded to one commit).
+ * Returns the base branch's new tip; `{ conflict }` when the trees do not merge cleanly; null when
+ * the repository has no git plane or the base branch does not exist there. The base tip moves
+ * atomically (update-ref with the expected old value), so a concurrent push loses to nobody.
+ */
+export function mergeIntoBranchInPlane(
+  repo: string,
+  baseBranch: string,
+  headSha: string,
+  message: string,
+  method: 'merge' | 'squash' | 'rebase',
+  occurredAt: string,
+  root?: string,
+): { sha: string } | { conflict: true } | null {
+  if (!hasBareRepo(repo, root)) return null;
+  const dir = bareRepoDir(repo, root);
+  const base = runGit(dir, ['rev-parse', '--verify', '--quiet', `refs/heads/${baseBranch}^{commit}`]);
+  if (base.code !== 0) return null;
+  const baseSha = base.stdout.toString('utf8').trim();
+  if (runGit(dir, ['merge-base', '--is-ancestor', headSha, baseSha]).code === 0) return { sha: baseSha };
+  const merged = runGit(dir, ['merge-tree', '--write-tree', baseSha, headSha]);
+  if (merged.code === 1) return { conflict: true };
+  if (merged.code !== 0) throw new Error(`github twin git plane: merge-tree failed (exit ${merged.code}): ${merged.stderr.trim()}`);
+  const treeSha = merged.stdout.toString('utf8').split('\n')[0]!.trim();
+  const parents = method === 'merge' ? [baseSha, headSha] : [baseSha];
+  const sha = writeGitCommitToPlane(repo, { message, treeSha, parents, author: GITHUB_IDENT, committer: GITHUB_IDENT, occurredAt }, root);
+  if (runGit(dir, ['update-ref', `refs/heads/${baseBranch}`, sha, baseSha]).code !== 0) return null;
+  return { sha };
+}