@runuai/host 0.2.4 → 0.2.8

package/db/migrations/0007_host_github_token_kind.sql

@@ -0,0 +1,7 @@
+-- ADR-033: non-expiring per-host tokens. `kind` distinguishes the stored token:
+--   'refresh' (legacy, ADR-027) → refresh_token_ct holds a refresh token; the
+--             host exchanges it for short-lived access tokens.
+--   'access'  (ADR-033)         → refresh_token_ct holds a long-lived, non-
+--             expiring access token; injected directly, no exchange/refresh.
+-- Existing rows default to 'refresh' (their current semantics).
+ALTER TABLE `host_github_tokens` ADD `kind` text DEFAULT 'refresh' NOT NULL;

package/db/migrations/meta/_journal.json

@@ -50,6 +50,13 @@
       "when": 1779900007000,
       "tag": "0006_host_project_env",
       "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1779900008000,
+      "tag": "0007_host_github_token_kind",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -62,9 +62,13 @@ export type NewHostEventRow = typeof hostEvents.$inferInsert;
 export const githubTokens = sqliteTable("host_github_tokens", {
   userId: text("user_id").primaryKey(),
   installationId: integer("installation_id").notNull(),
+  // ADR-033: holds a long-lived ACCESS token when kind="access", or a refresh
+  // token when kind="refresh" (legacy ADR-027). Encrypted at rest either way.
   refreshTokenCt: blob("refresh_token_ct").notNull(),
   refreshTokenNonce: blob("refresh_token_nonce").notNull(),
   refreshTokenExpiresAt: integer("refresh_token_expires_at"),
+  // "access" (non-expiring, ADR-033) | "refresh" (expiring, ADR-027).
+  kind: text("kind").notNull().default("refresh"),
   updatedAt: integer("updated_at").notNull(),
 });
 

package/lib/docker-exec.ts

@@ -59,6 +59,13 @@ export function dockerCli(
     child.on("close", (code) => {
       finish(code);
     });
+    // EPIPE guard: if the child exits without draining stdin (or our own
+    // timeout SIGKILLs it mid-write), the failed write surfaces as an 'error'
+    // event on the stdin stream — unhandled, that's an uncaughtException that
+    // would take down the whole host service. Today's inputs are tiny (a gh
+    // token) and complete synchronously, but this keeps the helper safe for
+    // any future caller piping real data.
+    child.stdin?.on("error", () => {});
     if (opts.input !== undefined) child.stdin?.write(opts.input);
     child.stdin?.end();
   });

package/lib/github-tokens.ts

@@ -16,58 +16,111 @@ import type { CloudToHost } from "../src/protocol";
 
 const REFRESH_LEAD_MS = 5 * 60 * 1000; // refresh 5 min before expiry
 const EXEC_TIMEOUT_MS = 10_000;
-const EXCHANGE_TIMEOUT_MS = 15_000; // cap the cloud token-exchange round-trip
+// 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;
 
 type GhConnectSet = Extract<CloudToHost, { kind: "gh.connect.set" }>;
 
 // --- token store ------------------------------------------------------------
 
-/** Encrypt + persist the user's refresh token (gh.connect.set handler). */
+/**
+ * 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 function onConnectSet(frame: GhConnectSet): { ok: boolean; error?: string } {
   try {
-    const sealed = sealAesGcm(frame.refreshToken);
+    // Fresh grant — a cached access token from the previous grant may be
+    // revoked; drop it so the next mint exchanges against the new token.
+    clearAccessCache(frame.userId);
+    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 sealed = sealAesGcm(token);
     const now = Date.now();
+    const fields = {
+      installationId: frame.installationId,
+      refreshTokenCt: sealed.ct,
+      refreshTokenNonce: sealed.nonce,
+      refreshTokenExpiresAt: frame.refreshTokenExpiresAt ?? null,
+      kind,
+      updatedAt: now,
+    };
     getDb()
       .insert(schema.githubTokens)
-      .values({
-        userId: frame.userId,
-        installationId: frame.installationId,
-        refreshTokenCt: sealed.ct,
-        refreshTokenNonce: sealed.nonce,
-        refreshTokenExpiresAt: frame.refreshTokenExpiresAt ?? null,
-        updatedAt: now,
-      })
-      .onConflictDoUpdate({
-        target: schema.githubTokens.userId,
-        set: {
-          installationId: frame.installationId,
-          refreshTokenCt: sealed.ct,
-          refreshTokenNonce: sealed.nonce,
-          refreshTokenExpiresAt: frame.refreshTokenExpiresAt ?? null,
-          updatedAt: now,
-        },
-      })
+      .values({ userId: frame.userId, ...fields })
+      .onConflictDoUpdate({ target: schema.githubTokens.userId, set: fields })
       .run();
+    notifyGithubChange();
     return { ok: true };
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : "store failed" };
   }
 }
 
-/** Delete a user's refresh token + clear their active-task refresh timers. */
-export function onConnectClear(userId: string): void {
-  deleteToken(userId);
-  for (const taskId of activeTaskIdsForUser(userId)) {
-    clearRefresh(taskId);
-    authExpiredHandler?.(taskId, userId, "GitHub disconnected");
+/**
+ * Disconnect GitHub on this host (gh.connect.clear handler). Deletes the token
+ * locally FIRST (so capabilities re-advertise immediately and the UI reflects
+ * removal without waiting on the network), then best-effort revokes it at
+ * GitHub. Whole body is guarded — a fired-and-forgotten failure must never
+ * crash the host (no global unhandledRejection handler).
+ *
+ * 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 async function onConnectClear(userId: string): Promise<void> {
+  try {
+    const stored = readStoredToken(userId);
+    deleteToken(userId); // fires onGithubChange → re-advertise capabilities
+    for (const taskId of activeTaskIdsForUser(userId)) {
+      clearRefresh(taskId);
+      authExpiredHandler?.(taskId, userId, "GitHub disconnected");
+    }
+    if (stored && stored.kind === "access") {
+      await revokeAtGitHub(stored.token);
+    } else if (stored) {
+      console.warn(
+        `[github] user ${userId}: legacy refresh token cleared locally; cannot single-token revoke at GitHub`,
+      );
+    }
+  } catch (err) {
+    console.warn(
+      `[github] disconnect failed: ${err instanceof Error ? err.message : err}`,
+    );
   }
 }
 
+/** Decrypt the user's stored token + its kind, or null if none. */
+function readStoredToken(
+  userId: string,
+): { token: string; kind: string } | null {
+  const row = getDb()
+    .select()
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  if (!row) return null;
+  const token = openAesGcm(
+    Buffer.from(row.refreshTokenCt as Uint8Array),
+    Buffer.from(row.refreshTokenNonce as Uint8Array),
+  );
+  return { token, kind: row.kind };
+}
+
 export function deleteToken(userId: string): void {
+  clearAccessCache(userId);
   getDb()
     .delete(schema.githubTokens)
     .where(eq(schema.githubTokens.userId, userId))
     .run();
+  notifyGithubChange();
 }
 
 export function hasToken(userId: string): boolean {
@@ -80,6 +133,29 @@ export function hasToken(userId: string): boolean {
   );
 }
 
+/** 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)
+    .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 */
+  }
+}
+
 function activeTaskIdsForUser(userId: string): string[] {
   return getDb()
     .select({ taskId: schema.hostTasks.taskId })
@@ -96,12 +172,43 @@ function activeTaskIdsForUser(userId: string): string[] {
 
 // --- access-token exchange --------------------------------------------------
 
-function exchangeUrl(): string {
+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}/api/github/oauth/exchange`;
+  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 {
@@ -115,8 +222,84 @@ interface ExchangeResult {
  * 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.
  */
-export async function requestAccessToken(
+const inflightExchanges = new Map<
+  string,
+  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 }
+>();
+
+/** Drop a user's cached access token (token deleted / re-granted). */
+function clearAccessCache(userId: string): void {
+  accessCache.delete(userId);
+}
+
+/** Test hook: reset the access-token cache. */
+export function clearAllAccessCache(): void {
+  accessCache.clear();
+}
+
+export function requestAccessToken(
+  userId: string,
+): Promise<{ accessToken: string; expiresAt: number | null } | null> {
+  // 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 = getDb()
+    .select({ kind: schema.githubTokens.kind })
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  if (!row) return Promise.resolve(null);
+  if (row.kind === "access") {
+    const stored = readStoredToken(userId);
+    return Promise.resolve(
+      stored ? { accessToken: stored.token, expiresAt: null } : 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) return existing;
+  const run = doRequestAccessToken(userId)
+    .then((tok) => {
+      if (tok) accessCache.set(userId, tok);
+      return tok;
+    })
+    .finally(() => {
+      inflightExchanges.delete(userId);
+    });
+  inflightExchanges.set(userId, run);
+  return run;
+}
+
+async function doRequestAccessToken(
   userId: string,
 ): Promise<{ accessToken: string; expiresAt: number } | null> {
   const row = getDb()
@@ -140,7 +323,19 @@ export async function requestAccessToken(
     signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
   });
   if (!res.ok) {
-    throw new Error(`gh token exchange failed: HTTP ${res.status}`);
+    // 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;
   if (data.refreshToken) {
@@ -226,6 +421,19 @@ export function scheduleRefresh(
   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);
+}
+
 async function runRefresh(taskId: string, userId: string): Promise<void> {
   try {
     const tok = await requestAccessToken(userId);
@@ -234,13 +442,14 @@ async function runRefresh(taskId: string, userId: string): Promise<void> {
       return;
     }
     await injectIntoContainer(taskId, tok.accessToken);
-    scheduleRefresh(taskId, userId, tok.expiresAt);
+    // Only re-schedule for an expiring token; non-expiring needs no refresh.
+    if (tok.expiresAt !== null) scheduleRefresh(taskId, userId, tok.expiresAt);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     // A revoked / expired refresh token can't recover — drop it to force a
     // clean re-grant through the OAuth flow. Anything else is likely transient
     // (network / cloud blip) — self-heal with a bounded retry.
-    if (/\b40[13]\b|revoked|invalid_grant|bad_refresh/i.test(reason)) {
+    if (isRevokedTokenError(reason)) {
       deleteToken(userId);
     } else {
       scheduleGithubRetry(taskId, userId, 0);
@@ -276,22 +485,42 @@ function clearGithubRetry(taskId: string): void {
   }
 }
 
+/** 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 = {},
 ): 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} attempts — giving up until /retry-gh`,
+      `[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);
-    void setupTaskGithub(taskId, userId, {}, attempt + 1);
+    const isActive = deps.taskIsActive ?? taskIsActive;
+    if (!isActive(taskId)) return; // task ended while we backed off
+    void setupTaskGithub(taskId, userId, deps, attempt + 1);
   }, delay);
   timer.unref?.();
   retryTimers.set(taskId, timer);
@@ -310,9 +539,11 @@ export interface SetupTaskDeps {
   hasToken?: (userId: string) => boolean;
   requestAccessToken?: (
     userId: string,
-  ) => Promise<{ accessToken: string; expiresAt: number } | null>;
+  ) => 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;
 }
 
 /**
@@ -345,7 +576,8 @@ export async function setupTaskGithub(
       const tok = await _request(userId);
       if (tok) {
         await _inject(taskId, tok.accessToken);
-        _schedule(taskId, userId, tok.expiresAt);
+        // Non-expiring (ADR-033) tokens (expiresAt null) need no refresh timer.
+        if (tok.expiresAt !== null) _schedule(taskId, userId, tok.expiresAt);
         clearGithubRetry(taskId);
         console.log(`[github] task ${taskId}: injected user access token`);
         return true;
@@ -363,10 +595,19 @@ export async function setupTaskGithub(
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     console.warn(`[github] task ${taskId}: gh setup failed: ${reason}`);
-    authExpiredHandler?.(taskId, userId, reason);
-    // Self-heal: a transient exchange/inject failure shouldn't strand the task
-    // on a stale token until a manual /retry-gh. Retry with bounded backoff.
-    scheduleGithubRetry(taskId, userId, attempt);
+    // 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);
+      authExpiredHandler?.(taskId, userId, reason);
+      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).
+    if (attempt === 0) authExpiredHandler?.(taskId, userId, reason);
+    scheduleGithubRetry(taskId, userId, attempt, deps);
     return false;
   } finally {
     setupInFlight.delete(taskId);

package/lib/orchestrator.ts

@@ -56,8 +56,19 @@ interface Channel {
   /** Per-agent first-turn message — only agents whose `initialPrompt` is
    *  non-empty have an entry. Delivered once at container-ready. */
   firstTurns: Map<string, string>;
-  /** True once agent sessions have been spawned (lazily, on first send). */
-  sessionsStarted: boolean;
+  /** In-flight (or completed) session start. A memoized promise — not a
+   *  boolean flag — so a concurrent deliver() awaits actual readiness instead
+   *  of observing "started" while the sessions map is still empty (the start
+   *  awaits docker work before populating it). Reset to null on failure so the
+   *  next ensure retries. */
+  sessionsReady: Promise<boolean> | null;
+  /** Agents with turn output already streamed for the current turn — i.e. the
+   *  cloud has buffered content for them (see ChannelRouter.turnBuffer). */
+  openTurns: Set<string>;
+  /** Agents whose current turn was interrupted (ESC) — their next
+   *  turn_complete is flagged `aborted` so the cloud DISCARDS the buffered
+   *  half-turn instead of delivering it to @-mentioned peers. */
+  interrupted: Set<string>;
   /** Per-agent respawn counter — bounded so a broken agent can't
    *  loop forever rewriting its config. */
   respawns: Map<string, number>;
@@ -149,7 +160,9 @@ class Orchestrator {
       containerName: `task-${taskId.toLowerCase()}-app-1`,
       preambles,
       firstTurns,
-      sessionsStarted: false,
+      sessionsReady: null,
+      openTurns: new Set(),
+      interrupted: new Set(),
       respawns: new Map(),
     };
     this.channels.set(taskId, channel);
@@ -167,16 +180,31 @@ class Orchestrator {
    *
    * Returns whether sessions are ready.
    */
-  private async ensureSessions(channel: Channel): Promise<boolean> {
-    if (channel.sessionsStarted) return true;
+  private ensureSessions(channel: Channel): Promise<boolean> {
+    // Memoized: every caller awaits the SAME in-flight start, so a concurrent
+    // deliver() can't observe "ready" while the sessions map is still empty
+    // (startSessions awaits docker work before populating it — the old boolean
+    // flag flipped before that await and opened exactly that window).
+    if (!channel.sessionsReady) {
+      channel.sessionsReady = this.startSessions(channel);
+      // A failed/aborted start must not poison the channel — reset so the
+      // next ensure retries (e.g. the task wasn't `running` yet).
+      channel.sessionsReady.then(
+        (ok) => {
+          if (!ok) channel.sessionsReady = null;
+        },
+        () => {
+          channel.sessionsReady = null;
+        },
+      );
+    }
+    return channel.sessionsReady;
+  }
 
+  private async startSessions(channel: Channel): Promise<boolean> {
     const task = getHostTask(channel.taskId);
     if (!task || task.statusMirror !== "running") return false;
 
-    // Flip the flag before the await so a concurrent send can't
-    // double-spawn the sessions.
-    channel.sessionsStarted = true;
-
     // Set the task creator's git author identity in the container (ADR-029).
     // The SSH key itself is installed earlier by task-up.sh (host clone +
     // container), using the creator's per-user key. Best-effort. Awaited but
@@ -267,8 +295,15 @@ class Orchestrator {
     taskId: string,
     agentId: string,
   ): Promise<{ ok: true } | { ok: false; error: string }> {
-    const session = this.channels.get(taskId)?.sessions.get(agentId);
-    if (!session) return { ok: false, error: "no active session" };
+    const channel = this.channels.get(taskId);
+    const session = channel?.sessions.get(agentId);
+    if (!channel || !session) return { ok: false, error: "no active session" };
+    // An interrupted turn is a half-turn — its eventual turn_complete must not
+    // hand the buffered fragment to @-mentioned peers. Flag it so the boundary
+    // goes out `aborted` and the cloud discards the buffer. Only when the turn
+    // actually streamed output (openTurns): an idle-agent ESC must not mark
+    // the NEXT legitimate turn as aborted.
+    if (channel.openTurns.has(agentId)) channel.interrupted.add(agentId);
     void session.interrupt();
     this.emitSystemNote(taskId, `Stopped @${agentId}.`);
     return { ok: true };
@@ -300,6 +335,7 @@ class Orchestrator {
   ): Promise<void> {
     switch (event.type) {
       case "message_delta": {
+        channel.openTurns.add(agentId);
         this.emitHost({
           kind: "agent.message_delta",
           taskId: channel.taskId,
@@ -309,6 +345,7 @@ class Orchestrator {
         break;
       }
       case "message_complete": {
+        channel.openTurns.add(agentId);
         this.emitHost({
           kind: "agent.message_complete",
           taskId: channel.taskId,
@@ -354,6 +391,10 @@ class Orchestrator {
         break;
       }
       case "error": {
+        // The turn died with the session — drop its turn-state flags so a
+        // respawned session starts clean.
+        channel.openTurns.delete(agentId);
+        channel.interrupted.delete(agentId);
         // Claude under load (especially Docker Desktop macOS) occasionally
         // unlinks ~/.claude.json mid-write during atomic config rewrites,
         // and a concurrent claude spawn lands during the gap and exits 0
@@ -381,10 +422,15 @@ class Orchestrator {
       case "turn_complete": {
         // Turn boundary — the cloud flushes any @-mentions buffered across this
         // turn's messages and wakes the mentioned peers with the full turn.
+        // An interrupted (ESC'd) turn goes out `aborted`: it's a half-turn, so
+        // the cloud discards the buffer instead of handing it to peers.
+        const aborted = channel.interrupted.delete(agentId);
+        channel.openTurns.delete(agentId);
         this.emitHost({
           kind: "agent.turn_complete",
           taskId: channel.taskId,
           agentId,
+          aborted,
         });
         break;
       }
@@ -695,10 +741,16 @@ export function buildSystemPreamble(
     "",
     `Agents in this channel: ${others}.`,
     "",
+    "The human you're working with is **@you**. When you need their",
+    "input, a decision, or their attention — a question, a blocker, an",
+    "approval, or you've finished and are handing back to them — end your",
+    "message by @-mentioning **@you** (e.g. `@you which approach do you`",
+    "`prefer?` or `@you done — PR is up for review`). That notifies them.",
+    "",
     "An agent only receives a message when it is explicitly @-mentioned",
-    "(or addressed by the human) — so always @-mention the agent you mean.",
-    "There is NO `peer` command and no shared tmux session; hand-offs are",
-    "just @-mentions in your replies.",
+    "(or addressed by the human) — so always @-mention the agent (or @you)",
+    "you mean. There is NO `peer` command and no shared tmux session;",
+    "hand-offs are just @-mentions in your replies.",
     "",
     "Because your input is only what you're addressed, you may be missing",
     "context from messages between the human and the other agents. The full",
@@ -817,15 +869,21 @@ interface DockerPs {
   State: string; // "running" | "exited" | "created" | "paused"
 }
 
-async function dockerListContainersByLabel(label: string): Promise<DockerPs[]> {
-  const res = await dockerCli([
-    "ps",
-    "--all",
-    "--filter",
-    `label=${label}`,
-    "--format",
-    "{{json .}}",
-  ]);
+/**
+ * Returns the task's containers, [] when docker reports none, or NULL when
+ * docker itself was unreachable/timed out (status null = spawn failure or our
+ * SIGKILL). The distinction matters: recovery treats [] as "container gone"
+ * and DOWNGRADES the task to stopped/error — doing that because a `docker ps`
+ * timed out under load would destroy a perfectly recoverable task.
+ */
+async function dockerListContainersByLabel(
+  label: string,
+): Promise<DockerPs[] | null> {
+  const res = await dockerCli(
+    ["ps", "--all", "--filter", `label=${label}`, "--format", "{{json .}}"],
+    { timeoutMs: 60_000 },
+  );
+  if (res.status === null) return null; // docker state UNKNOWN — don't act on it
   if (res.status !== 0) return [];
   return res.stdout
     .split("\n")
@@ -842,7 +900,9 @@ async function dockerListContainersByLabel(label: string): Promise<DockerPs[]> {
 }
 
 async function dockerStart(containerName: string): Promise<boolean> {
-  const res = await dockerCli(["start", containerName]);
+  // Starting a big dev container can legitimately take a while — give it far
+  // more than dockerCli's 30s default before declaring the task stopped.
+  const res = await dockerCli(["start", containerName], { timeoutMs: 120_000 });
   if (res.status !== 0) {
     console.error(
       `[orchestrator] docker start ${containerName} failed: ${res.stderr.trim()}`,
@@ -866,8 +926,15 @@ async function dockerPort(
   return Number.isFinite(port) ? port : null;
 }
 
-async function dockerExec(containerName: string, cmd: string[]): Promise<boolean> {
-  const res = await dockerCli(["exec", containerName, ...cmd]);
+async function dockerExec(
+  containerName: string,
+  cmd: string[],
+  timeoutMs?: number,
+): Promise<boolean> {
+  const res = await dockerCli(
+    ["exec", containerName, ...cmd],
+    timeoutMs === undefined ? {} : { timeoutMs },
+  );
   return res.status === 0;
 }
 
@@ -915,6 +982,14 @@ async function recoverOneTask(
   const containers = await dockerListContainersByLabel(
     `com.docker.compose.project=${composeProject}`,
   );
+  if (containers === null) {
+    // Docker unreachable / timed out — actual state unknown. Leave the row
+    // alone; the next recovery pass (or the next ensure) will see the truth.
+    console.warn(
+      `[orchestrator] recovery: ${task.taskId} skipped — docker did not answer`,
+    );
+    return;
+  }
 
   if (containers.length === 0) {
     // Container gone. Worktree state determines whether resume is
@@ -945,6 +1020,13 @@ async function recoverOneTask(
       });
       console.log(`[orchestrator] recovery: ${task.taskId} ports refreshed`);
     }
+    // Re-establish gh proactively (ADR-027): the restart killed the in-memory
+    // refresh timers, so an idle task's access token would silently expire
+    // ~8h later. Cheap with the per-user access-token cache — one exchange
+    // per user, every task re-injects from it. Best-effort.
+    if (task.ownerUserId) {
+      void setupTaskGithub(task.taskId, task.ownerUserId);
+    }
     return;
   }
 
@@ -960,7 +1042,11 @@ async function recoverOneTask(
     });
     return;
   }
-  if (!(await dockerExec(containerName, ["/usr/local/bin/uai-init"]))) {
+  // uai-init reinstalls workspace deps (pnpm/npm install) — minutes on a big
+  // repo. dockerCli's 30s default would SIGKILL it mid-install.
+  if (
+    !(await dockerExec(containerName, ["/usr/local/bin/uai-init"], 10 * 60_000))
+  ) {
     console.warn(
       `[orchestrator] recovery: ${task.taskId} uai-init failed; container is up but Editor may be down`,
     );
@@ -969,6 +1055,11 @@ async function recoverOneTask(
   db_setRuntime(task.taskId, {
     codeServerPort: port,
   });
+  // Same gh re-establish as the running branch — the restarted container's gh
+  // config is whatever it held when it exited.
+  if (task.ownerUserId) {
+    void setupTaskGithub(task.taskId, task.ownerUserId);
+  }
   console.log(
     `[orchestrator] recovery: ${task.taskId} resumed (port ${port ?? "?"})`,
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.2.4",
+  "version": "0.2.8",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/src/main.ts

@@ -25,8 +25,10 @@ import {
 import { getHostTask } from "../lib/runtime-state";
 import { getOrchestrator } from "../lib/orchestrator";
 import {
+  connectedUserIds,
   onConnectClear,
   onConnectSet,
+  onGithubChange,
   setAuthExpiredHandler,
 } from "../lib/github-tokens";
 import {
@@ -166,6 +168,7 @@ function buildCapabilities(): HostCapabilities {
   return {
     agentKinds: agentKindCapabilities(),
     runtimes: standardRuntimes(),
+    githubUsers: connectedUserIds(),
   };
 }
 
@@ -181,6 +184,9 @@ function sendCapabilities(): void {
 }
 
 onRegistryChange(() => sendCapabilities());
+// Re-advertise when a gh token is added/removed (ADR-033) so the host page's
+// per-host connected state updates promptly.
+onGithubChange(() => sendCapabilities());
 
 function connect(): void {
   if (stopping || fatal) return;
@@ -284,7 +290,15 @@ function connect(): void {
         break;
       }
       case "gh.connect.clear":
-        onConnectClear(frame.userId);
+        // Delete-then-revoke (ADR-033) is async + best-effort; ack immediately
+        // so the UI isn't gated on the GitHub revoke round-trip. The .catch is
+        // a belt over onConnectClear's own try/catch — a fire-and-forget
+        // rejection must never crash the host.
+        void onConnectClear(frame.userId).catch((err) =>
+          console.warn(
+            `[github] connect.clear failed: ${err instanceof Error ? err.message : err}`,
+          ),
+        );
         send(socket, { kind: "gh.connect.ack", userId: frame.userId, ok: true });
         break;
       case "ssh.key.get":
@@ -830,7 +844,9 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
     typeof frame.installationId === "number" &&
     typeof frame.githubLogin === "string" &&
     (frame.targetType === "User" || frame.targetType === "Organization") &&
-    typeof frame.refreshToken === "string"
+    // Exactly one token kind: accessToken (ADR-033) or refreshToken (ADR-027).
+    (typeof frame.accessToken === "string" ||
+      typeof frame.refreshToken === "string")
   ) {
     return {
       kind: "gh.connect.set",
@@ -838,7 +854,10 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
       installationId: frame.installationId,
       githubLogin: frame.githubLogin,
       targetType: frame.targetType,
-      refreshToken: frame.refreshToken,
+      accessToken:
+        typeof frame.accessToken === "string" ? frame.accessToken : undefined,
+      refreshToken:
+        typeof frame.refreshToken === "string" ? frame.refreshToken : undefined,
       refreshTokenExpiresAt:
         typeof frame.refreshTokenExpiresAt === "number"
           ? frame.refreshTokenExpiresAt

package/src/protocol.ts

@@ -68,6 +68,10 @@ export interface HostCapabilities {
     kind: string;
     availableVersions: string[];
   }>;
+  // ADR-033: cloud user ids that currently have a GitHub token ON THIS HOST —
+  // the per-host gh-connected state shown on the host detail page. Re-advertised
+  // whenever a token is added/removed. Optional: older hosts omit it.
+  githubUsers?: string[];
 }
 
 export interface TaskUpResult {
@@ -305,18 +309,25 @@ export type CloudToHost =
   // never responds, so the cloud never sends an ack. (HTTP tunnels only.)
   | { kind: "tunnel.requestEnd"; tunnelId: string }
   | { kind: "tunnel.close"; tunnelId: string; reason?: string }
-  // GitHub App connect lifecycle (ADR-027). The cloud forwards the user's
-  // refresh token to the host, which encrypts + persists it; the per-task
-  // access-token exchange is a host→cloud HTTP POST, not a frame.
+  // GitHub App connect lifecycle (ADR-027 / ADR-033). The cloud forwards the
+  // user's token to the host, which encrypts + persists it. Exactly one token
+  // is present:
+  //   - `accessToken`  → non-expiring per-host token (ADR-033). Injected into
+  //                      containers directly; no exchange, no refresh.
+  //   - `refreshToken` → legacy expiring token (ADR-027). The host exchanges it
+  //                      for short-lived access tokens (host→cloud HTTP POST).
   | {
       kind: "gh.connect.set";
       userId: string;
       installationId: number;
       githubLogin: string;
       targetType: "User" | "Organization";
-      refreshToken: string;
+      accessToken?: string;
+      refreshToken?: string;
       refreshTokenExpiresAt?: number;
     }
+  // Delete the user's token on the host. ADR-033: the host first POSTs the
+  // token to the cloud's /api/github/revoke (kill it at GitHub) before deleting.
   | { kind: "gh.connect.clear"; userId: string }
   // Per-user SSH key lifecycle (ADR-029). Keys are generated + stored on the
   // host; only the public key crosses the bridge (ssh.key.ack). `get` fetches
@@ -402,11 +413,14 @@ export type HostEvent =
   // The agent finished a turn (it may have emitted several message_complete
   // items within it). The cloud waits for this before waking @-mentioned peers,
   // so a peer is handed the agent's COMPLETE turn rather than a mid-turn
-  // fragment that happened to contain the mention.
+  // fragment that happened to contain the mention. `aborted` marks a turn that
+  // was interrupted (ESC): the cloud discards the buffered half-turn instead
+  // of delivering it.
   | {
       kind: "agent.turn_complete";
       taskId: string;
       agentId: string;
+      aborted?: boolean;
     }
   | {
       kind: "agent.tool_call";