@defrex/autobuild 0.8.0

package/packages/core/src/ports/forge/github-pr-attachments.ts

@@ -0,0 +1,351 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import {
+  hostedPrAttachmentAssetSchema,
+  prAttachmentSchema,
+  prImageHostSchema,
+  type HostedPrAttachmentAsset,
+} from '../../ontology'
+import type {
+  PrAttachmentHosting,
+  PrAttachmentReclaimRequest,
+  PrAttachmentUploadRequest,
+} from '../types'
+import { GitHubApiError, type GitHubRequest } from './github-transport'
+
+const repositoryJson = z
+  .object({
+    private: z.boolean().optional(),
+    visibility: z.enum(['public', 'private', 'internal']).optional(),
+  })
+  .refine(
+    (repository) => repository.private !== undefined || repository.visibility !== undefined,
+    'GitHub repository response must expose private or visibility',
+  )
+
+const releaseJson = z.object({
+  id: z.number().int().positive(),
+  draft: z.boolean(),
+  published_at: z.string().min(1).nullable(),
+  upload_url: z.string().url(),
+  immutable: z.boolean(),
+})
+
+const releaseAssetJson = z.object({
+  id: z.number().int().positive(),
+  name: z.string().min(1),
+  state: z.string().min(1),
+  content_type: z.string().min(1),
+  size: z.number().int().nonnegative(),
+  digest: z.string().nullable().optional(),
+  browser_download_url: z.string().url(),
+})
+type ReleaseAsset = z.infer<typeof releaseAssetJson>
+
+const SHA256 = /^[0-9a-f]{64}$/
+/** Bounded page walk for the release-asset listing. */
+const ASSET_PAGE_SIZE = 100
+const MAX_ASSET_PAGES = 20
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function repositoryParts(repository: string): [string, string] {
+  prImageHostSchema.shape.repository.parse(repository)
+  return repository.split('/') as [string, string]
+}
+
+function repositoryEndpoint(repository: string): string {
+  const [owner, name] = repositoryParts(repository)
+  return `repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`
+}
+
+/** Hash all identity inputs with explicit separators. Only a short,
+ * validated extension survives from the user-controlled filename. */
+export function githubPrAttachmentAssetName(
+  request: Pick<PrAttachmentUploadRequest, 'prUrl' | 'attachment' | 'sha256'>,
+): string {
+  const { artifact, filename, mediaType } = request.attachment
+  const extension = filename.match(/\.([A-Za-z0-9]{1,10})$/)?.[1]?.toLowerCase()
+  const digest = createHash('sha256')
+    .update(request.prUrl)
+    .update('\0')
+    .update(artifact.kind)
+    .update('\0')
+    .update(String(artifact.rev))
+    .update('\0')
+    .update(filename)
+    .update('\0')
+    .update(mediaType)
+    .update('\0')
+    .update(request.sha256)
+    .digest('hex')
+  return `autobuild-attachment-${digest}${extension === undefined ? '' : `.${extension}`}`
+}
+
+function uploadEndpoint(uploadUrl: string, name: string): string {
+  const base = uploadUrl.replace(/\{[^}]*\}$/, '')
+  return `${base}${base.includes('?') ? '&' : '?'}name=${encodeURIComponent(name)}`
+}
+
+export class GitHubPrAttachmentHosting implements PrAttachmentHosting {
+  private readonly transport: GitHubRequest
+  private readonly requestTimeoutMs: number
+  /** One GitHubForge instance serves one plumbing operation in production;
+   * share the target probe across that operation's attachment uploads. */
+  private readonly targetValidations = new Map<string, Promise<z.infer<typeof releaseJson>>>()
+
+  constructor(opts: { transport: GitHubRequest; requestTimeoutMs?: number }) {
+    this.transport = opts.transport
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+  }
+
+  /** One bounded transport call with the class's request timeout applied. */
+  private call(
+    method: string,
+    path: string,
+    opts?: { headers?: Record<string, string>; raw?: Uint8Array },
+  ): Promise<{
+    status: number
+    headers: Record<string, string>
+    json?: unknown
+    bytes?: Uint8Array
+  }> {
+    const signal = AbortSignal.timeout(this.requestTimeoutMs)
+    return this.transport(method, path, {
+      ...(opts?.headers !== undefined ? { headers: opts.headers } : {}),
+      ...(opts?.raw !== undefined ? { raw: opts.raw } : {}),
+      signal,
+    })
+  }
+
+  private parseJson<S extends z.ZodType>(
+    schema: S,
+    response: { json?: unknown },
+    what: string,
+  ): z.infer<S> {
+    const parsed = schema.safeParse(response.json)
+    if (!parsed.success) {
+      throw new Error(`unexpected GitHub response for ${what}: ${parsed.error.message}`)
+    }
+    return parsed.data
+  }
+
+  private async validateTarget(
+    request: PrAttachmentUploadRequest,
+  ): Promise<z.infer<typeof releaseJson>> {
+    const target = prImageHostSchema.parse(request.target)
+    const root = repositoryEndpoint(target.repository)
+    const repository = this.parseJson(
+      repositoryJson,
+      await this.call('GET', root),
+      `repository read of ${target.repository}`,
+    )
+    if (
+      repository.private === true ||
+      (repository.visibility !== undefined && repository.visibility !== 'public')
+    ) {
+      throw new Error(
+        `PR attachment host ${target.repository} is private; GitHub cannot render authenticated release assets inline`,
+      )
+    }
+
+    const release = this.parseJson(
+      releaseJson,
+      await this.call('GET', `${root}/releases/${target.releaseId}`),
+      `release read of ${target.repository}#${target.releaseId}`,
+    )
+    if (release.id !== target.releaseId) {
+      throw new Error(
+        `PR attachment host returned release ${release.id}, expected ${target.releaseId}`,
+      )
+    }
+    if (release.draft || release.published_at === null) {
+      throw new Error(
+        `PR attachment host release ${target.repository}#${target.releaseId} is not published`,
+      )
+    }
+    if (release.immutable === true) {
+      throw new Error(
+        `PR attachment host release ${target.repository}#${target.releaseId} is immutable`,
+      )
+    }
+    return release
+  }
+
+  private validatedTarget(
+    request: PrAttachmentUploadRequest,
+  ): Promise<z.infer<typeof releaseJson>> {
+    const key = `${request.target.repository}\0${request.target.releaseId}`
+    const existing = this.targetValidations.get(key)
+    if (existing !== undefined) return existing
+    const pending = this.validateTarget(request).catch((error) => {
+      this.targetValidations.delete(key)
+      throw error
+    })
+    this.targetValidations.set(key, pending)
+    return pending
+  }
+
+  private async listAssets(request: PrAttachmentUploadRequest): Promise<ReleaseAsset[]> {
+    const root = repositoryEndpoint(request.target.repository)
+    const assets: ReleaseAsset[] = []
+    for (let page = 1; page <= MAX_ASSET_PAGES; page += 1) {
+      const response = await this.call(
+        'GET',
+        `${root}/releases/${request.target.releaseId}/assets?per_page=${ASSET_PAGE_SIZE}&page=${page}`,
+      )
+      const batch = this.parseJson(
+        z.array(releaseAssetJson),
+        response,
+        `asset listing of ${request.target.repository}#${request.target.releaseId}`,
+      )
+      assets.push(...batch)
+      if (batch.length < ASSET_PAGE_SIZE) return assets
+    }
+    throw new Error(
+      `asset listing of ${request.target.repository}#${request.target.releaseId} exceeded ${MAX_ASSET_PAGES} pages`,
+    )
+  }
+
+  private assertCompatibleAsset(
+    asset: ReleaseAsset,
+    expected: { name: string; mediaType: string; size: number; digest: string },
+    target: PrAttachmentUploadRequest['target'],
+  ): HostedPrAttachmentAsset {
+    if (asset.name !== expected.name) {
+      throw new Error(
+        `PR attachment asset has name ${JSON.stringify(asset.name)}, expected ${JSON.stringify(expected.name)}`,
+      )
+    }
+    if (asset.state !== 'uploaded') {
+      throw new Error(
+        `PR attachment asset ${asset.name} has state ${JSON.stringify(asset.state)}, expected "uploaded"`,
+      )
+    }
+    if (asset.content_type !== expected.mediaType) {
+      throw new Error(
+        `PR attachment asset ${asset.name} has content type ${JSON.stringify(asset.content_type)}, expected ${JSON.stringify(expected.mediaType)}`,
+      )
+    }
+    if (asset.size !== expected.size) {
+      throw new Error(
+        `PR attachment asset ${asset.name} has size ${asset.size}, expected ${expected.size}`,
+      )
+    }
+    if (asset.digest != null && asset.digest !== expected.digest) {
+      throw new Error(
+        `PR attachment asset ${asset.name} has digest ${JSON.stringify(asset.digest)}, expected ${JSON.stringify(expected.digest)}`,
+      )
+    }
+    return hostedPrAttachmentAssetSchema.parse({
+      provider: 'github-release',
+      repository: target.repository,
+      releaseId: target.releaseId,
+      assetId: asset.id,
+      url: asset.browser_download_url,
+    })
+  }
+
+  async upload(request: PrAttachmentUploadRequest): Promise<HostedPrAttachmentAsset> {
+    const target = prImageHostSchema.parse(request.target)
+    if (!SHA256.test(request.sha256)) {
+      throw new Error('PR attachment upload requires a full lowercase SHA-256 blob ref')
+    }
+    const actual = createHash('sha256').update(request.content).digest('hex')
+    if (actual !== request.sha256) {
+      throw new Error(`PR attachment bytes hash to ${actual}, not expected blob ${request.sha256}`)
+    }
+    const attachment = prAttachmentSchema.parse(request.attachment)
+    if (!attachment.mediaType.startsWith('image/')) {
+      throw new Error(
+        `PR attachment image host accepts only image/* media, got ${JSON.stringify(attachment.mediaType)}`,
+      )
+    }
+    if (request.prUrl.trim() === '') {
+      throw new Error('PR attachment upload PR URL must be non-blank')
+    }
+
+    const normalized = { ...request, target, attachment }
+    const release = await this.validatedTarget(normalized)
+    const filename = githubPrAttachmentAssetName(normalized)
+    const expected = {
+      name: filename,
+      mediaType: normalized.attachment.mediaType,
+      size: normalized.content.byteLength,
+      digest: `sha256:${normalized.sha256}`,
+    }
+    const existing = (await this.listAssets(normalized)).find((asset) => asset.name === filename)
+
+    if (existing !== undefined) {
+      // GitHub may leave an incomplete starter/open row when an upload dies.
+      // It is safe to remove because its deterministic name belongs to this
+      // exact PR/attachment/blob identity; an uploaded mismatch is never clobbered.
+      if (existing.state === 'starter' || existing.state === 'open') {
+        await this.deleteAsset(target.repository, existing.id)
+      } else {
+        return this.assertCompatibleAsset(existing, expected, target)
+      }
+    }
+
+    try {
+      const uploaded = this.parseJson(
+        releaseAssetJson,
+        await this.call('POST', uploadEndpoint(release.upload_url, filename), {
+          headers: { 'Content-Type': normalized.attachment.mediaType },
+          raw: normalized.content,
+        }),
+        'PR attachment upload',
+      )
+      if (uploaded.name !== filename) {
+        throw new Error(
+          `PR attachment upload returned name ${JSON.stringify(uploaded.name)}, expected ${JSON.stringify(filename)}`,
+        )
+      }
+      return this.assertCompatibleAsset(uploaded, expected, target)
+    } catch (uploadError) {
+      // A lost response may still have committed the external write.
+      // Reconcile once before degrading finalize: adopt a compatible upload,
+      // or remove the incomplete starter/open remnant so failed attempts
+      // cannot accumulate untracked release storage.
+      let candidate: ReleaseAsset | undefined
+      try {
+        candidate = (await this.listAssets(normalized)).find((asset) => asset.name === filename)
+      } catch {
+        throw uploadError
+      }
+      if (candidate === undefined) throw uploadError
+      if (candidate.state === 'starter' || candidate.state === 'open') {
+        try {
+          await this.deleteAsset(target.repository, candidate.id)
+        } catch {
+          // Preserve the primary upload error; its deterministic name keeps
+          // the remnant identifiable to a later explicit retry or cleanup.
+        }
+        throw uploadError
+      }
+      return this.assertCompatibleAsset(candidate, expected, target)
+    }
+  }
+
+  private async deleteAsset(repository: string, assetId: number): Promise<void> {
+    try {
+      await this.call('DELETE', `${repositoryEndpoint(repository)}/releases/assets/${assetId}`)
+    } catch (error) {
+      // Absent (already deleted) is the reclaim goal met; anything else is a
+      // real failure.
+      if (error instanceof GitHubApiError && error.status === 404) return
+      throw new Error(
+        `PR attachment asset delete failed for ${repository}#${assetId}: ${errorMessage(error)}`,
+        { cause: error },
+      )
+    }
+  }
+
+  async reclaim(request: PrAttachmentReclaimRequest): Promise<void> {
+    const asset = hostedPrAttachmentAssetSchema.parse(request.asset)
+    await this.deleteAsset(asset.repository, asset.assetId)
+  }
+}

package/packages/core/src/ports/forge/github-transport.ts

@@ -0,0 +1,352 @@
+/**
+ * GitHub REST transport seam, shared by the forge adapter and its PR
+ * attachment hosting, plus the credential resolution every GitHub caller
+ * shares. Imports nothing from the forge module so both can import it
+ * without a cycle (the workspace module's `spawnExec` is the only production
+ * dependency), and tests inject a fake transport or exec seam instead of
+ * shelling `gh`.
+ */
+import { z } from 'zod'
+import { spawnExec } from '../workspace/git-worktree'
+
+export interface GitHubRequestOpts {
+  query?: Record<string, string>
+  /** JSON-serializable request body. Ignored when `raw` is set. */
+  body?: unknown
+  /** Extra headers (e.g. `Accept: application/vnd.github.raw`). */
+  headers?: Record<string, string>
+  /** Raw request bytes (release-asset upload); sets the body verbatim. */
+  raw?: Uint8Array
+  signal?: AbortSignal
+}
+
+export interface GitHubResponse {
+  status: number
+  /** Lowercased response headers of interest. */
+  headers: Record<string, string>
+  /** Parsed JSON body when the response declared one. */
+  json?: unknown
+  /** Raw response bytes when the body was not JSON. */
+  bytes?: Uint8Array
+}
+
+/**
+ * One authenticated GitHub REST call. `path` is API-relative
+ * (`repos/{owner}/{repo}/pulls/42`) or an absolute URL (release-asset
+ * `upload_url`). Non-2xx responses throw {@link GitHubApiError} — except
+ * `304 Not Modified`, which is returned (never thrown) because it is a
+ * documented *success* for a conditional request: callers that send
+ * revalidation headers such as `If-None-Match` read the 304 as "the cached
+ * representation is still current". A 304 carries no body, so the response
+ * has no `json` and no `bytes`.
+ */
+export type GitHubRequest = (
+  method: string,
+  path: string,
+  opts?: GitHubRequestOpts,
+) => Promise<GitHubResponse>
+
+/** Typed non-2xx response. `body` carries the parsed JSON (when any) so
+ * fail-closed callers can classify documented error shapes. */
+export class GitHubApiError extends Error {
+  readonly status: number
+  readonly body?: unknown
+
+  constructor(status: number, message: string, body?: unknown) {
+    super(message)
+    this.name = 'GitHubApiError'
+    this.status = status
+    this.body = body
+  }
+}
+
+const GITHUB_API_BASE = 'https://api.github.com'
+const GITHUB_API_VERSION = '2022-11-28'
+
+function githubErrorMessage(status: number, body: unknown, text: string): string {
+  if (body !== null && typeof body === 'object' && 'message' in body) {
+    const message = (body as { message?: unknown }).message
+    if (typeof message === 'string' && message !== '') return message
+  }
+  return text.trim() !== '' ? text.trim() : `GitHub API responded ${status}`
+}
+
+/** The documented plan-limitation error shape for the rulesets endpoint.
+ * Shared by the forge's fail-closed gate probe and its tests. */
+export const restPlanLimitation = z
+  .object({
+    message: z.literal(
+      'Upgrade to GitHub Pro or make this repository public to enable this feature.',
+    ),
+    documentation_url: z.literal('https://docs.github.com/rest/repos/rules#get-rules-for-a-branch'),
+  })
+  .passthrough()
+
+/** Where a transport's bearer token comes from: a literal, nothing (anonymous
+ * requests), or a resolver the transport invokes lazily — a bare token or a
+ * {@link GitHubCredential}, whose miss reason the transport then attaches to
+ * the error of any request that had to go out anonymously. The transport asks
+ * a resolver again at most once per {@link CREDENTIAL_MISS_TTL_MS}: after a
+ * miss (a momentarily locked keyring is neither frozen into anonymous access
+ * for the process lifetime nor re-probed on every request), and after a
+ * request answers `401 Unauthorized` (a rotated or revoked `gh auth login` is
+ * picked up without a restart, while a revoked-but-still-stored login cannot
+ * drive a gh spawn per request). */
+export type GitHubTokenSource =
+  | string
+  | undefined
+  | (() => Promise<string | undefined | GitHubCredential>)
+
+/** Minimum interval between two invocations of a token resolver. */
+export const CREDENTIAL_MISS_TTL_MS = 60_000
+
+/** Production transport: token-authenticated fetch against api.github.com.
+ * Callers pass a literal token or a resolver such as
+ * {@link githubTokenSource}; no `Authorization` header is sent when neither
+ * yields one. */
+export function createGitHubFetchTransport(opts: {
+  token?: GitHubTokenSource
+  apiBase?: string
+  now?: () => number
+}): GitHubRequest {
+  const source = opts.token
+  const now = opts.now ?? Date.now
+  let resolved: Promise<GitHubCredential> | undefined
+  /** When the current answer arrived; `undefined` while one is in flight. */
+  let resolvedAt: number | undefined
+  let missed = false
+  const stale = (): boolean =>
+    resolvedAt !== undefined && now() - resolvedAt >= CREDENTIAL_MISS_TTL_MS
+  const normalize = (answer: string | undefined | GitHubCredential): GitHubCredential => {
+    if (typeof answer === 'object') return answer
+    return answer === undefined || answer === ''
+      ? { token: undefined, reason: 'no GitHub credential was available' }
+      : { token: answer }
+  }
+  const resolveToken = (): Promise<GitHubCredential> => {
+    if (missed && stale()) resolved = undefined
+    if (resolved === undefined) {
+      resolvedAt = undefined
+      missed = false
+      const attempt = (typeof source === 'function' ? source() : Promise.resolve(source)).then(
+        normalize,
+      )
+      resolved = attempt
+      attempt.then(
+        (credential) => {
+          if (resolved !== attempt) return
+          resolvedAt = now()
+          missed = credential.token === undefined
+        },
+        () => {
+          // A rejected probe is not an answer at all — ask again next time.
+          if (resolved === attempt) resolved = undefined
+        },
+      )
+    }
+    return resolved
+  }
+  /** 401: the memoized token is no longer accepted. Drop it once the interval
+   * has passed so the next request resolves again; inside the interval the
+   * stale token keeps failing without spawning anything. */
+  const forgetToken = (): void => {
+    if (typeof source === 'function' && stale()) resolved = undefined
+  }
+  const base = opts.apiBase ?? GITHUB_API_BASE
+  return async (method, path, request = {}) => {
+    const credential = await resolveToken()
+    const token = credential.token
+    let url = /^https:\/\//i.test(path) ? path : `${base}/${path.replace(/^\/+/, '')}`
+    if (request.query !== undefined) {
+      const params = new URLSearchParams(request.query)
+      url += (url.includes('?') ? '&' : '?') + params.toString()
+    }
+    const headers: Record<string, string> = {
+      'X-GitHub-Api-Version': GITHUB_API_VERSION,
+      Accept: 'application/vnd.github+json',
+      ...request.headers,
+    }
+    if (token !== undefined && token !== '') headers.Authorization = `Bearer ${token}`
+    let body: BodyInit | undefined
+    if (request.raw !== undefined) body = request.raw as unknown as BodyInit
+    else if (request.body !== undefined) {
+      headers['Content-Type'] = 'application/json'
+      body = JSON.stringify(request.body)
+    }
+    const response = await fetch(url, {
+      method,
+      headers,
+      ...(body !== undefined ? { body } : {}),
+      ...(request.signal !== undefined ? { signal: request.signal } : {}),
+    })
+    const headerMap: Record<string, string> = {}
+    response.headers.forEach((value, key) => {
+      headerMap[key.toLowerCase()] = value
+    })
+    // A 304 Not Modified answers a conditional request (If-None-Match) and
+    // always carries an empty body — return it before the non-2xx throw so
+    // callers can treat revalidation success as success, not an error.
+    if (response.status === 304) {
+      return { status: 304, headers: headerMap }
+    }
+    const contentType = headerMap['content-type'] ?? ''
+    let text = ''
+    let json: unknown
+    let bytes: Uint8Array | undefined
+    if (contentType.includes('application/json')) {
+      text = await response.text()
+      try {
+        json = JSON.parse(text)
+      } catch {
+        // A non-JSON body behind a JSON content type is ordinary garbage.
+      }
+    } else {
+      // Binary bodies (release assets, raw file contents) are read as bytes —
+      // never round-tripped through text, which would corrupt arbitrary data.
+      const buffer = await response.arrayBuffer()
+      if (buffer.byteLength > 0) bytes = new Uint8Array(buffer)
+    }
+    if (!response.ok) {
+      if (response.status === 401) forgetToken()
+      if (bytes !== undefined) text = new TextDecoder().decode(bytes)
+      // An anonymous request that failed names why it was anonymous: a 404 on
+      // a private repository is otherwise indistinguishable from a bad path,
+      // and the operator's fix (export a token, or `gh auth login`) is the
+      // point of the message.
+      const anonymous =
+        credential.token === undefined ? ` (request was unauthenticated: ${credential.reason})` : ''
+      throw new GitHubApiError(
+        response.status,
+        `${githubErrorMessage(response.status, json, text)}${anonymous}`,
+        json,
+      )
+    }
+    return {
+      status: response.status,
+      headers: headerMap,
+      ...(json !== undefined ? { json } : {}),
+      ...(bytes !== undefined ? { bytes } : {}),
+    }
+  }
+}
+
+export function githubTokenFromEnv(
+  env: Readonly<Record<string, string | undefined>>,
+): string | undefined {
+  // `||`, not `??`: an exported-but-empty GITHUB_TOKEN (a templated .env or
+  // unit file) must not mask a valid GH_TOKEN.
+  const token = env.GITHUB_TOKEN || env.GH_TOKEN
+  return token !== undefined && token !== '' ? token : undefined
+}
+
+/** Subprocess seam for the gh CLI credential probe: argv and an abort signal
+ * in; exit code, stdout, and stderr out. The workspace module's `spawnExec`
+ * satisfies it and is the default; callers that own a richer exec seam adapt
+ * it so tests never reach a real `gh`. The signal is the probe's deadline. */
+export type GitHubCliExec = (
+  cmd: string[],
+  opts: { signal: AbortSignal },
+) => Promise<{ exitCode: number; stdout: string; stderr: string }>
+
+/** How long the gh probe may take before it is treated as "no credential".
+ * `gh auth token` never prompts, so anything this slow is a wedged keyring. */
+export const GH_CLI_TOKEN_TIMEOUT_MS = 10_000
+
+/** The argv of the gh CLI credential probe. Exported so exec seams in tests
+ * can recognize it. `--hostname` pins github.com even when the operator's
+ * default gh host is an enterprise instance, because the transport only ever
+ * speaks to api.github.com. */
+export const GH_CLI_TOKEN_COMMAND: readonly string[] = [
+  'gh',
+  'auth',
+  'token',
+  '--hostname',
+  'github.com',
+]
+
+/** Outcome of one credential lookup. A miss carries the reason so a
+ * fail-fast caller can say *why* (gh not installed, not logged in to
+ * github.com, timed out) instead of a generic "no token". */
+export type GitHubCredential = { token: string } | { token: undefined; reason: string }
+
+/** The credential the operator stored with `gh auth login`, read through
+ * `gh auth token`. Never throws: gh missing, unauthenticated, silent, or
+ * slower than the deadline all resolve to a miss with its reason. The
+ * deadline is enforced here — not in the spawner — so it holds for every
+ * injected exec seam: the probe is aborted through the signal and its result
+ * abandoned, so a wrapper script that forked the real gh and left the pipes
+ * open cannot hold the caller. The probe inherits this process's environment
+ * (gh reads its own keyring) and needs no working directory. */
+export async function githubTokenFromGhCli(
+  exec: GitHubCliExec = spawnExec,
+  timeoutMs: number = GH_CLI_TOKEN_TIMEOUT_MS,
+): Promise<GitHubCredential> {
+  const command = GH_CLI_TOKEN_COMMAND.join(' ')
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  const deadline = new Promise<GitHubCredential>((resolve) => {
+    controller.signal.addEventListener(
+      'abort',
+      () =>
+        resolve({
+          token: undefined,
+          reason: `\`${command}\` did not answer within ${timeoutMs} ms`,
+        }),
+      { once: true },
+    )
+  })
+  const probe = (async (): Promise<GitHubCredential> => {
+    try {
+      const result = await exec([...GH_CLI_TOKEN_COMMAND], { signal: controller.signal })
+      if (result.exitCode !== 0) {
+        const detail = result.stderr.trim() || result.stdout.trim()
+        return {
+          token: undefined,
+          reason: `\`${command}\` exited ${result.exitCode}${detail === '' ? '' : `: ${detail}`}`,
+        }
+      }
+      const token = result.stdout.trim()
+      if (token === '') return { token: undefined, reason: `\`${command}\` printed no token` }
+      return { token }
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error)
+      return { token: undefined, reason: `\`${command}\` could not run: ${detail}` }
+    }
+  })()
+  try {
+    return await Promise.race([probe, deadline])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** GitHub credential resolution for kernel-side forge access: `GITHUB_TOKEN`,
+ * then `GH_TOKEN` ({@link githubTokenFromEnv}), then the gh CLI's stored
+ * login. The environment variables serve hosted and sandboxed dispatchers,
+ * which have no gh and no keyring; the gh fallback keeps a local
+ * checkout-mode dispatcher working with nothing more than `gh auth login`, as
+ * it did before the adapter moved off gh subprocesses. A miss names what was
+ * tried. */
+export async function resolveGitHubToken(
+  env: Readonly<Record<string, string | undefined>>,
+  exec?: GitHubCliExec,
+): Promise<GitHubCredential> {
+  const fromEnv = githubTokenFromEnv(env)
+  if (fromEnv !== undefined) return { token: fromEnv }
+  const probe = await githubTokenFromGhCli(exec)
+  if (probe.token !== undefined) return probe
+  return {
+    token: undefined,
+    reason: `GITHUB_TOKEN and GH_TOKEN are unset and ${probe.reason}`,
+  }
+}
+
+/** A transport token source over {@link resolveGitHubToken}: the builtin
+ * forge's default. Resolves whenever the transport asks (first request, then
+ * after a miss interval or a 401). */
+export function githubTokenSource(
+  env: Readonly<Record<string, string | undefined>>,
+  exec?: GitHubCliExec,
+): () => Promise<GitHubCredential> {
+  return () => resolveGitHubToken(env, exec)
+}