@runuai/host 0.9.150 → 0.9.151

package/lib/runner-boot.ts

@@ -0,0 +1,10 @@
+/**
+ * Identity of this runner process lifetime.
+ *
+ * The bridge replay cursor and ADR-154's in-memory credential replicas must
+ * use the same value. Keeping the singleton in its own module prevents two
+ * subsystems from each drawing a plausible but different boot id.
+ */
+import { newId } from "./ulid";
+
+export const RUNNER_BOOT_ID = newId();

package/lib/runtime-activation-tail.ts

@@ -1,4 +1,11 @@
-export type RuntimeActivationAttemptResult = "complete" | "retry";
+/**
+ * `retry`: a transient failure, followed up within the epoch's bounded
+ * budget. `rerun`: the attempt was cut short by a one-time, monotonic
+ * transition (ADR-154: the runner leaving its own credentials), and the
+ * pass it now needs (one that sweeps first) runs at once, outside that
+ * budget and with a fresh one of its own, at most once per epoch.
+ */
+export type RuntimeActivationAttemptResult = "complete" | "retry" | "rerun";
 
 type ActivationAttempt = () => Promise<RuntimeActivationAttemptResult>;
 type RetrySchedule = (callback: () => void, delayMs: number) => () => void;
@@ -118,6 +125,10 @@ export class RuntimeActivationTail {
   private cancelRetry: (() => void) | null = null;
   private exhaustionReported = false;
   private stopped = false;
+  /** Who waits for no activation to be under way (whenSettled). */
+  private settledWaiters: Array<() => void> = [];
+  /** The epochs whose one rerun has been run. */
+  private readonly rerunEpochs = new Set<number>();
 
   constructor(options: RuntimeActivationTailOptions) {
     this.isCurrent = options.isCurrent;
@@ -162,7 +173,19 @@ export class RuntimeActivationTail {
       if (this.inFlight?.promise !== running) return;
       this.inFlight = null;
       if (
-        result === "retry" &&
+        result === "rerun" &&
+        !this.stopped &&
+        this.isCurrent(epoch) &&
+        !this.rerunEpochs.has(epoch)
+      ) {
+        // Outside the transient budget, with a fresh one of its own.
+        this.rerunEpochs.add(epoch);
+        this.cancelScheduledRetry();
+        this.retryAttempts = 0;
+        this.exhaustionReported = false;
+        void this.request(epoch, attempt);
+      } else if (
+        (result === "retry" || result === "rerun") &&
         !this.stopped &&
         this.isCurrent(epoch)
       ) {
@@ -170,6 +193,7 @@ export class RuntimeActivationTail {
       } else {
         this.resolve(epoch);
       }
+      this.notifySettled();
     });
     this.inFlight = { epoch, promise: running };
     return running;
@@ -196,13 +220,30 @@ export class RuntimeActivationTail {
     cancel = this.schedule(() => {
       if (this.cancelRetry !== cancel) return;
       this.cancelRetry = null;
-      if (this.stopped || !this.isCurrent(epoch)) return;
+      if (this.stopped || !this.isCurrent(epoch)) {
+        this.notifySettled();
+        return;
+      }
       void this.request(epoch, attempt);
     }, this.retryDelayMs);
     this.cancelRetry = cancel;
     return true;
   }
 
+  /** Whether an activation is under way: one running, or a retry of one
+   *  scheduled (#p2jdax: a recheck asked for meanwhile waits for it). */
+  underWay(): boolean {
+    return !this.stopped && (this.inFlight !== null || this.cancelRetry !== null);
+  }
+
+  /** Resolves once no activation is under way; never, once stopped (a
+   *  stopping host starts nothing more). */
+  whenSettled(): Promise<void> {
+    if (this.stopped) return new Promise<void>(() => {});
+    if (!this.underWay()) return Promise.resolve();
+    return new Promise<void>((resolve) => this.settledWaiters.push(resolve));
+  }
+
   /** Clear retry bookkeeping after another path proves the epoch operational. */
   resolve(epoch: number): void {
     if (this.retryEpoch !== epoch) return;
@@ -210,6 +251,12 @@ export class RuntimeActivationTail {
     this.retryEpoch = null;
     this.retryAttempts = 0;
     this.exhaustionReported = false;
+    this.notifySettled();
+  }
+
+  private notifySettled(): void {
+    if (this.stopped || this.underWay()) return;
+    for (const resolve of this.settledWaiters.splice(0)) resolve();
   }
 
   stop(): void {

package/lib/runtime-archive.ts

@@ -38,6 +38,19 @@ export const BUNDLED_RUNTIME_CAPABILITY =
 export const MANAGED_RUNTIME_CAPABILITY =
   "agent/managed-runtime-capability.json" as const;
 export const MANAGED_RUNTIME_CAPABILITY_VERSION = 4 as const;
+/**
+ * ADR-154 §13's cutover marker: this generation was built at or after the
+ * release that moved credentials to the cloud. It is a second file rather
+ * than capability 5 because the 0.9.149 and 0.9.150 validator accepts exactly
+ * capability 4, so the cutover release must still carry
+ * `{"capabilitySchemaVersion":4}` or no owned runner could install it. Like
+ * that marker in its day, this additive `agent/` file is ignored by every
+ * older validator. A generation without it predates the cutover and resolves
+ * to credentials capability 0.
+ */
+export const MANAGED_RUNTIME_CREDENTIALS =
+  "agent/managed-runtime-credentials.json" as const;
+export const MANAGED_RUNTIME_CREDENTIALS_VERSION = 1 as const;
 /** Plugin directory == plugin binary name in Apple's signed pkg payload. */
 const APPLE_CONTAINER_PLUGINS = Object.freeze([
   "container-core-images",
@@ -122,6 +135,10 @@ export interface ManagedRuntimeCapabilityDescriptorV4 {
   readonly capabilitySchemaVersion: 4;
 }
 
+export interface ManagedRuntimeCredentialsDescriptor {
+  readonly credentialsCapabilityVersion: number;
+}
+
 export type RuntimePlatformCapabilities =
   | { readonly capabilitySchemaVersion: 1 }
   | RuntimeCapabilityDescriptorV3;
@@ -129,6 +146,8 @@ export type RuntimePlatformCapabilities =
 export type ResolvedRuntimeCapabilities = RuntimePlatformCapabilities & {
   /** Effective rollback/update floor carried by this whole generation. */
   readonly runtimeCapabilityVersion: 1 | 3 | 4;
+  /** ADR-154 cutover marker; 0 for a generation built before the cutover. */
+  readonly credentialsCapabilityVersion: number;
 };
 
 export type RuntimeDescriptor = RuntimeDescriptorV1;
@@ -473,6 +492,8 @@ function validateEntryLayout(
     byPath,
     platformCapabilities.capabilitySchemaVersion,
   );
+  const credentialsCapabilityVersion =
+    validateArchivedManagedRuntimeCredentials(byPath);
   if (platformCapabilities.capabilitySchemaVersion === 3) {
     const bundled = platformCapabilities.bundledRuntime;
     const pluginBinaries = APPLE_CONTAINER_PLUGINS.map(
@@ -531,7 +552,31 @@ function validateEntryLayout(
       throw new Error(`runtime archive executable mode is invalid: ${executable}`);
     }
   }
-  return { ...platformCapabilities, runtimeCapabilityVersion };
+  return {
+    ...platformCapabilities,
+    runtimeCapabilityVersion,
+    credentialsCapabilityVersion,
+  };
+}
+
+function validateArchivedManagedRuntimeCredentials(
+  byPath: ReadonlyMap<string, ArchiveEntry>,
+): number {
+  const entry = byPath.get(MANAGED_RUNTIME_CREDENTIALS);
+  if (entry === undefined) return 0;
+  if (entry.type !== "0" || entry.data.length > MAX_PAX_BYTES) {
+    throw new Error(
+      "managed runtime credentials descriptor is not a regular file or is too large",
+    );
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(entry.data.toString("utf8"));
+  } catch {
+    throw new Error("managed runtime credentials descriptor is invalid JSON");
+  }
+  return validateManagedRuntimeCredentialsDescriptor(raw)
+    .credentialsCapabilityVersion;
 }
 
 function validateArchivedManagedRuntimeCapability(
@@ -672,6 +717,28 @@ export function validateManagedRuntimeCapabilityDescriptor(
   };
 }
 
+export function validateManagedRuntimeCredentialsDescriptor(
+  value: unknown,
+): ManagedRuntimeCredentialsDescriptor {
+  const object = strictObject(
+    value,
+    ["credentialsCapabilityVersion"],
+    "managed runtime credentials descriptor",
+  );
+  // Any version from 1 up, unlike the exact match above: that exact match is
+  // why the cutover needed this second file, and a later release must be able
+  // to raise this one in place. The floor compares it numerically.
+  const version = object.credentialsCapabilityVersion;
+  if (
+    typeof version !== "number" ||
+    !Number.isSafeInteger(version) ||
+    version < 1
+  ) {
+    throw new Error("unsupported managed runtime credentials descriptor");
+  }
+  return { credentialsCapabilityVersion: version };
+}
+
 function validateBundledRuntimeDescriptor(
   value: unknown,
 ): BundledRuntimeDescriptor {

package/lib/runtime-reconnect.ts

@@ -0,0 +1,86 @@
+/**
+ * A known-ready container runtime revalidated when the bridge reconnects: a
+ * healthy daemon can still have restarted while the bridge was offline. One
+ * label scan keeps ordinary cloud/network flaps cheap; only a missing,
+ * exited or unknowable active app takes the full per-task recovery.
+ *
+ * ADR-154: it runs on the credentials it began on, as an activation does
+ * (credentialsActivationFence). Off the runner's own before this process's
+ * credential sweep has succeeded, or once leaving them begins, it neither
+ * recovers nor publishes: it hands the runtime to the credentials-aware
+ * activation, which sweeps first. Off them after the sweep, its recovery
+ * goes through the credentials wrapper (the sweep already done).
+ */
+
+import {
+  cloudCredentialsSwept,
+  credentialsActivationFence,
+  onOwnCredentials,
+  recoverRuntimeOnCredentials,
+} from "./cloud-credential-host";
+
+export interface RuntimeReconnectDeps {
+  /** Suspends a ready runtime for revalidation; its epoch, or null. */
+  suspend(): number | null;
+  /** Probes the daemon again: ready or not. */
+  probe(): Promise<boolean>;
+  /** The readiness epoch is still this one, and the daemon ready. */
+  epochIsCurrent(epoch: number): boolean;
+  /** The epoch is current and the runner is not stopping. */
+  activationIsCurrent(epoch: number): boolean;
+  persistedEnvironmentsMatch(): Promise<boolean>;
+  recoveryVerdict(): Promise<"clean" | "needed" | "unknown">;
+  /** The orchestrator's per-task recovery. */
+  recover(isCurrent: () => boolean): Promise<boolean>;
+  /** A bounded activation retry for the epoch. */
+  scheduleRetry(epoch: number): void;
+  /** A full, credentials-aware activation pass for the epoch. */
+  requestActivation(epoch: number): void;
+  /** Marks the runtime operational for the epoch, resumes deferred agent
+   *  work and re-advertises; false when it could not be marked. */
+  publish(epoch: number): boolean;
+}
+
+export async function revalidateRuntimeOnConnect(deps: RuntimeReconnectDeps): Promise<void> {
+  const epoch = deps.suspend();
+  if (epoch === null) return;
+  const fence = credentialsActivationFence(() => deps.activationIsCurrent(epoch));
+  const handOver = (): void => {
+    if (deps.activationIsCurrent(epoch)) deps.requestActivation(epoch);
+  };
+  /** Not current any more: leaving the runner's own credentials hands the
+   *  runtime to the activation; a stale epoch ends here. */
+  const stopped = (): boolean => {
+    if (fence.isCurrent()) return false;
+    if (fence.leftLegacy()) handOver();
+    return true;
+  };
+  try {
+    if (!(await deps.probe()) || !deps.epochIsCurrent(epoch)) return;
+    if (!onOwnCredentials() && !cloudCredentialsSwept()) {
+      handOver();
+      return;
+    }
+    if (!(await deps.persistedEnvironmentsMatch())) return;
+    if (stopped()) return;
+    let recovered = (await deps.recoveryVerdict()) === "clean";
+    if (!recovered) {
+      recovered = await recoverRuntimeOnCredentials(deps.recover, () => fence.isCurrent());
+    }
+    if (stopped()) return;
+    // Prove the daemon once more after recovery so a mid-sweep loss cannot
+    // reopen commands and tunnels on an unresolved backend.
+    if (!(await deps.probe()) || !deps.epochIsCurrent(epoch)) return;
+    if (stopped()) return;
+    if (!recovered) {
+      deps.scheduleRetry(epoch);
+      return;
+    }
+    deps.publish(epoch);
+  } catch (error) {
+    console.warn(
+      `[host-agent] container runtime reconnect validation failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    if (deps.activationIsCurrent(epoch)) deps.scheduleRetry(epoch);
+  }
+}