agent-relay-runner 0.10.19 → 0.10.21

package/src/runner.ts

@@ -1,58 +1,120 @@
 import { hostname } from "node:os";
-import type { Message } from "agent-relay-sdk";
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { AgentProfile, ContextState, Message, ProviderCapabilities, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
 import { RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
-import type { ManagedProcess, ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus } from "./adapter";
+import { contextStateFromProbeMetrics, readContextProbeState } from "agent-relay-sdk/context-probe";
+import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
+import { messagesWithCachedAttachments } from "./attachment-cache";
 import { ClaimTracker } from "./claim-tracker";
 import { startControlServer, type ControlServer } from "./control-server";
+import { agentProfileProjectionReport } from "./profile-projection";
+import { profileUsesHostProviderGlobals } from "./profile-home";
+import { runtimeMetadata } from "./version";
 
 interface RunnerOptions {
   provider: string;
+  model?: string;
+  effort?: string;
   runnerId: string;
   instanceId: string;
   agentId?: string;
   relayUrl: string;
   token?: string;
+  tokenJti?: string;
+  tokenProfileId?: string;
+  tokenExpiresAt?: number;
+  rootTokenFallback?: boolean;
   cwd: string;
   headless: boolean;
   approvalMode: string;
   label?: string;
   rig?: string;
+  profile?: string;
+  agentProfile?: AgentProfile;
   prompt?: string;
+  systemPromptAppend?: string;
   tags: string[];
   capabilities: string[];
   providerArgs: string[];
   policyName?: string;
   spawnRequestId?: string;
+  automationId?: string;
+  automationRunId?: string;
+  workspace?: WorkspaceMetadata;
   tmuxSession?: string;
   startedAt: number;
   providerConfig: ProviderConfig;
   adapter: ProviderAdapter;
   onProviderExit?: (code: number | null) => void;
+  exitProcessOnShutdown?: boolean;
 }
 
+interface ActiveTaskClaim {
+  messageId: number;
+  taskId: number;
+  observedProviderBusy: boolean;
+}
+
+const CLAIM_RENEW_INTERVAL_MS = 5 * 60 * 1000;
+const HTTP_LIVENESS_INTERVAL_MS = 20_000;
+const HTTP_LIVENESS_LOG_INTERVAL_MS = 5 * 60 * 1000;
+const TOKEN_RENEW_RETRY_MS = 60_000;
+const UNEXPECTED_EXIT_WINDOW_MS = 2 * 60 * 1000;
+const RAPID_EXIT_MS = 30 * 1000;
+const MAX_RAPID_UNEXPECTED_EXITS = 3;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
 export class AgentRunner {
   private readonly agentId: string;
   private readonly claims = new ClaimTracker();
   private readonly http: RelayHttpClient;
   private readonly bus: RelayBusClient;
+  private currentToken?: string;
+  private currentTokenJti?: string;
+  private currentTokenProfileId?: string;
+  private currentTokenExpiresAt?: number;
   private control?: ControlServer;
   private process?: ManagedProcess;
   private stopped = false;
   private exitCommandInProgress = false;
+  private restartInProgress = false;
+  // Set for the whole unexpected-exit restart, including the pre-restart backoff
+  // sleep, so a second exit during that window can't launch a parallel restart.
+  private restartPending = false;
   private delivering = false;
   private drainTimer?: Timer;
+  private claimRenewTimer?: Timer;
+  private httpLivenessTimer?: Timer;
+  private httpLivenessInFlight = false;
+  private httpLivenessAuthFailed = false;
+  private httpLivenessLastLog?: { key: string; at: number };
+  private tokenRenewTimer?: Timer;
+  private tokenRenewInFlight = false;
+  private tokenRenewLastLog?: { key: string; at: number };
+  private processStartedAt = 0;
+  private providerSessionId = crypto.randomUUID();
+  private lifecycleAction?: "shutting-down" | "killing" | "restarting";
+  private readonly unexpectedExitTimes: number[] = [];
   private readonly pendingMessages = new Map<number, Message>();
+  private readonly activeTaskClaims = new Map<number, ActiveTaskClaim>();
+  private pendingTimelineEvent?: { status: string; id?: string; timestamp: number };
 
   constructor(private readonly options: RunnerOptions) {
     this.agentId = options.agentId ?? options.runnerId;
-    this.http = new RelayHttpClient({ baseUrl: options.relayUrl, token: options.token });
+    this.currentToken = options.token;
+    this.currentTokenJti = options.tokenJti;
+    this.currentTokenProfileId = options.tokenProfileId;
+    this.currentTokenExpiresAt = options.tokenExpiresAt;
+    const runtime = runtimeMetadata(options.provider);
+    this.http = new RelayHttpClient({ baseUrl: options.relayUrl, token: this.currentToken });
     this.bus = new RelayBusClient({
       url: relayBusUrl(options.relayUrl),
       role: "provider",
       componentId: options.runnerId,
       agentId: this.agentId,
       instanceId: options.instanceId,
-      token: options.token,
+      token: this.currentToken,
       machine: hostname(),
       capabilities: [
         ...new Set([
@@ -70,18 +132,37 @@ export class AgentRunner {
       ],
       tags: [...new Set([options.provider, ...csvTags(process.env.AGENT_RELAY_TAGS), ...options.tags, ...options.providerConfig.defaultTags, ...(options.headless ? ["headless"] : [])])],
       meta: {
+        ...runtime,
+        version: runtime.package.version,
         provider: options.provider,
+        model: options.model ?? null,
+        effort: options.effort ?? null,
+        profile: options.profile ?? null,
+        agentProfile: options.agentProfile ? appliedAgentProfileMetadata(options.provider, options.agentProfile) : null,
         runnerId: options.runnerId,
         startedAt: options.startedAt,
-        tmuxSession: options.tmuxSession ?? null,
+        tmuxSession: this.providerTerminalSession() ?? options.tmuxSession ?? null,
+        tmuxSocket: this.providerTerminalSocket() ?? null,
         policyName: options.policyName ?? null,
         spawnRequestId: options.spawnRequestId ?? null,
+        automationId: options.automationId ?? null,
+        automationRunId: options.automationRunId ?? null,
+        workspace: options.workspace ?? null,
+        workspaceMode: options.workspace?.requestedMode ?? options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE ?? null,
         runnerManaged: true,
         cwd: options.cwd,
         approvalMode: options.approvalMode,
         label: options.label ?? null,
+        auth: {
+          profileId: this.currentTokenProfileId ?? null,
+          jti: this.currentTokenJti ?? null,
+          expiresAt: this.currentTokenExpiresAt ?? null,
+          rootTokenFallback: options.rootTokenFallback === true,
+        },
         lifecycleCapabilities: lifecycleCapabilities(),
+        providerCapabilities: runtimeProviderCapabilities(options),
       },
+      heartbeatMeta: () => this.heartbeatRuntimeMeta(),
       heartbeatIntervalMs: 30_000,
       initialStatus: "idle",
     });
@@ -92,10 +173,21 @@ export class AgentRunner {
   }
 
   async run(): Promise<void> {
-    this.control = startControlServer({ onStatus: (status) => this.setProviderStatus(status) });
+    this.control = startControlServer({
+      onStatus: (status) => this.setProviderStatus(status),
+      onTerminalAttachSpec: () => this.terminalAttachSpec(),
+      onReplyObligations: () => this.http.listReplyObligations(this.agentId),
+    });
+    this.writeRunnerInfoFile();
     this.options.adapter.onStatusChange((status) => {
+      if (this.restartInProgress || this.restartPending) return;
+      const semanticStatus = typeof status === "string" ? status : status.status;
+      if (this.shouldRestartUnexpectedProviderExit(semanticStatus)) {
+        void this.restartUnexpectedProviderExit(semanticStatus);
+        return;
+      }
       this.setProviderStatus(status);
-      if (runnerShouldResolveProviderExit(status, this.exitCommandInProgress)) this.options.onProviderExit?.(status === "offline" ? 0 : 1);
+      if (runnerShouldResolveProviderExit(semanticStatus, this.exitCommandInProgress)) this.options.onProviderExit?.(semanticStatus === "offline" ? 0 : 1);
     });
     this.bus.on("message.new", (message) => this.enqueueMessage(message as Message));
     this.bus.on("command", (type, params, commandId, command) => {
@@ -104,8 +196,14 @@ export class AgentRunner {
     this.bus.on("error", (code, message) => this.handleBusError(String(code), String(message)));
     await this.bus.connect();
     this.process = await this.spawnProvider();
+    this.writeRunnerInfoFile();
+    this.processStartedAt = Date.now();
     this.publishStatus();
+    await this.deliverInitialPrompt();
     await this.bootstrapUnreadMessages();
+    this.startClaimRenewer();
+    this.startHttpLiveness();
+    this.scheduleRuntimeTokenRenewal();
     this.scheduleDrain();
   }
 
@@ -121,23 +219,37 @@ export class AgentRunner {
     }
     if (this.drainTimer) clearTimeout(this.drainTimer);
     this.drainTimer = undefined;
+    if (this.claimRenewTimer) clearInterval(this.claimRenewTimer);
+    this.claimRenewTimer = undefined;
+    if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
+    this.httpLivenessTimer = undefined;
+    if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
+    this.tokenRenewTimer = undefined;
     this.control?.stop();
     await this.bus.close();
   }
 
   private async spawnProvider(): Promise<ManagedProcess> {
+    this.providerSessionId = crypto.randomUUID();
+    const includeProviderGlobals = profileUsesHostProviderGlobals(this.options);
     const env = {
       ...process.env as Record<string, string>,
-      ...this.options.providerConfig.env,
+      ...(includeProviderGlobals ? this.options.providerConfig.env : {}),
       AGENT_RELAY_RUNNER_PORT: String(this.control!.port),
       AGENT_RELAY_RUNNER_ID: this.options.runnerId,
+      AGENT_RELAY_PROVIDER_SESSION_ID: this.providerSessionId,
       AGENT_RELAY_ID: this.agentId,
       AGENT_RELAY_URL: this.options.relayUrl,
       AGENT_RELAY_APPROVAL: this.options.approvalMode,
-      ...(this.options.token ? { AGENT_RELAY_TOKEN: this.options.token } : {}),
+      ...(this.currentToken ? { AGENT_RELAY_TOKEN: this.currentToken } : {}),
+      ...(this.currentTokenJti ? { AGENT_RELAY_TOKEN_JTI: this.currentTokenJti } : {}),
+      ...(this.currentTokenProfileId ? { AGENT_RELAY_TOKEN_PROFILE: this.currentTokenProfileId } : {}),
+      ...(this.currentTokenExpiresAt ? { AGENT_RELAY_TOKEN_EXPIRES_AT: String(this.currentTokenExpiresAt) } : {}),
     };
     const config: RunnerSpawnConfig = {
       provider: this.options.provider,
+      model: this.options.model,
+      effort: this.options.effort,
       runnerId: this.options.runnerId,
       instanceId: this.options.instanceId,
       agentId: this.agentId,
@@ -147,7 +259,11 @@ export class AgentRunner {
       approvalMode: this.options.approvalMode,
       ...(this.options.label ? { label: this.options.label } : {}),
       ...(this.options.rig ? { rig: this.options.rig } : {}),
+      ...(this.options.profile ? { profile: this.options.profile } : {}),
+      ...(this.options.agentProfile ? { agentProfile: this.options.agentProfile } : {}),
       ...(this.options.prompt ? { prompt: this.options.prompt } : {}),
+      ...(this.options.systemPromptAppend ? { systemPromptAppend: this.options.systemPromptAppend } : {}),
+      ...(this.options.tmuxSession ? { tmuxSession: this.options.tmuxSession } : {}),
       providerArgs: this.options.providerArgs,
       providerConfig: this.options.providerConfig,
       env,
@@ -159,6 +275,32 @@ export class AgentRunner {
     return this.options.adapter.spawn(config);
   }
 
+  private async terminalAttachSpec(): Promise<TerminalAttachSpec> {
+    if (!this.process) throw new Error("provider process is unavailable");
+    if (!this.options.adapter.terminalAttachSpec) throw new Error("provider does not support terminal attach");
+    return this.options.adapter.terminalAttachSpec(this.process);
+  }
+
+  private writeRunnerInfoFile(): void {
+    const file = process.env.AGENT_RELAY_RUNNER_INFO_FILE;
+    if (!file || !this.control) return;
+    try {
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, JSON.stringify({
+        agentId: this.agentId,
+        runnerId: this.options.runnerId,
+        provider: this.options.provider,
+        controlUrl: this.control.url,
+        pid: process.pid,
+        ...(this.providerTerminalSession() ? { tmuxSession: this.providerTerminalSession() } : {}),
+        ...(this.providerTerminalSocket() ? { tmuxSocket: this.providerTerminalSocket() } : {}),
+        startedAt: this.options.startedAt,
+      }, null, 2) + "\n", { mode: 0o600 });
+    } catch (error) {
+      console.error(`[runner] failed to write runner info file: ${error}`);
+    }
+  }
+
   private enqueueMessage(message: Message): void {
     if (!this.matchesMessage(message)) return;
     this.pendingMessages.set(message.id, message);
@@ -174,6 +316,16 @@ export class AgentRunner {
     }
   }
 
+  private async deliverInitialPrompt(): Promise<void> {
+    const prompt = this.options.prompt?.trim();
+    if (!prompt || !this.process || !this.options.adapter.deliverInitialPrompt) return;
+    try {
+      await this.options.adapter.deliverInitialPrompt(this.process, prompt);
+    } catch (error) {
+      console.error(`[runner] initial prompt delivery failed: ${error}`);
+    }
+  }
+
   private scheduleDrain(delayMs = 0): void {
     if (this.stopped || this.drainTimer) return;
     this.drainTimer = setTimeout(() => {
@@ -191,25 +343,50 @@ export class AgentRunner {
     this.delivering = true;
     const messages = [...this.pendingMessages.values()].sort((a, b) => a.id - b.id);
     this.pendingMessages.clear();
+    const deliverable: Message[] = [];
+    const providerAlreadyBusy = this.claims.reasons().includes("provider-turn");
     for (const message of messages) {
       if (message.claimable) {
-        const claimed = await this.http.claimMessage(message.id, this.agentId).catch(() => false);
-        if (!claimed) continue;
-        this.claims.startClaim("message", String(message.id), message.claimExpiresAt);
+        const claimed = await this.http.claimMessageResult(message.id, this.agentId).catch(() => ({ ok: false, claimExpiresAt: undefined }));
+        if (!claimed.ok) continue;
+        this.claims.startClaim("message", String(message.id), claimed.claimExpiresAt);
+        const taskId = taskIdFromMessage(message);
+        if (taskId) {
+          this.activeTaskClaims.set(message.id, { messageId: message.id, taskId, observedProviderBusy: providerAlreadyBusy });
+          this.claims.startClaim("task", String(taskId), claimed.claimExpiresAt);
+          await this.updateTaskStatus(taskId, {
+            status: "in_progress",
+            agentId: this.agentId,
+            metadata: { messageId: message.id, completedBy: "runner" },
+          }).catch((error) => console.error(`[runner] task ${taskId} in_progress update failed: ${error}`));
+        }
       }
+      deliverable.push(message);
+    }
+    if (deliverable.length === 0) {
+      this.delivering = false;
+      this.publishStatus();
+      return;
     }
     this.publishStatus();
     let failed = false;
     try {
-      await this.options.adapter.deliver(this.process, messages);
-      for (const message of messages) {
+      const prepared = await messagesWithCachedAttachments(deliverable, this.http, {
+        agentId: this.agentId,
+        onError: (message) => console.error(`[runner] ${message}`),
+      });
+      await this.options.adapter.deliver(this.process, prepared);
+      for (const message of deliverable) {
         await this.http.markRead(message.id, this.agentId).catch(() => {});
-        this.claims.finishClaim("message", String(message.id));
+        if (!taskIdFromMessage(message)) this.claims.finishClaim("message", String(message.id));
       }
     } catch (error) {
       failed = true;
       if (shouldLogDeliveryFailure(error)) console.error(`[runner] message delivery failed: ${error}`);
-      for (const message of messages) this.pendingMessages.set(message.id, message);
+      for (const message of deliverable) {
+        this.clearActiveClaim(message);
+        this.pendingMessages.set(message.id, message);
+      }
     } finally {
       this.delivering = false;
       this.publishStatus();
@@ -220,17 +397,35 @@ export class AgentRunner {
   private async handleCommand(type: string, params: Record<string, unknown>, commandId: string, command?: Record<string, unknown>): Promise<void> {
     const target = typeof command?.target === "string" ? command.target : this.agentId;
     if (target !== this.agentId && target !== this.options.runnerId) return;
-    if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.kill") return;
+    if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.reconnect" && type !== "agent.kill" && type !== "agent.compact" && type !== "agent.clearContext" && type !== "agent.injectContext" && type !== "agent.permissionDecision") return;
 
-    const exitAfterCommand = type !== "agent.restart";
-    if (exitAfterCommand) this.exitCommandInProgress = true;
+    const exitAfterCommand = type === "agent.shutdown" || type === "agent.kill";
+    if (exitAfterCommand) {
+      this.exitCommandInProgress = true;
+      this.lifecycleAction = type === "agent.kill" ? "killing" : "shutting-down";
+    } else if (type === "agent.restart") {
+      this.lifecycleAction = "restarting";
+    }
     this.claims.startClaim("command", commandId);
     this.publishStatus();
-    await this.updateCommand(commandId, "accepted");
-    await this.updateCommand(commandId, "running");
     try {
+      await this.updateCommand(commandId, "accepted");
+      await this.updateCommand(commandId, "running");
+      let providerResult: Record<string, unknown> | void = undefined;
       if (type === "agent.restart") await this.restartProvider();
-      else await this.shutdownProvider(type === "agent.kill");
+      else if (type === "agent.reconnect") this.publishStatus();
+      else if (type === "agent.compact") {
+        if (!this.options.adapter.compact || !this.process) throw new Error("provider does not support compact");
+        providerResult = await this.options.adapter.compact(this.process);
+      } else if (type === "agent.clearContext") {
+        if (!this.options.adapter.clearContext || !this.process) throw new Error("provider does not support clearContext");
+        providerResult = await this.options.adapter.clearContext(this.process);
+      } else if (type === "agent.injectContext") {
+        if (!this.process) throw new Error("provider process is unavailable");
+        providerResult = await this.injectContext(params);
+      } else if (type === "agent.permissionDecision") {
+        providerResult = await this.respondToPermissionDecision(params);
+      } else await this.shutdownProvider(type === "agent.kill", commandTimeoutMs(params));
       await this.updateCommand(commandId, "succeeded", {
         action: type,
         agentId: this.agentId,
@@ -238,6 +433,7 @@ export class AgentRunner {
         policyName: this.options.policyName,
         spawnRequestId: this.options.spawnRequestId,
         reason: typeof params.reason === "string" ? params.reason : undefined,
+        ...(providerResult ? { providerResult } : {}),
       });
     } catch (error) {
       await this.updateCommand(commandId, "failed", undefined, error instanceof Error ? error.message : String(error)).catch(() => {});
@@ -245,32 +441,136 @@ export class AgentRunner {
       this.claims.finishClaim("command", commandId);
       if (exitAfterCommand) {
         await this.http.deleteAgent(this.agentId).catch(() => {});
-        setTimeout(() => void this.stop().catch((error) => {
-          console.error(`[runner] stop after command failed: ${error}`);
-        }).finally(() => process.exit(0)), 10);
+        if (this.options.exitProcessOnShutdown !== false) {
+          setTimeout(() => void this.stop().catch((error) => {
+            console.error(`[runner] stop after command failed: ${error}`);
+          }).finally(() => process.exit(0)), 10);
+        }
       } else if (!this.stopped) {
+        this.lifecycleAction = undefined;
         this.publishStatus();
       }
     }
   }
 
+  private async injectContext(params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const content = typeof params.content === "string" ? params.content.trim() : "";
+    if (!content) throw new Error("content required");
+    const memoryIds = Array.isArray(params.memoryIds) ? params.memoryIds.filter((id): id is string => typeof id === "string") : [];
+    await this.options.adapter.deliver(this.process!, [{
+      id: 0,
+      from: "system",
+      to: this.agentId,
+      kind: "system",
+      subject: "Agent Relay memory context",
+      body: content,
+      payload: {
+        memoryInjection: true,
+        reason: typeof params.reason === "string" ? params.reason : undefined,
+        memoryIds,
+      },
+      readBy: [],
+      createdAt: Date.now(),
+    }]);
+    return { memoryIds, injectedMemoryCount: memoryIds.length };
+  }
+
+  private async respondToPermissionDecision(params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    const approvalId = typeof params.approvalId === "string" ? params.approvalId : "";
+    const decision = typeof params.decision === "string" ? params.decision : "";
+    if (!approvalId) throw new Error("approvalId required");
+    if (decision !== "approve" && decision !== "approve-session" && decision !== "deny" && decision !== "abort") {
+      throw new Error("decision must be approve, approve-session, deny, or abort");
+    }
+    const input: ProviderPermissionDecisionInput = {
+      approvalId,
+      decision: decision as ProviderPermissionDecision,
+      ...(typeof params.reason === "string" ? { reason: params.reason } : {}),
+    };
+    if (this.control?.resolvePermissionDecision(input)) {
+      return { approvalId, decision, provider: "claude" };
+    }
+    if (!this.process) throw new Error("provider process is unavailable");
+    if (!this.options.adapter.respondToPermissionDecision) throw new Error("provider does not support permission decisions");
+    const result = await this.options.adapter.respondToPermissionDecision(this.process, input);
+    return { approvalId, decision, ...(result ? { providerResult: result } : {}) };
+  }
+
   private async restartProvider(): Promise<void> {
-    if (this.process) {
-      await this.options.adapter.shutdown(this.process, {
-        graceful: true,
-        timeoutMs: this.options.providerConfig.headless.shutdownTimeoutMs,
-      });
+    this.restartInProgress = true;
+    try {
+      if (this.process) {
+        await this.options.adapter.shutdown(this.process, {
+          graceful: true,
+          timeoutMs: this.options.providerConfig.headless.shutdownTimeoutMs,
+        });
+      }
+      this.claims.clearTerminalStatus();
+      this.claims.clearWorkKind("provider-turn");
+      this.claims.clearWorkKind("subagent");
+      if (this.stopped) return;
+      this.process = await this.spawnProvider();
+      this.processStartedAt = Date.now();
+    } finally {
+      this.restartInProgress = false;
+    }
+  }
+
+  private shouldRestartUnexpectedProviderExit(status: SemanticStatus): boolean {
+    return runnerShouldRestartUnexpectedProviderExit(status, {
+      exitCommandInProgress: this.exitCommandInProgress,
+      stopped: this.stopped,
+      restartInProgress: this.restartInProgress,
+      provider: this.options.provider,
+      headless: this.options.headless,
+      hasTerminalSession: typeof this.process?.meta?.tmuxSession === "string"
+        || (this.options.adapter.supportsUnexpectedExitRestart?.() ?? false),
+    });
+  }
+
+  private async restartUnexpectedProviderExit(status: SemanticStatus): Promise<void> {
+    if (this.restartPending) return;
+    this.restartPending = true;
+    try {
+      const now = Date.now();
+      const runtimeMs = this.processStartedAt ? now - this.processStartedAt : Number.POSITIVE_INFINITY;
+      const recent = this.unexpectedExitTimes.filter((time) => now - time <= UNEXPECTED_EXIT_WINDOW_MS);
+      recent.push(now);
+      this.unexpectedExitTimes.splice(0, this.unexpectedExitTimes.length, ...recent);
+
+      if (runtimeMs < RAPID_EXIT_MS && recent.length > MAX_RAPID_UNEXPECTED_EXITS) {
+        console.error(`[runner] provider session exited ${recent.length} times within ${Math.round(UNEXPECTED_EXIT_WINDOW_MS / 1000)}s; giving up`);
+        this.setProviderStatus(status);
+        this.options.onProviderExit?.(0);
+        return;
+      }
+
+      const delayMs = Math.min(10_000, Math.max(500, 500 * recent.length));
+      console.warn(`[runner] provider session exited unexpectedly after ${Math.round(runtimeMs / 1000)}s; restarting in ${delayMs}ms`);
+      await Bun.sleep(delayMs);
+      if (this.stopped || this.exitCommandInProgress) return;
+      try {
+        await this.restartProvider();
+        this.publishStatus();
+        this.scheduleDrain();
+      } catch (error) {
+        console.error(`[runner] provider restart after unexpected exit failed: ${error}`);
+        this.setProviderStatus("error");
+        this.options.onProviderExit?.(1);
+      }
+    } finally {
+      this.restartPending = false;
     }
-    if (this.stopped) return;
-    this.process = await this.spawnProvider();
   }
 
-  private async shutdownProvider(hard: boolean): Promise<void> {
-    await this.bus.statusAsync({ agentStatus: "idle", ready: false });
+  private async shutdownProvider(hard: boolean, timeoutMs = this.options.providerConfig.headless.shutdownTimeoutMs): Promise<void> {
+    this.lifecycleAction = hard ? "killing" : "shutting-down";
+    this.publishStatus();
+    await this.bus.statusAsync({ agentStatus: "idle", ready: false, meta: { lifecycleAction: this.lifecycleAction, lifecycleActionAt: Date.now() } });
     if (this.process) {
       await this.options.adapter.shutdown(this.process, {
         graceful: !hard,
-        timeoutMs: this.options.providerConfig.headless.shutdownTimeoutMs,
+        timeoutMs,
       });
     }
     this.claims.setTerminalStatus("offline");
@@ -293,33 +593,269 @@ export class AgentRunner {
     }
   }
 
-  private setProviderStatus(status: SemanticStatus): void {
-    if (status === "busy") this.claims.setProviderBusy(true);
-    else if (status === "idle") this.claims.setProviderBusy(false);
+  private setProviderStatus(update: ProviderStatusUpdate): void {
+    const status = typeof update === "string" ? update : update.status;
+    const providerSessionId = typeof update === "string" ? undefined : update.providerSessionId;
+    if (providerSessionId && providerSessionId !== this.providerSessionId) return;
+    const reason = typeof update === "string" ? "provider-turn" : update.reason ?? "provider-turn";
+    const id = typeof update === "string" ? reason : update.id ?? reason;
+    if (typeof update !== "string" && update.timeline) {
+      this.pendingTimelineEvent = {
+        status: update.timeline.status,
+        ...(update.timeline.id ? { id: update.timeline.id } : {}),
+        timestamp: update.timeline.timestamp ?? Date.now(),
+      };
+    }
+    if (status === "busy") {
+      this.claims.clearTerminalStatus();
+      this.claims.startWork(reason, id, typeof update === "string" ? {} : {
+        label: update.label,
+        role: update.role,
+        parentId: update.parentId,
+        metadata: {
+          ...(update.metadata ?? {}),
+          ...(update.providerState ? { providerState: update.providerState } : {}),
+        },
+      });
+      if (reason === "provider-turn") {
+        for (const claim of this.activeTaskClaims.values()) claim.observedProviderBusy = true;
+      }
+    } else if (status === "idle") {
+      this.claims.clearTerminalStatus();
+      this.claims.finishWork(reason, id);
+      if (reason === "provider-turn") void this.completeObservedTaskClaims();
+    }
     else if (status === "offline" || status === "error") this.claims.setTerminalStatus(status);
+    if (typeof update !== "string") {
+      for (const kind of update.clear ?? []) this.claims.clearWorkKind(kind);
+    }
     this.publishStatus();
   }
 
   private publishStatus(): void {
     const status = this.claims.currentStatus();
     const agentStatus = runnerAgentStatus(status);
+    const activeWork = this.claims.activeWork();
+    const activeSubagents = activeWork.filter((item) => item.kind === "subagent");
+    const providerState = providerStateFromActiveWork(activeWork);
     this.bus.setSemanticStatus(status === "offline" || status === "error" ? "idle" : status);
+    const timelineEvent = this.pendingTimelineEvent;
+    this.pendingTimelineEvent = undefined;
     this.bus.status({
       agentStatus,
       ready: agentStatus !== "offline" && !this.stopped,
       meta: {
         runnerId: this.options.runnerId,
         startedAt: this.options.startedAt,
-        tmuxSession: this.options.tmuxSession ?? null,
+        tmuxSession: this.providerTerminalSession() ?? this.options.tmuxSession ?? null,
+        tmuxSocket: this.providerTerminalSocket() ?? null,
         policyName: this.options.policyName ?? null,
         spawnRequestId: this.options.spawnRequestId ?? null,
+        automationId: this.options.automationId ?? null,
+        automationRunId: this.options.automationRunId ?? null,
+        workspace: this.options.workspace ?? null,
+        workspaceMode: this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE ?? null,
+        lifecycleAction: this.lifecycleAction ?? null,
+        profile: this.options.profile ?? null,
         ...(status === "error" ? { terminalStatus: "error" } : {}),
         busyReasons: this.claims.reasons(),
+        activeWork,
+        activeSubagents,
+        activeSubagentCount: activeSubagents.length,
+        providerState,
+        auth: {
+          profileId: this.currentTokenProfileId ?? null,
+          jti: this.currentTokenJti ?? null,
+          expiresAt: this.currentTokenExpiresAt ?? null,
+          rootTokenFallback: this.options.rootTokenFallback === true,
+        },
+        ...(timelineEvent ? { timelineEvent } : {}),
         transport: this.bus.transportState,
       },
     });
   }
 
+  private startHttpLiveness(): void {
+    if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
+    void this.publishHttpLiveness();
+    this.httpLivenessTimer = setInterval(() => {
+      void this.publishHttpLiveness();
+    }, HTTP_LIVENESS_INTERVAL_MS);
+  }
+
+  private async publishHttpLiveness(): Promise<void> {
+    if (this.stopped || this.httpLivenessInFlight || this.httpLivenessAuthFailed) return;
+    this.httpLivenessInFlight = true;
+    const status = this.claims.currentStatus();
+    const agentStatus = runnerAgentStatus(status);
+    try {
+      await this.http.setStatus(this.agentId, agentStatus, this.options.instanceId);
+      await this.http.setReady(this.agentId, agentStatus !== "offline", this.options.instanceId);
+      await this.http.heartbeat(this.agentId, this.options.instanceId);
+      await this.bootstrapUnreadMessages();
+    } catch (error) {
+      if (!this.stopped) this.handleHttpLivenessFailure(error);
+    } finally {
+      this.httpLivenessInFlight = false;
+    }
+  }
+
+  private handleHttpLivenessFailure(error: unknown): void {
+    const authFailed = isHttpAuthError(error);
+    this.logHttpLivenessFailure(error, authFailed);
+    if (!authFailed) return;
+    this.httpLivenessAuthFailed = true;
+    if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
+    this.httpLivenessTimer = undefined;
+  }
+
+  private logHttpLivenessFailure(error: unknown, authFailed: boolean): void {
+    const key = httpErrorKey(error);
+    const now = Date.now();
+    if (
+      this.httpLivenessLastLog?.key === key &&
+      now - this.httpLivenessLastLog.at < HTTP_LIVENESS_LOG_INTERVAL_MS
+    ) return;
+    this.httpLivenessLastLog = { key, at: now };
+    const suffix = authFailed ? "auth failed; stopping HTTP liveness retries until restart" : String(error);
+    this.logRunnerDiagnostic(`[runner] HTTP liveness update failed: ${suffix}`);
+  }
+
+  private logRunnerDiagnostic(message: string): void {
+    if (this.options.headless) {
+      console.error(message);
+      return;
+    }
+    try {
+      const logDir = join(process.env.HOME || ".", ".agent-relay", "logs");
+      mkdirSync(logDir, { recursive: true });
+      appendFileSync(join(logDir, `runner-${safeLogName(this.agentId)}.log`), `[${new Date().toISOString()}] ${message}\n`);
+    } catch {
+      // Do not write runner diagnostics into an interactive provider TUI.
+    }
+  }
+
+  private scheduleRuntimeTokenRenewal(delayMs?: number): void {
+    if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
+    this.tokenRenewTimer = undefined;
+    if (!this.isRuntimeTokenRenewable()) return;
+    const computedDelay = delayMs ?? runtimeTokenRenewDelayMs(this.currentTokenExpiresAt!, Date.now());
+    if (computedDelay === undefined) return;
+    const schedule = runtimeTokenRenewTimerSchedule(computedDelay);
+    if (!schedule) return;
+    this.tokenRenewTimer = setTimeout(() => {
+      this.tokenRenewTimer = undefined;
+      if (!schedule.renew) {
+        this.scheduleRuntimeTokenRenewal();
+        return;
+      }
+      void this.renewRuntimeToken();
+    }, schedule.delayMs);
+  }
+
+  private isRuntimeTokenRenewable(): boolean {
+    return Boolean(
+      this.currentToken &&
+      this.currentTokenExpiresAt &&
+      this.currentTokenExpiresAt * 1000 > Date.now() &&
+      (this.currentTokenProfileId === "provider-agent" || this.currentTokenProfileId === "provider-interactive"),
+    );
+  }
+
+  private async renewRuntimeToken(): Promise<void> {
+    if (this.stopped || this.tokenRenewInFlight || !this.isRuntimeTokenRenewable()) return;
+    this.tokenRenewInFlight = true;
+    try {
+      const renewed = await this.http.renewRuntimeToken();
+      this.currentToken = renewed.token;
+      this.currentTokenJti = renewed.record.jti;
+      this.currentTokenProfileId = renewed.record.profileId ?? this.currentTokenProfileId;
+      this.currentTokenExpiresAt = renewed.record.expiresAt;
+      this.options.token = renewed.token;
+      this.options.tokenJti = renewed.record.jti;
+      this.options.tokenProfileId = this.currentTokenProfileId;
+      this.options.tokenExpiresAt = this.currentTokenExpiresAt;
+      this.http.setToken(renewed.token);
+      this.bus.setToken(renewed.token);
+      this.httpLivenessAuthFailed = false;
+      this.pendingTimelineEvent = {
+        status: "runtime-token-renewed",
+        id: renewed.record.jti,
+        timestamp: Date.now(),
+      };
+      this.bus.reconnectTransport("runtime token renewed");
+      this.publishStatus();
+      this.scheduleRuntimeTokenRenewal();
+    } catch (error) {
+      this.logRuntimeTokenRenewalFailure(error);
+      this.pendingTimelineEvent = {
+        status: "runtime-token-renewal-failed",
+        timestamp: Date.now(),
+      };
+      this.publishStatus();
+      this.scheduleRuntimeTokenRenewal(TOKEN_RENEW_RETRY_MS);
+    } finally {
+      this.tokenRenewInFlight = false;
+    }
+  }
+
+  private logRuntimeTokenRenewalFailure(error: unknown): void {
+    const key = httpErrorKey(error);
+    const now = Date.now();
+    if (
+      this.tokenRenewLastLog?.key === key &&
+      now - this.tokenRenewLastLog.at < HTTP_LIVENESS_LOG_INTERVAL_MS
+    ) return;
+    this.tokenRenewLastLog = { key, at: now };
+    this.logRunnerDiagnostic(`[runner] runtime token renewal failed: ${String(error)}`);
+  }
+
+  private heartbeatRuntimeMeta(): Record<string, unknown> | undefined {
+    const processContext = this.latestProcessContext();
+    const probeMetrics = this.latestProbeMetrics();
+    const probeContext = probeMetrics ? contextStateFromProbeMetrics(probeMetrics) : undefined;
+    const context = processContext ?? probeContext;
+    const terminalSession = this.providerTerminalSession();
+    const terminalSocket = this.providerTerminalSocket();
+    const probeModel: ProbeModelInfo | undefined = probeMetrics?.model || probeMetrics?.effort
+      ? { model: probeMetrics.model, effort: probeMetrics.effort }
+      : undefined;
+    const meta: Record<string, unknown> = {
+      providerCapabilities: runtimeProviderCapabilities(
+        this.options,
+        context ? { source: context.source, confidence: context.confidence } : undefined,
+        probeModel,
+      ),
+      ...(terminalSession ? { tmuxSession: terminalSession } : {}),
+      ...(terminalSocket ? { tmuxSocket: terminalSocket } : {}),
+    };
+    if (context) meta.context = context;
+    return meta;
+  }
+
+  private providerTerminalSession(): string | undefined {
+    return typeof this.process?.meta?.tmuxSession === "string" ? this.process.meta.tmuxSession : undefined;
+  }
+
+  private providerTerminalSocket(): string | undefined {
+    return typeof this.process?.meta?.tmuxSocket === "string" ? this.process.meta.tmuxSocket : undefined;
+  }
+
+  private latestProcessContext(): ContextState | undefined {
+    const getContext = this.process?.meta?.getContext;
+    if (typeof getContext === "function") {
+      const context = getContext();
+      if (isContextState(context)) return context;
+    }
+    const context = this.process?.meta?.context;
+    return isContextState(context) ? context : undefined;
+  }
+
+  private latestProbeMetrics() {
+    const stateDir = process.env.AGENT_RELAY_CONTEXT_STATE_DIR;
+    return readContextProbeState(this.agentId, stateDir);
+  }
+
   private matchesMessage(message: Message): boolean {
     return runnerMessageMatches(message, {
       agentId: this.agentId,
@@ -329,8 +865,61 @@ export class AgentRunner {
       capabilities: this.options.capabilities,
       defaultTags: this.options.providerConfig.defaultTags,
       defaultCapabilities: this.options.providerConfig.defaultCapabilities,
+      allowBroadTargets: this.options.agentProfile?.relay?.context !== false,
     });
   }
+
+  private startClaimRenewer(): void {
+    if (this.claimRenewTimer) return;
+    this.claimRenewTimer = setInterval(() => {
+      void this.renewActiveTaskClaims();
+    }, CLAIM_RENEW_INTERVAL_MS);
+  }
+
+  private async renewActiveTaskClaims(): Promise<void> {
+    for (const claim of this.activeTaskClaims.values()) {
+      const renewed = await this.http.renewMessageClaim(claim.messageId, this.agentId).catch(() => ({ ok: false, claimExpiresAt: undefined }));
+      if (renewed.ok) {
+        this.claims.startClaim("message", String(claim.messageId), renewed.claimExpiresAt);
+        this.claims.startClaim("task", String(claim.taskId), renewed.claimExpiresAt);
+      }
+    }
+    this.publishStatus();
+  }
+
+  private async completeObservedTaskClaims(): Promise<void> {
+    const completed = [...this.activeTaskClaims.values()].filter((claim) => claim.observedProviderBusy);
+    for (const claim of completed) {
+      const ok = await this.updateTaskStatus(claim.taskId, {
+        status: "done",
+        agentId: this.agentId,
+        body: `Runner observed provider completion for message #${claim.messageId}`,
+        metadata: { messageId: claim.messageId, completedBy: "runner" },
+      })
+        .then(() => true)
+        .catch((error) => {
+          console.error(`[runner] task ${claim.taskId} completion update failed: ${error}`);
+          return false;
+        });
+      if (!ok) continue;
+      this.activeTaskClaims.delete(claim.messageId);
+      this.claims.finishClaim("message", String(claim.messageId));
+      this.claims.finishClaim("task", String(claim.taskId));
+    }
+    if (completed.length > 0) this.publishStatus();
+  }
+
+  private async updateTaskStatus(taskId: number, input: TaskStatusInput): Promise<void> {
+    await this.http.updateTaskStatus(taskId, input);
+  }
+
+  private clearActiveClaim(message: Message): void {
+    const taskId = taskIdFromMessage(message);
+    this.claims.finishClaim("message", String(message.id));
+    if (!taskId) return;
+    this.activeTaskClaims.delete(message.id);
+    this.claims.finishClaim("task", String(taskId));
+  }
 }
 
 export function runnerMessageMatches(message: Pick<Message, "to" | "resolvedToAgent">, target: {
@@ -341,10 +930,13 @@ export function runnerMessageMatches(message: Pick<Message, "to" | "resolvedToAg
   capabilities: string[];
   defaultTags: string[];
   defaultCapabilities: string[];
+  allowBroadTargets?: boolean;
 }): boolean {
   if (message.resolvedToAgent === target.agentId) return true;
-  if (message.to === target.agentId || message.to === "broadcast") return true;
+  if (message.to === target.agentId) return true;
   if (target.label && message.to === `label:${target.label}`) return true;
+  if (target.allowBroadTargets === false) return false;
+  if (message.to === "broadcast") return true;
   if (message.to.startsWith("tag:")) {
     const tag = message.to.slice("tag:".length);
     return target.tags.includes(tag) || target.defaultTags.includes(tag) || tag === target.provider;
@@ -356,6 +948,11 @@ export function runnerMessageMatches(message: Pick<Message, "to" | "resolvedToAg
   return false;
 }
 
+export function taskIdFromMessage(message: Pick<Message, "payload">): number | undefined {
+  const taskId = message.payload?.taskId;
+  return Number.isSafeInteger(taskId) ? taskId as number : undefined;
+}
+
 function csvTags(raw: string | undefined): string[] {
   return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
 }
@@ -381,11 +978,51 @@ export function runnerShouldResolveProviderExit(status: SemanticStatus, exitComm
   return !exitCommandInProgress && (status === "offline" || status === "error");
 }
 
+export function runnerShouldRestartUnexpectedProviderExit(
+  status: SemanticStatus,
+  input: {
+    exitCommandInProgress: boolean;
+    stopped: boolean;
+    restartInProgress: boolean;
+    provider?: string;
+    headless: boolean;
+    hasTerminalSession: boolean;
+  },
+): boolean {
+  return status === "offline"
+    && !input.exitCommandInProgress
+    && !input.stopped
+    && !input.restartInProgress
+    && input.headless
+    && input.hasTerminalSession;
+}
+
+function commandTimeoutMs(params: Record<string, unknown>, fallback = 10_000): number {
+  const raw = params.timeoutMs;
+  if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return fallback;
+  return Math.min(raw, 60_000);
+}
+
 export function shouldLogDeliveryFailure(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
   return message !== "no Claude monitor connected";
 }
 
+export function runtimeTokenRenewDelayMs(expiresAtSeconds: number, nowMs = Date.now()): number | undefined {
+  const expiresAtMs = expiresAtSeconds * 1000;
+  const ttlMs = expiresAtMs - nowMs;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) return undefined;
+  const leadMs = Math.min(60 * 60 * 1000, Math.max(60_000, Math.floor(ttlMs * 0.2)));
+  const jitterMs = Math.floor(Math.random() * Math.min(30_000, Math.max(0, leadMs / 2)));
+  return Math.max(1_000, ttlMs - leadMs - jitterMs);
+}
+
+export function runtimeTokenRenewTimerSchedule(delayMs: number): { delayMs: number; renew: boolean } | undefined {
+  if (!Number.isFinite(delayMs) || delayMs <= 0) return undefined;
+  if (delayMs > MAX_TIMER_DELAY_MS) return { delayMs: MAX_TIMER_DELAY_MS, renew: false };
+  return { delayMs, renew: true };
+}
+
 function lifecycleCapabilities(): Record<string, true> {
   return {
     shutdownHard: true,
@@ -394,3 +1031,137 @@ function lifecycleCapabilities(): Record<string, true> {
     transportReconnect: true,
   };
 }
+
+interface ProbeModelInfo {
+  model?: string;
+  effort?: string;
+}
+
+function runtimeProviderCapabilities(options: RunnerOptions, contextStats?: { source: "api" | "statusline" | "hook" | "estimate"; confidence: "exact" | "reported" | "estimated" }, probeModel?: ProbeModelInfo): ProviderCapabilities {
+  const model = options.model ?? probeModel?.model;
+  const effort = options.effort ?? probeModel?.effort;
+  const modelSource = options.model ? "runtime" as const : probeModel?.model ? "provider" as const : "runtime" as const;
+  return {
+    lifecycle: {
+      managed: true,
+      shutdownHard: options.provider === "claude" ? options.headless : true,
+      restartHard: options.provider === "claude" ? options.headless : true,
+      semanticStatus: true,
+      reconnect: true,
+    },
+    model: {
+      provider: options.provider,
+      alias: model,
+      id: model,
+      effort,
+      source: modelSource,
+      confidence: options.model ? "reported" : probeModel?.model ? "reported" : "unknown",
+      lastUpdatedAt: options.startedAt,
+    },
+    session: {
+      approvalMode: options.approvalMode,
+      fileRead: true,
+      fileWrite: options.approvalMode !== "read-only",
+      shell: options.approvalMode !== "read-only",
+      source: "runtime",
+      confidence: "reported",
+      lastUpdatedAt: options.startedAt,
+    },
+    ...runtimeProviderContextCapabilities(options, contextStats),
+    ...runtimeProviderTerminalCapabilities(options),
+    source: "runtime",
+    confidence: "reported",
+    lastUpdatedAt: options.startedAt,
+  };
+}
+
+function runtimeProviderTerminalCapabilities(options: RunnerOptions): Pick<ProviderCapabilities, "terminal"> {
+  if (options.provider === "claude" && options.headless) {
+    return {
+      terminal: {
+        live: {
+          read: true,
+          write: true,
+        },
+      },
+    };
+  }
+  if (options.provider === "codex") {
+    return {
+      terminal: {
+        attach: {
+          create: true,
+          read: true,
+          write: true,
+          detach: true,
+        },
+      },
+    };
+  }
+  return {};
+}
+
+function appliedAgentProfileMetadata(provider: string, profile: AgentProfile): Record<string, unknown> {
+  const projection = provider === "claude" || provider === "codex"
+    ? agentProfileProjectionReport({ provider, profile })
+    : undefined;
+  return {
+    name: profile.name,
+    base: profile.base,
+    provider: profile.provider ?? "any",
+    relay: profile.relay,
+    instructions: {
+      repoInstructions: profile.instructions.repoInstructions,
+      globalInstructions: profile.instructions.globalInstructions,
+      appendCount: profile.instructions.append.length,
+      hasSystem: Boolean(profile.instructions.system),
+    },
+    skills: profile.skills.filter((item) => item.enabled).length,
+    plugins: profile.plugins.filter((item) => item.enabled).length,
+    mcp: { mode: profile.mcp.mode },
+    hooks: { mode: profile.hooks.mode },
+    permissions: profile.permissions,
+    projection,
+  };
+}
+
+function runtimeProviderContextCapabilities(options: RunnerOptions, contextStats?: { source: "api" | "statusline" | "hook" | "estimate"; confidence: "exact" | "reported" | "estimated" }): Pick<ProviderCapabilities, "context"> {
+  const context: NonNullable<ProviderCapabilities["context"]> = {};
+  if (contextStats) context.stats = contextStats;
+  if (options.provider === "codex" || (options.provider === "claude" && options.headless)) {
+    context.compact = true;
+    context.clear = true;
+  }
+  context.inject = true;
+  return Object.keys(context).length ? { context } : {};
+}
+
+function providerStateFromActiveWork(activeWork: Array<{ kind: string; metadata?: Record<string, unknown> }>): Record<string, unknown> | null {
+  const providerTurn = activeWork.find((item) => item.kind === "provider-turn");
+  const state = providerTurn?.metadata?.providerState;
+  return state && typeof state === "object" && !Array.isArray(state) ? state as Record<string, unknown> : null;
+}
+
+function isHttpAuthError(error: unknown): boolean {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return status === 401 || status === 403;
+}
+
+function httpErrorKey(error: unknown): string {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  if (typeof status === "number") return `status:${status}`;
+  return String(error);
+}
+
+function safeLogName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_.-]+/g, "_").slice(0, 180);
+}
+
+function isContextState(value: unknown): value is ContextState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value as Record<string, unknown>;
+  return typeof state.utilization === "number" &&
+    typeof state.lifecycleState === "string" &&
+    typeof state.source === "string" &&
+    typeof state.confidence === "string";
+}