@dxos/plugin-github 0.7.4 → 0.13.0

package/src/operations/sync.ts

@@ -0,0 +1,807 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as Layer from 'effect/Layer';
+import * as Semaphore from 'effect/Semaphore';
+
+import * as ConnectorSync from '@dxos/app-toolkit/ConnectorSync';
+import * as LayoutOperation from '@dxos/app-toolkit/LayoutOperation';
+import * as Operation from '@dxos/compute/Operation';
+import { Database, Filter, Obj, Query, Ref, Type } from '@dxos/echo';
+import { Cursor } from '@dxos/link';
+import { log } from '@dxos/log';
+import * as Binding from '@dxos/plugin-connector/Binding';
+import { Milestone, Organization, Person, Task, TaskSet } from '@dxos/types';
+
+import { meta } from '#meta';
+import { GitHubOperation } from '#types';
+
+import { GITHUB_SOURCE } from '../constants.ts';
+import {
+  GitHubProjectMissingError,
+  GitHubRepoInaccessibleError,
+  GitHubRepoUnresolvedError,
+  formatGitHubSyncFailure,
+} from '../errors.ts';
+import { GitHubApi } from '../services/index.ts';
+
+const { mergeField, snapshotField } = ConnectorSync;
+
+//
+// Direction: bidirectional (pull-then-push) for projects and tasks.
+//
+// Each sync pass syncs one binding (one repo). It first pulls every reachable
+// Organization, Person, Project, and Task from GitHub into ECHO, then walks the
+// local mirrors and pushes any field that diverged from the snapshot taken at
+// the end of the previous pull. Snapshots live on the `Cursor` object's
+// `spec.snapshots[<github id>]` (where ids are the GitHub-issued numeric ids,
+// stringified for stable foreign-key matching).
+//
+// Mapped fields per object:
+//   Project (repo): description (description-only — see updateRepo for why
+//                   `name` is intentionally not pushed)
+//   Task (issue):   title, description, status (open/closed)
+//
+// Conflict policy is remote-wins (mirrors Trello/Linear). Comments are NOT
+// synced (the chunked-yield rewrite is still pending; see TODO below).
+//
+// Attribution caveat: pushed edits are attributed to the GitHub App / OAuth
+// user that owns the connection token, not to the local user who made the
+// edit. This is unavoidable with the current token model — a write from
+// "Person A in space" appears on GitHub as a write from the App. Document
+// before enabling for shared spaces.
+//
+// New local objects (no GitHub foreign key) are NOT pushed in this pass —
+// creating a new GitHub issue requires (owner, repo) which we currently
+// don't surface from local Tasks unambiguously.
+//
+// Sync target shape: each binding's target is the local root Project for one
+// REPOSITORY. The repo's owning org (and org members) are auto-pulled.
+//
+
+//
+// Tunables
+//
+
+/** Per-repo issue parallelism. */
+const ISSUE_CONCURRENCY = 4;
+
+//
+// Snapshot field shapes (stored on Cursor's `spec.snapshots`)
+//
+
+/**
+ * Snapshot shapes. Fields are required (not `?`) because every snapshot is
+ * written in one shot via {@link Cursor.writeSnapshot} after a pull; absence-of-
+ * snapshot is modeled by `Cursor.readSnapshot` returning `undefined`. `name` on a
+ * Project is recorded but not pushed — see {@link GitHubApi.updateRepo}.
+ */
+type ProjectSnapshot = {
+  name: string;
+  description: string;
+};
+
+type TaskSnapshot = {
+  title: string;
+  description: string;
+  status: 'todo' | 'done';
+};
+
+//
+// Foreign-key + lookup helpers
+//
+
+const fkFor = (id: string | number) => ({ source: GITHUB_SOURCE, id: String(id) });
+
+/**
+ * Generic foreign-key lookup. Type is forwarded to `Filter.foreignKeys`
+ * untyped — the caller supplies the result type via the explicit `T` parameter
+ * (mirrors how plugin-trello casts after `Database.query(...).run`).
+ */
+const findByForeignId = <T>(type: Type.AnyEntity, id: string | number) =>
+  Effect.gen(function* () {
+    const results = yield* Database.query(Query.select(Filter.foreignKeys(type as never, [fkFor(id)]))).run;
+    return results.length > 0 ? (results[0] as T) : undefined;
+  });
+
+//
+// Field mappers (GitHub ↔ DXOS)
+//
+
+/**
+ * Maps GitHub issue state to a Task status. GitHub issues only have `open` /
+ * `closed` — there's no "in progress" concept, so we collapse open→`todo` and
+ * closed→`done`. PRs use the same mapping; merged PRs are reported as `closed`
+ * by GitHub plus a non-null `pull_request.merged_at`.
+ */
+const issueStateToTaskStatus = (state: string): 'todo' | 'done' => (state === 'closed' ? 'done' : 'todo');
+
+/**
+ * Reverse of {@link issueStateToTaskStatus}. `'started'` is collapsed to
+ * `open` since GitHub has no equivalent state. Returns undefined when the
+ * status is unrecognised so the caller can skip the push instead of failing.
+ */
+const taskStatusToIssueState = (status: string | undefined): 'open' | 'closed' | undefined => {
+  switch (status) {
+    case 'done':
+      return 'closed';
+    case 'todo':
+    case 'started':
+      return 'open';
+    default:
+      return undefined;
+  }
+};
+
+const sinceFromOptions = (options: GitHubOperation.SyncOptions | undefined): string | undefined => {
+  const days = options?.maxDaysBack;
+  if (typeof days !== 'number' || days <= 0) {
+    return undefined;
+  }
+  return new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString();
+};
+
+/** GitHub reports `due_on` as an ISO datetime; `Milestone.targetDate` is date-only. */
+const dueOnToTargetDate = (dueOn: string | null | undefined): string | undefined => dueOn?.slice(0, 10) ?? undefined;
+
+/**
+ * Move a task into `container`. Idempotent — sync runs repeatedly and must never append a second
+ * ref for a task already in the set.
+ */
+export const setTaskContainer = Effect.fn('setTaskContainer')(function* (task: Task.Task, container: TaskSet.TaskSet) {
+  const listed = container.tasks.some(Ref.hasEntityId(task.id));
+  // A stale entry for a task now parented elsewhere is not membership; it still needs re-rooting.
+  if (listed && Obj.getParent(task)?.id === container.id) {
+    return;
+  }
+  // The reverse-ref index, not `Obj.getParent`: legacy sets may hold refs to tasks whose parent
+  // edge has not yet been healed to the set, and every holder must drop its stale entry.
+  const previous = yield* Database.query(
+    Query.select(Filter.id(task.id)).referencedBy(TaskSet.TaskSet, 'tasks'),
+  ).run.pipe(Effect.orElseSucceed(() => []));
+  for (const set of previous) {
+    if (set.id === container.id) {
+      continue;
+    }
+    Obj.update(set, (set) => {
+      TaskSet.removeRefsInPlace(set.tasks, new Set([task.id]));
+    });
+  }
+  // A task filed as a sub-task is listed by its parent rather than a set; it leaves that list too.
+  const parent = Task.getParentTask(task);
+  if (parent) {
+    Obj.update(parent, (parent) => {
+      TaskSet.removeRefsInPlace(parent.subtasks ?? [], new Set([task.id]));
+    });
+  }
+  if (!listed) {
+    Obj.update(container, (container) => {
+      container.tasks.push(Ref.make(task));
+    });
+  }
+  // `tasks` claims only an unparented task, so a move between sets moves the edge itself.
+  Obj.setParent(task, container);
+});
+
+//
+// Pull (snapshot-driven three-way merge for Project + Task; simple upsert for Org/Person)
+//
+
+const upsertOrganization = Effect.fn('upsertOrganization')(function* (org: GitHubApi.GitHubOrg) {
+  const existing = yield* findByForeignId<Organization.Organization>(Organization.Organization, org.id);
+  if (existing) {
+    Obj.update(existing, (existing) => {
+      existing.name = org.name ?? org.login;
+      if (org.description != null) {
+        existing.description = org.description;
+      }
+      if (org.blog) {
+        existing.website = org.blog;
+      }
+      if (org.avatar_url) {
+        existing.image = org.avatar_url;
+      }
+    });
+    return existing;
+  }
+  const created = Obj.make(Organization.Organization, {
+    [Obj.Meta]: { keys: [fkFor(org.id)] },
+    name: org.name ?? org.login,
+    description: org.description ?? undefined,
+    website: org.blog ?? undefined,
+    image: org.avatar_url ?? undefined,
+  });
+  return yield* Database.add(created);
+});
+
+const upsertPerson = Effect.fn('upsertPerson')(function* (
+  user: GitHubApi.GitHubUser,
+  organization: Organization.Organization | undefined,
+) {
+  const existing = yield* findByForeignId<Person.Person>(Person.Person, user.id);
+  if (existing) {
+    Obj.update(existing, (existing) => {
+      existing.fullName = user.name ?? user.login;
+      if (user.avatar_url) {
+        existing.image = user.avatar_url;
+      }
+      if (organization && !existing.organization) {
+        existing.organization = Ref.make(organization);
+      }
+      // Add the GitHub login identity if not already present.
+      const ids = existing.identities ?? [];
+      if (!ids.some((entry: { value: string }) => entry.value === user.login)) {
+        (existing.identities ??= []).push({ label: 'github', value: user.login });
+      }
+    });
+    return existing;
+  }
+  const created = Person.make({
+    [Obj.Meta]: { keys: [fkFor(user.id)] },
+    fullName: user.name ?? user.login,
+    image: user.avatar_url ?? undefined,
+    organization: organization ? Ref.make(organization) : undefined,
+    identities: [{ label: 'github', value: user.login }],
+  });
+  return yield* Database.add(created);
+});
+
+/**
+ * Pull a GitHub repo into ECHO as a Project. Mapped fields go through
+ * three-way merge against `binding.snapshots[<repo id>]`; the snapshot
+ * is then refreshed to remote-current so the next push pass sees only
+ * fields the user has edited locally. `name` is recorded in the snapshot
+ * (so we can detect divergence) but is not pushed back — see
+ * {@link GitHubApi.updateRepo}.
+ */
+const upsertProject = Effect.fn('upsertProject')(function* (
+  binding: Cursor.ExternalCursor,
+  repo: GitHubApi.GitHubRepo,
+) {
+  const remoteFields: Required<ProjectSnapshot> = {
+    name: repo.full_name,
+    description: repo.description ?? '',
+  };
+  const fid = String(repo.id);
+  const existing = yield* findByForeignId<TaskSet.TaskSet>(TaskSet.TaskSet, repo.id);
+
+  if (existing) {
+    const snapshot = Cursor.readSnapshot<ProjectSnapshot>(binding, fid);
+    const nameResult = mergeField<string | undefined>(
+      existing.name,
+      remoteFields.name,
+      snapshotField(snapshot, 'name'),
+    );
+    const descriptionResult = mergeField<string | undefined>(
+      existing.description,
+      remoteFields.description,
+      snapshotField(snapshot, 'description'),
+    );
+    const writeName = nameResult.source === 'remote' && existing.name !== nameResult.value;
+    const writeDescription = descriptionResult.source === 'remote' && existing.description !== descriptionResult.value;
+    if (writeName || writeDescription) {
+      Obj.update(existing, (existing) => {
+        if (writeName) {
+          existing.name = nameResult.value;
+        }
+        if (writeDescription) {
+          existing.description = descriptionResult.value;
+        }
+      });
+    }
+    Cursor.writeSnapshot(binding, fid, remoteFields);
+    return existing;
+  }
+
+  const created = TaskSet.make({
+    [Obj.Meta]: { keys: [fkFor(repo.id)] },
+    name: repo.full_name,
+    description: repo.description ?? undefined,
+  });
+  const persisted = yield* Database.add(created);
+  Cursor.writeSnapshot(binding, fid, remoteFields);
+  return persisted;
+});
+
+/**
+ * Pull a GitHub milestone into ECHO. Mirrored remote-wins without a snapshot merge — milestones
+ * are pull-only (nothing here pushes milestone edits back), so there is no local side to protect.
+ */
+export const upsertMilestone = Effect.fn('upsertMilestone')(function* (
+  taskSet: TaskSet.TaskSet,
+  remote: GitHubApi.GitHubMilestone,
+) {
+  const name = remote.title;
+  const description = remote.description ?? undefined;
+  // GitHub's open/closed milestone state is deliberately not mapped: `Milestone` derives progress
+  // from its tasks, so a stored status could contradict the work it contains.
+  const targetDate = dueOnToTargetDate(remote.due_on);
+
+  const existing = yield* findByForeignId<Milestone.Milestone>(Milestone.Milestone, remote.id);
+  const milestone =
+    existing ??
+    (yield* Database.add(Milestone.make({ [Obj.Meta]: { keys: [fkFor(remote.id)] }, name, description, targetDate })));
+  if (existing) {
+    Obj.update(existing, (existing) => {
+      existing.name = name;
+      existing.description = description;
+      existing.targetDate = targetDate;
+    });
+  }
+  // Sequence is the `milestones` array; the parent edge only carries deletion cascade.
+  if (!taskSet.milestones.some(Ref.hasEntityId(milestone.id))) {
+    Obj.update(taskSet, (taskSet) => {
+      taskSet.milestones.push(Ref.make(milestone));
+    });
+    Obj.setParent(milestone, taskSet);
+  }
+  return milestone;
+});
+
+/**
+ * Pull a GitHub issue into ECHO as a Task. Same merge shape as
+ * {@link upsertProject}, against snapshot fields {title, description, status}.
+ * Non-mapped fields (`Task.priority`, `Task.estimate`, etc.) are preserved.
+ *
+ * Set membership is NOT wired here: this runs concurrently per issue and `TaskSet.tasks` is a
+ * shared array, so the caller applies {@link setTaskContainer} sequentially afterwards.
+ *
+ * `milestone` is the local mirror of `issue.milestone`, mirrored remote-wins outside the snapshot
+ * merge (nothing pushes milestone edits back, so there is no local side to protect).
+ */
+export const upsertTask = Effect.fn('upsertTask')(function* (
+  binding: Cursor.ExternalCursor,
+  issue: GitHubApi.GitHubIssue,
+  assignedPerson: Person.Person | undefined,
+  milestone: Milestone.Milestone | undefined,
+) {
+  const remoteFields: Required<TaskSnapshot> = {
+    title: issue.title,
+    description: issue.body ?? '',
+    status: issueStateToTaskStatus(issue.state),
+  };
+  const fid = String(issue.id);
+  const existing = yield* findByForeignId<Task.Task>(Task.Task, issue.id);
+
+  if (existing) {
+    const snapshot = Cursor.readSnapshot<TaskSnapshot>(binding, fid);
+    // Task.title is required (non-optional) so the merge produces a string.
+    const titleResult = mergeField<string>(existing.title, remoteFields.title, snapshotField(snapshot, 'title'));
+    const descriptionResult = mergeField<string | undefined>(
+      existing.description,
+      remoteFields.description,
+      snapshotField(snapshot, 'description'),
+    );
+    // existing.status is the full Task status union; the snapshot only ever holds GitHub's
+    // collapsed shape ('todo' | 'done'). Widen the merge type so both sides typecheck and let
+    // mergeField compare them as plain values.
+    const statusResult = mergeField<Task.Task['status']>(
+      existing.status,
+      remoteFields.status,
+      snapshotField(snapshot, 'status'),
+    );
+    const writeTitle = titleResult.source === 'remote' && existing.title !== titleResult.value;
+    const writeDescription = descriptionResult.source === 'remote' && existing.description !== descriptionResult.value;
+    const writeStatus = statusResult.source === 'remote' && existing.status !== statusResult.value;
+    Obj.update(existing, (existing) => {
+      if (writeTitle) {
+        existing.title = titleResult.value;
+      }
+      if (writeDescription) {
+        existing.description = descriptionResult.value;
+      }
+      if (writeStatus) {
+        existing.status = statusResult.value;
+      }
+      if (assignedPerson && !existing.assignee?.contact) {
+        existing.assignee = { contact: Ref.make(assignedPerson) };
+      }
+      if (milestone) {
+        if (existing.milestone?.target?.id !== milestone.id) {
+          existing.milestone = Ref.make(milestone);
+        }
+        // Clear only when GitHub itself reports no milestone; a merely unresolved one would
+        // otherwise wipe a perfectly good local assignment.
+      } else if (issue.milestone == null && existing.milestone !== undefined) {
+        existing.milestone = undefined;
+      }
+    });
+    Cursor.writeSnapshot(binding, fid, remoteFields);
+    return { task: existing, created: false };
+  }
+
+  const created = Task.make({
+    [Obj.Meta]: { keys: [fkFor(issue.id)] },
+    title: issue.title,
+    description: issue.body ?? '',
+    status: issueStateToTaskStatus(issue.state),
+    assignee: assignedPerson ? { contact: Ref.make(assignedPerson) } : undefined,
+    milestone: milestone ? Ref.make(milestone) : undefined,
+  });
+  const persisted = yield* Database.add(created);
+  Cursor.writeSnapshot(binding, fid, remoteFields);
+  return { task: persisted, created: true };
+});
+
+//
+// Push (snapshot diff → GitHub mutations)
+//
+
+export type GitHubPushResult = {
+  projects: number;
+  tasks: number;
+};
+
+/**
+ * Push reconciler for one repo. Walks the locally-mirrored Project for the
+ * given repo plus every Task whose foreign key matches one of the issues we
+ * just pulled, diffs against the binding's snapshot, and PATCHes any diverged
+ * field back to GitHub.
+ *
+ * Behaviour:
+ *   - Project description divergence → PATCH /repos/{owner}/{repo}.
+ *     `name` divergence is logged but NOT pushed (rename is destructive and
+ *     almost never desired from a sync mirror).
+ *   - Task title / description / status divergence → PATCH the issue.
+ *   - Tombstones (`Obj.isDeleted`) are skipped.
+ *
+ * After a successful push the snapshot is refreshed with the values just
+ * sent so the next pass sees no divergence even before the next pull.
+ *
+ * The push callbacks' error type is generic. The reconciler doesn't inspect
+ * or recover from those errors — it propagates so the outer `Effect.result`
+ * at the call site can record the binding's `lastError`. Generic-`E` keeps
+ * this module decoupled from the HTTP error hierarchy of `GitHubApi`.
+ */
+export const pushRepoUpdates: <E, R>(
+  binding: Cursor.ExternalCursor,
+  repo: GitHubApi.GitHubRepo,
+  remoteIssuesById: ReadonlyMap<string, GitHubApi.GitHubIssue>,
+  push: {
+    /** Wraps `GitHubApi.updateIssue`. */
+    updateIssue: (
+      owner: string,
+      repo: string,
+      issueNumber: number,
+      input: GitHubApi.IssueUpdateInput,
+    ) => Effect.Effect<void, E, R>;
+    /** Wraps `GitHubApi.updateRepo`. */
+    updateRepo: (owner: string, repo: string, input: GitHubApi.RepoUpdateInput) => Effect.Effect<void, E, R>;
+  },
+) => Effect.Effect<GitHubPushResult, E, Database.Service | R> = Effect.fn('pushRepoUpdates')(
+  function* (binding, repo, remoteIssuesById, push) {
+    let projects = 0;
+    let tasks = 0;
+
+    // Project (repo) push — description only.
+    {
+      const fid = String(repo.id);
+      const local = yield* findByForeignId<TaskSet.TaskSet>(TaskSet.TaskSet, repo.id);
+      if (local && !Obj.isDeleted(local)) {
+        const snapshot = Cursor.readSnapshot<ProjectSnapshot>(binding, fid);
+        if (snapshot) {
+          const localName = local.name ?? '';
+          const localDescription = local.description ?? '';
+          const input: GitHubApi.RepoUpdateInput = {};
+          let diverged = false;
+          if (snapshot.description !== undefined && snapshot.description !== localDescription) {
+            input.description = localDescription;
+            diverged = true;
+          }
+          if (snapshot.name !== undefined && snapshot.name !== localName) {
+            // We deliberately don't push repo renames — see updateRepo above.
+            // Log instead so the user can chase down via the audit channel.
+            log.warn('github push: local repo name diverges from remote; rename push is intentionally disabled', {
+              repoId: fid,
+              localName,
+              snapshotName: snapshot.name,
+            });
+          }
+          if (diverged) {
+            yield* push.updateRepo(repo.owner.login, repo.name, input);
+            Cursor.writeSnapshot(binding, fid, {
+              ...snapshot,
+              description: localDescription,
+            });
+            projects++;
+          }
+        }
+      }
+    }
+
+    // Task (issue) push — title / body / state.
+    for (const [id, remoteIssue] of remoteIssuesById) {
+      const local = yield* findByForeignId<Task.Task>(Task.Task, id);
+      if (!local || Obj.isDeleted(local)) {
+        continue;
+      }
+      const snapshot = Cursor.readSnapshot<TaskSnapshot>(binding, id);
+      if (!snapshot) {
+        continue;
+      }
+      const localTitle = local.title ?? '';
+      const localDescription = local.description ?? '';
+      const localStatus = local.status;
+      const desiredStatusForSnapshot: 'todo' | 'done' | undefined =
+        localStatus === 'done' ? 'done' : localStatus === 'todo' || localStatus === 'started' ? 'todo' : undefined;
+
+      const input: GitHubApi.IssueUpdateInput = {};
+      let diverged = false;
+      if (snapshot.title !== undefined && snapshot.title !== localTitle) {
+        input.title = localTitle;
+        diverged = true;
+      }
+      if (snapshot.description !== undefined && snapshot.description !== localDescription) {
+        input.body = localDescription;
+        diverged = true;
+      }
+      // Status push is pull-only for PRs. GitHub uses the same /issues/{n}
+      // endpoint for issues and PRs, but `state: 'closed'` on a PR rejects
+      // it (the closed-without-merge red badge), and merging requires a
+      // separate `PUT /pulls/{n}/merge` endpoint we don't support. The safe
+      // default is to never push a status change for a PR — log if local
+      // and snapshot diverge so the divergence is auditable.
+      const isPullRequest = remoteIssue.pull_request != null;
+      if (
+        !isPullRequest &&
+        snapshot.status !== undefined &&
+        desiredStatusForSnapshot !== undefined &&
+        snapshot.status !== desiredStatusForSnapshot
+      ) {
+        const issueState = taskStatusToIssueState(localStatus);
+        if (issueState) {
+          input.state = issueState;
+          diverged = true;
+        }
+      } else if (
+        isPullRequest &&
+        snapshot.status !== undefined &&
+        desiredStatusForSnapshot !== undefined &&
+        snapshot.status !== desiredStatusForSnapshot
+      ) {
+        log.warn('github push: PR status diverged locally; pull-only for PRs (status will not be pushed)', {
+          issueId: id,
+          number: remoteIssue.number,
+          localStatus,
+          snapshotStatus: snapshot.status,
+        });
+      }
+      if (!diverged) {
+        continue;
+      }
+
+      yield* push.updateIssue(repo.owner.login, repo.name, remoteIssue.number, input);
+      // Refresh the snapshot: title / description / status sent. Status only
+      // gets refreshed when we actually pushed a state change (issues only) —
+      // for PRs we keep the snapshot's previous status, so the warning above
+      // keeps firing until either the user reverts locally or the PR's state
+      // changes on GitHub and a pull catches up.
+      Cursor.writeSnapshot(binding, id, {
+        ...snapshot,
+        title: localTitle,
+        description: localDescription,
+        status: input.state !== undefined ? (desiredStatusForSnapshot ?? snapshot.status) : snapshot.status,
+      });
+      tasks++;
+    }
+
+    return { projects, tasks };
+  },
+);
+
+//
+// Main handler
+//
+
+/**
+ * Per-binding sync body run by the account-level fan-out: reconcile the one repo the
+ * binding targets, stamping success/failure onto the binding and toasting either way.
+ */
+const syncRepoBinding = Effect.fn('syncRepoBinding')(function* (binding: Cursor.ExternalCursor) {
+  const project = yield* Database.load(binding.spec.target);
+  const db = Obj.getDatabase(binding) ?? Obj.getDatabase(project);
+  if (!db) {
+    return yield* Effect.fail(new ConnectorSync.DatabaseMissingError());
+  }
+
+  // The repo's foreign id: prefer the binding's `externalId`, falling back
+  // to the GitHub foreign key on the target object.
+  const externalId =
+    binding.spec.externalId ?? Obj.getMeta(project).keys.find((key) => key.source === GITHUB_SOURCE)?.id;
+
+  const outcome = yield* Effect.result(
+    Effect.gen(function* () {
+      if (externalId === undefined) {
+        return yield* Effect.fail(new GitHubRepoUnresolvedError());
+      }
+
+      // Fetch all repos visible to the token once so the binding can
+      // resolve its remote `GitHubRepo`. The binding stores the numeric
+      // repo id as `externalId` (a stringified integer).
+      // TODO(wittjosiah): Switch to `fetchRepo(owner, name)` once the
+      //   binding carries `owner`/`name`. `fetchUserRepos()` walks every
+      //   repo the token can see and dominates large-account syncs.
+      const allRepos = yield* GitHubApi.fetchUserRepos();
+      const remoteRepo = allRepos.find((repo) => String(repo.id) === externalId);
+      if (!remoteRepo) {
+        return yield* Effect.fail(new GitHubRepoInaccessibleError());
+      }
+
+      const options = (binding.spec.options ?? undefined) as GitHubOperation.SyncOptions | undefined;
+
+      // Upsert the local Project for this repo (three-way merge).
+      yield* upsertProject(binding, remoteRepo);
+
+      // Cross-issue dedup for Person upserts: parallel per-issue work can
+      // race two upserts for the same login (same assignee on multiple
+      // issues, or org members). Without serialization both fibers find no
+      // foreign-key match, both insert, leaving duplicate Person rows. The
+      // semaphore + cache pair gives us a single in-flight upsert per login;
+      // subsequent callers read from `personByLogin`.
+      const personByLogin = new Map<string, Person.Person>();
+      const personSemaphore = yield* Semaphore.make(1);
+      const ensurePerson = (user: GitHubApi.GitHubUser, organization: Organization.Organization | undefined) =>
+        personSemaphore.withPermits(1)(
+          Effect.gen(function* () {
+            const cached = personByLogin.get(user.login);
+            if (cached) {
+              return cached;
+            }
+            const person = yield* upsertPerson(user, organization);
+            personByLogin.set(user.login, person);
+            return person;
+          }),
+        );
+
+      // Auto-pull the owning org + members for this repo's owner.
+      // `/orgs/{owner}` returns 404 for user-owned repos (personal
+      // accounts are not orgs). Treat that as "no org to sync" and
+      // continue — the Project just won't have a parent organization.
+      let pulledOrganizations = 0;
+      const owner = remoteRepo.owner.login;
+      const orgResult = yield* Effect.result(GitHubApi.fetchOrg(owner));
+      if (orgResult._tag === 'Success') {
+        const organization = yield* upsertOrganization(orgResult.success);
+        pulledOrganizations++;
+        const members = yield* GitHubApi.fetchOrgMembers(owner);
+        for (const member of members) {
+          yield* ensurePerson(member, organization);
+        }
+      } else {
+        log.info('github sync: owner is not an org, skipping org/member pull', { owner });
+      }
+
+      // Re-resolve the local Project after upsert so issue upserts and
+      // pushes operate on the persisted record.
+      const localProject = yield* findByForeignId<TaskSet.TaskSet>(TaskSet.TaskSet, remoteRepo.id);
+      if (!localProject) {
+        return yield* Effect.fail(new GitHubProjectMissingError());
+      }
+
+      // Milestones before issues: an issue's `milestone` has to resolve to a local mirror, and the
+      // repo endpoint also surfaces milestones no open issue points at yet.
+      const milestoneByRemoteId = new Map<number, Milestone.Milestone>();
+      const remoteMilestones = yield* GitHubApi.fetchRepoMilestones(remoteRepo.owner.login, remoteRepo.name);
+      for (const remoteMilestone of remoteMilestones) {
+        milestoneByRemoteId.set(remoteMilestone.id, yield* upsertMilestone(localProject, remoteMilestone));
+      }
+
+      let pulledTasks = 0;
+      const since = sinceFromOptions(options);
+      const issues = yield* GitHubApi.fetchRepoIssues(remoteRepo.owner.login, remoteRepo.name, { since });
+      const remoteIssuesById = new Map<string, GitHubApi.GitHubIssue>();
+      const pulled = yield* Effect.forEach(
+        issues,
+        (issue) =>
+          Effect.gen(function* () {
+            // Resolve assignee — first assignee only for v1. External
+            // (non-org) assignees are upserted lazily; the semaphored
+            // `ensurePerson` dedups across fibers.
+            const assigneeUser = issue.assignees?.[0];
+            const assignedPerson = assigneeUser ? yield* ensurePerson(assigneeUser, undefined) : undefined;
+            const milestone = issue.milestone ? milestoneByRemoteId.get(issue.milestone.id) : undefined;
+
+            const { task, created } = yield* upsertTask(binding, issue, assignedPerson, milestone);
+            remoteIssuesById.set(String(issue.id), issue);
+            if (created) {
+              pulledTasks++;
+            }
+
+            // TODO(wittjosiah): Comments sync disabled — re-enable once
+            // chunked/yielded to avoid automerge_wasm crash when upserting
+            // many comments in one tick.
+            return task;
+          }),
+        { concurrency: ISSUE_CONCURRENCY },
+      );
+
+      // Sequential: `TaskSet.tasks` is one shared array, so concurrent appends would drop entries.
+      // `Effect.forEach` preserves input order, so the set's order mirrors GitHub's.
+      for (const task of pulled) {
+        yield* setTaskContainer(task, localProject);
+      }
+
+      // Push: snapshot-diff the local Project + Tasks for this repo and
+      // PATCH only the diverged fields.
+      //
+      // TODO(wittjosiah): `remoteIssuesById` is built from
+      //   `fetchRepoIssues(..., { since })`, so when `maxDaysBack` is set
+      //   this push pass cannot see locally-edited tasks whose remote issue
+      //   is older than the window. Switch the candidate set to the local
+      //   mirror (every Task with a GITHUB_SOURCE fk under this repo) once
+      //   we store `number` per task so we don't need the remote payload to PATCH.
+      const pushResult = yield* pushRepoUpdates(binding, remoteRepo, remoteIssuesById, {
+        updateIssue: (owner, repoName, issueNumber, input) =>
+          GitHubApi.updateIssue(owner, repoName, issueNumber, input).pipe(Effect.map(() => undefined)),
+        updateRepo: (owner, repoName, input) =>
+          GitHubApi.updateRepo(owner, repoName, input).pipe(Effect.map(() => undefined)),
+      });
+
+      return {
+        pulled: {
+          organizations: pulledOrganizations,
+          people: personByLogin.size,
+          projects: 1,
+          tasks: pulledTasks,
+          comments: 0,
+        },
+        pushed: pushResult,
+      };
+    }).pipe(Effect.provide(Layer.provideMerge(Database.layer(db), GitHubApi.fromAccessToken(binding.spec.source)))),
+  );
+
+  // Write sync state onto the binding.
+  if (outcome._tag === 'Success') {
+    Cursor.advance(binding);
+    yield* Effect.ignore(
+      Operation.invoke(LayoutOperation.AddToast, {
+        id: `${meta.profile.key}.sync-success`,
+        icon: 'ph--check--regular',
+        title: ['sync-toast.success.label', { ns: meta.profile.key }],
+      }),
+    );
+    return { pulled: outcome.success.pulled };
+  } else {
+    const message = formatGitHubSyncFailure(outcome.failure);
+    Cursor.recordError(binding, message);
+    log.warn('github sync: binding failed', { error: outcome.failure });
+    yield* Effect.ignore(
+      Operation.invoke(LayoutOperation.AddToast, {
+        id: `${meta.profile.key}.sync-error`,
+        icon: 'ph--warning--regular',
+        title: ['sync-toast.error.label', { ns: meta.profile.key }],
+        description: message,
+      }),
+    );
+    return yield* Effect.fail(outcome.failure);
+  }
+}, Effect.provide(FetchHttpClient.layer));
+
+const handler: Operation.WithHandler<typeof GitHubOperation.SyncGitHubRepositories> =
+  GitHubOperation.SyncGitHubRepositories.pipe(
+    Operation.withHandler(({ connection, priority }) =>
+      Binding.syncAll({
+        connection,
+        priority,
+        sync: (binding) => syncRepoBinding(binding),
+      }).pipe(
+        Effect.map(({ outputs }) => ({
+          pulled: outputs.reduce(
+            (total, { pulled }) => ({
+              organizations: total.organizations + pulled.organizations,
+              people: total.people + pulled.people,
+              projects: total.projects + pulled.projects,
+              tasks: total.tasks + pulled.tasks,
+              comments: total.comments + pulled.comments,
+            }),
+            { organizations: 0, people: 0, projects: 0, tasks: 0, comments: 0 },
+          ),
+        })),
+      ),
+    ),
+  );
+
+export default handler;