@runuai/host 0.9.170 → 0.9.171

package/lib/credentials-activation-authority.ts

@@ -65,6 +65,14 @@
  * transition the authority does. Should saying so fail, the
  * runner is pending again, withdraws what it advertised, and says so later.
  *
+ * What stops the switch is said to the cloud as well as logged (`status`,
+ * on every capability frame; `onStatusChange` when it changes): the latest
+ * refusal or blocker, who gave it (the cloud's answer, or this runner), each
+ * blocker apart and every Compose project the retirement could not prove
+ * Uai's. A transient one (the container runtime still preparing after a
+ * reconnect, an unanswered ask) never replaces a substantive one: an
+ * operator reading Connections sees what to fix, not what fixes itself.
+ *
  * The record holds no secret: `{"schemaVersion":1,"step":"local",
  * "stopped":[{"taskId":"…","runEpoch":3}]}`. One the runner cannot read
  * counts as `local`, never as `legacy`: a damaged record may stand for a
@@ -88,6 +96,14 @@ import {
 import { dirname } from "node:path";
 
 import type { CredentialsActivationPhase } from "../src/cloud-credentials";
+import {
+  MAX_CREDENTIALS_SWITCH_BLOCKER_CHARS,
+  MAX_CREDENTIALS_SWITCH_BLOCKERS,
+  MAX_CREDENTIALS_SWITCH_DETAIL_CHARS,
+  MAX_CREDENTIALS_SWITCH_PROJECTS,
+  type CredentialsSwitchCapability,
+  type CredentialsSwitchStuck,
+} from "../src/protocol";
 import type { CredentialsMode } from "./cloud-credential-host";
 import type { RetirementPlan } from "./legacy-runtime-retirement";
 import { isSafeHostTaskId } from "./task-identity";
@@ -167,6 +183,12 @@ export interface ActivationAuthorityDeps<Retirement = RetirementPlan> {
   /** Ask the runner's supervisor for a restart. */
   restart: (why: string) => void;
   log: (line: string) => void;
+  /** `status()` changed: advertise it again. */
+  onStatusChange?: () => void;
+  /** What `status()` says of a blocker, made fit to leave the machine (the
+   *  home directory as `~`). */
+  redact?: (text: string) => string;
+  now?: () => number;
 }
 
 export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
@@ -191,6 +213,14 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
   #lastNote: string | null = null;
   /** Leaving the runner's own credentials failed in this process. */
   #stuck = false;
+  /** What stops the switch now, as `status()` says it. */
+  #blocker: CredentialsSwitchStuck | null = null;
+  /** Every Compose project the current blocker names, past the status's
+   *  bound too: what the log lists, and what tells one blocker from another
+   *  when only names past that bound changed. */
+  #blockerProjects = "";
+  /** `status()` as last told to `onStatusChange`'s caller. */
+  #published: string | null = null;
 
   constructor(deps: ActivationAuthorityDeps<Retirement>) {
     this.#deps = deps;
@@ -218,6 +248,13 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
     return this.#record?.step ?? null;
   }
 
+  /** Where the switch stands, for the capability frame (see the header). */
+  status(): CredentialsSwitchCapability {
+    const state = this.mode();
+    const stuck = state === "active" ? null : this.#blocker;
+    return stuck === null ? { state } : { state, stuck: { ...stuck } };
+  }
+
   mode(): CredentialsMode {
     if (this.#record === null) {
       return this.#initiallyPending ? "pending" : "legacy";
@@ -249,9 +286,12 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
   advance(): Promise<void> {
     if (this.#advancing === null) {
       this.#advancing = this.#advanceOnce()
-        .catch((error: unknown) => this.#note(`activation stopped: ${message(error)}; it tries again later`))
+        .catch((error: unknown) =>
+          this.#block("runner", error, `activation stopped: ${message(error)}; it tries again later`),
+        )
         .finally(() => {
           this.#advancing = null;
+          this.#publish();
         });
     }
     return this.#advancing;
@@ -266,10 +306,13 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
     }
     let plan: Retirement | null = null;
     if (this.#record === null) {
-      if (!this.#deps.eligible()) return;
-      const prepared = await this.#deps.ask("prepare");
+      if (!this.#deps.eligible()) {
+        this.#blocker = null;
+        return;
+      }
+      const prepared = await this.#ask("prepare");
       if (!prepared.ok) {
-        this.#note(`the cloud did not agree to cloud credentials yet: ${prepared.error}`);
+        this.#block("cloud", prepared.error, `the cloud did not agree to cloud credentials yet: ${prepared.error}`);
         return;
       }
       const paused = this.#deps.pauseLegacyStarts();
@@ -287,7 +330,9 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
         this.#record ??= readActivationRecord(this.#deps.recordPath);
         if (this.#record === null) {
           paused.resume();
-          this.#note(
+          this.#block(
+            "runner",
+            error,
             this.#initiallyPending
               ? `the v1-required task machine stays pending, with no v0 fallback: ${message(error)}`
               : `the runner stays on its own credentials, nothing changed: ${message(error)}`,
@@ -295,6 +340,7 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
           return;
         }
       }
+      this.#blocker = null;
       this.#deps.log("[credentials] switching to cloud credentials: leaving the runner's own");
     }
     if (!this.#synced()) return;
@@ -319,11 +365,16 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
       plan ??= await this.#deps.planRetirement();
       await this.#retire(plan);
       await this.#deps.claimFloor();
-      const committed = await this.#deps.ask("commit");
+      const committed = await this.#ask("commit");
       if (!committed.ok) {
-        this.#note(`the cloud did not record this runner's switch yet: ${committed.error}; it runs no task meanwhile`);
+        this.#block(
+          "cloud",
+          committed.error,
+          `the cloud did not record this runner's switch yet: ${committed.error}; it runs no task meanwhile`,
+        );
         return;
       }
+      this.#blocker = null;
       this.#write({ ...this.#record, step: "cloud" });
     }
     if (this.#record?.step === "cloud") {
@@ -350,7 +401,9 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
         this.#write(record);
       }
     } catch (error) {
-      this.#note(
+      this.#block(
+        "runner",
+        error,
         `the activation record is not known to be on disk yet (${message(error)}): the switch waits, running no task, ` +
           "until it is",
       );
@@ -373,7 +426,9 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
       try {
         await this.#deps.sweep();
       } catch (error) {
-        this.#note(
+        this.#block(
+          "runner",
+          error,
           `the recovery sweep failed (${message(error)}): the runner stays pending, running no task, and sweeps again later`,
         );
         return;
@@ -397,10 +452,15 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
     }
     if (failure === null) {
       this.#announced = true;
+      this.#blocker = null;
       this.#deps.log("[credentials] tasks run on cloud credentials");
       return;
     }
-    this.#note(`saying the runner is active failed (${message(failure)}): it is pending again, and tries again later`);
+    this.#block(
+      "runner",
+      failure,
+      `saying the runner is active failed (${message(failure)}): it is pending again, and tries again later`,
+    );
     try {
       this.#deps.onActiveWithdrawn();
     } catch (error) {
@@ -441,6 +501,67 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
     this.#durable = true;
   }
 
+  /** One phase asked of the cloud. An ask that could not be made or was not
+   *  answered says nothing about the switch: transient. */
+  async #ask(phase: CredentialsActivationPhase): Promise<ActivationAnswer> {
+    try {
+      return await this.#deps.ask(phase);
+    } catch (error) {
+      throw new TransientActivationError(message(error));
+    }
+  }
+
+  /** A refusal or blocker: logged, and what `status()` says unless it is
+   *  transient and a substantive one is already said (see the header). */
+  #block(by: CredentialsSwitchStuck["by"], why: unknown, line: string): void {
+    this.#note(line);
+    const transient = isTransient(why);
+    if (transient && this.#blocker !== null && this.#blocker.transient !== true) return;
+    const redact = this.#deps.redact ?? ((text: string) => text);
+    const detail = bounded(redact(oneLine(typeof why === "string" ? why : message(why))), MAX_CREDENTIALS_SWITCH_DETAIL_CHARS);
+    const next: CredentialsSwitchStuck = { by, detail, since: (this.#deps.now ?? Date.now)() };
+    const structured = why as { blockers?: unknown; unprovenProjects?: unknown } | null;
+    const blockers = stringList(structured?.blockers);
+    if (blockers.length > 0) {
+      next.blockers = blockers
+        .slice(0, MAX_CREDENTIALS_SWITCH_BLOCKERS)
+        .map((blocker) => bounded(redact(oneLine(blocker)), MAX_CREDENTIALS_SWITCH_BLOCKER_CHARS));
+    }
+    const projects = stringList(structured?.unprovenProjects);
+    if (projects.length > 0) {
+      next.composeProjects = { names: projects.slice(0, MAX_CREDENTIALS_SWITCH_PROJECTS), total: projects.length };
+    }
+    if (transient) next.transient = true;
+    const previous = this.#blocker;
+    const allProjects = projects.join(" ");
+    // The same blocker again keeps when it was first seen. "The same" counts
+    // every project, not only the ones the status has room for.
+    if (previous !== null && sameBlocker(previous, next) && allProjects === this.#blockerProjects) return;
+    this.#blocker = next;
+    this.#blockerProjects = allProjects;
+    // The status names at most MAX_CREDENTIALS_SWITCH_PROJECTS, and the
+    // line above is cut short: the log names every one, once per blocker,
+    // for the operator Connections sends here for the rest.
+    if (projects.length > 0) {
+      this.#deps.log(
+        `[credentials] Compose projects nothing proves Uai's (${projects.length}), each to remove ` +
+          `(docker compose -p <name> down) or rename: ${allProjects}`,
+      );
+    }
+  }
+
+  /** `onStatusChange` when `status()` says something new. */
+  #publish(): void {
+    const now = JSON.stringify(this.status());
+    if (now === this.#published) return;
+    this.#published = now;
+    try {
+      this.#deps.onStatusChange?.();
+    } catch (error) {
+      this.#note(`advertising the switch's status failed: ${message(error)}`);
+    }
+  }
+
   /** The same note twice in a row is logged once: a refusal is asked about
    *  again every few minutes. */
   #note(line: string): void {
@@ -450,6 +571,33 @@ export class CredentialsActivationAuthority<Retirement = RetirementPlan> {
   }
 }
 
+class TransientActivationError extends Error {
+  readonly transient = true;
+}
+
+function isTransient(why: unknown): boolean {
+  return why !== null && typeof why === "object" && (why as { transient?: unknown }).transient === true;
+}
+
+function sameBlocker(a: CredentialsSwitchStuck, b: CredentialsSwitchStuck): boolean {
+  const { since: _a, ...left } = a;
+  const { since: _b, ...right } = b;
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item !== "") : [];
+}
+
+function oneLine(text: string): string {
+  return text.replace(/\s*\n\s*(?:- )?/g, "; ").trim();
+}
+
+function bounded(text: string, max: number): string {
+  const nonEmpty = text === "" ? "unknown" : text;
+  return nonEmpty.length <= max ? nonEmpty : `${nonEmpty.slice(0, max - 1)}…`;
+}
+
 /** The record; null when there is none. One the runner cannot read is
  *  `local` with nothing owed (see the header). */
 export function readActivationRecord(path: string): ActivationRecord | null {

package/lib/legacy-runtime-retirement.ts

@@ -22,7 +22,12 @@
  *   isolation), and which the operator removes or renames. A row with no
  *   runtime (a task that went down keeps its row, its runtime fields
  *   cleared) neither blocks nor vouches for anything. The plan records the
- *   engine it was made against.
+ *   engine it was made against. Its rejection is a `RetirementBlockedError`:
+ *   each blocker apart, and every unproven project named, so the cloud can
+ *   show the operator all of them with the command that clears each
+ *   (ADR-154 §13 build notes, 2026-10-27). Such a project is never removed
+ *   here: a Compose label proves neither who made a stack nor that nothing
+ *   uses it now (another runner may share this Docker and workspace root).
  * - `retireLegacyTaskRuntimes` carries a plan out, only after the runner has
  *   committed to the switch. Each task's check, Stop and removal share its
  *   lifecycle slot: before its assignment closes and again before anything
@@ -117,6 +122,26 @@ export interface RetirementDeps extends RetirementPlanDeps {
   log: (line: string) => void;
 }
 
+/**
+ * The plan's refusal: every blocker apart (`blockers`), and apart from them
+ * the `task-*` Compose projects nothing proves Uai's (all of them, for the
+ * operator to remove or rename). The message names both, as the log has.
+ * `transient`: nothing is wrong yet, the runner only cannot look now (its
+ * container runtime is still preparing); the next attempt looks again.
+ */
+export class RetirementBlockedError extends Error {
+  readonly blockers: string[];
+  readonly unprovenProjects: string[];
+  readonly transient: boolean;
+  constructor(message: string, options: { blockers?: string[]; unprovenProjects?: string[]; transient?: boolean } = {}) {
+    super(message);
+    this.name = "RetirementBlockedError";
+    this.blockers = options.blockers ?? [];
+    this.unprovenProjects = options.unprovenProjects ?? [];
+    this.transient = options.transient === true;
+  }
+}
+
 export interface RetirementReport {
   /** Tasks whose runtime is gone (or was already). */
   retired: string[];
@@ -136,8 +161,9 @@ export async function planLegacyTaskRuntimeRetirement(deps: RetirementPlanDeps):
   const blockers: string[] = [];
   const snapshot = deps.snapshot();
   if (snapshot.runtimeProblem !== null || snapshot.machine === null) {
-    throw new Error(
+    throw new RetirementBlockedError(
       `task runtimes cannot be retired now: the container runtime is not ready (${snapshot.runtimeProblem ?? "no engine is pinned"})`,
+      { transient: true },
     );
   }
   if (!snapshot.fence.ok) blockers.push(snapshot.fence.detail ?? "the task rows do not match the pinned container runtime");
@@ -183,6 +209,7 @@ export async function planLegacyTaskRuntimeRetirement(deps: RetirementPlanDeps):
   }
 
   const appleOrphans: string[] = [];
+  const unprovenProjects: string[] = [];
   try {
     if (deps.apple) {
       const named = new Set(rows.map((task) => `task-${task.taskId}-app`));
@@ -193,18 +220,26 @@ export async function planLegacyTaskRuntimeRetirement(deps: RetirementPlanDeps):
       const named = new Set(rows.map((task) => `task-${task.taskId}`));
       for (const project of await listTaskProjects(deps.docker)) {
         if (named.has(project)) continue;
-        blockers.push(
-          `Compose project ${project} has containers but no task on this runner: nothing proves it Uai's, so it is not removed. ` +
-            `If it was a task's, remove it (docker compose -p ${project} down); otherwise rename it`,
-        );
+        unprovenProjects.push(project);
       }
     }
   } catch (error) {
     blockers.push(`the task runtime inventory failed: ${message(error)}`);
   }
 
-  if (blockers.length > 0) {
-    throw new Error(`task runtimes cannot all be retired: ${blockers.join("; ").slice(0, 1500)}`);
+  if (blockers.length > 0 || unprovenProjects.length > 0) {
+    const all = [
+      ...blockers,
+      ...unprovenProjects.map(
+        (project) =>
+          `Compose project ${project} has containers but no task on this runner: nothing proves it Uai's, so it is not removed. ` +
+          `If it was a task's, remove it (docker compose -p ${project} down); otherwise rename it`,
+      ),
+    ];
+    throw new RetirementBlockedError(`task runtimes cannot all be retired: ${all.join("; ").slice(0, 1500)}`, {
+      blockers,
+      unprovenProjects,
+    });
   }
   return { machine: snapshot.machine, removals, appleOrphans };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.170",
+  "version": "0.9.171",
   "description": "Uai host \u2014 runs ephemeral AI tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Uai Tech <team@runuai.com>",

package/src/main.ts

@@ -784,6 +784,9 @@ const credentialsActivation = new CredentialsActivationAuthority<CredentialsReti
     requestManagedHostRestart();
   },
   log: (line) => console.warn(line),
+  // What stops the switch reaches the cloud too, not only this log.
+  onStatusChange: () => sendCapabilities(),
+  redact: redactHomeDirectory,
 });
 setCredentialsModeSource(() => credentialsActivation.mode());
 /** ADR-154 §13: the steady/operator cadence. Active runners report their
@@ -1581,9 +1584,18 @@ function buildCapabilities(): HostCapabilities {
     engineAccounts: engineAccountSummaries(),
     engines: engineCatalogCapabilities(),
     githubUsers: connectedUserIds(),
+    // ADR-154 §13: where the switch to cloud credentials stands, and why.
+    credentialsSwitch: credentialsActivation.status(),
   };
 }
 
+/** A path under the home directory, as `~/…`: a status line leaves the
+ *  machine, and the account name in a path is not the cloud's to keep. */
+function redactHomeDirectory(text: string): string {
+  const home = homedir();
+  return home.length > 1 ? text.split(home).join("~") : text;
+}
+
 // engineCliStatuses probes binaries asynchronously; capabilities build
 // synchronously. The snapshot starts empty (cliInstalled: false) and each
 // build kicks a refresh that re-advertises only when the answer changed.

package/src/protocol.ts

@@ -4140,6 +4140,99 @@ export interface HostCapabilities {
   // 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[];
+  /** ADR-154 §13: where this runner's switch to cloud credentials stands, and
+   *  what stops it. Optional: hosts before 0.9.171 omit it, and the cloud
+   *  then says only that the runner has not switched. */
+  credentialsSwitch?: CredentialsSwitchCapability;
+}
+
+/**
+ * ADR-154 §13: the runner's switch to cloud credentials, as its capability
+ * frame reports it. `state` is the runner's credentials mode. `stuck` is the
+ * latest substantive refusal or blocker while the switch has not finished:
+ * `by: "cloud"` the cloud's answer, `by: "runner"` something on the machine.
+ * A transient one (the container runtime still preparing after a reconnect,
+ * the bridge down) never replaces a substantive one; it shows only when
+ * there is nothing else to say. Bounded and secret-free: the runner's own log
+ * words (task ids, Compose project names, folder paths with the home
+ * directory as `~`), never a credential.
+ */
+export interface CredentialsSwitchCapability {
+  state: "legacy" | "pending" | "active";
+  stuck?: CredentialsSwitchStuck;
+}
+
+export interface CredentialsSwitchStuck {
+  by: "cloud" | "runner";
+  /** The refusal or blocker in one line. */
+  detail: string;
+  /** Each blocker on its own, when the runner found several. */
+  blockers?: string[];
+  /** The `task-*` Compose projects nothing proves Uai's, which the operator
+   *  removes (`docker compose -p <name> down`) or renames: the first
+   *  `MAX_CREDENTIALS_SWITCH_PROJECTS` names, and how many there are. */
+  composeProjects?: { names: string[]; total: number };
+  /** Nothing is wrong yet: the runner could not look (see above). */
+  transient?: boolean;
+  /** Epoch ms this refusal or blocker was first seen, unchanged since. */
+  since: number;
+}
+
+export const MAX_CREDENTIALS_SWITCH_DETAIL_CHARS = 600;
+export const MAX_CREDENTIALS_SWITCH_BLOCKERS = 20;
+export const MAX_CREDENTIALS_SWITCH_BLOCKER_CHARS = 300;
+export const MAX_CREDENTIALS_SWITCH_PROJECTS = 100;
+
+/** The capability, exact and bounded; undefined when it is not one. The
+ *  cloud drops a malformed one alone, never the frame around it. */
+export function parseCredentialsSwitchCapability(value: unknown): CredentialsSwitchCapability | undefined {
+  if (!isPlainRecord(value)) return undefined;
+  const { state, stuck } = value;
+  if (state !== "legacy" && state !== "pending" && state !== "active") return undefined;
+  if (Object.keys(value).some((key) => key !== "state" && key !== "stuck")) return undefined;
+  if (stuck === undefined) return { state };
+  if (!isPlainRecord(stuck)) return undefined;
+  const allowed = new Set(["by", "detail", "blockers", "composeProjects", "transient", "since"]);
+  if (Object.keys(stuck).some((key) => !allowed.has(key))) return undefined;
+  const boundedText = (text: unknown, max: number): text is string =>
+    typeof text === "string" && text.length >= 1 && text.length <= max;
+  if (stuck.by !== "cloud" && stuck.by !== "runner") return undefined;
+  if (!boundedText(stuck.detail, MAX_CREDENTIALS_SWITCH_DETAIL_CHARS)) return undefined;
+  if (typeof stuck.since !== "number" || !Number.isSafeInteger(stuck.since) || stuck.since < 0) return undefined;
+  if (stuck.transient !== undefined && typeof stuck.transient !== "boolean") return undefined;
+  const out: CredentialsSwitchStuck = { by: stuck.by, detail: stuck.detail, since: stuck.since };
+  if (stuck.blockers !== undefined) {
+    if (
+      !Array.isArray(stuck.blockers) ||
+      stuck.blockers.length > MAX_CREDENTIALS_SWITCH_BLOCKERS ||
+      !stuck.blockers.every((blocker) => boundedText(blocker, MAX_CREDENTIALS_SWITCH_BLOCKER_CHARS))
+    ) {
+      return undefined;
+    }
+    out.blockers = [...stuck.blockers];
+  }
+  if (stuck.composeProjects !== undefined) {
+    const projects = stuck.composeProjects;
+    if (!isPlainRecord(projects) || Object.keys(projects).some((key) => key !== "names" && key !== "total")) return undefined;
+    const { names, total } = projects;
+    if (
+      !Array.isArray(names) ||
+      names.length > MAX_CREDENTIALS_SWITCH_PROJECTS ||
+      !names.every((name) => typeof name === "string" && /^task-[a-z0-9][a-z0-9_-]{0,127}$/.test(name)) ||
+      typeof total !== "number" ||
+      !Number.isSafeInteger(total) ||
+      total < names.length
+    ) {
+      return undefined;
+    }
+    out.composeProjects = { names: [...names] as string[], total };
+  }
+  if (stuck.transient === true) out.transient = true;
+  return { state, stuck: out };
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
 /** One transcript projection the cloud asks the host to append to (ADR-083). */