@moondeck/station 0.0.1 → 1.0.0

package/lib/github-tokens.ts

@@ -0,0 +1,2439 @@
+/**
+ * Host-side GitHub token manager (ADR-027).
+ *
+ * Owns the encrypted refresh token (`host_github_tokens`), the per-task access
+ * token mint + container injection, and the refresh schedule. Access tokens are
+ * never stored — they go straight into the container's gh config. The refresh
+ * exchange is a host→cloud HTTP POST to /api/github/oauth/exchange.
+ */
+
+import { and, eq } from "drizzle-orm";
+
+import { configuredCredentialStore, queueStoreWrite, userParameterName } from "./credential-store";
+import { getDb, schema } from "./db";
+import { githubApiOrigin } from "./github-origin";
+import { sealAesGcm, openAesGcm } from "./secrets";
+import { dockerCli } from "./docker-exec";
+import {
+  removeTaskAppContainer,
+  taskAppContainerName,
+  taskAppContainerState,
+  taskContainerCli,
+} from "./task-container-cli";
+import {
+  RUNTIME_AUTHORITY_ENV,
+  runtimeAuthorityDockerExecArgs,
+} from "./runtime-authority";
+import {
+  backgroundContainerWorkAllowed,
+  ContainerRuntimeUnavailableError,
+  requireContainerRuntimeOperational,
+} from "./runtime-guard";
+import {
+  configureTaskSshTransport,
+  ensureTaskSshIdentity,
+} from "./git-identity";
+import type { TaskEnvironmentHandle } from "./task-environment/types";
+import { onOwnCredentials, whileOnOwnCredentials } from "./cloud-credential-host";
+import { sidecarMode } from "./sidecar";
+import { signInBoxMode } from "./signin-box";
+import {
+  MAX_GITHUB_INSTALLATIONS,
+  MAX_GITHUB_REPOSITORIES_PER_INSTALLATION,
+  type CloudToHost,
+  type GitHubRepositoryAccessErrorCode,
+} from "../src/protocol";
+
+const REFRESH_LEAD_MS = 5 * 60 * 1000; // refresh 5 min before expiry
+const EXEC_TIMEOUT_MS = 10_000;
+// Cap the cloud token-exchange round-trip. Generous on purpose: aborting an
+// exchange that GitHub already completed burns the single-use refresh token
+// (we never see the rotated replacement), so a slow success beats a fast
+// ambiguous abort.
+const EXCHANGE_TIMEOUT_MS = 30_000;
+const MANAGED_GH_CONFIG_DIR = "/home/node/.config/gh";
+const SAFE_CONTAINER_PATH = "/usr/bin:/bin";
+
+// `docker exec` inherits the task container's project environment. Override
+// loader/config variables before the first executable starts, then use env -i
+// so arbitrary GIT_CONFIG_KEY_* and similar project keys cannot influence the
+// managed gh/git mutation. Commands themselves use absolute paths.
+const SANITIZED_DOCKER_EXEC_ENV = [
+  "-e",
+  "HOME=/home/node",
+  "-e",
+  `GH_CONFIG_DIR=${MANAGED_GH_CONFIG_DIR}`,
+  "-e",
+  `PATH=${SAFE_CONTAINER_PATH}`,
+  "-e",
+  "XDG_CONFIG_HOME=",
+  "-e",
+  "LD_PRELOAD=",
+  "-e",
+  "LD_LIBRARY_PATH=",
+  "-e",
+  "DYLD_INSERT_LIBRARIES=",
+  "-e",
+  "DYLD_LIBRARY_PATH=",
+  "-e",
+  "GIT_CONFIG=",
+  "-e",
+  "GIT_CONFIG_GLOBAL=",
+  "-e",
+  "GIT_CONFIG_SYSTEM=",
+  "-e",
+  "GIT_CONFIG_NOSYSTEM=",
+  "-e",
+  "GIT_CONFIG_COUNT=0",
+  "-e",
+  "GIT_EXEC_PATH=",
+  "-e",
+  "GIT_SSH=",
+  "-e",
+  "GIT_SSH_COMMAND=",
+  "-e",
+  "GIT_ASKPASS=",
+  "-e",
+  "SSH_ASKPASS=",
+] as const;
+
+export const CLEAN_CONTAINER_ENV = [
+  "/usr/bin/env",
+  "-i",
+  "HOME=/home/node",
+  `GH_CONFIG_DIR=${MANAGED_GH_CONFIG_DIR}`,
+  `PATH=${SAFE_CONTAINER_PATH}`,
+] as const;
+
+/** Provider-exec form of {@link SANITIZED_DOCKER_EXEC_ENV}: same overrides,
+ * carried as a bounded env record instead of docker `-e` flags. */
+export const SANITIZED_CONTAINER_ENV: Readonly<Record<string, string>> =
+  Object.freeze({
+    HOME: "/home/node",
+    GH_CONFIG_DIR: MANAGED_GH_CONFIG_DIR,
+    PATH: SAFE_CONTAINER_PATH,
+    XDG_CONFIG_HOME: "",
+    LD_PRELOAD: "",
+    LD_LIBRARY_PATH: "",
+    DYLD_INSERT_LIBRARIES: "",
+    DYLD_LIBRARY_PATH: "",
+    GIT_CONFIG: "",
+    GIT_CONFIG_GLOBAL: "",
+    GIT_CONFIG_SYSTEM: "",
+    GIT_CONFIG_NOSYSTEM: "",
+    GIT_CONFIG_COUNT: "0",
+    GIT_EXEC_PATH: "",
+    GIT_SSH: "",
+    GIT_SSH_COMMAND: "",
+    GIT_ASKPASS: "",
+    SSH_ASKPASS: "",
+  });
+
+function managedContainerExecArgs(
+  container: string,
+  command: string[],
+  stdin = false,
+): string[] {
+  return [
+    "exec",
+    ...(stdin ? ["-i"] : []),
+    "-u",
+    "node",
+    ...SANITIZED_DOCKER_EXEC_ENV,
+    ...runtimeAuthorityDockerExecArgs(),
+    container,
+    ...CLEAN_CONTAINER_ENV,
+    ...command,
+  ];
+}
+
+type GhConnectSet = Extract<CloudToHost, { kind: "gh.connect.set" }>;
+
+// Every local grant replacement/removal advances the user's generation. Slow
+// token exchanges and container mutations capture the generation they began
+// under and must not publish their result after a newer connect/disconnect.
+const githubAuthGenerations = new Map<string, number>();
+const githubConnectionTransitionQueues = new Map<string, Promise<void>>();
+
+function githubAuthGeneration(userId: string): number {
+  return githubAuthGenerations.get(userId) ?? 0;
+}
+
+function advanceGithubAuthGeneration(userId: string): number {
+  const next = githubAuthGeneration(userId) + 1;
+  githubAuthGenerations.set(userId, next);
+  accessCache.delete(userId);
+  // The request itself cannot be cancelled safely (the refresh token may have
+  // rotated at GitHub), but a new grant must never join that stale promise.
+  inflightExchanges.delete(userId);
+  return next;
+}
+
+/** Serialize connect/set/clear for one user. Without this outer fence, a clear
+ * that lands while set is awaiting task-up invalidation can be overwritten by
+ * the older set storing its token afterward. */
+export function runGithubConnectionTransition<T>(
+  userId: string,
+  transition: () => Promise<T>,
+  admit?: () => void,
+): Promise<T> {
+  const previous =
+    githubConnectionTransitionQueues.get(userId) ?? Promise.resolve();
+  let result!: Promise<T>;
+  let tail!: Promise<void>;
+  result = previous
+    .catch(() => {})
+    .then(() => {
+      admit?.();
+      return transition();
+    })
+    .finally(() => {
+      if (githubConnectionTransitionQueues.get(userId) === tail) {
+        githubConnectionTransitionQueues.delete(userId);
+      }
+    });
+  tail = result.then(
+    () => {},
+    () => {},
+  );
+  githubConnectionTransitionQueues.set(userId, tail);
+  return result;
+}
+
+/**
+ * Persist a monotonic credential mutation fence before changing the token row.
+ * The generation survives disconnect because it lives in a separate table, so
+ * a delayed older connect cannot recreate a credential after a newer clear.
+ */
+export type GitHubCredentialMutation = "set" | "clear";
+
+export interface GitHubCredentialGenerationClaim {
+  generation: number;
+  replay: boolean;
+}
+
+export function claimGithubCredentialGeneration(
+  userId: string,
+  requestedGeneration: number | undefined,
+  mutation: GitHubCredentialMutation,
+): GitHubCredentialGenerationClaim | null {
+  if (
+    requestedGeneration !== undefined &&
+    (!Number.isSafeInteger(requestedGeneration) || requestedGeneration < 0)
+  ) {
+    return null;
+  }
+  return getDb().transaction((tx) => {
+    const current = tx
+      .select({
+        generation: schema.githubCredentialGenerations.generation,
+        mutation: schema.githubCredentialGenerations.mutation,
+      })
+      .from(schema.githubCredentialGenerations)
+      .where(eq(schema.githubCredentialGenerations.userId, userId))
+      .get();
+    // Generationless frames belong permanently to the legacy generation-zero
+    // namespace. Never derive a newer value from local state: a delayed old
+    // cloud frame must not outrank an explicit generation from a newer cloud.
+    // Once a clear has closed generation zero, the normal clear->set replay
+    // rule below deliberately requires a cloud upgrade before reconnecting.
+    const generation = requestedGeneration ?? 0;
+    if (!Number.isSafeInteger(generation) || generation < 0) return null;
+    if (current && current.generation > generation) return null;
+    if (current && current.generation === generation) {
+      if (current.mutation === mutation) {
+        return { generation, replay: true };
+      }
+      // Clearing the exact generation that was just stored is the safe
+      // compensation path when the cloud mirror is superseded between host
+      // storage and DB attachment. The reverse transition would resurrect a
+      // cleared credential and is always rejected.
+      if (current.mutation === "set" && mutation === "clear") {
+        tx.update(schema.githubCredentialGenerations)
+          .set({ mutation: "clear", updatedAt: Date.now() })
+          .where(eq(schema.githubCredentialGenerations.userId, userId))
+          .run();
+        return { generation, replay: false };
+      }
+      return null;
+    }
+    const values = { userId, generation, mutation, updatedAt: Date.now() };
+    tx.insert(schema.githubCredentialGenerations)
+      .values(values)
+      .onConflictDoUpdate({
+        target: schema.githubCredentialGenerations.userId,
+        set: { generation, mutation, updatedAt: values.updatedAt },
+      })
+      .run();
+    return { generation, replay: false };
+  });
+}
+
+export function githubCredentialGenerationMatches(
+  userId: string,
+  generation: number,
+): boolean {
+  if (!Number.isSafeInteger(generation) || generation < 0) return false;
+  return getDb().transaction((tx) => {
+    const fence = tx
+      .select({
+        generation: schema.githubCredentialGenerations.generation,
+        mutation: schema.githubCredentialGenerations.mutation,
+      })
+      .from(schema.githubCredentialGenerations)
+      .where(eq(schema.githubCredentialGenerations.userId, userId))
+      .get();
+    const token = tx
+      .select({ generation: schema.githubTokens.generation })
+      .from(schema.githubTokens)
+      .where(eq(schema.githubTokens.userId, userId))
+      .get();
+    return (
+      fence?.mutation === "set" &&
+      fence.generation === generation &&
+      token?.generation === generation
+    );
+  });
+}
+
+// --- token store ------------------------------------------------------------
+
+/**
+ * Encrypt + persist the user's token (gh.connect.set handler). ADR-033: a
+ * non-expiring grant carries `accessToken` (stored kind="access", injected
+ * directly); a legacy expiring grant carries `refreshToken` (kind="refresh",
+ * exchanged per task). Exactly one is present.
+ */
+export interface ConnectSetDeps {
+  invalidateCredentials?: (userId: string) => Promise<void>;
+  readStored?: (
+    userId: string,
+  ) => StoredGitHubGrant | null;
+  deleteLocal?: (userId: string) => void;
+  storeLocal?: (
+    userId: string,
+    fields: {
+      installationId: number;
+      generation: number;
+      refreshTokenCt: Buffer;
+      refreshTokenNonce: Buffer;
+      refreshTokenExpiresAt: number | null;
+      kind: string;
+      updatedAt: number;
+    },
+  ) => void;
+  taskIds?: (userId: string) => string[];
+  reconcile?: (taskId: string, userId: string) => Promise<boolean>;
+  revoke?: (token: string) => Promise<void>;
+  seal?: typeof sealAesGcm;
+  notifyChange?: () => void;
+}
+
+export async function onConnectSet(
+  frame: GhConnectSet,
+  deps: ConnectSetDeps = {},
+): Promise<{ ok: boolean; error?: string }> {
+  let oldGrantRemoved = false;
+  let replacementStored = false;
+  let priorGrant: StoredGitHubGrant | null = null;
+  try {
+    const token = frame.accessToken ?? frame.refreshToken;
+    if (!token) return { ok: false, error: "gh.connect.set carried no token" };
+    const kind = frame.accessToken ? "access" : "refresh";
+    const credentialGeneration = frame.generation ?? 0;
+    const sealed = (deps.seal ?? sealAesGcm)(token);
+    const now = Date.now();
+    const fields = {
+      installationId: frame.installationId,
+      generation: credentialGeneration,
+      refreshTokenCt: sealed.ct,
+      refreshTokenNonce: sealed.nonce,
+      refreshTokenExpiresAt: frame.refreshTokenExpiresAt ?? null,
+      kind,
+      updatedAt: now,
+    };
+
+    try {
+      priorGrant = (deps.readStored ?? readStoredToken)(frame.userId);
+    } catch (err) {
+      // A corrupt superseded row must not prevent replacement. It can still be
+      // deleted locally and every container is authoritatively scrubbed below.
+      console.warn(
+        `[github] user ${frame.userId}: could not read token before replacement: ${
+          err instanceof Error ? err.message : err
+        }`,
+      );
+    }
+
+    // A retry of the exact same operation is safe and still reconciles tasks;
+    // reusing one generation for different credential material is not. Without
+    // this check a replayed opId/generation could replace the token while the
+    // cloud continued to trust the original binding generation.
+    if (
+      priorGrant?.generation === credentialGeneration &&
+      (priorGrant.token !== token ||
+        priorGrant.kind !== kind ||
+        priorGrant.installationId !== frame.installationId)
+    ) {
+      return {
+        ok: false,
+        error: "conflicting GitHub credential replay for one generation",
+      };
+    }
+
+    // Remove the old grant before fencing host-side Git. A task that begins
+    // while account switching is in progress must not mint or seed the old
+    // user's credential. The replacement is already sealed above, so failures
+    // before this point leave the existing connection untouched.
+    (deps.deleteLocal ?? deleteStoredTokenRow)(frame.userId);
+    oldGrantRemoved = true;
+    advanceGithubAuthGeneration(frame.userId);
+
+    // Account switching must also retire A remotely. Skip when GitHub sent the
+    // same access token again, which would otherwise revoke replacement B.
+    if (
+      priorGrant?.kind === "access" &&
+      priorGrant.token !== token
+    ) {
+      await bestEffortRevoke(
+        frame.userId,
+        priorGrant.token,
+        deps.revoke ?? revokeAtGitHub,
+      );
+    }
+
+    // Existing task-up operations may still be using the old ephemeral cache.
+    // Invalidate and drain them before publishing the replacement grant.
+    await deps.invalidateCredentials?.(frame.userId);
+
+    if (deps.storeLocal) deps.storeLocal(frame.userId, fields);
+    else if (signInBoxMode()) {
+      // ADR-136 sign-in box: the store first, awaited; a row with no
+      // material; the token in the bounded cache only.
+      await storeGithubTokenStoreFirst(
+        frame.userId,
+        {
+          installationId: fields.installationId,
+          generation: fields.generation,
+          refreshTokenExpiresAt: fields.refreshTokenExpiresAt,
+          kind,
+          updatedAt: now,
+        },
+        token,
+      );
+    } else storeTokenRow(frame.userId, fields);
+    replacementStored = true;
+    // Advance again only after the replacement is durable. This detaches work
+    // started during the no-grant fence and lets reconciliation capture B.
+    advanceGithubAuthGeneration(frame.userId);
+    (deps.notifyChange ?? notifyGithubChange)();
+
+    // Account-switch acknowledgement is a credential boundary: wait until each
+    // container that could retain A has been removed or scrubbed and configured
+    // with B. Main injects a task-lifecycle wrapper so a concurrent task-up is
+    // completed before this per-task credential transition runs.
+    const taskIds = (deps.taskIds ?? credentialCleanupTaskIdsForUser)(
+      frame.userId,
+    );
+    const reconcile = deps.reconcile ?? reconcileTaskGitAuth;
+    const settled = await Promise.allSettled(
+      taskIds.map((taskId) => reconcile(taskId, frame.userId)),
+    );
+    const rejected = settled.find(
+      (result): result is PromiseRejectedResult => result.status === "rejected",
+    );
+    if (rejected) throw rejected.reason;
+    if (settled.some((result) => result.status === "fulfilled" && !result.value)) {
+      throw new Error("GitHub credential replacement did not reach every task");
+    }
+    return { ok: true };
+  } catch (err) {
+    // If the old grant was already removed, advertise the authoritative local
+    // state and scrub live containers through the normal no-token reconciler.
+    // Never leave a failed account switch looking connected to the old user.
+    if (oldGrantRemoved && !replacementStored) {
+      (deps.notifyChange ?? notifyGithubChange)();
+      const taskIds = (deps.taskIds ?? credentialCleanupTaskIdsForUser)(
+        frame.userId,
+      );
+      const reconcile = deps.reconcile ?? reconcileTaskGitAuth;
+      await Promise.allSettled(
+        taskIds.map((taskId) => reconcile(taskId, frame.userId)),
+      );
+    }
+    return { ok: false, error: err instanceof Error ? err.message : "store failed" };
+  }
+}
+
+function deleteStoredTokenRow(userId: string): void {
+  forgetGithubToken(userId);
+  const result = getDb()
+    .delete(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .run();
+  // A connect clears any prior grant first; with none stored there is no
+  // parameter to delete either.
+  if (result.changes > 0) deleteGithubTokenFromStore(userId);
+}
+
+function storeTokenRow(
+  userId: string,
+  fields: {
+    installationId: number;
+    generation: number;
+    refreshTokenCt: Buffer;
+    refreshTokenNonce: Buffer;
+    refreshTokenExpiresAt: number | null;
+    kind: string;
+    updatedAt: number;
+  },
+): void {
+  getDb().transaction((tx) => {
+    const fence = tx
+      .select({
+        generation: schema.githubCredentialGenerations.generation,
+        mutation: schema.githubCredentialGenerations.mutation,
+      })
+      .from(schema.githubCredentialGenerations)
+      .where(eq(schema.githubCredentialGenerations.userId, userId))
+      .get();
+    if (
+      fence?.mutation !== "set" ||
+      fence.generation !== fields.generation
+    ) {
+      throw new Error("GitHub credential generation changed before storage");
+    }
+    tx.insert(schema.githubTokens)
+      .values({ userId, ...fields })
+      .onConflictDoUpdate({ target: schema.githubTokens.userId, set: fields })
+      .run();
+  });
+  mirrorGithubTokenToStore(userId);
+}
+
+// ---------------------------------------------------------------------------
+// Credential store mirror (ADR-134 slice 2): `<prefix>/users/<userId>/github`.
+// The generation rides along so a replacement host imports the row behind the
+// same durable fence (a later disconnect this host never saw still wins).
+// Owned hosts: no-ops.
+// ---------------------------------------------------------------------------
+
+export interface StoredGithubToken {
+  v: 1;
+  kind: "github";
+  userId: string;
+  installationId: number;
+  generation: number;
+  tokenKind: string;
+  token: string;
+  expiresAt: number | null;
+  updatedAt: number;
+}
+
+export function githubTokenParameterName(userId: string): string {
+  return userParameterName(userId, "github");
+}
+
+/** The row as it is mirrored (token decrypted). Never logged. On the
+ *  sign-in box a store-held row yields the cached token, or null when the
+ *  cache is cold — there is nothing here to mirror then. */
+export function githubTokenStoreValue(userId: string): StoredGithubToken | null {
+  const row = getDb()
+    .select()
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  if (!row) return null;
+  const token = isStoreHeldGithubRow(row)
+    ? cachedGithubToken(userId)
+    : openAesGcm(
+        Buffer.from(row.refreshTokenCt as Uint8Array),
+        Buffer.from(row.refreshTokenNonce as Uint8Array),
+      );
+  if (token === null) return null;
+  return {
+    v: 1,
+    kind: "github",
+    userId,
+    installationId: row.installationId,
+    generation: row.generation,
+    tokenKind: row.kind,
+    token,
+    expiresAt: row.refreshTokenExpiresAt ?? null,
+    updatedAt: row.updatedAt,
+  };
+}
+
+export function setGithubTokenStoreRef(userId: string, storeRef: string): void {
+  getDb()
+    .update(schema.githubTokens)
+    .set({ storeRef })
+    .where(eq(schema.githubTokens.userId, userId))
+    .run();
+}
+
+export function listGithubTokenStoreRows(): Array<{ userId: string; storeRef: string | null }> {
+  return getDb()
+    .select({ userId: schema.githubTokens.userId, storeRef: schema.githubTokens.storeRef })
+    .from(schema.githubTokens)
+    .all();
+}
+
+export function mirrorGithubTokenToStore(userId: string): void {
+  // ADR-136 sign-in box: rows hold no material; the store was written first.
+  if (signInBoxMode()) return;
+  queueStoreWrite(`mirror github token ${userId}`, async (store) => {
+    const value = githubTokenStoreValue(userId);
+    if (!value) return;
+    const name = githubTokenParameterName(userId);
+    await store.put(name, JSON.stringify(value));
+    setGithubTokenStoreRef(userId, name);
+  });
+}
+
+export function deleteGithubTokenFromStore(userId: string): void {
+  queueStoreWrite(`delete github token ${userId}`, (store) =>
+    store.delete(githubTokenParameterName(userId)),
+  );
+}
+
+/**
+ * Reconcile import: a token this host lacks. Claims the stored generation as
+ * a `set` first — refused (false) when this host's fence already moved past
+ * it, so a disconnect that outran the store's delete can never resurrect a
+ * token here.
+ */
+export function importGithubTokenFromStore(
+  value: StoredGithubToken,
+  storeRef: string,
+): boolean {
+  const claim = claimGithubCredentialGeneration(value.userId, value.generation, "set");
+  if (!claim) return false;
+  const sealed = sealAesGcm(value.token);
+  const fields = {
+    installationId: value.installationId,
+    generation: value.generation,
+    refreshTokenCt: sealed.ct,
+    refreshTokenNonce: sealed.nonce,
+    refreshTokenExpiresAt: value.expiresAt,
+    kind: value.tokenKind,
+    updatedAt: value.updatedAt,
+    storeRef,
+  };
+  getDb()
+    .insert(schema.githubTokens)
+    .values({ userId: value.userId, ...fields })
+    .onConflictDoUpdate({ target: schema.githubTokens.userId, set: fields })
+    .run();
+  notifyGithubChange();
+  return true;
+}
+
+async function bestEffortRevoke(
+  userId: string,
+  token: string,
+  revoke: (token: string) => Promise<void>,
+): Promise<void> {
+  try {
+    await revoke(token);
+  } catch (err) {
+    console.warn(
+      `[github] user ${userId}: token revoke failed after local removal: ${
+        err instanceof Error ? err.message : err
+      }`,
+    );
+  }
+}
+
+/**
+ * Disconnect GitHub on this host (gh.connect.clear handler). The surrounding
+ * claimed `clear` generation makes the stored row inert immediately. Keep that
+ * row recoverable until every live container has dropped the credential and
+ * selected its disconnected transport; only then delete it and best-effort
+ * revoke remotely. A runtime loss can therefore reject without turning a
+ * retryable scrub into an irreversible half-transition.
+ *
+ * ADR-033: only a non-expiring ACCESS token can be revoked by token
+ * (`DELETE /applications/{client_id}/token` matches access tokens only — a
+ * refresh token 404s, which the cloud endpoint would mis-report as success).
+ * Legacy refresh tokens aren't single-token revocable; the short-lived access
+ * tokens they mint expire on their own.
+ */
+export interface ConnectClearDeps {
+  readStored?: (
+    userId: string,
+  ) => StoredGitHubGrant | null;
+  deleteLocal?: (userId: string) => void;
+  activeTaskIds?: (userId: string) => string[];
+  reconcile?: (taskId: string, userId: string) => Promise<boolean>;
+  revoke?: (token: string) => Promise<void>;
+  invalidateCredentials?: (userId: string) => Promise<void>;
+}
+
+export async function onConnectClear(
+  userId: string,
+  deps: ConnectClearDeps = {},
+): Promise<void> {
+  let stored: StoredGitHubGrant | null = null;
+  try {
+    stored = (deps.readStored ?? readStoredToken)(userId);
+  } catch (err) {
+    // A corrupt legacy row must not make Disconnect impossible. We can still
+    // delete it locally and clean every live container; only remote revocation
+    // is unavailable because the token could not be decrypted.
+    console.warn(
+      `[github] user ${userId}: could not read token before disconnect: ${
+        err instanceof Error ? err.message : err
+      }`,
+    );
+  }
+
+  // Incrementing the host-Git generation prevents any not-yet-started use of
+  // an old prepared handle. Await already-started task-up operations before
+  // discovering and scrubbing containers: a task may create its app container
+  // while Disconnect is in flight.
+  await deps.invalidateCredentials?.(userId);
+
+  const activeTasks = (deps.activeTaskIds ?? credentialCleanupTaskIdsForUser)(
+    userId,
+  );
+  for (const taskId of activeTasks) {
+    clearRefresh(taskId);
+  }
+  const reconcile = deps.reconcile ?? reconcileTaskGitAuth;
+  const settled = await Promise.allSettled(
+    activeTasks.map((taskId) => reconcile(taskId, userId)),
+  );
+  const failed = settled.find(
+    (result): result is PromiseRejectedResult => result.status === "rejected",
+  );
+  if (failed) throw failed.reason;
+
+  // The claimed clear already removed this generation from every authority
+  // read. Delete the recoverable ciphertext only after all container scrubs
+  // crossed their durable boundary, so the same-generation operation can be
+  // retried if Docker disappeared mid-transition.
+  (deps.deleteLocal ?? deleteToken)(userId);
+
+  // Await best-effort remote revocation while the caller still owns the
+  // per-user transition lock. revokeAtGitHub catches its own failures; the
+  // wrapper also contains failures from injected test/alternate implementations.
+  if (stored?.kind === "access") {
+    await bestEffortRevoke(
+      userId,
+      stored.token,
+      deps.revoke ?? revokeAtGitHub,
+    );
+  } else if (stored) {
+    console.warn(
+      `[github] user ${userId}: legacy refresh token cleared locally; cannot single-token revoke at GitHub`,
+    );
+  }
+}
+
+/** Fail-closed rollback for a generation that was claimed for set but could
+ * not be fully reconciled. The tombstone transition happens before cleanup is
+ * awaited, so task/token readers stop trusting the credential immediately. */
+export async function rollbackClaimedGitHubCredentialSet(
+  userId: string,
+  generation: number,
+  deps: ConnectClearDeps = {},
+): Promise<boolean> {
+  const rollback = claimGithubCredentialGeneration(
+    userId,
+    generation,
+    "clear",
+  );
+  if (!rollback) return false;
+  try {
+    await onConnectClear(userId, deps);
+  } catch (err) {
+    console.warn(
+      `[github] user ${userId}: claimed set rollback cleanup failed: ${
+        err instanceof Error ? err.message : err
+      }`,
+    );
+  }
+  return true;
+}
+
+interface StoredGitHubGrant {
+  token: string;
+  kind: string;
+  installationId?: number;
+  generation?: number;
+}
+
+type PersistedGitHubGrant = StoredGitHubGrant & {
+  installationId: number;
+  generation: number;
+};
+
+/** Decrypt any stored token, including an inert row from an older generation.
+ * Transition handlers need the old ciphertext solely so they can revoke it;
+ * task and verification readers use `readCurrentStoredToken` below. */
+function readStoredToken(
+  userId: string,
+): PersistedGitHubGrant | null {
+  const row = getDb()
+    .select()
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  if (!row) return null;
+  // ADR-136 sign-in box: a store-held row answers from the bounded cache
+  // (filled by `loadGithubTokenIntoCache` on the async paths) or not at all.
+  const token = isStoreHeldGithubRow(row)
+    ? cachedGithubToken(userId)
+    : openAesGcm(
+        Buffer.from(row.refreshTokenCt as Uint8Array),
+        Buffer.from(row.refreshTokenNonce as Uint8Array),
+      );
+  if (token === null) return null;
+  return {
+    token,
+    kind: row.kind,
+    installationId: row.installationId,
+    generation: row.generation,
+  };
+}
+
+function readCurrentStoredToken(userId: string): PersistedGitHubGrant | null {
+  const stored = readStoredToken(userId);
+  return stored &&
+    githubCredentialGenerationMatches(userId, stored.generation)
+    ? stored
+    : null;
+}
+
+export function deleteToken(userId: string): void {
+  forgetGithubToken(userId);
+  getDb()
+    .delete(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .run();
+  deleteGithubTokenFromStore(userId);
+  advanceGithubAuthGeneration(userId);
+  notifyGithubChange();
+}
+
+export function hasToken(userId: string): boolean {
+  // Metadata only: a store-held row (sign-in box) counts as connected whether
+  // or not its token is in the cache right now.
+  const row = getDb()
+    .select({ generation: schema.githubTokens.generation })
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  return row !== undefined && githubCredentialGenerationMatches(userId, row.generation);
+}
+
+/** All cloud user ids with a GitHub token on this host (for capabilities). */
+export function connectedUserIds(): string[] {
+  return getDb()
+    .select({ userId: schema.githubTokens.userId })
+    .from(schema.githubTokens)
+    .innerJoin(
+      schema.githubCredentialGenerations,
+      and(
+        eq(
+          schema.githubCredentialGenerations.userId,
+          schema.githubTokens.userId,
+        ),
+        eq(
+          schema.githubCredentialGenerations.generation,
+          schema.githubTokens.generation,
+        ),
+      ),
+    )
+    .where(eq(schema.githubCredentialGenerations.mutation, "set"))
+    .all()
+    .map((r) => r.userId);
+}
+
+// Fires whenever the set of stored tokens changes (add/remove), so the host
+// can re-advertise capabilities and the UI reflects per-host gh state promptly.
+let githubChangeHandler: (() => void) | null = null;
+export function onGithubChange(fn: (() => void) | null): void {
+  githubChangeHandler = fn;
+}
+function notifyGithubChange(): void {
+  try {
+    githubChangeHandler?.();
+  } catch {
+    /* never let a listener break token handling */
+  }
+}
+
+export function taskMayRetainGithubCredential(task: {
+  endedAt: number | null;
+  composeProject: string | null;
+  statusMirror: string | null;
+}): boolean {
+  // Active/starting rows may gain a container while Disconnect is running.
+  // Ended rows need cleanup only when their compose identity is preserved;
+  // task-down clears composeProject after destroying the stack. A failed
+  // task-up can leave a conventional app container before compose metadata was
+  // persisted, so error rows are probed by task id as well.
+  return (
+    task.endedAt == null ||
+    task.composeProject != null ||
+    task.statusMirror === "error"
+  );
+}
+
+function taskCredentialRowsForUser(userId: string) {
+  return getDb()
+    .select({
+      taskId: schema.hostTasks.taskId,
+      endedAt: schema.hostTasks.endedAt,
+      composeProject: schema.hostTasks.composeProject,
+      statusMirror: schema.hostTasks.statusMirror,
+    })
+    .from(schema.hostTasks)
+    .where(eq(schema.hostTasks.ownerUserId, userId))
+    .all();
+}
+
+function credentialCleanupTaskIdsForUser(userId: string): string[] {
+  return taskCredentialRowsForUser(userId)
+    .filter(taskMayRetainGithubCredential)
+    .map((r) => r.taskId);
+}
+
+function runningTaskIdsForUser(userId: string): string[] {
+  return taskCredentialRowsForUser(userId)
+    .filter((task) => task.endedAt == null)
+    .map((task) => task.taskId);
+}
+
+/**
+ * Re-mint + inject a (re)connected token into the user's live tasks — so a
+ * reconnect on Account applies to running containers, not only new tasks. Clear
+ * any armed retry chain first (a fresh grant must not be swallowed by an outage
+ * backoff, and `setupTaskGithub`'s duplicate-chain guard would no-op it) then
+ * run setup fresh. Fire-and-forget per task; best-effort by construction.
+ */
+export function reinjectRunningTasks(userId: string): void {
+  for (const taskId of runningTaskIdsForUser(userId)) {
+    clearRefresh(taskId);
+    void reconcileTaskGitAuth(taskId, userId).catch((err) =>
+      console.warn(
+        `[github] task ${taskId}: credential reconciliation failed: ${
+          err instanceof Error ? err.message : err
+        }`,
+      ),
+    );
+  }
+}
+
+// --- access-token exchange --------------------------------------------------
+
+function cloudHttpBase(): string {
+  const cloud = process.env.UAI_CLOUD_URL ?? "ws://127.0.0.1:8789/host";
+  const u = new URL(cloud);
+  const proto =
+    u.protocol === "wss:" ? "https:" : u.protocol === "ws:" ? "http:" : u.protocol;
+  return `${proto}//${u.host}`;
+}
+
+function exchangeUrl(): string {
+  return `${cloudHttpBase()}/api/github/oauth/exchange`;
+}
+
+/**
+ * Revoke a token at GitHub via the cloud (which holds the App client secret —
+ * the host can't revoke alone). Same host→cloud HTTP pattern as the exchange;
+ * the token transits the cloud transiently, never stored (ADR-015/ADR-033).
+ * Best-effort — callers proceed to delete locally regardless.
+ */
+async function revokeAtGitHub(token: string): Promise<void> {
+  try {
+    const res = await fetch(`${cloudHttpBase()}/api/github/revoke`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-uai-host-token": process.env.UAI_HOST_TOKEN ?? "",
+      },
+      body: JSON.stringify({ token }),
+      signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      console.warn(`[github] token revoke returned HTTP ${res.status}`);
+    }
+  } catch (err) {
+    console.warn(
+      `[github] token revoke failed (deleting locally anyway): ${err instanceof Error ? err.message : err}`,
+    );
+  }
+}
+
+interface ExchangeResult {
+  accessToken: string;
+  expiresAt: number;
+  refreshToken: string | null;
+  refreshTokenExpiresAt: number | null;
+}
+
+/**
+ * Mint a fresh access token for the user via the cloud exchange. Persists a
+ * rotated refresh token if GitHub returned one. Returns null when the user has
+ * no token on this host. Throws on exchange failure.
+ *
+ * Deduped PER USER: GitHub refresh tokens are single-use (each exchange
+ * rotates them), and GitHub treats reuse of a consumed token as a compromise
+ * signal that can kill the whole grant. Concurrent task setups for the same
+ * user (several task-ups at once, or every channel re-ensure after a host
+ * restart) used to race the rotation — the loser burned the grant and every
+ * exchange afterwards failed until a manual re-connect. The access token is
+ * per-user anyway, so concurrent callers share one in-flight exchange.
+ */
+const inflightExchanges = new Map<
+  string,
+  {
+    generation: number;
+    promise: Promise<{ accessToken: string; expiresAt: number } | null>;
+  }
+>();
+
+/**
+ * Per-user ACCESS-token cache. Access tokens live ~8h, but every exchange
+ * ROTATES the single-use refresh token — and a rotation whose response is
+ * lost mid-flight (our timeout firing while GitHub already rotated) burns the
+ * grant, forcing a manual re-connect. So exchange as rarely as possible: all
+ * task setups and refresh timers for a user share one cached access token
+ * until it nears expiry. The refresh timers fire at expiry−5min, inside the
+ * 15min stale window, so exactly one of them performs the real exchange (the
+ * in-flight dedupe serializes any ties) and the rest re-inject from cache.
+ */
+const ACCESS_CACHE_LEAD_MS = 15 * 60 * 1000;
+const accessCache = new Map<
+  string,
+  { accessToken: string; expiresAt: number }
+>();
+
+const INSTALLATION_PAGE_SIZE = 100;
+const REPOSITORY_PAGE_SIZE = 100;
+const REPOSITORY_PAGE_CAP = Math.ceil(
+  MAX_GITHUB_REPOSITORIES_PER_INSTALLATION / REPOSITORY_PAGE_SIZE,
+);
+const GITHUB_LIST_TIMEOUT_MS = 10_000;
+// Bound only the GitHub listing phase. The installation bridge allows 60s so a
+// legacy refresh-token exchange (up to 30s) can precede this 25s window; the
+// repository bridge uses 30s because the complete installation call has just
+// warmed that user's access-token cache. Every REST page gets the smaller of
+// its normal timeout and the remaining listing budget.
+const GITHUB_LIST_OPERATION_TIMEOUT_MS = 25_000;
+
+function githubListSignal(deadline: number): AbortSignal {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) throw new Error("github list operation timed out");
+  return AbortSignal.timeout(Math.min(GITHUB_LIST_TIMEOUT_MS, remaining));
+}
+
+export class GitHubRepositoryAccessError extends Error {
+  constructor(
+    readonly code: GitHubRepositoryAccessErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "GitHubRepositoryAccessError";
+  }
+}
+
+interface GitHubListDeps {
+  requestAccessToken?: typeof requestAccessToken;
+  fetch?: typeof fetch;
+  credentialGenerationMatches?: typeof githubCredentialGenerationMatches;
+  /** When the whole operation must end (the token's read included). Absent,
+   *  the listing alone gets its own bound once a token is in hand. */
+  deadlineAt?: number;
+}
+
+/**
+ * The token could not be read where it is kept (the sign-in box's store):
+ * a fixed message, and a transient code, never the store's own words.
+ */
+export class GitHubTokenUnreadableError extends Error {
+  constructor() {
+    super("the GitHub sign-in could not be read");
+    this.name = "GitHubTokenUnreadableError";
+  }
+}
+
+
+/**
+ * Every installation GitHub currently lists for this user, read with the token
+ * this host already holds — the host-side half of `gh.installations.list`.
+ *
+ * This is what lets a misbound installation row be pruned without the user
+ * reconnecting: the cloud mirror predates `(user_id, installation_id)` keying
+ * and cannot be trusted, but the host can ask GitHub on the user's behalf at
+ * any time, with no browser round trip.
+ *
+ * THROWS rather than returning a partial list. The caller prunes bindings that
+ * are absent from the result, so a truncated or failed read would delete
+ * legitimate grants — absence is only meaningful in a list we fully retrieved.
+ */
+export async function listUserInstallationIds(
+  userId: string,
+  deps: GitHubListDeps = {},
+  generation = 0,
+): Promise<number[]> {
+  if (
+    !(deps.credentialGenerationMatches ?? githubCredentialGenerationMatches)(
+      userId,
+      generation,
+    )
+  ) {
+    throw new GitHubRepositoryAccessError(
+      "reauth_required",
+      "the host GitHub credential belongs to a different binding generation",
+    );
+  }
+  let tok: Awaited<ReturnType<typeof requestAccessToken>>;
+  try {
+    tok = await (deps.requestAccessToken ?? requestAccessToken)(userId);
+  } catch (err) {
+    if (err instanceof GitHubTokenUnreadableError) {
+      throw new GitHubRepositoryAccessError("github_unavailable", err.message);
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new GitHubRepositoryAccessError(
+      isTransientGithubError(reason) ? "github_unavailable" : "reauth_required",
+      reason,
+    );
+  }
+  if (!tok) {
+    throw new GitHubRepositoryAccessError(
+      "token_missing",
+      `no github token stored for user ${userId}`,
+    );
+  }
+  const ids = new Set<number>();
+  const deadline = deps.deadlineAt ?? Date.now() + GITHUB_LIST_OPERATION_TIMEOUT_MS;
+  let res: Response;
+  try {
+    res = await (deps.fetch ?? fetch)(
+      `${githubApiOrigin()}/user/installations` +
+        `?per_page=${INSTALLATION_PAGE_SIZE}&page=1`,
+      {
+        headers: {
+          authorization: `Bearer ${tok.accessToken}`,
+          accept: "application/vnd.github+json",
+          "user-agent": "uai-host",
+        },
+        signal: githubListSignal(deadline),
+      },
+    );
+  } catch (err) {
+    throw new GitHubRepositoryAccessError(
+      "github_unavailable",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+  if (!res.ok) {
+    throw new GitHubRepositoryAccessError(
+      res.status === 401 ? "reauth_required" : "github_unavailable",
+      `github installation list failed: HTTP ${res.status}`,
+    );
+  }
+  let data: { total_count?: unknown; installations?: unknown };
+  try {
+    data = (await res.json()) as {
+      total_count?: unknown;
+      installations?: unknown;
+    };
+  } catch {
+    throw new GitHubRepositoryAccessError(
+      "invalid_response",
+      "github installation list returned invalid json",
+    );
+  }
+  if (
+    !Number.isSafeInteger(data.total_count) ||
+    (data.total_count as number) < 0 ||
+    (data.total_count as number) > MAX_GITHUB_INSTALLATIONS ||
+    !Array.isArray(data.installations) ||
+    data.installations.length !== data.total_count
+  ) {
+    throw new GitHubRepositoryAccessError(
+      "invalid_response",
+      "github installation list returned an incomplete body",
+    );
+  }
+  for (const inst of data.installations) {
+    // Reject the whole response rather than skipping the entry. The caller
+    // prunes bindings absent from this list, so a silently dropped or duplicate
+    // id is indistinguishable from a complete GitHub verdict.
+    if (!inst || typeof inst !== "object") {
+      throw new GitHubRepositoryAccessError(
+        "invalid_response",
+        "github returned a malformed installation entry",
+      );
+    }
+    const id = (inst as { id?: unknown }).id;
+    if (
+      !Number.isSafeInteger(id) ||
+      (id as number) <= 0 ||
+      ids.has(id as number)
+    ) {
+      throw new GitHubRepositoryAccessError(
+        "invalid_response",
+        "github returned a malformed or duplicate installation id",
+      );
+    }
+    ids.add(id as number);
+  }
+
+  // A newer set/clear may have landed while GitHub was answering. Returning
+  // the old actor's complete list after that point would let the cloud prune
+  // bindings under the newer credential, so re-check at the publication edge.
+  if (
+    !(deps.credentialGenerationMatches ?? githubCredentialGenerationMatches)(
+      userId,
+      generation,
+    )
+  ) {
+    throw new GitHubRepositoryAccessError(
+      "reauth_required",
+      "the host GitHub credential changed during installation verification",
+    );
+  }
+
+  return [...ids];
+}
+
+export async function listUserInstallationRepositoryIds(
+  userId: string,
+  installationId: number,
+  deps: GitHubListDeps = {},
+  generation = 0,
+): Promise<{ repositoryIds: number[]; truncated: boolean }> {
+  if (
+    !(deps.credentialGenerationMatches ?? githubCredentialGenerationMatches)(
+      userId,
+      generation,
+    )
+  ) {
+    throw new GitHubRepositoryAccessError(
+      "reauth_required",
+      "the host GitHub credential belongs to a different binding generation",
+    );
+  }
+  let tok: Awaited<ReturnType<typeof requestAccessToken>>;
+  try {
+    tok = await (deps.requestAccessToken ?? requestAccessToken)(userId);
+  } catch (err) {
+    if (err instanceof GitHubTokenUnreadableError) {
+      throw new GitHubRepositoryAccessError("github_unavailable", err.message);
+    }
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new GitHubRepositoryAccessError(
+      isTransientGithubError(reason) ? "github_unavailable" : "reauth_required",
+      reason,
+    );
+  }
+  if (!tok) {
+    throw new GitHubRepositoryAccessError(
+      "token_missing",
+      `no github token stored for user ${userId}`,
+    );
+  }
+  const repositoryIds = new Set<number>();
+  let truncated = false;
+  const deadline = deps.deadlineAt ?? Date.now() + GITHUB_LIST_OPERATION_TIMEOUT_MS;
+  for (let page = 1; page <= REPOSITORY_PAGE_CAP; page++) {
+    let res: Response;
+    try {
+      res = await (deps.fetch ?? fetch)(
+        `${githubApiOrigin()}/user/installations/${installationId}/repositories` +
+          `?per_page=${REPOSITORY_PAGE_SIZE}&page=${page}`,
+        {
+          headers: {
+            authorization: `Bearer ${tok.accessToken}`,
+            accept: "application/vnd.github+json",
+            "user-agent": "uai-host",
+          },
+          signal: githubListSignal(deadline),
+        },
+      );
+    } catch (err) {
+      throw new GitHubRepositoryAccessError(
+        "github_unavailable",
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+    if (!res.ok) {
+      const code: GitHubRepositoryAccessErrorCode =
+        res.status === 401
+          ? "reauth_required"
+          : res.status === 404
+            ? "installation_inaccessible"
+            : "github_unavailable";
+      throw new GitHubRepositoryAccessError(
+        code,
+        `github repository list failed for installation ${installationId}: HTTP ${res.status}`,
+      );
+    }
+    let data: { repositories?: unknown };
+    try {
+      data = (await res.json()) as { repositories?: unknown };
+    } catch {
+      throw new GitHubRepositoryAccessError(
+        "invalid_response",
+        "github repository list returned invalid json",
+      );
+    }
+    if (!Array.isArray(data.repositories)) {
+      throw new GitHubRepositoryAccessError(
+        "invalid_response",
+        "github repository list returned an invalid body",
+      );
+    }
+    const batch = data.repositories;
+    for (const repo of batch) {
+      if (!repo || typeof repo !== "object") {
+        // Repository results are an allowlist. Omitting an unparseable entry
+        // can only withhold access, so preserve the valid IDs but make the
+        // partial result explicit. (Installation-list entries are different:
+        // omission there could drive a destructive prune and must throw.)
+        truncated = true;
+        continue;
+      }
+      const id = (repo as { id?: unknown }).id;
+      if (!Number.isSafeInteger(id) || (id as number) <= 0) {
+        truncated = true;
+        continue;
+      }
+      repositoryIds.add(id as number);
+    }
+    if (batch.length < REPOSITORY_PAGE_SIZE) break;
+    if (page === REPOSITORY_PAGE_CAP) truncated = true;
+  }
+  if (
+    !(deps.credentialGenerationMatches ?? githubCredentialGenerationMatches)(
+      userId,
+      generation,
+    )
+  ) {
+    throw new GitHubRepositoryAccessError(
+      "reauth_required",
+      "the host GitHub credential changed during repository verification",
+    );
+  }
+  return {
+    repositoryIds: [...repositoryIds].slice(
+      0,
+      MAX_GITHUB_REPOSITORIES_PER_INSTALLATION,
+    ),
+    truncated:
+      truncated || repositoryIds.size > MAX_GITHUB_REPOSITORIES_PER_INSTALLATION,
+  };
+}
+
+/** Test hook: reset the access-token cache. */
+export function clearAllAccessCache(): void {
+  accessCache.clear();
+  inflightExchanges.clear();
+  githubAuthGenerations.clear();
+}
+
+/**
+ * ADR-154 §13, the cutover purge, once the token rows are gone: no GitHub
+ * token stays in this process. Each user with a cached access token or an
+ * exchange under way moves to a new generation, as at a sign-out, which
+ * drops both; an exchange that ends later then caches and stores nothing.
+ * The sign-in box's cache goes too. Unlike the test hook above, no
+ * generation goes back, so nothing fenced off before is let in again.
+ */
+export function forgetGithubTokensInMemory(): void {
+  for (const userId of new Set([...accessCache.keys(), ...inflightExchanges.keys()])) {
+    advanceGithubAuthGeneration(userId);
+  }
+  boxTokens.clear();
+}
+
+export async function requestAccessToken(
+  userId: string,
+): Promise<{ accessToken: string; expiresAt: number | null } | null> {
+  // ADR-136 sign-in box: the token is read from the store on demand for
+  // the installation listing and a legacy exchange, never kept on disk.
+  if (signInBoxMode()) {
+    try {
+      await loadGithubTokenIntoCache(userId);
+    } catch (err) {
+      console.warn(
+        `[github] user ${userId}: could not read the token from the credential store: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  const generation = githubAuthGeneration(userId);
+  // ADR-033 non-expiring path: the stored token IS the access token — return it
+  // directly, no exchange/cache/rotation. `expiresAt: null` ⇒ no refresh.
+  const row = readCurrentStoredToken(userId);
+  if (!row) return Promise.resolve(null);
+  if (row.kind === "access") {
+    return Promise.resolve({ accessToken: row.token, expiresAt: null });
+  }
+
+  // Legacy expiring path (ADR-027): cache + in-flight dedupe + exchange.
+  const cached = accessCache.get(userId);
+  if (cached && cached.expiresAt - Date.now() > ACCESS_CACHE_LEAD_MS) {
+    return Promise.resolve(cached);
+  }
+  const existing = inflightExchanges.get(userId);
+  if (existing?.generation === generation) return existing.promise;
+  let run!: Promise<{ accessToken: string; expiresAt: number } | null>;
+  run = doRequestAccessToken(userId, generation)
+    .then((tok) => {
+      if (tok && githubAuthGeneration(userId) === generation) {
+        accessCache.set(userId, tok);
+      }
+      return tok;
+    })
+    .finally(() => {
+      if (inflightExchanges.get(userId)?.promise === run) {
+        inflightExchanges.delete(userId);
+      }
+    });
+  inflightExchanges.set(userId, { generation, promise: run });
+  return run;
+}
+
+async function doRequestAccessToken(
+  userId: string,
+  generation: number,
+): Promise<{ accessToken: string; expiresAt: number } | null> {
+  const row = getDb().transaction((tx) => {
+    const token = tx
+      .select()
+      .from(schema.githubTokens)
+      .where(eq(schema.githubTokens.userId, userId))
+      .get();
+    if (!token) return null;
+    const fence = tx
+      .select({
+        generation: schema.githubCredentialGenerations.generation,
+        mutation: schema.githubCredentialGenerations.mutation,
+      })
+      .from(schema.githubCredentialGenerations)
+      .where(eq(schema.githubCredentialGenerations.userId, userId))
+      .get();
+    return fence?.mutation === "set" &&
+      fence.generation === token.generation
+      ? token
+      : null;
+  });
+  if (!row) return null;
+
+  const refreshToken = isStoreHeldGithubRow(row)
+    ? cachedGithubToken(userId)
+    : openAesGcm(
+        Buffer.from(row.refreshTokenCt as Uint8Array),
+        Buffer.from(row.refreshTokenNonce as Uint8Array),
+      );
+  if (refreshToken === null) return null;
+  const res = await fetch(exchangeUrl(), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-uai-host-token": process.env.UAI_HOST_TOKEN ?? "",
+    },
+    body: JSON.stringify({ refreshToken }),
+    signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+  });
+  if (!res.ok) {
+    // Include the cloud's error body: it passes GitHub's OAuth error code
+    // through (e.g. "bad_refresh_token"/"invalid_grant" inside the 502
+    // message), which is the ONLY reliable revocation signal. The bare HTTP
+    // status is not one — the cloud returns 401 solely for a host-token
+    // mismatch and wraps every GitHub-side failure as 502.
+    let detail = "";
+    try {
+      const body = (await res.json()) as { message?: string };
+      if (body && typeof body.message === "string") detail = ` — ${body.message}`;
+    } catch {
+      // non-JSON body — status alone will have to do
+    }
+    throw new Error(`gh token exchange failed: HTTP ${res.status}${detail}`);
+  }
+  const data = (await res.json()) as ExchangeResult;
+  // A reconnect/disconnect may have replaced the DB row while the network
+  // exchange was in flight. Never overwrite that newer grant with the rotated
+  // refresh token from the superseded exchange.
+  if (
+    data.refreshToken &&
+    githubAuthGeneration(userId) === generation &&
+    isStoreHeldGithubRow(row)
+  ) {
+    // ADR-136 sign-in box: the rotated token goes to the cache and the store,
+    // never onto the row.
+    rememberGithubToken(userId, data.refreshToken);
+    const rotated: StoredGithubToken = {
+      v: 1,
+      kind: "github",
+      userId,
+      installationId: row.installationId,
+      generation: row.generation,
+      tokenKind: row.kind,
+      token: data.refreshToken,
+      expiresAt: data.refreshTokenExpiresAt ?? row.refreshTokenExpiresAt ?? null,
+      updatedAt: Date.now(),
+    };
+    queueStoreWrite(`rotate github token ${userId}`, (store) =>
+      store.put(githubTokenParameterName(userId), JSON.stringify(rotated)),
+    );
+  } else if (
+    data.refreshToken &&
+    githubAuthGeneration(userId) === generation
+  ) {
+    const sealed = sealAesGcm(data.refreshToken);
+    getDb().transaction((tx) => {
+      const fence = tx
+        .select({
+          generation: schema.githubCredentialGenerations.generation,
+          mutation: schema.githubCredentialGenerations.mutation,
+        })
+        .from(schema.githubCredentialGenerations)
+        .where(eq(schema.githubCredentialGenerations.userId, userId))
+        .get();
+      if (
+        fence?.mutation !== "set" ||
+        fence.generation !== row.generation
+      ) {
+        return;
+      }
+      tx.update(schema.githubTokens)
+        .set({
+          refreshTokenCt: sealed.ct,
+          refreshTokenNonce: sealed.nonce,
+          refreshTokenExpiresAt:
+            data.refreshTokenExpiresAt ?? row.refreshTokenExpiresAt,
+          updatedAt: Date.now(),
+        })
+        .where(
+          and(
+            eq(schema.githubTokens.userId, userId),
+            eq(schema.githubTokens.generation, row.generation),
+          ),
+        )
+        .run();
+    });
+  }
+  return { accessToken: data.accessToken, expiresAt: data.expiresAt };
+}
+
+// ---------------------------------------------------------------------------
+// ADR-136 sign-in box: a token row here holds NO ciphertext — `refresh_token_ct`
+// is empty, the row is "store-held" — the token lives in the store and, only
+// while the box needs it (the installation listing, a legacy exchange, the
+// revoke of a superseded grant), in this bounded in-memory cache. Never on
+// disk. The row's metadata still drives `hasToken` / `connectedUserIds` and
+// the generation fence exactly as on any host.
+// ---------------------------------------------------------------------------
+
+const BOX_TOKEN_CACHE_MS = 10 * 60_000;
+const boxTokens = new Map<string, { token: string; until: number }>();
+
+export const GITHUB_TOKEN_TAGS = {
+  installationId: "uai_installation_id",
+  generation: "uai_generation",
+  tokenKind: "uai_token_kind",
+  expiresAt: "uai_expires_at",
+  updatedAt: "uai_updated_at",
+} as const;
+
+export function isStoreHeldGithubRow(row: { refreshTokenCt: unknown }): boolean {
+  const ct = row.refreshTokenCt;
+  if (ct === null || ct === undefined) return true;
+  if (ct instanceof Uint8Array) return ct.byteLength === 0;
+  return false;
+}
+
+export function rememberGithubToken(userId: string, token: string): void {
+  boxTokens.set(userId, { token, until: Date.now() + BOX_TOKEN_CACHE_MS });
+}
+
+export function cachedGithubToken(userId: string): string | null {
+  const entry = boxTokens.get(userId);
+  if (!entry) return null;
+  if (entry.until <= Date.now()) {
+    boxTokens.delete(userId);
+    return null;
+  }
+  return entry.token;
+}
+
+export function forgetGithubToken(userId: string): void {
+  boxTokens.delete(userId);
+}
+
+/** Test seam. */
+export function clearGithubTokenCacheForTesting(): void {
+  boxTokens.clear();
+}
+
+/** The secret-free metadata a token parameter carries as tags, so a
+ *  replacement box lists the user as connected without reading the value. */
+export function githubTokenMetadataTags(value: {
+  installationId: number;
+  generation: number;
+  tokenKind: string;
+  expiresAt: number | null;
+  updatedAt: number;
+}): Record<string, string> {
+  return {
+    [GITHUB_TOKEN_TAGS.installationId]: String(value.installationId),
+    [GITHUB_TOKEN_TAGS.generation]: String(value.generation),
+    [GITHUB_TOKEN_TAGS.tokenKind]: value.tokenKind,
+    [GITHUB_TOKEN_TAGS.expiresAt]: value.expiresAt === null ? "" : String(value.expiresAt),
+    [GITHUB_TOKEN_TAGS.updatedAt]: String(value.updatedAt),
+  };
+}
+
+/** Fill the cache from the store for a store-held row. True when a token is
+ *  cached afterwards (or the row is not store-held); false when there is no
+ *  row, no store, or no parameter. Throws on a store failure. */
+export async function loadGithubTokenIntoCache(userId: string): Promise<boolean> {
+  if (cachedGithubToken(userId) !== null) return true;
+  const row = getDb()
+    .select({
+      refreshTokenCt: schema.githubTokens.refreshTokenCt,
+      generation: schema.githubTokens.generation,
+    })
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  if (!row) return false;
+  if (!isStoreHeldGithubRow(row)) return true;
+  const store = configuredCredentialStore();
+  if (!store) return false;
+  const raw = await store.get(githubTokenParameterName(userId));
+  if (!raw) return false;
+  const parsed: unknown = JSON.parse(raw);
+  const value =
+    parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as { token?: unknown; generation?: unknown })
+      : {};
+  if (typeof value.token !== "string" || value.token.length === 0) {
+    throw new Error("the stored GitHub token is malformed");
+  }
+  if (value.generation !== row.generation) {
+    console.warn(
+      `[github] user ${userId}: the credential store holds generation ${String(value.generation)}, this box recorded ${row.generation}`,
+    );
+  }
+  rememberGithubToken(userId, value.token);
+  return true;
+}
+
+/** A token row with no material (sign-in box). Same fence as `storeTokenRow`. */
+export function insertStoreHeldGithubTokenRow(
+  userId: string,
+  fields: {
+    installationId: number;
+    generation: number;
+    refreshTokenExpiresAt: number | null;
+    kind: string;
+    updatedAt: number;
+    storeRef: string;
+  },
+): void {
+  const values = {
+    ...fields,
+    refreshTokenCt: Buffer.alloc(0),
+    refreshTokenNonce: Buffer.alloc(0),
+  };
+  getDb().transaction((tx) => {
+    const fence = tx
+      .select({
+        generation: schema.githubCredentialGenerations.generation,
+        mutation: schema.githubCredentialGenerations.mutation,
+      })
+      .from(schema.githubCredentialGenerations)
+      .where(eq(schema.githubCredentialGenerations.userId, userId))
+      .get();
+    if (fence?.mutation !== "set" || fence.generation !== fields.generation) {
+      throw new Error("GitHub credential generation changed before storage");
+    }
+    tx.insert(schema.githubTokens)
+      .values({ userId, ...values })
+      .onConflictDoUpdate({ target: schema.githubTokens.userId, set: values })
+      .run();
+  });
+}
+
+/** Sign-in box (ADR-136): the store first, awaited — a refused put is the
+ *  connect's failure — then tags, a store-held row, and the cache. */
+export async function storeGithubTokenStoreFirst(
+  userId: string,
+  fields: {
+    installationId: number;
+    generation: number;
+    refreshTokenExpiresAt: number | null;
+    kind: string;
+    updatedAt: number;
+  },
+  token: string,
+): Promise<void> {
+  const store = configuredCredentialStore();
+  if (!store) throw new Error("the sign-in box has no credential store to hold the token");
+  const name = githubTokenParameterName(userId);
+  const value: StoredGithubToken = {
+    v: 1,
+    kind: "github",
+    userId,
+    installationId: fields.installationId,
+    generation: fields.generation,
+    tokenKind: fields.kind,
+    token,
+    expiresAt: fields.refreshTokenExpiresAt,
+    updatedAt: fields.updatedAt,
+  };
+  await store.put(name, JSON.stringify(value));
+  try {
+    await store.tag(name, githubTokenMetadataTags(value));
+  } catch (err) {
+    console.warn(
+      `[github] user ${userId}: tagging ${name} failed (${err instanceof Error ? err.message : String(err)}) — a replacement box reads the value once to list this user`,
+    );
+  }
+  insertStoreHeldGithubTokenRow(userId, { ...fields, storeRef: name });
+  rememberGithubToken(userId, token);
+}
+
+/** Delete the row only (no store call) — the start-time reconcile's "gone
+ *  elsewhere" move on the sign-in box. */
+export function deleteGithubTokenRowLocal(userId: string): void {
+  forgetGithubToken(userId);
+  getDb()
+    .delete(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .run();
+  notifyGithubChange();
+}
+
+// --- container injection ----------------------------------------------------
+
+/** Injectable docker-exec seam (mocked in tests). Async so the docker call
+ *  doesn't block the host event loop (runs on every channel ensure + refresh). */
+export type DockerExec = (
+  args: string[],
+  input: string,
+) => Promise<{ status: number | null; stderr: string }>;
+
+const defaultExec: DockerExec = async (args, input) => {
+  const res = await taskContainerCli(args, {
+    input,
+    timeoutMs: EXEC_TIMEOUT_MS,
+  });
+  return { status: res.status, stderr: res.stderr };
+};
+
+/**
+ * Write the access token into the container's gh config and make gh Git's
+ * HTTPS credential helper. Also removes the legacy global HTTPS→SSH rewrite so
+ * reconnecting heals already-running containers without recreation.
+ */
+export async function injectIntoContainer(
+  taskId: string,
+  accessToken: string,
+  exec: DockerExec = defaultExec,
+  admitContainerWork: () => void = requireContainerRuntimeOperational,
+  environment?: Pick<TaskEnvironmentHandle, "exec">,
+): Promise<void> {
+  const container = taskAppContainerName(taskId);
+  // Provider-neutral path: same in-container `/usr/bin/env -i` command, same
+  // sanitized-plus-authority environment, argv/stdin separation preserved.
+  const run: (
+    command: string[],
+    input: string,
+  ) => Promise<{ status: number | null; stderr: string }> = environment
+    ? async (command, input) => {
+        const [first, ...rest] = [...CLEAN_CONTAINER_ENV, ...command];
+        const result = await environment.exec({
+          projectEnvProfile: "maintenance",
+          argv: [first!, ...rest],
+          user: "node",
+          env: { ...SANITIZED_CONTAINER_ENV, ...RUNTIME_AUTHORITY_ENV },
+          ...(input ? { stdin: Buffer.from(input) } : {}),
+          timeoutMs: EXEC_TIMEOUT_MS,
+          maxOutputBytes: 256 * 1024,
+        });
+        return {
+          status: result.exitCode,
+          stderr: Buffer.from(result.stderr).toString("utf8"),
+        };
+      }
+    : (command, input) =>
+        exec(
+          managedContainerExecArgs(container, command, input.length > 0),
+          input,
+        );
+  admitContainerWork();
+  const res = await run(
+    [
+      "/usr/bin/gh",
+      "auth",
+      "login",
+      "--with-token",
+      "--hostname",
+      "github.com",
+      "--git-protocol",
+      "https",
+    ],
+    `${accessToken}\n`,
+  );
+  admitContainerWork();
+  if (res.status !== 0) {
+    throw new Error(`gh auth login failed in ${container}: ${res.stderr.trim()}`);
+  }
+
+  admitContainerWork();
+  const setup = await run(
+    ["/usr/bin/gh", "auth", "setup-git", "--hostname", "github.com"],
+    "",
+  );
+  admitContainerWork();
+  if (setup.status !== 0) {
+    throw new Error(
+      `gh git credential setup failed in ${container}: ${setup.stderr.trim()}`,
+    );
+  }
+
+  admitContainerWork();
+  const transport = await run(
+    [
+      "/bin/sh",
+      "-c",
+      "/usr/bin/git config --global --unset-all 'url.git@github.com:.insteadOf' >/dev/null 2>&1 || true; " +
+        "/usr/bin/git config --global --unset-all core.sshCommand >/dev/null 2>&1 || true; " +
+        "/usr/bin/git config --global --replace-all 'url.https://github.com/.insteadOf' 'git@github.com:'; " +
+        "/usr/bin/git config --global --add 'url.https://github.com/.insteadOf' 'ssh://git@github.com/'",
+    ],
+    "",
+  );
+  admitContainerWork();
+  if (transport.status !== 0) {
+    throw new Error(
+      `Git HTTPS transport setup failed in ${container}: ${transport.stderr.trim()}`,
+    );
+  }
+}
+
+// --- refresh schedule -------------------------------------------------------
+
+const timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+type AuthExpiredHandler = (taskId: string, userId: string, reason: string) => void;
+let authExpiredHandler: AuthExpiredHandler | null = null;
+
+/** Phase D wires this to the task-chat "auth expired" system message. */
+export function setAuthExpiredHandler(fn: AuthExpiredHandler | null): void {
+  authExpiredHandler = fn;
+}
+
+export function scheduleRefresh(
+  taskId: string,
+  userId: string,
+  expiresAt: number,
+  generation = githubAuthGeneration(userId),
+): void {
+  clearRefresh(taskId);
+  const delay = Math.max(0, expiresAt - Date.now() - REFRESH_LEAD_MS);
+  const timer = setTimeout(() => {
+    timers.delete(taskId);
+    if (githubAuthGeneration(userId) !== generation) return;
+    if (!backgroundContainerWorkAllowed()) {
+      scheduleGithubRetry(taskId, userId, 0, {}, generation);
+      return;
+    }
+    void enqueueTaskGitAuth(taskId, userId, {}, {
+      generation,
+      getGeneration: () => githubAuthGeneration(userId),
+      attempt: 0,
+    }).catch((err) => {
+      if (githubAuthGeneration(userId) !== generation) return;
+      console.warn(
+        `[github] task ${taskId}: refresh reconciliation failed: ${
+          err instanceof Error ? err.message : err
+        }`,
+      );
+      scheduleGithubRetry(taskId, userId, 0, {}, generation);
+    });
+  }, delay);
+  timer.unref?.();
+  timers.set(taskId, timer);
+}
+
+/**
+ * True when the exchange error names a GitHub-side revocation — the refresh
+ * token itself is dead, so retrying is pointless and the user must re-grant.
+ * Deliberately keyed on GitHub's OAuth error strings (passed through the
+ * cloud's 502 body by requestAccessToken), NOT on bare HTTP status: the cloud
+ * returns 401 only for a host-token mismatch and wraps all GitHub failures as
+ * 502, so a status like "401"/"403" alone never means "revoked" — the old
+ * \b40[13]\b match here deleted VALID refresh tokens on host-auth/proxy noise.
+ */
+function isRevokedTokenError(reason: string): boolean {
+  return /revoked|invalid_grant|bad_refresh/i.test(reason);
+}
+
+/**
+ * True when the failure names a genuinely bad credential — GitHub answered the
+ * validation with 401/403 ("Bad credentials"), so the token really is wrong and
+ * only a reconnect fixes it. Distinct from a 5xx blip (see below).
+ */
+function isBadCredentialError(reason: string): boolean {
+  return /validating token: HTTP 40[13]\b|Bad credentials|401 Unauthorized|403 Forbidden/i.test(
+    reason,
+  );
+}
+
+/**
+ * True when the failure is a GitHub-side / network blip that a retry will heal
+ * — the API returned 5xx (as happens when `gh auth login` validates the token
+ * against api.github.com during an outage), a rate-limit, or the fetch itself
+ * failed. Such a failure must NOT be surfaced as "authentication expired —
+ * reconnect": the token is fine, GitHub is briefly unavailable. A genuine bad
+ * credential (401/403) is explicitly excluded so it still routes to reconnect.
+ */
+export function isTransientGithubError(reason: string): boolean {
+  if (isBadCredentialError(reason)) return false;
+  // A blank reason proves nothing about the credential. Seen live 2026-08-25:
+  // `gh auth login` raced its own task's teardown (the container died under
+  // the exec), exited nonzero with EMPTY stderr, and the fall-through verdict
+  // told the user their auth expired and to reconnect — it hadn't. Unknown
+  // must route to the retrying/soft path, never to a reconnect demand.
+  if (reason.trim() === "") return true;
+  return (
+    /HTTP 5\d\d|Service Unavailable|Bad Gateway|Gateway Time-?out|server error|rate limit|too many requests|secondary rate|unavailable|unreachable/i.test(
+      reason,
+    ) ||
+    /\bfetch failed\b|timeout|timed out|ETIMEDOUT|ECONNRESET|ECONNREFUSED|ECONNABORTED|ENOTFOUND|EAI_AGAIN|socket hang up|\bnetwork\b/i.test(
+      reason,
+    )
+  );
+}
+
+export function clearRefresh(taskId: string): void {
+  clearGithubRetry(taskId);
+  const t = timers.get(taskId);
+  if (t) {
+    clearTimeout(t);
+    timers.delete(taskId);
+  }
+}
+
+// --- self-heal: retry a failed gh setup with bounded backoff ----------------
+// A gh setup/refresh can fail transiently — e.g. the cloud token-exchange fetch
+// times out while the host is briefly unreachable (as happened when the bridge
+// was flapping). Without a retry the task is stranded on a stale/invalid token
+// until someone runs /retry-gh, because ensureSessions won't re-inject once a
+// channel's sessions are started. Retry with bounded backoff; cleared on
+// success (clearGithubRetry) and on task teardown (via clearRefresh).
+const RETRY_BACKOFF_MS = [5_000, 20_000, 60_000, 180_000, 300_000];
+const retryTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+function clearGithubRetry(taskId: string): void {
+  const t = retryTimers.get(taskId);
+  if (t) {
+    clearTimeout(t);
+    retryTimers.delete(taskId);
+  }
+}
+
+/** Is the task still live on this host? Retries for ended tasks would docker
+ *  exec against a removed container and post notes into a finished chat. */
+function taskIsActive(taskId: string): boolean {
+  const row = getDb()
+    .select({ endedAt: schema.hostTasks.endedAt })
+    .from(schema.hostTasks)
+    .where(eq(schema.hostTasks.taskId, taskId))
+    .get();
+  return row != null && row.endedAt == null;
+}
+
+function scheduleGithubRetry(
+  taskId: string,
+  userId: string,
+  attempt: number,
+  deps: SetupTaskDeps = {},
+  generation = githubAuthGeneration(userId),
+): void {
+  clearGithubRetry(taskId);
+  if (attempt >= RETRY_BACKOFF_MS.length) {
+    // attempt counts retries fired so far; +1 for the initial try.
+    console.warn(
+      `[github] task ${taskId}: gh setup still failing after ${attempt + 1} attempts — giving up until /retry-gh`,
+    );
+    authExpiredHandler?.(
+      taskId,
+      userId,
+      "gh setup kept failing — send /retry-gh once the connection recovers",
+    );
+    return;
+  }
+  const delay = RETRY_BACKOFF_MS[attempt] ?? 300_000;
+  const timer = setTimeout(() => {
+    retryTimers.delete(taskId);
+    if (githubAuthGeneration(userId) !== generation) return;
+    const isActive = deps.taskIsActive ?? taskIsActive;
+    if (!isActive(taskId)) return; // task ended while we backed off
+    if (!backgroundContainerWorkAllowed()) {
+      // Runtime downtime is not a failed GitHub attempt. Preserve the same
+      // retry budget and wait for another backoff window instead of spawning
+      // Docker while the host is deliberately fail-closed.
+      scheduleGithubRetry(taskId, userId, attempt, deps, generation);
+      return;
+    }
+    void enqueueTaskGitAuth(taskId, userId, {}, {
+      generation,
+      getGeneration: () => githubAuthGeneration(userId),
+      setupDeps: deps,
+      attempt: attempt + 1,
+    }).catch((err) => {
+      if (githubAuthGeneration(userId) !== generation) return;
+      console.warn(
+        `[github] task ${taskId}: retry reconciliation failed: ${
+          err instanceof Error ? err.message : err
+        }`,
+      );
+      scheduleGithubRetry(taskId, userId, attempt + 1, deps, generation);
+    });
+  }, delay);
+  timer.unref?.();
+  retryTimers.set(taskId, timer);
+}
+
+/** Test/diagnostic: is a gh-setup retry currently armed for this task? */
+export function hasPendingGithubRetry(taskId: string): boolean {
+  return retryTimers.has(taskId);
+}
+
+/**
+ * Injectable seams for {@link setupTaskGithub} (mocked in tests so the decision
+ * logic needs neither the host DB nor docker). All default to the real impls.
+ */
+export interface SetupTaskDeps {
+  hasToken?: (userId: string) => boolean;
+  requestAccessToken?: (
+    userId: string,
+  ) => Promise<{ accessToken: string; expiresAt: number | null } | null>;
+  inject?: (taskId: string, token: string) => void | Promise<void>;
+  schedule?: (taskId: string, userId: string, expiresAt: number) => void;
+  deleteToken?: (userId: string) => void;
+  taskIsActive?: (taskId: string) => boolean;
+  scrub?: (taskId: string) => Promise<boolean | void>;
+  /** Late-bound provider handle for the default injection path. Absent (or
+   * null at call time) keeps the legacy Docker fallback. */
+  environment?: () => Pick<TaskEnvironmentHandle, "exec"> | null;
+}
+
+/**
+ * Set up GitHub auth for a task at task-up (ADR-027). Connected user → mint +
+ * inject an access token + schedule refresh. Else UAI_GH_PAT_FALLBACK → inject
+ * the PAT (no refresh; attributes to the PAT owner). Else skip. Best-effort:
+ * a failure emits the auth-expired note but never aborts task-up. Returns true
+ * iff a token was injected.
+ */
+interface SetupExecutionGuard {
+  generation: number;
+  isCurrent: () => boolean;
+  admitContainerWork: () => void;
+}
+
+export async function setupTaskGithub(
+  taskId: string,
+  userId: string,
+  deps: SetupTaskDeps = {},
+  attempt = 0,
+  guard?: SetupExecutionGuard,
+): Promise<boolean> {
+  const capturedGeneration =
+    guard?.generation ?? githubAuthGeneration(userId);
+  const isCurrent =
+    guard?.isCurrent ??
+    (() => githubAuthGeneration(userId) === capturedGeneration);
+  const _hasToken = deps.hasToken ?? hasToken;
+  const _request = deps.requestAccessToken ?? requestAccessToken;
+  const _inject =
+    deps.inject ??
+    ((t: string, tok: string) =>
+      injectIntoContainer(
+        t,
+        tok,
+        defaultExec,
+        guard?.admitContainerWork ?? requireContainerRuntimeOperational,
+        deps.environment?.() ?? undefined,
+      ));
+  if (!isCurrent()) return false;
+  try {
+    if (_hasToken(userId)) {
+      const tok = await _request(userId);
+      if (tok && isCurrent()) {
+        guard?.admitContainerWork();
+        await _inject(taskId, tok.accessToken);
+        guard?.admitContainerWork();
+        // The mutation itself cannot be interrupted, but a newer transition is
+        // already queued behind us. Do not let this stale run arm more work.
+        if (!isCurrent()) return false;
+        // Non-expiring (ADR-033) tokens (expiresAt null) need no refresh timer.
+        if (tok.expiresAt !== null) {
+          if (deps.schedule) {
+            deps.schedule(taskId, userId, tok.expiresAt);
+          } else {
+            scheduleRefresh(
+              taskId,
+              userId,
+              tok.expiresAt,
+              capturedGeneration,
+            );
+          }
+        }
+        clearGithubRetry(taskId);
+        console.log(`[github] task ${taskId}: injected user access token`);
+        return true;
+      }
+    }
+    if (!isCurrent()) return false;
+    const pat = process.env.UAI_GH_PAT_FALLBACK;
+    if (pat) {
+      // The PAT is ONE host-wide credential, and injectIntoContainer wires it
+      // into `gh` AND all git transport. Injecting it for whoever happens to
+      // own the task therefore authenticates that user's container as the
+      // PAT's owner, handing every unconnected user the owner's full
+      // read/write repository access. That was invisible while a host had one
+      // user and became a silent cross-user credential leak the moment it had
+      // two. Bind the PAT to the single user it belongs to and fail closed
+      // otherwise: a host that upgrades into multi-user must not start
+      // leaking because nobody remembered to unset an env var.
+      const patOwner = process.env.UAI_GH_PAT_FALLBACK_USER_ID;
+      if (!patOwner) {
+        console.warn(
+          `[github] task ${taskId}: UAI_GH_PAT_FALLBACK is set but ` +
+            "UAI_GH_PAT_FALLBACK_USER_ID is not — refusing to inject a " +
+            "host-wide PAT into a task. Set the owner's user id to keep the " +
+            "single-user fallback, or remove the PAT and connect GitHub per " +
+            "user.",
+        );
+      } else if (patOwner !== userId) {
+        console.warn(
+          `[github] task ${taskId}: PAT fallback is owned by ${patOwner}, ` +
+            `not task owner ${userId} — skipping.`,
+        );
+      } else {
+        guard?.admitContainerWork();
+        await _inject(taskId, pat);
+        guard?.admitContainerWork();
+        clearGithubRetry(taskId);
+        console.log(`[github] task ${taskId}: using PAT fallback (no refresh)`);
+        return true;
+      }
+    }
+    console.log(`[github] task ${taskId}: gh not configured for user ${userId}`);
+    return false;
+  } catch (err) {
+    // A newer connect/disconnect owns the final state and is queued behind this
+    // operation. The superseded run must neither delete its grant nor retry.
+    if (!isCurrent()) return false;
+    // Runtime unavailability is not an ordinary "GitHub not configured" or
+    // retryable credential verdict. Reconciliation callers must reject so a
+    // destructive set/clear transition cannot be acknowledged as complete.
+    if (err instanceof ContainerRuntimeUnavailableError) throw err;
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[github] task ${taskId}: gh setup failed: ${reason}`);
+    // A task already torn down must not receive notes: its thread is
+    // read-only, and a gh failure RACING that teardown (exec into a dying
+    // container, live 2026-08-25) says nothing a reader can act on.
+    const taskStillActive = (deps.taskIsActive ?? taskIsActive)(taskId);
+    // A revoked refresh token can't recover by retrying — drop it so the user
+    // gets a clean re-grant, and tell the chat once.
+    if (isRevokedTokenError(reason)) {
+      (deps.deleteToken ?? deleteToken)(userId);
+      if (taskStillActive) authExpiredHandler?.(taskId, userId, reason);
+      return false;
+    }
+    // A retry chain already armed for this task means a sibling entry point
+    // (task-up and channel-ensure both call setup) already reported this and
+    // owns recovery — don't post a duplicate note or start a competing chain.
+    // `/retry-gh` clears the chain first, so a manual retry is never swallowed.
+    if (attempt === 0 && retryTimers.has(taskId)) return false;
+    // Transient: self-heal with bounded backoff. Post the chat note only on
+    // the FIRST failure of a chain — each retry re-enters this catch, and six
+    // "gh auth" notes for one outage is noise. Exhaustion posts its own note
+    // (in scheduleGithubRetry). The handler classifies the reason (transient
+    // 5xx blip vs. genuine expiry) and words the note accordingly.
+    if (attempt === 0 && taskStillActive) {
+      authExpiredHandler?.(taskId, userId, reason);
+    }
+    scheduleGithubRetry(
+      taskId,
+      userId,
+      attempt,
+      deps,
+      capturedGeneration,
+    );
+    return false;
+  }
+}
+
+// One task-local queue owns transport transitions. Connect/disconnect frames,
+// channel recovery, and /retry-gh can otherwise overlap: a slow old-token
+// injection must never win after a newer disconnect (or vice versa).
+const gitAuthReconcileQueues = new Map<string, Promise<boolean>>();
+
+const REMOVE_MANAGED_GITHUB_AUTH = [
+  "set -eu",
+  "/usr/bin/rm -f -- \"$GH_CONFIG_DIR/hosts.yml\"",
+  "test ! -e \"$GH_CONFIG_DIR/hosts.yml\"",
+  "/usr/bin/git config --global --unset-all 'credential.https://github.com.helper' >/dev/null 2>&1 || true",
+  "/usr/bin/git config --global --unset-all 'credential.https://gist.github.com.helper' >/dev/null 2>&1 || true",
+  "/usr/bin/git config --global --unset-all 'url.git@github.com:.insteadOf' >/dev/null 2>&1 || true",
+  "/usr/bin/git config --global --unset-all core.sshCommand >/dev/null 2>&1 || true",
+  "/usr/bin/git config --global --replace-all 'url.https://github.com/.insteadOf' 'git@github.com:'",
+  "/usr/bin/git config --global --add 'url.https://github.com/.insteadOf' 'ssh://git@github.com/'",
+  "test -z \"$(/usr/bin/git config --global --get-all 'credential.https://github.com.helper' 2>/dev/null || true)\"",
+  "test -z \"$(/usr/bin/git config --global --get-all 'credential.https://gist.github.com.helper' 2>/dev/null || true)\"",
+].join("; ");
+
+type DockerCommand = typeof dockerCli;
+
+async function checkedDockerCommand(
+  run: DockerCommand,
+  args: string[],
+  label: string,
+  timeoutMs = EXEC_TIMEOUT_MS,
+  admitContainerWork: () => void = requireContainerRuntimeOperational,
+): Promise<Awaited<ReturnType<DockerCommand>>> {
+  admitContainerWork();
+  const result = await run(args, { timeoutMs });
+  admitContainerWork();
+  if (result.status !== 0) {
+    throw new Error(
+      `${label} failed: ${result.stderr.trim() || `exit ${result.status}`}`,
+    );
+  }
+  return result;
+}
+
+export async function removeGithubFromContainer(
+  taskId: string,
+  run: DockerCommand = taskContainerCli,
+  admitContainerWork: () => void = requireContainerRuntimeOperational,
+): Promise<boolean> {
+  // ADR-133: a task machine has no container runtime and no app container —
+  // the credential lives in the machine's own gh config, installed over the
+  // environment at task-up (`machineTaskGithubAuth`). Inspecting Docker here
+  // threw `spawn docker ENOENT` on every session start, so no agent ever
+  // came up on the first live hostless run (2026-09-10, smoke 6). Same answer
+  // a Docker host gives for a machine task: no container, nothing to scrub.
+  if (sidecarMode()) return false;
+  const container = taskAppContainerName(taskId);
+  admitContainerWork();
+  const observed = await taskAppContainerState(container, run as never);
+  admitContainerWork();
+  if (observed.kind === "unknown") {
+    throw new Error(`inspect ${container} failed: ${observed.detail}`);
+  }
+  if (observed.kind === "absent") {
+    return false; // no container means no credential to retain
+  }
+
+  if (observed.kind !== "running") {
+    // Never start or unpause untrusted task code while its old credential is
+    // still on disk. The app container is disposable; workspace/repository
+    // state lives outside it and provisioning recreates it on Resume.
+    admitContainerWork();
+    await removeTaskAppContainer(container, run as never);
+    admitContainerWork();
+    return false;
+  }
+
+  await checkedDockerCommand(
+    run,
+    managedContainerExecArgs(container, [
+      "/bin/sh",
+      "-c",
+      REMOVE_MANAGED_GITHUB_AUTH,
+    ]),
+    `remove managed GitHub auth from ${container}`,
+    EXEC_TIMEOUT_MS,
+    admitContainerWork,
+  );
+  return true;
+}
+
+export interface ReconcileTaskGitAuthDeps {
+  hasToken?: (userId: string) => boolean;
+  setupGithub?: (taskId: string, userId: string) => Promise<boolean>;
+  setupDeps?: SetupTaskDeps;
+  authGeneration?: (userId: string) => number;
+  logoutContainer?: (taskId: string) => Promise<boolean | void>;
+  ensureSsh?: (taskId: string, userId: string) => Promise<boolean>;
+  selectSsh?: (taskId: string) => Promise<boolean>;
+  /** Last-hop Docker admission. Recovery supplies an epoch-scoped predicate
+   * while the public runtime deliberately remains `checking`. */
+  admitContainerWork?: () => void;
+}
+
+interface ReconcileInvocation {
+  generation: number;
+  getGeneration: () => number;
+  setupDeps?: SetupTaskDeps;
+  attempt: number;
+}
+
+/**
+ * Re-read the current host credential state and select exactly one Git
+ * transport for a live task: connected user token over HTTPS, otherwise the
+ * task owner's SSH identity. Serialized per task for reconnect safety.
+ */
+export function reconcileTaskGitAuth(
+  taskId: string,
+  userId: string,
+  deps: ReconcileTaskGitAuthDeps = {},
+): Promise<boolean> {
+  const getGeneration = () =>
+    (deps.authGeneration ?? githubAuthGeneration)(userId);
+  return enqueueTaskGitAuth(taskId, userId, deps, {
+    generation: getGeneration(),
+    getGeneration,
+    setupDeps: deps.setupDeps,
+    attempt: 0,
+  });
+}
+
+/**
+ * ADR-154: the runner's own GitHub sign-in (or its SSH key) reaches a task
+ * only while the runner is on its own credentials. Leaving them waits for a
+ * reconciliation already under way, and each of its steps, the last write
+ * included, is fenced on them: none starts once leaving has begun.
+ */
+function enqueueTaskGitAuth(
+  taskId: string,
+  userId: string,
+  deps: ReconcileTaskGitAuthDeps,
+  invocation: ReconcileInvocation,
+): Promise<boolean> {
+  return (
+    whileOnOwnCredentials(() => enqueueOwnTaskGitAuth(taskId, userId, deps, invocation)) ??
+    Promise.resolve(false)
+  );
+}
+
+function enqueueOwnTaskGitAuth(
+  taskId: string,
+  userId: string,
+  deps: ReconcileTaskGitAuthDeps,
+  invocation: ReconcileInvocation,
+): Promise<boolean> {
+  const previous = gitAuthReconcileQueues.get(taskId) ?? Promise.resolve(false);
+  let queued: Promise<boolean>;
+  queued = previous
+    .catch(() => false)
+    .then(async () => {
+      const isCurrent = () =>
+        invocation.getGeneration() === invocation.generation && onOwnCredentials();
+      const admitContainerWork =
+        deps.admitContainerWork ?? requireContainerRuntimeOperational;
+      if (!isCurrent()) return false;
+      admitContainerWork();
+
+      const connected =
+        deps.hasToken ?? invocation.setupDeps?.hasToken ?? hasToken;
+      const shouldConnect = connected(userId);
+      if (!shouldConnect) clearRefresh(taskId);
+
+      // Authoritative replacement, not gh's multi-account add/switch behavior:
+      // remove every managed account/helper first, in the same per-task queue,
+      // then install only the current user's credential. Non-running containers
+      // are removed rather than executed with the old credential on disk.
+      const logoutContainer =
+        deps.logoutContainer ??
+        invocation.setupDeps?.scrub ??
+        ((id: string) =>
+          removeGithubFromContainer(id, taskContainerCli, admitContainerWork));
+      const canConfigureLiveTransport = await logoutContainer(taskId);
+      if (!isCurrent()) return false;
+      admitContainerWork();
+      if (canConfigureLiveTransport === false) {
+        // No credential-bearing container remains. A connected credential will
+        // be installed when Compose recreates it; disconnected state is already
+        // fully scrubbed.
+        return shouldConnect;
+      }
+
+      if (shouldConnect) {
+        if (deps.setupGithub) {
+          admitContainerWork();
+          const result = await deps.setupGithub(taskId, userId);
+          if (!isCurrent()) return false;
+          admitContainerWork();
+          return result;
+        }
+        admitContainerWork();
+        const result = await setupTaskGithub(
+          taskId,
+          userId,
+          invocation.setupDeps,
+          invocation.attempt,
+          {
+            generation: invocation.generation,
+            isCurrent,
+            admitContainerWork,
+          },
+        );
+        if (!isCurrent()) return false;
+        admitContainerWork();
+        return result;
+      }
+
+      // SSH remains an opt-in fallback for users who did not connect GitHub;
+      // ensuring the identity also keeps commit/tag signing available. Never
+      // select SSH transport unless a usable identity was actually asserted.
+      admitContainerWork();
+      const hasSshIdentity = deps.ensureSsh
+        ? await deps.ensureSsh(taskId, userId)
+        : await ensureTaskSshIdentity(taskId, userId, undefined, {
+            // Machine/sidecar tasks install the key over the environment.
+            environment: () => invocation.setupDeps?.environment?.() ?? null,
+          });
+      if (!isCurrent()) return false;
+      admitContainerWork();
+      if (hasSshIdentity) {
+        admitContainerWork();
+        const selected = await (
+          deps.selectSsh ?? configureTaskSshTransport
+        )(taskId);
+        if (!isCurrent()) return false;
+        admitContainerWork();
+        if (!selected) {
+          throw new Error(
+            `task ${taskId}: SSH fallback transport could not be configured`,
+          );
+        }
+      } else {
+        console.log(
+          `[github] task ${taskId}: managed GitHub credential removed; using credential-free HTTPS`,
+        );
+      }
+      return false;
+    })
+    .finally(() => {
+      if (gitAuthReconcileQueues.get(taskId) === queued) {
+        gitAuthReconcileQueues.delete(taskId);
+      }
+    });
+  gitAuthReconcileQueues.set(taskId, queued);
+  return queued;
+}
+
+/** Test/maintenance hook: drop all scheduled refresh + retry timers. */
+export function clearAllRefreshTimers(): void {
+  for (const t of timers.values()) clearTimeout(t);
+  timers.clear();
+  for (const t of retryTimers.values()) clearTimeout(t);
+  retryTimers.clear();
+}