Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

59.0 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { promises as fs } from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import { GitHubIssueCache } from './cache'
import {
  evictPullsToFit,
  FULL_REFRESH_MIN_INTERVAL_MS,
  GitHubIssueService,
  REFRESH_MIN_INTERVAL_MS,
  type GitHubIssueServiceContext,
  type GitHubIssuesClientLike
} from './service'
import { GitHubRequestCoordinator } from './request-coordinator'
import type {
  GitHubIssue,
  IssueHeartbeatResult,
  IssuePageResult,
  ListIssueOptions,
  NormalisedProjectKanbanGitHub,
  UpdateIssueInput
} from '../../shared/github-issues'

let userDataDir: string

const config: NormalisedProjectKanbanGitHub = {
  repository: 'o/r',
  columnMappings: [
    { columnId: 'todo', label: 'status:todo' },
    { columnId: 'doing', label: 'status:doing' },
    { columnId: 'done', label: 'status:done' }
  ],
  completionColumnId: 'done',
  revision: 'mapping-1'
}

const issue = (number: number, over: Partial<GitHubIssue> = {}): GitHubIssue => ({
  id: 1_000 + number,
  number,
  title: `Issue ${number}`,
  body: '',
  state: 'open',
  stateReason: null,
  htmlUrl: `https://github.com/o/r/issues/${number}`,
  apiUrl: `https://api.github.com/repos/o/r/issues/${number}`,
  labels: [],
  assignees: [],
  createdAt: '2026-08-01T10:00:00Z',
  updatedAt: `2026-08-09T10:00:${String(number).padStart(2, '0')}Z`,
  locked: false,
  ...over
})

class FixtureClient implements GitHubIssuesClientLike {
  issues = new Map<number, GitHubIssue>()
  updates: Array<{ number: number; input: UpdateIssueInput }> = []
  /** What GitHub records as the reason when the write names none, or overrides the one asked for. */
  recordedReason?: GitHubIssue['stateReason']
  repositoryLabels: Array<{ id: number; name: string; color: string; description: null }> = []
  createdLabels: Array<{ name: string; color: string }> = []

  constructor(issues: GitHubIssue[]) {
    for (const item of issues) this.issues.set(item.number, item)
  }

  heartbeats: Array<string | undefined> = []

  async listIssues(_repository: string, _options: ListIssueOptions): Promise<IssuePageResult> {
    return { items: [...this.issues.values()] }
  }

  /** Honest stand-in for GitHub's conditional heartbeat: the validator is derived from the most
   *  recently updated item, exactly what the real endpoint's body (and so its ETag) depends on. */
  currentHeartbeatEtag(): string {
    const top = [...this.issues.values()]
      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || b.number - a.number)[0]
    return top ? `W/"${top.number}@${top.updatedAt}"` : 'W/"empty"'
  }

  async issuesHeartbeat(_repository: string, etag?: string): Promise<IssueHeartbeatResult> {
    this.heartbeats.push(etag)
    const current = this.currentHeartbeatEtag()
    return etag === current ? { notModified: true, etag } : { notModified: false, etag: current }
  }

  async getIssue(_repository: string, number: number) {
    return structuredClone(this.issues.get(number)!)
  }

  async updateIssue(
    _repository: string,
    number: number,
    input: UpdateIssueInput
  ) {
    this.updates.push({ number, input: structuredClone(input) })
    const current = this.issues.get(number)!
    const updated = {
      ...current,
      ...(input.state ? {
        state: input.state,
        stateReason: this.recordedReason !== undefined
          ? this.recordedReason
          : input.stateReason ?? (input.state === 'closed' ? 'completed' as const : 'reopened' as const)
      } : {}),
      ...(input.labels ? {
        labels: input.labels.map((name, index) => ({ id: index + 1, name, color: '8b5cf6' }))
      } : {}),
      updatedAt: '2026-08-09T11:00:00Z'
    }
    this.issues.set(number, updated)
    return structuredClone(updated)
  }

  async listRepositoryLabels() { return { items: structuredClone(this.repositoryLabels) } }
  async createLabel(_repository: string, input: { name: string; color: string }) {
    this.createdLabels.push(structuredClone(input))
    const label = { id: 99 + this.createdLabels.length, name: input.name, color: input.color, description: null }
    this.repositoryLabels.push(label)
    return label
  }

  // The report path does not run through GitHubIssueService, so these are declaration-only here.
  // They must still THROW rather than return a fake issue: a test that accidentally reaches them
  // should fail loudly instead of asserting against a value nothing produced.
  async createIssue(): Promise<never> { throw new Error('createIssue not used by this fixture') }
  async createIssueComment(): Promise<never> {
    throw new Error('createIssueComment not used by this fixture')
  }
}

function context(client: FixtureClient, over: Partial<GitHubIssueServiceContext> = {}): GitHubIssueServiceContext {
  return {
    localApprovalId: 'local-1',
    projectId: 'project-1',
    repository: 'o/r',
    config,
    controlRevision: 1,
    credentialGeneration: 1,
    userId: 'user-1',
    client,
    columnColors: { todo: '#0a84ff', doing: '#ffd60a', done: '#30d158' },
    mappingApproved: true,
    ...over
  }
}

beforeEach(async () => {
  userDataDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nt-github-service-'))
})

afterEach(async () => {
  await fs.rm(userDataDir, { recursive: true, force: true })
})

describe('evictPullsToFit', () => {
  const pull = (number: number): GitHubIssue =>
    issue(number, { pull: { draft: false, mergedAt: null } })

  it('leaves a harvest that already fits untouched', () => {
    const items = [issue(1), pull(2)]
    expect(evictPullsToFit(items, () => true)).toEqual({ items, pullsTruncated: false })
  })

  it('drops the oldest pull requests and keeps every issue', () => {
    const items = [issue(1), issue(2), pull(3), pull(4), pull(5)]
    const trimmed = evictPullsToFit(items, (candidate) => candidate.length <= 3)
    expect(trimmed?.pullsTruncated).toBe(true)
    expect(trimmed?.items.map((item) => item.number).sort()).toEqual([1, 2, 5])
  })

  it('refuses when the issues alone miss the bound, leaving the incomplete path to answer', () => {
    expect(evictPullsToFit([issue(1), issue(2), pull(3)], (candidate) => candidate.length <= 1))
      .toBeNull()
  })
})

describe('GitHubIssueService', () => {
  it('renders a cached snapshot immediately and refreshes it in the background', async () => {
    const client = new FixtureClient([issue(2)])
    let release!: () => void
    let started!: () => void
    const refreshStarted = new Promise<void>((resolve) => { started = resolve })
    client.listIssues = async () => {
      started()
      await new Promise<void>((resolve) => { release = resolve })
      return { items: [issue(2)] }
    }
    const cache = new GitHubIssueCache(userDataDir)
    await cache.bind('local-1', 'project-1', 'o/r', 'user-1')
    await cache.saveComplete('user-1', 'o/r', {
      issues: [issue(1)], etags: {}, lastSuccessfulRefreshAt: 1, lastFullReconciliationAt: 1
    })
    let refreshed!: () => void
    const refreshFinished = new Promise<void>((resolve) => { refreshed = resolve })
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      onDelta: () => refreshed()
    })

    const initial = await service.subscribe(1, { projectId: 'project-1' })
    expect(initial.items.map((item) => item.number)).toEqual([1])
    await refreshStarted
    release()
    await refreshFinished
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).items
      .map((item) => item.number)).toEqual([2])
  })

  it('does not repopulate private data when cache is cleared during a refresh', async () => {
    const client = new FixtureClient([issue(2)])
    let release!: () => void
    let started!: () => void
    const refreshStarted = new Promise<void>((resolve) => { started = resolve })
    client.listIssues = async () => {
      started()
      await new Promise<void>((resolve) => { release = resolve })
      return { items: [issue(2)] }
    }
    const cache = new GitHubIssueCache(userDataDir)
    await cache.bind('local-1', 'project-1', 'o/r', 'user-1')
    await cache.saveComplete('user-1', 'o/r', {
      issues: [issue(1)], etags: {}, lastSuccessfulRefreshAt: 1, lastFullReconciliationAt: 1
    })
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      projectContextForCacheDeletion: async () => context(client)
    })

    const refreshing = service.refresh({ projectId: 'project-1', full: true })
    await refreshStarted
    const clearing = service.clearCache({ projectId: 'project-1' })
    release()
    await Promise.all([refreshing, clearing])

    expect(await cache.boundUserId('local-1', 'project-1', 'o/r')).toBeNull()
    expect(await cache.load('user-1', 'o/r')).toEqual({ version: 1 })
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).items)
      .toEqual([])
  })

  it('blocks a mutation whose repository state would be created after cache deletion begins', async () => {
    const shown = issue(42)
    const client = new FixtureClient([shown])
    const cache = new GitHubIssueCache(userDataDir)
    await cache.bind('local-1', 'project-1', 'o/r', 'user-1')
    await cache.saveComplete('user-1', 'o/r', {
      issues: [shown], etags: {}, lastSuccessfulRefreshAt: 1, lastFullReconciliationAt: 1
    })
    let releaseContext!: () => void
    let contextStarted!: () => void
    const started = new Promise<void>((resolve) => { contextStarted = resolve })
    let contextCalls = 0
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => {
        contextCalls += 1
        if (contextCalls === 1) {
          contextStarted()
          await new Promise<void>((resolve) => { releaseContext = resolve })
        }
        return context(client)
      },
      projectContextForCacheDeletion: async () => context(client)
    })

    const moving = service.moveIssue({
      projectId: 'project-1', issueNumber: 42, toColumnId: 'doing',
      expectedUpdatedAt: shown.updatedAt
    })
    await started
    const clearing = service.clearCache({ projectId: 'project-1' })
    releaseContext()
    const [moveResult] = await Promise.all([moving, clearing])

    expect(moveResult.status).toBe('read-only')
    expect(client.updates).toEqual([])
    expect(await cache.load('user-1', 'o/r')).toEqual({ version: 1 })
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).items)
      .toEqual([])
  })

  it('purges subscribed in-memory issue bodies and emits an empty cache-change delta', async () => {
    const client = new FixtureClient([issue(1, { body: 'private issue body' })])
    const deltas: number[][] = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      projectContextForCacheDeletion: async () => context(client),
      onDelta: (_uiId, _projectId, numbers) => deltas.push(numbers)
    })
    await service.subscribe(1, { projectId: 'project-1' })
    deltas.length = 0

    await service.clearCache({ projectId: 'project-1' })

    expect(deltas).toEqual([[]])
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).items)
      .toEqual([])
  })

  it('waits for a cache writer from another project sharing the repository', async () => {
    class PausingCache extends GitHubIssueCache {
      pause = false
      private releaseWrite!: () => void
      private writeStarted!: () => void
      readonly started = new Promise<void>((resolve) => { this.writeStarted = resolve })

      release(): void { this.releaseWrite() }

      override async saveComplete(
        userId: string,
        repository: string,
        snapshot: Parameters<GitHubIssueCache['saveComplete']>[2]
      ): Promise<void> {
        if (this.pause) {
          this.writeStarted()
          await new Promise<void>((resolve) => { this.releaseWrite = resolve })
        }
        await super.saveComplete(userId, repository, snapshot)
      }
    }
    const shown = issue(42)
    const client = new FixtureClient([shown])
    const cache = new PausingCache(userDataDir)
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async (projectId) => context(client, { projectId }),
      projectContextForCacheDeletion: async (projectId) => context(client, { projectId })
    })
    await service.refresh({ projectId: 'project-1', full: true })
    await service.refresh({ projectId: 'project-2', full: true })
    cache.pause = true

    const moving = service.moveIssue({
      projectId: 'project-2', issueNumber: 42, toColumnId: 'doing',
      expectedUpdatedAt: shown.updatedAt
    })
    await cache.started
    let clearFinished = false
    const clearing = service.clearCache({ projectId: 'project-1' })
      .then(() => { clearFinished = true })
    await new Promise((resolve) => setTimeout(resolve, 0))
    expect(clearFinished).toBe(false)

    cache.release()
    await Promise.all([moving, clearing])

    expect(await cache.load('user-1', 'o/r')).toEqual({ version: 1 })
  })

  it('rebuilds every page unconditionally during a full reconciliation', async () => {
    const client = new FixtureClient([])
    const calls: Array<{ page: number; etag?: string }> = []
    client.listIssues = async (_repository: string, options: { page: number; etag?: string }) => {
      calls.push({ page: options.page, ...(options.etag ? { etag: options.etag } : {}) })
      return options.page === 1
        ? { items: [issue(1)], nextPage: 2, etag: 'page-one' }
        : { items: [issue(2)], etag: 'page-two' }
    }
    const cache = new GitHubIssueCache(userDataDir)
    await cache.saveComplete('user-1', 'o/r', {
      issues: [issue(99)], etags: { old: 'etag' },
      lastSuccessfulRefreshAt: 1, lastFullReconciliationAt: 1
    })
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      now: () => 10_000
    })

    await service.refresh({ projectId: 'project-1', full: true })

    expect(calls).toEqual([{ page: 1 }, { page: 2 }])
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).items
      .map((item) => item.number)).toEqual([2, 1])
  })

  it('advances the incremental watermark to refresh start, not completion', async () => {
    const client = new FixtureClient([issue(1)])
    const times = [1_000, 9_000, 12_000]
    const cache = new GitHubIssueCache(userDataDir)
    await cache.saveComplete('user-1', 'o/r', {
      issues: [], etags: {}, lastSuccessfulRefreshAt: 500, lastFullReconciliationAt: 999
    })
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      now: () => times.shift() ?? 12_000
    })
    await service.refresh({ projectId: 'project-1' })
    const saved = await cache.load('user-1', 'o/r')
    expect(saved.lastComplete?.lastSuccessfulRefreshAt).toBe(1_000)
  })

  it('does not let one of our own writes advance the incremental watermark', async () => {
    // Only a completed scan has looked at everything up to its start. Our write looked at ONE
    // issue, so a third party's change landing between the last scan and our write must still be
    // inside the next incremental `since` window, not deferred to the daily full pass.
    const client = new FixtureClient([issue(1), issue(2)])
    const sinces: Array<string | undefined> = []
    client.listIssues = async (_repository, options: ListIssueOptions) => {
      sinces.push(options.since)
      return { items: [...client.issues.values()]
        .filter((item) => !options.since || item.updatedAt >= options.since) }
    }
    let clock = Date.parse('2026-08-09T10:05:00Z')
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      now: () => clock
    })
    await service.refresh({ projectId: 'project-1', full: true })

    // Someone else edits issue 2 after our scan...
    client.issues.set(2, issue(2, { title: 'Renamed elsewhere', updatedAt: '2026-08-09T10:06:00Z' }))
    // ...and only then do we move issue 1.
    clock = Date.parse('2026-08-09T10:10:00Z')
    expect((await service.moveIssue({
      projectId: 'project-1', issueNumber: 1, toColumnId: 'doing',
      expectedUpdatedAt: issue(1).updatedAt
    })).status).toBe('confirmed')

    clock = Date.parse('2026-08-09T12:00:00Z')
    await service.refresh({ projectId: 'project-1' })
    expect(sinces.at(-1)).toBe(new Date(Date.parse('2026-08-09T10:05:00Z') - 2_000).toISOString())
    const shown = await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })
    expect(shown.items.find((item) => item.number === 2)?.title).toBe('Renamed elsewhere')
    // The page's "last refreshed" is the scan's, not the write's: nothing was re-read then.
    expect(shown.lastSuccessfulRefreshAt).toBe(Date.parse('2026-08-09T12:00:00Z'))
  })

  it('refreshes and maps open, closed, unmatched, and conflicting issues', async () => {
    const client = new FixtureClient([
      issue(1, { labels: [{ id: 1, name: 'status:todo', color: '0a84ff' }] }),
      issue(2),
      issue(3, { labels: [
        { id: 1, name: 'status:todo', color: '0a84ff' },
        { id: 2, name: 'status:doing', color: 'ffd60a' }
      ] }),
      issue(4, { state: 'closed', labels: [] })
    ])
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      now: () => 10_000
    })
    await service.refresh({ projectId: 'project-1', full: true })

    expect((await service.query({ projectId: 'project-1', columnId: 'todo', pageSize: 50 })).items
      .map((item) => item.number)).toEqual([1])
    const ungrouped = await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })
    expect(ungrouped.items.map((item) => [item.number, item.conflict])).toEqual([
      [3, 'multiple-mapped-labels'],
      [2, null]
    ])
    expect((await service.query({ projectId: 'project-1', columnId: 'done', pageSize: 50 })).items
      .map((item) => item.number)).toEqual([4])
  })

  it('reads and clears an approved private cache while signed out', async () => {
    const client = new FixtureClient([issue(1)])
    const cache = new GitHubIssueCache(userDataDir)
    const online = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })
    await online.refresh({ projectId: 'project-1', full: true })

    const offline = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => { throw new Error('not-authenticated') },
      projectContextForCache: async () => {
        const { credentialGeneration: _generation, userId: _userId, client: _client, ...base } = context(client)
        return base
      }
    })
    expect((await offline.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).items
      .map((item) => item.number)).toEqual([1])
    await offline.clearCache({ projectId: 'project-1' })
    expect(await cache.boundUserId('local-1', 'project-1', 'o/r')).toBeNull()
    expect(await cache.load('user-1', 'o/r')).toEqual({ version: 1 })
  })

  it('uses one poll timer for every visible subscriber to the same repository', async () => {
    const client = new FixtureClient([])
    const timers: Array<() => Promise<void>> = []
    const cleared: unknown[] = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length },
      clearInterval: (id) => { cleared.push(id) }
    })
    await service.subscribe(1, { projectId: 'project-1' })
    await service.subscribe(2, { projectId: 'project-1' })
    expect(timers).toHaveLength(1)
    service.unsubscribe(1, 'project-1')
    expect(cleared).toEqual([])
    service.unsubscribe(2, 'project-1')
    expect(cleared).toEqual([1])
  })

  it('polls through an invalid shared project to a valid project for the repository', async () => {
    const client = new FixtureClient([issue(1)])
    const timers: Array<() => Promise<void>> = []
    let firstProjectValid = true
    const deltas: Array<[string, number[]]> = []
    const polledProjects: string[] = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async (projectId) => {
        if (!firstProjectValid) polledProjects.push(projectId)
        if (projectId === 'project-1' && !firstProjectValid) throw new Error('approval-revoked')
        return context(client, { projectId })
      },
      setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length },
      onDelta: (_uiId, projectId, numbers) => { deltas.push([projectId, numbers]) }
    })
    await service.subscribe(1, { projectId: 'project-1' })
    await service.subscribe(2, { projectId: 'project-2' })
    firstProjectValid = false
    client.issues.set(2, issue(2))

    await timers[0]()

    expect(polledProjects[0]).toBe('project-1')
    expect(polledProjects).toContain('project-2')
    expect(deltas).toContainEqual(['project-2', [2]])
    expect((await service.query({ projectId: 'project-2', columnId: null, pageSize: 50 })).items
      .map((item) => item.number)).toEqual([2, 1])
  })

  it('migrates subscribers and timer ownership when the authenticated identity changes', async () => {
    const firstClient = new FixtureClient([issue(1)])
    const secondClient = new FixtureClient([issue(2)])
    const timers: Array<() => Promise<void>> = []
    const cleared: unknown[] = []
    let identity = 'user-1'
    let refreshed!: () => void
    const refreshSeen = new Promise<void>((resolve) => { refreshed = resolve })
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(
        identity === 'user-1' ? firstClient : secondClient,
        { userId: identity, credentialGeneration: identity === 'user-1' ? 1 : 2 }
      ),
      setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length },
      clearInterval: (timer) => { cleared.push(timer) },
      onDelta: (_uiId, _projectId, numbers) => {
        if (numbers.includes(2)) refreshed()
      }
    })
    await service.subscribe(7, { projectId: 'project-1' })
    identity = 'user-2'

    await timers[0]()
    await refreshSeen

    expect(cleared).toEqual([1])
    expect(timers).toHaveLength(2)
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).items
      .map((item) => item.number)).toEqual([2])
    service.unsubscribe(7, 'project-1')
    expect(cleared).toEqual([1, 2])
  })

  it('drops all subscriptions for a disconnected client and sends deltas only to subscribers', async () => {
    const client = new FixtureClient([issue(1)])
    const deltas: Array<[number, string, number[]]> = []
    const timers: Array<() => void> = []
    const cleared: unknown[] = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async (projectId) => context(client, { projectId }),
      setInterval: (fn) => { timers.push(fn); return timers.length },
      clearInterval: (id) => { cleared.push(id) },
      onDelta: (uiId, projectId, numbers) => deltas.push([uiId, projectId, numbers])
    })
    await service.subscribe(7, { projectId: 'project-1' })
    await service.subscribe(8, { projectId: 'project-2' })
    client.issues.set(2, issue(2))
    await service.refresh({ projectId: 'project-1', full: true })
    expect(deltas.slice(-2)).toEqual([
      [7, 'project-1', [2]],
      [8, 'project-2', [2]]
    ])

    service.dropClient(7)
    service.dropClient(8)
    expect(cleared).toEqual([1])
  })

  it('notifies subscribers when a full refresh only removes issues', async () => {
    const client = new FixtureClient([issue(1), issue(2)])
    const deltas: number[][] = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      onDelta: (_uiId, _projectId, numbers) => deltas.push(numbers)
    })
    await service.subscribe(1, { projectId: 'project-1' })
    deltas.length = 0
    client.issues.delete(2)

    await service.refresh({ projectId: 'project-1', full: true })

    expect(deltas).toEqual([[2]])
  })

  it('notifies subscribers when a refresh changes completeness without issue changes', async () => {
    const client = new FixtureClient([])
    client.listIssues = async () => ({
      items: Array.from({ length: 10_001 }, (_, index) => issue(index + 1))
    })
    const deltas: number[][] = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      onDelta: (_uiId, _projectId, numbers) => deltas.push(numbers)
    })
    await service.subscribe(1, { projectId: 'project-1' })

    expect(deltas).toEqual([[]])
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).readOnly)
      .toBe(true)
  })

  it('calculates counts from the active search and GitHub label filter', async () => {
    const client = new FixtureClient([
      issue(1, { title: 'Alpha bug', labels: [{ id: 1, name: 'bug', color: 'd73a4a' }] }),
      issue(2, { title: 'Beta task', labels: [{ id: 2, name: 'feature', color: '0a84ff' }] })
    ])
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir), coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })
    await service.refresh({ projectId: 'project-1', full: true })
    const page = await service.query({
      projectId: 'project-1', columnId: null, pageSize: 50,
      search: 'alpha', labelFilter: ['github:bug']
    })
    expect(page.items.map((item) => item.number)).toEqual([1])
    expect(page.counts).toEqual({ ungrouped: 1 })
  })

  it('closes in completion, reopens outside it, and preserves unrelated labels', async () => {
    const shown = issue(42, {
      state: 'closed',
      labels: [
        { id: 1, name: 'status:done', color: '30d158' },
        { id: 2, name: 'bug', color: 'd73a4a' }
      ]
    })
    const client = new FixtureClient([shown])
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator({ sleep: async () => undefined }),
      contextForProject: async () => context(client)
    })
    await service.refresh({ projectId: 'project-1', full: true })
    const result = await service.moveIssue({
      projectId: 'project-1', issueNumber: 42, toColumnId: 'todo', expectedUpdatedAt: shown.updatedAt
    })
    expect(result.status).toBe('confirmed')
    expect(client.updates).toEqual([{ number: 42, input: {
      state: 'open', stateReason: 'reopened', labels: ['bug', 'status:todo']
    } }])
  })

  it('returns stale data without writing when the displayed version changed', async () => {
    const client = new FixtureClient([issue(42, { updatedAt: '2026-08-09T11:00:00Z' })])
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })
    await service.refresh({ projectId: 'project-1', full: true })
    const result = await service.moveIssue({
      projectId: 'project-1', issueNumber: 42, toColumnId: 'doing',
      expectedUpdatedAt: '2026-08-09T10:00:00Z'
    })
    expect(result).toMatchObject({ status: 'stale', issue: { updatedAt: '2026-08-09T11:00:00Z' } })
    expect(client.updates).toEqual([])
  })

  it('rejects mutation when the repository is incomplete or the issue is outside the complete snapshot', async () => {
    const client = new FixtureClient([issue(42)])
    const cache = new GitHubIssueCache(userDataDir)
    await cache.saveIncompleteAttempt('user-1', 'o/r', {
      reason: 'issue-limit', observedAt: 1, partialIssues: [issue(42)]
    })
    const service = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })
    expect(await service.moveIssue({
      projectId: 'project-1', issueNumber: 42, toColumnId: 'doing',
      expectedUpdatedAt: issue(42).updatedAt
    })).toEqual({ status: 'read-only' })
    expect(client.updates).toEqual([])
  })

  it('verifies GitHub confirmed the requested state and labels', async () => {
    const client = new FixtureClient([issue(42)])
    client.updateIssue = async (_repository, number) => structuredClone(client.issues.get(number)!)
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir), coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })
    await service.refresh({ projectId: 'project-1', full: true })
    await expect(service.moveIssue({
      projectId: 'project-1', issueNumber: 42, toColumnId: 'doing',
      expectedUpdatedAt: issue(42).updatedAt
    })).rejects.toThrow('mutation-not-confirmed')
  })

  it('cancels before the write when the approval epoch changes in the queue', async () => {
    const client = new FixtureClient([issue(42)])
    let moving = false
    let moveReads = 0
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => {
        if (moving) moveReads += 1
        return context(client, { controlRevision: moving && moveReads >= 3 ? 2 : 1 })
      }
    })
    await service.refresh({ projectId: 'project-1', full: true })
    moving = true
    const result = await service.moveIssue({
      projectId: 'project-1', issueNumber: 42, toColumnId: 'doing',
      expectedUpdatedAt: issue(42).updatedAt
    })
    expect(result.status).toBe('configuration-changed')
    expect(client.updates).toEqual([])
  })

  it('creates only missing mapped labels with column colours', async () => {
    const client = new FixtureClient([])
    client.repositoryLabels = [{ id: 1, name: 'STATUS:TODO', color: 'ffffff', description: null }]
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator({ sleep: async () => undefined }),
      contextForProject: async () => context(client)
    })
    const result = await service.createMissingLabels({ projectId: 'project-1' })
    expect(result).toEqual({
      status: 'confirmed',
      created: ['status:doing', 'status:done'],
      remaining: []
    })
    expect(client.createdLabels).toEqual([
      { name: 'status:doing', color: 'ffd60a' },
      { name: 'status:done', color: '30d158' }
    ])
  })

  it('treats an exact concurrently created label as success and reports exact ownership', async () => {
    const client = new FixtureClient([])
    const original = client.createLabel.bind(client)
    let raced = false
    client.createLabel = async (repository, input) => {
      if (!raced) {
        raced = true
        client.repositoryLabels.push({ id: 500, name: input.name.toUpperCase(),
          color: input.color, description: null })
        throw Object.assign(new Error('already exists'), { status: 422 })
      }
      return original(repository, input)
    }
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator({ sleep: async () => undefined }),
      contextForProject: async () => context(client)
    })
    expect(await service.createMissingLabels({ projectId: 'project-1' })).toEqual({
      status: 'confirmed',
      created: ['status:doing', 'status:done'],
      remaining: []
    })
  })

  it('returns refresh-pending after one confirmed write when cache persistence fails', async () => {
    class FailingCache extends GitHubIssueCache {
      override async saveComplete(): Promise<void> { throw new Error('disk full') }
    }
    const shown = issue(42)
    const client = new FixtureClient([shown])
    const cache = new FailingCache(userDataDir)
    await GitHubIssueCache.prototype.saveComplete.call(cache, 'user-1', 'o/r', {
      issues: [shown], etags: {}, lastSuccessfulRefreshAt: 1, lastFullReconciliationAt: 1
    })
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })
    const result = await service.moveIssue({
      projectId: 'project-1', issueNumber: 42, toColumnId: 'doing',
      expectedUpdatedAt: shown.updatedAt
    })
    expect(result.status).toBe('refresh-pending')
    expect(client.updates).toHaveLength(1)
  })

  it('omits state from a move that does not change it, so GitHub keeps state_reason', async () => {
    // A closed-as-not_planned issue maps into the completion column, so a drag that lands it back
    // where it already is would PATCH state:'closed' again. GitHub rewrites state_reason to
    // 'completed' for that write, silently destroying the "wontfix" record nobody asked to change.
    const shelved = issue(5, {
      state: 'closed',
      stateReason: 'not_planned',
      labels: [{ id: 1, name: 'status:doing', color: 'ffd60a' }]
    })
    const client = new FixtureClient([shelved])
    const cache = new GitHubIssueCache(userDataDir)
    await cache.bind('local-1', 'project-1', 'o/r', 'user-1')
    await cache.saveComplete('user-1', 'o/r', {
      issues: [shelved], etags: {}, lastSuccessfulRefreshAt: 1, lastFullReconciliationAt: 1
    })
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })

    const result = await service.moveIssue({
      projectId: 'project-1', issueNumber: 5, toColumnId: 'done',
      expectedUpdatedAt: shelved.updatedAt
    })

    expect(result.status).toBe('confirmed')
    expect(client.updates).toHaveLength(1)
    expect(client.updates[0].input.state).toBeUndefined()
    expect(client.updates[0].input.labels).toEqual(['status:done'])
  })

  it('still sends state when the move really does change it', async () => {
    const open = issue(6, { labels: [{ id: 1, name: 'status:doing', color: 'ffd60a' }] })
    const client = new FixtureClient([open])
    const cache = new GitHubIssueCache(userDataDir)
    await cache.bind('local-1', 'project-1', 'o/r', 'user-1')
    await cache.saveComplete('user-1', 'o/r', {
      issues: [open], etags: {}, lastSuccessfulRefreshAt: 1, lastFullReconciliationAt: 1
    })
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })

    const result = await service.moveIssue({
      projectId: 'project-1', issueNumber: 6, toColumnId: 'done',
      expectedUpdatedAt: open.updatedAt
    })

    expect(result.status).toBe('confirmed')
    expect(client.updates[0].input.state).toBe('closed')
  })

  it('skips a repeat refresh inside the minimum interval', async () => {
    const client = new FixtureClient([issue(1)])
    let listed = 0
    client.listIssues = async () => {
      listed += 1
      return { items: [issue(1)] }
    }
    let clock = 1_000_000
    let resolutions = 0
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => {
        resolutions += 1
        return context(client)
      },
      now: () => clock
    })

    await service.refresh({ projectId: 'project-1' })
    expect(listed).toBe(1)
    expect(client.heartbeats).toHaveLength(1)
    const afterFirst = resolutions

    clock += 1_000
    await service.refresh({ projectId: 'project-1' })
    expect(client.heartbeats).toHaveLength(1)
    // The throttle must run BEFORE the credential resolution, or the expensive half still happens.
    expect(resolutions).toBe(afterFirst)

    clock += REFRESH_MIN_INTERVAL_MS
    await service.refresh({ projectId: 'project-1' })
    // Admitted again. Nothing changed upstream, so it stops at the (free) conditional heartbeat.
    expect(client.heartbeats).toHaveLength(2)
    expect(listed).toBe(1)
  })

  it('lets a full refresh through its own longer interval, not the incremental one', async () => {
    const client = new FixtureClient([issue(1)])
    const fullPages: Array<string | undefined> = []
    client.listIssues = async (_repository, options: ListIssueOptions) => {
      fullPages.push(options.since)
      return { items: [issue(1)] }
    }
    let clock = 1_000_000
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      now: () => clock
    })

    await service.refresh({ projectId: 'project-1', full: true })
    expect(fullPages).toHaveLength(1)

    clock += REFRESH_MIN_INTERVAL_MS
    await service.refresh({ projectId: 'project-1', full: true })
    expect(fullPages).toHaveLength(1)

    clock += FULL_REFRESH_MIN_INTERVAL_MS
    await service.refresh({ projectId: 'project-1', full: true })
    expect(fullPages).toHaveLength(2)
  })

  it('pages issues and pull requests as separate kinds, counting each on its own', async () => {
    const pull = issue(7, {
      pull: { draft: true, mergedAt: null },
      labels: [{ id: 1, name: 'status:doing', color: 'ffd60a' }]
    })
    const client = new FixtureClient([issue(1), pull])
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })
    await service.subscribe(1, { projectId: 'project-1' })

    // No kind means issues: the page a caller that predates pull requests still asks for.
    const issues = await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })
    expect(issues.items.map((item) => item.number)).toEqual([1])
    expect(issues.counts).toEqual({ ungrouped: 1 })

    const pulls = await service.query({
      projectId: 'project-1', columnId: 'doing', pageSize: 50, kind: 'pull'
    })
    expect(pulls.items.map((item) => item.number)).toEqual([7])
    expect(pulls.items[0].pull).toEqual({ draft: true, mergedAt: null })
    expect(pulls.counts).toEqual({ doing: 1 })
    // The board never writes a pull request, and the page says so rather than trusting callers.
    expect(pulls.readOnly).toBe(true)
  })

  it('reports the pull lane as partial when pull requests were evicted to fit', async () => {
    const client = new FixtureClient([])
    const cache = new GitHubIssueCache(userDataDir)
    await cache.bind('local-1', 'project-1', 'o/r', 'user-1')
    await cache.saveComplete('user-1', 'o/r', {
      issues: [issue(1), issue(2, { pull: { draft: false, mergedAt: null } })],
      etags: {},
      lastSuccessfulRefreshAt: 1,
      lastFullReconciliationAt: 1,
      pullsTruncated: true
    })
    const service = new GitHubIssueService({
      cache,
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })

    const pulls = await service.query({
      projectId: 'project-1', columnId: null, pageSize: 50, kind: 'pull'
    })
    const issues = await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })
    expect(pulls.partial).toBe(true)
    expect(issues.partial).toBe(false)
  })

  it('refuses to move a pull request, which shares the issue number space', async () => {
    const client = new FixtureClient([issue(5, { pull: { draft: false, mergedAt: null } })])
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir),
      coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client)
    })
    await service.subscribe(1, { projectId: 'project-1' })

    expect(await service.moveIssue({
      projectId: 'project-1',
      issueNumber: 5,
      toColumnId: 'done',
      expectedUpdatedAt: '2026-08-09T10:05Z'
    })).toEqual({ status: 'invalid-target' })
    expect(client.updates).toEqual([])
  })
})

describe('GitHubIssueService heartbeat', () => {
  function counting(client: FixtureClient) {
    const scans: ListIssueOptions[] = []
    const list = client.listIssues.bind(client)
    client.listIssues = async (repository, options) => {
      scans.push(structuredClone(options))
      return list(repository, options)
    }
    return scans
  }

  async function seeded(issues: GitHubIssue[], etags: Record<string, string>, over: {
    lastFullReconciliationAt?: number
  } = {}) {
    const cache = new GitHubIssueCache(userDataDir)
    await cache.bind('local-1', 'project-1', 'o/r', 'user-1')
    await cache.saveComplete('user-1', 'o/r', {
      issues, etags, lastSuccessfulRefreshAt: 5_000,
      lastFullReconciliationAt: over.lastFullReconciliationAt ?? 5_000
    })
    return cache
  }

  it('skips the whole scan when the heartbeat answers 304', async () => {
    const client = new FixtureClient([issue(1), issue(2)])
    const scans = counting(client)
    const cache = await seeded([issue(1), issue(2)], { heartbeat: client.currentHeartbeatEtag() })
    const deltas: number[][] = []
    const service = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      now: () => 10_000,
      onDelta: (_uiId, _projectId, numbers) => deltas.push(numbers)
    })

    // Opening the board refreshes in the background (a snapshot is cached, so it renders at once).
    await service.subscribe(1, { projectId: 'project-1' })
    await vi.waitFor(() => expect(client.heartbeats).toHaveLength(1))
    await vi.waitFor(() => expect(deltas).toHaveLength(1))

    expect(client.heartbeats).toEqual([client.currentHeartbeatEtag()])
    expect(scans).toEqual([])
    // Nothing changed on GitHub, but subscribers still re-read their pages (from the local cache,
    // at no GitHub cost) — as every refresh always made them do. What a page says is not only
    // issues: read only, the mapping approval and the completion column are derived by the host
    // at query time, and a board that is never prompted keeps showing the old answer.
    expect(deltas).toEqual([[]])
  })

  it('does not let a 304 freeze an incomplete repository: it keeps scanning', async () => {
    const client = new FixtureClient([issue(1)])
    const scans = counting(client)
    const cache = await seeded([issue(1)], { heartbeat: client.currentHeartbeatEtag() })
    await cache.saveIncompleteAttempt('user-1', 'o/r', { reason: 'issue-limit', observedAt: 5_000 })
    const service = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client), now: () => 10_000
    })

    await service.refresh({ projectId: 'project-1' })

    expect(scans).toHaveLength(1)
  })

  it('runs the incremental since scan when the heartbeat reports a change, and persists the new ETag', async () => {
    const client = new FixtureClient([issue(1)])
    const scans = counting(client)
    const cache = await seeded([issue(1)], { heartbeat: client.currentHeartbeatEtag() })
    client.issues.set(2, issue(2))
    const service = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client),
      now: () => 10_000
    })

    await service.refresh({ projectId: 'project-1' })

    expect(scans).toHaveLength(1)
    expect(scans[0].since).toBe(new Date(3_000).toISOString())
    expect((await cache.load('user-1', 'o/r')).lastComplete?.etags)
      .toEqual({ heartbeat: client.currentHeartbeatEtag() })
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).items
      .map((item) => item.number)).toEqual([2, 1])
  })

  it('reuses the persisted ETag after a restart instead of paying for a scan', async () => {
    const client = new FixtureClient([issue(1)])
    const cache = await seeded([], {})
    const first = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client), now: () => 10_000
    })
    await first.refresh({ projectId: 'project-1' })

    // A fresh service over the same on-disk cache is what an app restart looks like.
    const scans = counting(client)
    const restarted = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client), now: () => 20_000
    })
    await restarted.refresh({ projectId: 'project-1' })

    expect(client.heartbeats.at(-1)).toBe(client.currentHeartbeatEtag())
    expect(scans).toEqual([])
  })

  it('still scans on a full reconciliation even when the heartbeat answers 304', async () => {
    const client = new FixtureClient([issue(1)])
    const scans = counting(client)
    const cache = await seeded([issue(1), issue(9)], { heartbeat: client.currentHeartbeatEtag() })
    const service = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client), now: () => 10_000
    })

    // A deletion or a transfer out of the repository does not move the top item, so the daily
    // reconciliation is the only thing that can notice one — the heartbeat must never skip it.
    await service.refresh({ projectId: 'project-1', full: true })

    expect(scans).toHaveLength(1)
    expect(scans[0].since).toBeUndefined()
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).items
      .map((item) => item.number)).toEqual([1])
  })

  it('stores the validator read BEFORE the scan, so a change during the scan is seen next time', async () => {
    const client = new FixtureClient([issue(1)])
    const cache = await seeded([issue(1)], {})
    const list = client.listIssues.bind(client)
    client.listIssues = async (repository, options) => {
      const page = await list(repository, options)
      // An edit lands on GitHub after the scan read its page but before the snapshot is saved.
      client.issues.set(3, issue(3))
      return page
    }
    const service = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client), now: () => 10_000
    })

    await service.refresh({ projectId: 'project-1' })

    const stored = (await cache.load('user-1', 'o/r')).lastComplete?.etags.heartbeat
    expect(stored).toBe('W/"1@2026-08-09T10:00:01Z"')
    expect(stored).not.toBe(client.currentHeartbeatEtag())
  })
})

describe('GitHubIssueService rate budget', () => {
  const low = { resource: 'core', limit: 5_000, remaining: 12, resetAt: 9_000_000 }

  it('pauses the background poll below the budget floor, but a refresh the user asks for still runs', async () => {
    let clock = 1_000_000
    const client = new FixtureClient([issue(1)])
    const coordinator = new GitHubRequestCoordinator({ now: () => clock })
    const timers: Array<() => Promise<void>> = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir), coordinator,
      contextForProject: async () => context(client),
      now: () => clock,
      setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length }
    })
    await service.subscribe(1, { projectId: 'project-1' })
    expect(client.heartbeats).toHaveLength(1)

    coordinator.noteRateSample('user-1', low)
    await timers[0]()
    expect(client.heartbeats).toHaveLength(1)

    clock += REFRESH_MIN_INTERVAL_MS
    await service.refresh({ projectId: 'project-1' })
    expect(client.heartbeats).toHaveLength(2)
  })

  it('tells the board until when sync is held, instead of going quiet', async () => {
    const clock = 1_000_000
    const client = new FixtureClient([issue(1)])
    const coordinator = new GitHubRequestCoordinator({ now: () => clock })
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir), coordinator,
      contextForProject: async () => context(client), now: () => clock
    })
    await service.refresh({ projectId: 'project-1' })
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).throttle)
      .toBeUndefined()

    coordinator.noteRateSample('user-1', low)
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).throttle)
      .toEqual({ until: 9_000_000, kind: 'low-budget' })
  })

  it('prompts subscribers to re-read once when the poll pauses, not on every skipped minute', async () => {
    const clock = 1_000_000
    const client = new FixtureClient([issue(1)])
    const coordinator = new GitHubRequestCoordinator({ now: () => clock })
    const timers: Array<() => Promise<void>> = []
    const deltas: number[][] = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir), coordinator,
      contextForProject: async () => context(client), now: () => clock,
      setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length },
      onDelta: (_uiId, _projectId, numbers) => deltas.push(numbers)
    })
    await service.subscribe(1, { projectId: 'project-1' })
    const before = deltas.length
    coordinator.noteRateSample('user-1', low)

    await timers[0]()
    await timers[0]()

    expect(deltas.slice(before)).toEqual([[]])
  })

  it('prompts subscribers once when a poll is refused by a rate limit', async () => {
    const clock = 1_000_000
    const client = new FixtureClient([issue(1)])
    const coordinator = new GitHubRequestCoordinator({ now: () => clock })
    const timers: Array<() => Promise<void>> = []
    const deltas: number[][] = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir), coordinator,
      contextForProject: async () => context(client), now: () => clock,
      setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length },
      onDelta: (_uiId, _projectId, numbers) => deltas.push(numbers)
    })
    await service.subscribe(1, { projectId: 'project-1' })
    const before = deltas.length
    client.issuesHeartbeat = async () => {
      throw Object.assign(new Error('rate-limited'), { code: 'rate-limited', retryAt: 2_000_000 })
    }

    await timers[0]()
    await timers[0]()

    expect(deltas.slice(before)).toEqual([[]])
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).throttle)
      .toEqual({ until: 2_000_000, kind: 'rate-limited' })
  })
})

describe('GitHubIssueService close reason', () => {
  async function ready(issues: GitHubIssue[]) {
    const client = new FixtureClient(issues)
    const cache = new GitHubIssueCache(userDataDir)
    await cache.bind('local-1', 'project-1', 'o/r', 'user-1')
    await cache.saveComplete('user-1', 'o/r', {
      issues, etags: {}, lastSuccessfulRefreshAt: 1, lastFullReconciliationAt: 1
    })
    const service = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client), now: () => 10_000
    })
    return { client, service }
  }
  const todo = [{ id: 1, name: 'status:todo', color: '0a84ff' }]
  const done = [{ id: 3, name: 'status:done', color: '30d158' }]

  it('closes with the reason the user chose', async () => {
    const shown = issue(1, { labels: todo })
    const { client, service } = await ready([shown])
    const result = await service.moveIssue({
      projectId: 'project-1', issueNumber: 1, toColumnId: 'done',
      expectedUpdatedAt: shown.updatedAt, closeReason: 'not_planned'
    })
    expect(result.status).toBe('confirmed')
    expect(client.updates[0].input).toEqual({
      state: 'closed', stateReason: 'not_planned', labels: ['status:done']
    })
  })

  it('closes as completed when no reason was given, which is what GitHub does on its own', async () => {
    const shown = issue(1, { labels: todo })
    const { client, service } = await ready([shown])
    await service.moveIssue({
      projectId: 'project-1', issueNumber: 1, toColumnId: 'done', expectedUpdatedAt: shown.updatedAt
    })
    expect(client.updates[0].input.stateReason).toBe('completed')
  })

  it('reopens with state_reason reopened, whatever close reason the caller sent', async () => {
    const shown = issue(1, { state: 'closed', stateReason: 'not_planned', labels: done })
    const { client, service } = await ready([shown])
    await service.moveIssue({
      projectId: 'project-1', issueNumber: 1, toColumnId: 'todo',
      expectedUpdatedAt: shown.updatedAt, closeReason: 'not_planned'
    })
    expect(client.updates[0].input).toEqual({ state: 'open', stateReason: 'reopened', labels: ['status:todo'] })
  })

  it('sends no reason for a move that does not change the state', async () => {
    const shown = issue(1, { labels: todo })
    const { client, service } = await ready([shown])
    await service.moveIssue({
      projectId: 'project-1', issueNumber: 1, toColumnId: 'doing',
      expectedUpdatedAt: shown.updatedAt, closeReason: 'not_planned'
    })
    expect(client.updates[0].input).toEqual({ labels: ['status:doing'] })
  })

  it('refuses a reason it does not know without writing anything', async () => {
    const shown = issue(1, { labels: todo })
    const { client, service } = await ready([shown])
    const result = await service.moveIssue({
      projectId: 'project-1', issueNumber: 1, toColumnId: 'done',
      expectedUpdatedAt: shown.updatedAt, closeReason: 'wontfix' as never
    })
    expect(result.status).toBe('invalid-target')
    expect(client.updates).toEqual([])
  })

  it('does not report a close as confirmed when GitHub recorded a different reason', async () => {
    const shown = issue(1, { labels: todo })
    const { client, service } = await ready([shown])
    client.recordedReason = 'completed'
    await expect(service.moveIssue({
      projectId: 'project-1', issueNumber: 1, toColumnId: 'done',
      expectedUpdatedAt: shown.updatedAt, closeReason: 'not_planned'
    })).rejects.toThrow('mutation-not-confirmed')
  })
})

describe('GitHubIssueService mapping approval', () => {
  async function ready(mappingApproved: boolean) {
    const shown = issue(1, { labels: [{ id: 1, name: 'status:todo', color: '0a84ff' }] })
    const client = new FixtureClient([shown])
    const cache = new GitHubIssueCache(userDataDir)
    await cache.bind('local-1', 'project-1', 'o/r', 'user-1')
    await cache.saveComplete('user-1', 'o/r', {
      issues: [shown], etags: {}, lastSuccessfulRefreshAt: 1, lastFullReconciliationAt: 1
    })
    const service = new GitHubIssueService({
      cache, coordinator: new GitHubRequestCoordinator(),
      contextForProject: async () => context(client, { mappingApproved }), now: () => 10_000
    })
    return { client, service, shown }
  }

  it('writes nothing to GitHub under a column mapping this machine has not approved', async () => {
    const { client, service, shown } = await ready(false)
    expect(await service.moveIssue({
      projectId: 'project-1', issueNumber: 1, toColumnId: 'done', expectedUpdatedAt: shown.updatedAt
    })).toEqual({ status: 'read-only' })
    expect((await service.createMissingLabels({ projectId: 'project-1' })).status).toBe('read-only')
    expect(client.updates).toEqual([])
    expect(client.createdLabels).toEqual([])
  })

  it('still shows the issues, read only, and says the mapping is what needs approving', async () => {
    const { service } = await ready(false)
    const page = await service.query({ projectId: 'project-1', columnId: 'todo', pageSize: 50 })
    expect(page.items.map((item) => item.number)).toEqual([1])
    expect(page.readOnly).toBe(true)
    expect(page.mappingNotApproved).toBe(true)
  })

  it('writes as before once the mapping is approved', async () => {
    const { client, service, shown } = await ready(true)
    const page = await service.query({ projectId: 'project-1', columnId: 'todo', pageSize: 50 })
    expect(page.readOnly).toBe(false)
    expect(page.mappingNotApproved).toBeUndefined()
    await service.moveIssue({
      projectId: 'project-1', issueNumber: 1, toColumnId: 'doing', expectedUpdatedAt: shown.updatedAt
    })
    expect(client.updates).toHaveLength(1)
  })
})

describe('GitHubIssueService throttle lift', () => {
  it('prompts subscribers again when the hold lifts, so the board stops saying it is paused', async () => {
    let clock = 1_000_000
    const client = new FixtureClient([issue(1)])
    const coordinator = new GitHubRequestCoordinator({ now: () => clock })
    const timers: Array<() => Promise<void>> = []
    const deltas: number[][] = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir), coordinator,
      contextForProject: async () => context(client), now: () => clock,
      setInterval: (fn) => { timers.push(fn as () => Promise<void>); return timers.length },
      onDelta: (_uiId, _projectId, numbers) => deltas.push(numbers)
    })
    await service.subscribe(1, { projectId: 'project-1' })
    coordinator.noteRateSample('user-1', { resource: 'core', limit: 5_000, remaining: 12, resetAt: 2_000_000 })
    await timers[0]()
    const held = deltas.length

    // The window resets. Nothing changed upstream, so the heartbeat answers 304 and the scan is
    // skipped — the only thing that changed is that sync is no longer held.
    clock = 2_000_000
    await timers[0]()

    expect(deltas.slice(held)).toEqual([[]])
    expect((await service.query({ projectId: 'project-1', columnId: null, pageSize: 50 })).throttle)
      .toBeUndefined()
    // And a hold that comes back later is announced again rather than taken for the old one.
    coordinator.noteRateSample('user-1', { resource: 'core', limit: 5_000, remaining: 12, resetAt: 2_000_000 + 3_600_000 })
    await timers[0]()
    expect(deltas.slice(held)).toEqual([[], []])
  })
})

describe('GitHubIssueService notifyProject', () => {
  it('prompts only that project\'s subscribers to re-read', async () => {
    const client = new FixtureClient([issue(1)])
    const deltas: Array<[number, string, number[]]> = []
    const service = new GitHubIssueService({
      cache: new GitHubIssueCache(userDataDir), coordinator: new GitHubRequestCoordinator(),
      contextForProject: async (projectId) => context(client, { projectId }), now: () => 10_000,
      onDelta: (uiId, projectId, numbers) => deltas.push([uiId, projectId, numbers])
    })
    await service.subscribe(7, { projectId: 'project-1' })
    await service.subscribe(8, { projectId: 'project-2' })
    deltas.length = 0

    service.notifyProject('project-1')

    expect(deltas).toEqual([[7, 'project-1', []]])
  })
})