agent-relay-runner 0.64.0 → 0.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/config.ts

@@ -89,6 +89,16 @@ export function runtimeTokenExpiresAtFromEnv(): string | undefined {
   return process.env.AGENT_RELAY_TOKEN_EXPIRES_AT;
 }
 
+// Deadline for a freshly spawned runner's INITIAL relay registration. Reconnects after the
+// first registration retry forever (a long-lived agent rides out a relay blip), but the
+// initial handshake is bounded: a runner that can never register (a token the relay rejects,
+// an unreachable relay) must EXIT instead of hanging `active` forever — a hung runner is
+// invisible to the orchestrator's exit detection, so the spawn-parent is never notified.
+export function registrationTimeoutMsFromEnv(): number {
+  const parsed = Number(process.env.AGENT_RELAY_REGISTRATION_TIMEOUT_MS);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 60_000;
+}
+
 export function agentProfileNameFromEnv(): string | undefined {
   return process.env.AGENT_RELAY_AGENT_PROFILE;
 }

package/src/index.ts

@@ -344,5 +344,11 @@ export function detectApprovalModeFromArgs(provider: string, defaultArgs: string
 }
 
 if (import.meta.main) {
-  await main();
+  main().catch((error) => {
+    // A fatal startup failure (e.g. the runner could not register with the relay within the
+    // deadline) must exit non-zero, not hang or swallow — the orchestrator's exit detection
+    // then reports it and the spawn-parent is notified instead of waiting on a silent zombie.
+    console.error(`[agent-relay] runner fatal: ${errMessage(error)}`);
+    process.exit(1);
+  });
 }

package/src/runner-core.ts

@@ -22,7 +22,7 @@ import { ensureSessionScratch, reapSessionScratch, sweepStaleSessions, type Sess
 import { deliverBufferedMcpCall as deliverBufferedMcpOutboxCall, deliverRunnerOutboxEvent } from "./mcp-outbox";
 import { RunnerInsights } from "./runner-insights";
 import { BusyReconciler } from "./busy-reconciler";
-import { capsFromEnv, contextStateDirFromEnv, logLevelFromEnv, mcpProxyEnabledFromEnv, orchestratorBaseDirFromEnv, orchestratorUrlFromEnv, runnerInfoFileFromEnv, runnerLogFileFromEnv, runnerOutboxDirWithInfoFallback, sessionDebugEnabled, tagsFromEnv, workspaceModeFromEnv } from "./config";
+import { capsFromEnv, contextStateDirFromEnv, logLevelFromEnv, mcpProxyEnabledFromEnv, orchestratorBaseDirFromEnv, orchestratorUrlFromEnv, registrationTimeoutMsFromEnv, runnerInfoFileFromEnv, runnerLogFileFromEnv, runnerOutboxDirWithInfoFallback, sessionDebugEnabled, tagsFromEnv, workspaceModeFromEnv } from "./config";
 import {
   appliedAgentProfileMetadata,
   commandTimeoutMs,
@@ -34,6 +34,7 @@ import {
   latestClaudeResumeIdFromLogFile,
   lifecycleCapabilities,
   providerStateFromActiveWork,
+  registerWithinDeadline,
   relayBusUrl,
   runnerAgentStatus,
   runnerBusErrorAction,
@@ -447,7 +448,7 @@ export class AgentRunner {
       void this.handleCommand(type, params, commandId, command);
     });
     this.bus.on("error", (code, message) => this.handleBusError(String(code), String(message)));
-    await this.bus.connect();
+    await registerWithinDeadline(this.bus, registrationTimeoutMsFromEnv(), this.options.relayUrl, (reason) => logger.fatal("register", reason));
     this.obligationCache.start();
     this.outbox.start();
     this.sessionOutbox.start();

package/src/runner-helpers.ts

@@ -56,6 +56,36 @@ export function stripRunnerClaimedGuidance(body: string): string {
   return body.replace(RUNNER_CLAIMED_GUIDANCE_RE, "");
 }
 
+// Bound a runner's INITIAL relay registration. `connect` resolves on the first `registered`
+// frame and otherwise loops forever, so a token the relay rejects (401 at the WS upgrade)
+// hangs here silently. Race it against `timeoutMs`; on timeout, surface a fatal reason, tear
+// down the bus (stop the retry loop) and throw so the process exits and the orchestrator
+// observes it instead of a silent zombie. Reconnects after first registration stay infinite.
+export async function registerWithinDeadline(
+  bus: { connect: () => Promise<void>; close: () => Promise<void> },
+  timeoutMs: number,
+  relayUrl: string,
+  onFatal: (reason: string) => void,
+): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(
+      `runner failed to register with the relay within ${timeoutMs}ms — aborting so the orchestrator `
+      + `observes the exit instead of a silent hang (relay ${relayUrl}; check the relay is reachable `
+      + `and the runner token is valid).`,
+    )), timeoutMs);
+  });
+  try {
+    await Promise.race([bus.connect(), deadline]);
+  } catch (error) {
+    onFatal(errMessage(error));
+    await bus.close().catch(() => {});
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 export function csvTags(raw: string | undefined): string[] {
   return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
 }