@runuai/host 0.9.161 → 0.9.163

package/lib/orchestrator.ts

@@ -31,6 +31,7 @@ import { dirname, join } from "node:path";
 import { inArray } from "drizzle-orm";
 
 import { getDb, schema } from "./db";
+import { newId } from "./ulid";
 import { mockAgentFactory } from "./agents/mock";
 import { realAgentFactory } from "./agents/factory";
 import { resolveAgentMode } from "./agents/mode";
@@ -152,7 +153,12 @@ import {
   codexHomeIsolatable,
   codexHomeSeedCommand,
   codexPerAgentHome,
+  clearEngineAccountCooldowns,
+  clearEngineAccountCooldownWindow,
   cooldownEngineAccount,
+  cooldownEngineAccountUntil,
+  cooldownEngineAccountWindow,
+  cooldownEngineAccountWindowUntil,
   noteEngineAccountUsed,
   pickEngineAccount,
   provisionEngineAccounts,
@@ -227,6 +233,7 @@ import {
 import { env } from "./env";
 import type {
   ChannelEnsureInput,
+  EngineUsageFrame,
   ChannelHuman,
   HostEvent,
 } from "../src/protocol";
@@ -247,6 +254,17 @@ import {
 import { forgetTaskEnvSnapshot } from "./task-env-source";
 
 export type HostEventSubscriber = (event: HostEvent) => void;
+/** True means the frame reached the current cloud transport generation. */
+export type EngineUsageSubscriber = (frame: EngineUsageFrame) => boolean;
+
+export const ENGINE_USAGE_REFRESH_MS = 15 * 60_000;
+
+interface DeliveredEngineUsage {
+  payload: string;
+  sentAt: number;
+  taskId: string;
+  agentId: string;
+}
 
 // Rolling upgrade fence: v0 Secretary runners were launched under the
 // communicator tool-denial profile and may survive a host restart. Durable
@@ -568,6 +586,18 @@ const LEASED_CREDENTIAL_BLANKS: Readonly<Record<string, string>> = Object.freeze
  *  again. */
 const LEASED_SYNC_RETRY_MS = 30_000;
 
+const ENGINE_USAGE_KINDS = new Set<EngineUsageFrame["engine"]>([
+  "claude",
+  "codex",
+  "grok",
+  "cursor",
+  "opencode",
+]);
+
+function isEngineUsageKind(kind: string): kind is EngineUsageFrame["engine"] {
+  return ENGINE_USAGE_KINDS.has(kind as EngineUsageFrame["engine"]);
+}
+
 /** ADR-154 §6: the exact lease material a spawn starts on: an AI account's,
  *  or, for the Managed Engine, the task's open run alone (its agent's task
  *  token is its credential). */
@@ -762,6 +792,10 @@ export class Orchestrator {
    *  later command cannot overtake an earlier one after channel close. */
   private readonly taskLifecycleTails = new Map<string, Promise<void>>();
   private readonly hostSubscribers = new Set<HostEventSubscriber>();
+  private readonly engineUsageSubscribers = new Set<EngineUsageSubscriber>();
+  /** Last payload (excluding report id/time) for each leased account + agent.
+   * Structured Claude events can repeat without any state change. */
+  private readonly lastEngineUsage = new Map<string, DeliveredEngineUsage>();
   /** ADR-154 §6: launch slots retired whose retirement has not yet reached
    *  their runtime, per task, whatever channel they were in: an agent's next
    *  spawn launches there only once they have (`retireLeasedLaunch`). */
@@ -779,6 +813,11 @@ export class Orchestrator {
     return () => this.hostSubscribers.delete(fn);
   }
 
+  subscribeEngineUsageFrames(fn: EngineUsageSubscriber): () => void {
+    this.engineUsageSubscribers.add(fn);
+    return () => this.engineUsageSubscribers.delete(fn);
+  }
+
   /**
    * The cloud credential composer changed the MCP view it serves for a task.
    * Its committed lease view, not the independently delivered channel spec,
@@ -896,6 +935,30 @@ export class Orchestrator {
     }
   }
 
+  private emitEngineUsage(frame: EngineUsageFrame): boolean {
+    let delivered = false;
+    for (const fn of this.engineUsageSubscribers) {
+      try {
+        delivered = fn(frame) || delivered;
+      } catch {
+        // Usage is best-effort; a broken bridge subscriber cannot affect a
+        // running agent turn.
+      }
+    }
+    return delivered;
+  }
+
+  private forgetEngineUsage(taskId: string, agentId?: string): void {
+    for (const [key, delivered] of this.lastEngineUsage) {
+      if (
+        delivered.taskId === taskId &&
+        (agentId === undefined || delivered.agentId === agentId)
+      ) {
+        this.lastEngineUsage.delete(key);
+      }
+    }
+  }
+
   // -- channel lifecycle ----------------------------------------------------
 
   registerChannelSpec(spec: ChannelEnsureInput): void {
@@ -2595,7 +2658,6 @@ export class Orchestrator {
                   task.ownerUserId,
                   apiUrl,
                   cliSecret,
-                  this.isPromptLevelSecretary(channel, agent.id),
                 ),
                 task,
               ),
@@ -4371,7 +4433,6 @@ export class Orchestrator {
                 task.ownerUserId,
                 apiUrl,
                 cliSecret,
-                this.isPromptLevelSecretary(channel, agent.id),
               ),
               task,
             ),
@@ -4588,6 +4649,7 @@ export class Orchestrator {
    * could silently restart canceled work on the new generation.
    */
   private retireRunnerGeneration(channel: Channel, agentId: string): void {
+    this.forgetEngineUsage(channel.taskId, agentId);
     const aborted = channel.interrupted.delete(agentId);
     channel.activeTurns.delete(agentId);
     channel.acceptedPrompts.delete(agentId);
@@ -4931,6 +4993,105 @@ export class Orchestrator {
   ): Promise<void> {
     if (!this.isActiveChannel(channel)) return;
     switch (event.type) {
+      case "account_usage": {
+        // Only the exact live session's cloud-leased ACCOUNT may be named on
+        // the wire. A runner default slot and the Managed Engine's task-token
+        // identity are deliberately unreportable.
+        if (channel.sessions.get(agentId) !== session) break;
+        const identity = channel.leasedIdentityByAgent.get(agentId);
+        if (!identity || identity.subject !== "account") break;
+        const agent = channel.roster.find((candidate) => candidate.id === agentId);
+        if (!agent || !isEngineUsageKind(agent.kind)) break;
+
+        const coverage = event.usage.coverage;
+        if (event.usage.status === "limited") {
+          const limitedWindows =
+            coverage?.kind === "all-windows"
+              ? event.usage.windows
+                  .filter((window) => (window.usedPercent ?? 0) >= 100)
+                  .map((window) => window.window)
+              : coverage?.kind === "window"
+                ? [coverage.window]
+                : [];
+          const causes = limitedWindows.length > 0 ? limitedWindows : [null];
+          for (const window of causes) {
+            if (window === null) {
+              if (event.usage.resetsAt === undefined) {
+                cooldownEngineAccount(identity.credentialId);
+              } else {
+                cooldownEngineAccountUntil(
+                  identity.credentialId,
+                  event.usage.resetsAt,
+                );
+              }
+            } else if (event.usage.resetsAt === undefined) {
+              cooldownEngineAccountWindow(identity.credentialId, window);
+            } else {
+              cooldownEngineAccountWindowUntil(
+                identity.credentialId,
+                window,
+                event.usage.resetsAt,
+              );
+            }
+          }
+        } else if (coverage?.kind === "window") {
+          clearEngineAccountCooldownWindow(
+            identity.credentialId,
+            coverage.window,
+          );
+        } else if (coverage?.kind === "all-windows") {
+          clearEngineAccountCooldowns(identity.credentialId);
+        }
+
+        const key = `${identity.credentialId}\0${agentId}`;
+        const payload = JSON.stringify({
+          taskId: channel.taskId,
+          engine: agent.kind,
+          credentialId: identity.credentialId,
+          status: event.usage.status,
+          resetsAt: event.usage.resetsAt,
+          usingOverage: event.usage.usingOverage,
+          windows: event.usage.windows,
+          source: event.usage.source,
+        });
+        const now = Date.now();
+        const previous = this.lastEngineUsage.get(key);
+        if (
+          previous?.payload === payload &&
+          now - previous.sentAt < ENGINE_USAGE_REFRESH_MS
+        ) {
+          break;
+        }
+        const delivered = this.emitEngineUsage({
+          kind: "engine.usage",
+          reportId: newId(),
+          taskId: channel.taskId,
+          agentId,
+          engine: agent.kind,
+          credentialId: identity.credentialId,
+          status: event.usage.status,
+          ...(event.usage.resetsAt === undefined
+            ? {}
+            : { resetsAt: event.usage.resetsAt }),
+          ...(event.usage.usingOverage === undefined
+            ? {}
+            : { usingOverage: event.usage.usingOverage }),
+          windows: event.usage.windows,
+          source: event.usage.source,
+          observedAt: event.usage.observedAt,
+        });
+        // A disconnected bridge returns false. Do not suppress the next
+        // identical observation unless this one actually reached the socket.
+        if (delivered) {
+          this.lastEngineUsage.set(key, {
+            payload,
+            sentAt: now,
+            taskId: channel.taskId,
+            agentId,
+          });
+        }
+        break;
+      }
       case "message_delta": {
         this.markActiveTurn(channel, agentId);
         channel.openTurns.add(agentId);
@@ -5065,6 +5226,7 @@ export class Orchestrator {
             agentId,
             agent,
             abortBoundaryOnRosterChange,
+            event.resetsAt,
           ))
         ) {
           break;
@@ -5488,7 +5650,6 @@ export class Orchestrator {
         task.ownerUserId,
         apiUrl,
         cliSecret,
-        this.isPromptLevelSecretary(channel, agent.id),
       );
       const boundAccountId = channel.accountByAgent.get(agentId);
       const boundAccount = boundAccountId
@@ -5586,6 +5747,7 @@ export class Orchestrator {
     agentId: string,
     agent: RosterAgent,
     abortBoundaryOnRosterChange = false,
+    resetsAt?: number,
   ): Promise<boolean> {
     if (!this.isActiveChannel(channel)) return true;
     if (channel.rosterSessionChanges.has(agentId)) {
@@ -5609,7 +5771,10 @@ export class Orchestrator {
     if (budget > MAX_ROTATIONS_PER_AGENT) return false;
 
     const current = channel.accountByAgent.get(agentId);
-    if (current) cooldownEngineAccount(current);
+    if (current) {
+      if (resetsAt === undefined) cooldownEngineAccount(current);
+      else cooldownEngineAccountUntil(current, resetsAt);
+    }
     const next = this.pickAccount(
       channel,
       agent.kind,
@@ -5698,7 +5863,6 @@ export class Orchestrator {
         task.ownerUserId,
         apiUrl,
         cliSecret,
-        this.isPromptLevelSecretary(channel, agent.id),
       );
       channel.accountByAgent.set(agentId, next.id);
       noteEngineAccountUsed(next.id);
@@ -5908,7 +6072,6 @@ export class Orchestrator {
         task.ownerUserId,
         apiUrl,
         cliSecret,
-        this.isPromptLevelSecretary(channel, agent.id),
       );
       channel.accountByAgent.set(agentId, account.id);
       noteEngineAccountUsed(account.id);
@@ -6161,6 +6324,7 @@ export class Orchestrator {
     this.channelSpecs.delete(taskId);
     const ch = this.channels.get(taskId);
     if (!ch) return Promise.resolve();
+    this.forgetEngineUsage(taskId);
     // Invalidate the generation BEFORE the first await. Browser setup and the
     // start/reconcile factory continuations all check this identity, so none
     // can repopulate an orphan channel while its sessions close.
@@ -6893,8 +7057,8 @@ export function buildSystemPreamble(
           "  (at least one of the three; `default` as the model or effort clears it to",
           "  the engine's own default)",
           "- `crew remove @agent --why \"…\"`",
-          "Use the smallest crew the job needs, often none: do small work yourself and",
-          "hire only when parallel work or a different skill or model pays for itself.",
+          "Use the smallest crew the job needs, often none, and hire only when",
+          "parallel work or a different skill or model pays for itself.",
           "A new agent is idle until you `dispatch` to it, so brief it then. Remove an",
           "agent when its part is done; its handle is not reused, so hiring that",
           "persona again gives it a new one. A model change restarts that agent and drops",
@@ -6919,18 +7083,24 @@ export function buildSystemPreamble(
               "connections and persona permissions of any task agent, except native",
               "subagents: helpers your engine starts on its own would work outside the",
               "crew, unpriced and unseen by the humans, so they are switched off. Work",
-              "for another agent goes to a crew agent through `dispatch`. Your default",
-              "job is to communicate,",
+              "for another agent goes to a crew agent through `dispatch`.",
+              // One rule for who does the work, the plan's, so this section and
+              // "Your crew" cannot disagree: the crew may be nobody.
+              "Who does each step is your plan's call: do it yourself when one agent",
+              "is enough, hand it to the crew when parallel work or another skill or",
+              "model pays for itself. A human's request for you to do something",
+              "yourself overrides the plan.",
+              "",
             ]
           : [
               "Your Secretary role is prompt-guided, not tool-restricted. You have the",
               "same normal tools, approved MCP connections, model choice, and persona",
               "permissions as any other task agent. Your default job is to communicate,",
+              "coordinate, and dispatch implementation work rather than doing it yourself.",
+              "If the human explicitly asks YOU to make a change, you may use those tools",
+              "and do it directly; otherwise hand mutations to a crew agent.",
+              "",
             ]),
-        "coordinate, and dispatch implementation work rather than doing it yourself.",
-        "If the human explicitly asks YOU to make a change, you may use those tools",
-        "and do it directly; otherwise hand mutations to a crew agent.",
-        "",
       ]
     : [];
   const groupMessageBrief = isSecretary
@@ -7280,7 +7450,7 @@ export function buildSystemPreamble(
               ? ", `todo list|add|edit|remove|claim|done`"
               : "") +
             (agent.permissions?.includes("previews.write")
-              ? ", `preview add <name> <port>`"
+              ? ", `preview add|enable|public <name>`"
               : "") +
             (agent.permissions?.includes("projects.write")
               ? ", `project create --name --repo`"
@@ -7355,8 +7525,10 @@ export function buildSystemPreamble(
           ...(agent.permissions?.includes("previews.write")
             ? [
                 "**Previews:** started a dev server? `preview add <name>",
-                "<containerPort>` exposes it so the human can open it (they",
-                "enable it from the task's preview menu).",
+                "<containerPort>` registers it, then `preview enable <name>` turns",
+                "it on and prints its URL: give that URL to the humans. It needs",
+                "a sign-in; `preview public <name>` makes the task's previews",
+                "a link anyone can open — only when a human asks for that.",
               ]
             : []),
           "",

package/lib/task-credential-cleanup.ts

@@ -64,7 +64,8 @@ export interface TaskCredentialCleanupDeps {
   db?: Db;
   hooks: TaskCredentialCleanupHooks;
   removePath?: (row: HostCredentialCleanupPath) => Promise<void>;
-  /** Full cleanup only: destroy one exact runtime and prove it absent. */
+  /** Full cleanup under the cloud's taskDown (`reason: "teardown"`) only:
+   *  destroy one exact runtime and prove it absent. */
   destroyRuntime?: (request: {
     taskId: string;
     runEpoch: number;
@@ -464,9 +465,18 @@ export class TaskCredentialCleanupCoordinator {
     }
 
     // A whole-task cleanup may prove absence by destroying the exact writable
-    // runtime instead. Selective removal must never take this broader action.
+    // runtime instead, but ONLY inside the cloud's taskDown of this run (the
+    // durable reason `teardown` has no other source). Every other cleanup —
+    // boot recovery, a fence escalation, stop, park, assignment — defers: the
+    // gate stays closed, the pending witness and inventory rows stay, and the
+    // registry's retry tries the exact paths again later. A failed exec is
+    // not proof of absence; Docker briefly gone (an OrbStack update,
+    // 2026-10-20) once turned this fallback into task-down.sh on every live
+    // task, deleting their worktrees. Selective removal must never take this
+    // broader action either.
     if (
       !consumersFailed &&
+      request.reason === "teardown" &&
       request.credentialIds === undefined &&
       failed.length > 0
     ) {

package/lib/task-environment/machine-task-up.ts

@@ -1015,7 +1015,8 @@ export function createMachineHostTaskEnvironmentProvider(
           // timeouts bound the wait). A teardown left for later could take a
           // replacement, which reuses the task's machine name.
           const late = await provisioning.catch(() => null);
-          if (late) await late.handle.teardown().catch(() => {});
+          // A reused machine holds the task's work: stopped, never destroyed.
+          if (late) await (late.reused ? late.handle.stop() : late.handle.teardown()).catch(() => {});
         }
         throw error;
       }
@@ -1043,7 +1044,10 @@ export function createMachineHostTaskEnvironmentProvider(
       const abandon = (): Promise<void> => {
         over = true;
         abandoning ??= (async () => {
-          await handle.teardown().catch(() => {});
+          // Only a machine this start launched is destroyed. One it reused (a
+          // Resume of a stopped machine) holds the task's work on its disk, so
+          // a failed start stops it again and the next Resume tries afresh.
+          await (provisioned.reused ? handle.stop() : handle.teardown()).catch(() => {});
           await joinBounded(begun, deps.abandonJoinMs ?? ABANDON_JOIN_MS);
         })();
         return abandoning;

package/lib/task-environment/machine.ts

@@ -862,6 +862,7 @@ export function createMachineTaskEnvironmentProvider(
           `machine ${machineId} state is unknown: ${existing.detail ?? "no detail"}`,
         );
       }
+      const reused = existing.state !== "absent";
       if (existing.state === "absent") {
         const launched = await deps.machines.launch({
           taskId,
@@ -935,7 +936,7 @@ export function createMachineTaskEnvironmentProvider(
           );
         }
       }
-      return { handle, result: handle.descriptor };
+      return { handle, result: handle.descriptor, reused };
     },
 
     async reconstruct(

package/lib/task-environment/types.ts

@@ -349,6 +349,10 @@ export interface TaskEnvironmentProvisioned<TResult, TTeardownResult = void> {
   handle: TaskEnvironmentHandle<TTeardownResult>;
   /** Provider launch result retained for rolling wire compatibility. */
   result: TResult;
+  /** The provider reused an environment that already existed — a Resume's
+   *  stopped machine, whose disk holds the task's work — rather than creating
+   *  it. A failed start stops such an environment; it never destroys it. */
+  reused?: boolean;
 }
 
 export interface TaskEnvironmentProvider<

package/package.json

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

package/scripts/agent/task-down.sh

@@ -5,6 +5,13 @@
 # 2. rm -rf the whole task dir — workspace + task-private Git repositories.
 #    Host caches under projects/<id>/host-cache.git persist.
 # 3. Persist final state: status=killed (unless already error/shipped).
+#
+# Destruction needs explicit terminal intent: the runner sets
+# UAI_TASK_DOWN_TERMINAL=1 only on the cloud taskDown path (a task close or
+# orphan GC). Without it the script refuses before touching Docker or disk —
+# a stray caller (recovery, a credential-cleanup fallback, an operator
+# running the script by hand) must never delete a live task's worktree
+# (2026-10-20: a cleanup fallback did, while Docker was briefly gone).
 
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -20,6 +27,12 @@ if [ "${#task_id}" -gt 128 ] ||
    [[ ! "$task_id" =~ ^[a-z0-9][a-z0-9_-]*$ ]]; then
   emit_err "BAD_ARGS" "invalid task id" "task identity validation"
 fi
+# Before UAI_TASK_ID is set: a refusal must not mark the live task errored.
+if [ "${UAI_TASK_DOWN_TERMINAL:-}" != "1" ]; then
+  emit_err "BAD_ARGS" \
+    "task-down requires terminal intent (UAI_TASK_DOWN_TERMINAL=1, set only by the cloud taskDown); refusing to destroy task $task_id" \
+    "terminal intent"
+fi
 UAI_TASK_ID="$task_id"
 setup_err_trap
 validate_task_runtime_selection

package/scripts/agent/task-up.sh

@@ -1453,9 +1453,39 @@ while IFS= read -r project_obj; do
       git_host_control -C "$worktree_repo_dir" worktree repair \
         "$worktree_target" 2>/dev/null || true
     fi
+  elif [ -n "$task_branch" ] && [ "$task_branch" != "null" ] \
+       && [ "$task_branch" != "$project_default" ] \
+       && ! git_host_control -C "$worktree_repo_dir" rev-parse --verify --quiet \
+            "refs/heads/$task_branch" >/dev/null 2>&1 \
+       && git_host_control -C "$worktree_repo_dir" rev-parse --verify --quiet \
+            "refs/remotes/origin/$task_branch^{commit}" >/dev/null 2>&1; then
+    # The worktree is gone but the task's branch is on the remote (a lost
+    # task directory, 2026-10-20: Resume rebuilt from the base, putting the
+    # agents on the wrong code with the pushed commits out of sight). The
+    # fetch above is fresh — a missing worktree makes a failed fetch fatal —
+    # so continue from the pushed branch, never the base.
+    step "WORKTREE_FAILED" "git worktree add from origin/$task_branch ($project_id)"
+    log "worktree for $project_slug missing — restoring it from origin/$task_branch"
+    # The base this task branched from, as nearly as the remote can tell:
+    # where the task branch leaves the default branch.
+    env_schema_oid=$(git_host_control -C "$mirror_dir" merge-base \
+      "refs/remotes/origin/$task_branch" "refs/remotes/origin/$project_default" \
+      2>/dev/null || true)
+    if [ -n "$env_schema_oid" ]; then
+      record_env_schema_base "$project_id" "oid $env_schema_oid" \
+        || log "warning: could not record the .env.schema base for $project_id; its keys without a binding are withheld"
+    fi
+    # --no-track: the sanitizer above already wrote this branch's upstream.
+    if ! git_host_control -C "$worktree_repo_dir" worktree add --no-track \
+      "$worktree_target" -b "$task_branch" "refs/remotes/origin/$task_branch"; then
+      emit_err "WORKTREE_FAILED" \
+        "could not restore the task worktree from origin/$task_branch for $repo_url" \
+        "git worktree add from origin/$task_branch ($project_id)"
+    fi
   elif git_host_control -C "$worktree_repo_dir" rev-parse --verify --quiet \
        "refs/remotes/origin/$project_default" >/dev/null 2>&1; then
     # Normal case: branch the task worktree off origin/<defaultBranch>.
+    # Only when the remote has no branch of this task's yet.
     step "WORKTREE_FAILED" "git worktree add ($project_id)"
     # The same commit the task repository just copied, read where the task
     # never writes: the host cache, under this project's lock.

package/src/main.ts

@@ -285,6 +285,7 @@ import { hostCommands, hostEvents, setManagedHostRestartHook } from "./index";
 import { EventOutbox, transmitEventOutbox } from "./event-outbox";
 import {
   HostErrorCode,
+  ENGINE_USAGE_PROTOCOL_FEATURE,
   EVENT_REPLAY_PROTOCOL_FEATURE,
   GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
   GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
@@ -1486,6 +1487,7 @@ function buildCapabilities(): HostCapabilities {
       HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE,
       HOST_ENGINE_ACCOUNT_MANAGE_PROTOCOL_FEATURE,
       HOST_ENGINE_DISCONNECT_PROTOCOL_FEATURE,
+      ENGINE_USAGE_PROTOCOL_FEATURE,
       LIVE_ROSTER_EDIT_PROTOCOL_FEATURE,
       AGENT_TOKEN_GENERATION_PROTOCOL_FEATURE,
       // The echo adapter cannot execute the in-task CLI. Advertising typed
@@ -2874,6 +2876,11 @@ async function connect(): Promise<void> {
       return false;
     }
   };
+  const stopEngineUsageSubscription = getOrchestrator().subscribeEngineUsageFrames(
+    (frame) => {
+      return sendRemoteOperationFrame(frame);
+    },
+  );
 
   let projectEnvOperationTail = Promise.resolve();
   const projectEnvGenerationIsCurrent = (): boolean =>
@@ -2916,6 +2923,7 @@ async function connect(): Promise<void> {
   };
 
   const cleanup = (): void => {
+    stopEngineUsageSubscription();
     // Connection loss revokes the serving gate before deferred transport
     // cleanup yields. A late close from a superseded socket must not revoke a
     // replacement generation that has already committed its fresh snapshot.

package/src/protocol.ts

@@ -156,6 +156,60 @@ export const HOST_ENGINE_ACCOUNT_MANAGE_PROTOCOL_FEATURE =
   "host-engine-account-manage-v1";
 export const HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE =
   "host-engine-account-scopes-v1";
+/** AI-account usage (ADR-157 slice 3, amended 2026-10-21): the host reports
+ * what an engine CLI said about the account an agent runs on — Claude Code's
+ * `rate_limit_event`, Codex's `account/rateLimits` — and the reset time of a
+ * cut-off, as `engine.usage` frames. Reports are best-effort and
+ * self-superseding: a lost one is replaced by the next. The cloud keeps the
+ * latest per account and never asks the provider itself (subscription
+ * sign-ins are for the engine CLIs only). A host advertises this once it
+ * sends the frames; the cloud needs nothing from a host without it. */
+export const ENGINE_USAGE_PROTOCOL_FEATURE = "engine-usage-v1";
+export const MAX_ENGINE_USAGE_WINDOWS = 8;
+
+/** One usage window of an AI account, in the engine's own terms. Every
+ *  measurement is optional: an engine reports what it reports. */
+export interface EngineUsageWindow {
+  /** The engine's name for the window: Claude's `rateLimitType`
+   *  (`five_hour`, `seven_day`, `seven_day_opus`, …) or Codex's `primary` /
+   *  `secondary`. At most 64 characters. */
+  window: string;
+  /** Window length in minutes. */
+  windowMinutes?: number;
+  /** Share of the window used, 0–100. */
+  usedPercent?: number;
+  /** When the window resets, epoch ms. */
+  resetsAt?: number;
+}
+
+/** One usage report for one leased AI account (ADR-154 `credentialId`).
+ *  Accounts that are not cloud credentials (a host's own default slot) are
+ *  never reported. */
+export interface EngineUsageFrame {
+  kind: "engine.usage";
+  /** Host-minted, unique per report; a repeat is ignored. */
+  reportId: string;
+  taskId: string;
+  agentId: string;
+  engine: "claude" | "codex" | "grok" | "cursor" | "opencode";
+  /** The `uai_credentials` id the agent's session runs on. */
+  credentialId: string;
+  /** `allowed`: working; `warning`: the engine says it is close to a limit;
+   *  `limited`: cut off until `resetsAt` (or an unknown time). */
+  status: "allowed" | "warning" | "limited";
+  /** When a `limited` account should work again, epoch ms, if known. */
+  resetsAt?: number;
+  /** Whether the engine says it is now billing past the plan (Claude
+   *  "overage"), when it says. */
+  usingOverage?: boolean;
+  windows: EngineUsageWindow[];
+  /** What the report was read from. */
+  source: "claude-rate-limit-event" | "codex-rate-limits" | "error-text";
+  /** When the engine said it, epoch ms (host clock). The cloud keeps the
+   *  newest per account, so a late report never overwrites a newer one. */
+  observedAt: number;
+}
+
 /** ADR-049 addendum: live roster edits. On channel.ensure the host diffs the
  * live roster against the spec — an agent whose kind, model or effort changed
  * has its session recycled so the reconciler respawns it on the new settings,
@@ -4806,6 +4860,7 @@ export type HostToCloud =
   // cloud's replay watermark only applies within a matching boot. Optional
   // for pre-103 hosts (which also never send seq'd events).
   | { kind: "auth"; token: string; hostId: string; bootId?: string }
+  | EngineUsageFrame
   | { kind: "host.capabilities"; capabilities: HostCapabilities }
   | {
       kind: "host.inventory.page";