@anusornneal/chat-relay 0.9.1 → 0.10.0

package/README.md

@@ -35,7 +35,7 @@ From any directory:
 npx @anusornneal/chat-relay@latest remote
 ```
 
-On the first run, Chat Relay opens browser-based device authorization. Sign in, approve the computer, then return to the terminal.
+On the first run, Chat Relay opens browser-based device authorization. Choose **Continue with Google and authorize computer**, sign in with the same Google account used for the ChatGPT connector, then return to the terminal. Device sign-in requires configured Google OAuth and does not accept a local username/password.
 
 The CLI saves the device credentials in your user profile, so later you can reconnect with the same command:
 

package/agent/connection-state.mjs

@@ -73,7 +73,8 @@ export class AgentConnectionState {
     const connectedAtMs = this.connectedAt ? Date.parse(this.connectedAt) : NaN;
     this.disconnectedAt = disconnectedAt;
     this.lastDisconnectedAt = disconnectedAt;
-    this.lastCloseCode = Number.isFinite(Number(code)) ? Number(code) : null;
+    const closeCode = code === null || code === undefined ? NaN : Number(code);
+    this.lastCloseCode = Number.isFinite(closeCode) ? closeCode : null;
     this.lastDisconnectReason = cleanReason(reason);
     this.lastConnectionDurationMs = Number.isFinite(connectedAtMs)
       ? Math.max(0, Math.trunc(Number(now) - connectedAtMs))

package/agent/heartbeat-ack-watchdog.mjs

@@ -0,0 +1,89 @@
+export const HEARTBEAT_ACK_TIMEOUT_REASON = "heartbeat_ack_timeout";
+
+export function heartbeatAckDecision({ now, deadlineAt }) {
+  const currentTime = Number(now);
+  const deadline = Number(deadlineAt);
+  if (!Number.isFinite(currentTime) || !Number.isFinite(deadline)) {
+    return { timedOut: false, remainingMs: null, overdueMs: 0 };
+  }
+  if (currentTime <= deadline) {
+    return { timedOut: false, remainingMs: deadline - currentTime, overdueMs: 0 };
+  }
+  return { timedOut: true, remainingMs: 0, overdueMs: currentTime - deadline };
+}
+
+export class HeartbeatAckWatchdog {
+  constructor(options) {
+    this.timeoutMs = Number(options.timeoutMs);
+    this.onTimeout = options.onTimeout;
+    this.now = options.now ?? Date.now;
+    this.setTimer = options.setTimer ?? setTimeout;
+    this.clearTimer = options.clearTimer ?? clearTimeout;
+    this.timer = null;
+    this.active = false;
+    this.lastAckAt = null;
+    this.deadlineAt = null;
+    this.lastTimeout = null;
+  }
+
+  start(now = this.now()) {
+    this.active = true;
+    this.lastAckAt = Number(now);
+    this.#arm();
+  }
+
+  acknowledge(now = this.now()) {
+    if (!this.active) return;
+    this.lastAckAt = Number(now);
+    this.#arm();
+  }
+
+  stop() {
+    this.active = false;
+    this.deadlineAt = null;
+    if (this.timer !== null) this.clearTimer(this.timer);
+    this.timer = null;
+  }
+
+  snapshot(now = this.now()) {
+    const decision = heartbeatAckDecision({ now, deadlineAt: this.deadlineAt });
+    return {
+      active: this.active,
+      timeoutMs: this.timeoutMs,
+      lastAckAt: this.lastAckAt === null ? null : new Date(this.lastAckAt).toISOString(),
+      deadlineAt: this.deadlineAt === null ? null : new Date(this.deadlineAt).toISOString(),
+      remainingMs: this.active ? decision.remainingMs : null,
+      lastTimeoutReason: this.lastTimeout?.reason ?? null,
+      lastTimedOutAt: this.lastTimeout ? new Date(this.lastTimeout.detectedAt).toISOString() : null,
+      lastTimeoutOverdueMs: this.lastTimeout?.overdueMs ?? null,
+    };
+  }
+
+  #arm() {
+    if (this.timer !== null) this.clearTimer(this.timer);
+    this.deadlineAt = this.lastAckAt + this.timeoutMs;
+    const delay = Math.max(1, this.deadlineAt - this.now() + 1);
+    this.timer = this.setTimer(() => this.#check(), delay);
+    this.timer?.unref?.();
+  }
+
+  #check() {
+    this.timer = null;
+    if (!this.active) return;
+    const detectedAt = Number(this.now());
+    const decision = heartbeatAckDecision({ now: detectedAt, deadlineAt: this.deadlineAt });
+    if (!decision.timedOut) {
+      this.#arm();
+      return;
+    }
+    this.active = false;
+    this.lastTimeout = {
+      reason: HEARTBEAT_ACK_TIMEOUT_REASON,
+      lastAckAt: this.lastAckAt,
+      deadlineAt: this.deadlineAt,
+      detectedAt,
+      overdueMs: decision.overdueMs,
+    };
+    this.onTimeout({ ...this.lastTimeout, timeoutMs: this.timeoutMs });
+  }
+}

package/agent/local-agent.mjs

@@ -7,6 +7,10 @@ import { CapabilityScheduler } from "./capability-scheduler.mjs";
 import { AgentConnectionState } from "./connection-state.mjs";
 import { buildAgentHello } from "./protocol.mjs";
 import { AgentLifecycle, AGENT_RESTART_EXIT_CODE } from "./lifecycle.mjs";
+import {
+  HeartbeatAckWatchdog,
+  HEARTBEAT_ACK_TIMEOUT_REASON,
+} from "./heartbeat-ack-watchdog.mjs";
 
 const relayUrl = process.env.RELAY_URL;
 const agentToken = process.env.AGENT_TOKEN;
@@ -66,8 +70,25 @@ let reauthorizationRequired = false;
 let activeSocket = null;
 let reconnectTimer = null;
 let heartbeatTimer = null;
+let transportHeartbeatTimer = null;
+let transportPongDeadlineTimer = null;
 let stopping = false;
 
+const TRANSPORT_PING_MS = Math.max(5000, Math.min(Number(process.env.AGENT_TRANSPORT_PING_MS) || 20000, 60000));
+const TRANSPORT_PONG_TIMEOUT_MS = Math.max(3000, Math.min(Number(process.env.AGENT_TRANSPORT_PONG_TIMEOUT_MS) || 8000, 30000));
+const FAST_RECONNECT_MS = Math.max(100, Math.min(Number(process.env.AGENT_FAST_RECONNECT_MS) || 250, 5000));
+const FAST_RECONNECT_STABLE_MS = Math.max(5000, Math.min(Number(process.env.AGENT_FAST_RECONNECT_STABLE_MS) || 30000, 300000));
+const HEARTBEAT_ACK_TIMEOUT_MS = Math.max(15000, Math.min(Number(process.env.AGENT_HEARTBEAT_ACK_TIMEOUT_MS) || 45000, 180000));
+const heartbeatAckWatchdog = new HeartbeatAckWatchdog({
+  timeoutMs: HEARTBEAT_ACK_TIMEOUT_MS,
+  onTimeout: () => {
+    const socket = activeSocket;
+    if (!socket || socket.readyState !== WebSocket.OPEN) return;
+    connectionState.markSocketError(HEARTBEAT_ACK_TIMEOUT_REASON);
+    try { socket.terminate(); } catch {}
+  },
+});
+
 function currentWorkSummary() {
   const terminal = terminals.observability();
   const terminalExec = scheduler.snapshot().terminalExec || {};
@@ -125,10 +146,11 @@ async function handlePayload(payload) {
         allowedRoots: files.getRoots(),
         reconnectMs: connectionState.baseReconnectMs,
         connection: { ...connectionState.snapshot(), processId: process.pid },
+        heartbeatAckWatchdog: heartbeatAckWatchdog.snapshot(),
         lifecycle: lifecycle.snapshot(),
         terminalContinuity: {
           processId: process.pid,
-          activeSessions: terminals.list().filter((session) => session.status === "running").length,
+          ...terminals.getContinuityConfig(),
         },
         protocol: {
           protocolVersion: agentHello.protocolVersion,
@@ -250,9 +272,39 @@ function clearReconnectTimer() {
 }
 
 function stopHeartbeat() {
-  if (!heartbeatTimer) return;
-  clearInterval(heartbeatTimer);
-  heartbeatTimer = null;
+  heartbeatAckWatchdog.stop();
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+  if (transportHeartbeatTimer) {
+    clearInterval(transportHeartbeatTimer);
+    transportHeartbeatTimer = null;
+  }
+  if (transportPongDeadlineTimer) {
+    clearTimeout(transportPongDeadlineTimer);
+    transportPongDeadlineTimer = null;
+  }
+}
+
+function armTransportPongDeadline(socket) {
+  if (transportPongDeadlineTimer) clearTimeout(transportPongDeadlineTimer);
+  transportPongDeadlineTimer = setTimeout(() => {
+    if (socket !== activeSocket || socket.readyState !== WebSocket.OPEN) return;
+    connectionState.markSocketError("transport_pong_timeout");
+    try { socket.terminate(); } catch {}
+  }, TRANSPORT_PONG_TIMEOUT_MS);
+}
+
+function sendTransportPing(socket) {
+  if (socket !== activeSocket || socket.readyState !== WebSocket.OPEN) return;
+  try {
+    socket.ping();
+    armTransportPongDeadline(socket);
+  } catch (error) {
+    connectionState.markSocketError(error instanceof Error ? error.message : "transport_ping_failed");
+    try { socket.terminate(); } catch {}
+  }
 }
 
 function sendHeartbeat(socket) {
@@ -276,6 +328,7 @@ function sendHeartbeat(socket) {
         lastDisconnectReason: connectionState.lastDisconnectReason,
         lastConnectionDurationMs: connectionState.lastConnectionDurationMs,
         lastSocketError: connectionState.lastSocketError,
+        heartbeatAckWatchdog: heartbeatAckWatchdog.snapshot(now),
         queues: scheduler.snapshot(),
       },
     }));
@@ -285,8 +338,10 @@ function sendHeartbeat(socket) {
 
 function startHeartbeat(socket) {
   stopHeartbeat();
+  heartbeatAckWatchdog.start();
   sendHeartbeat(socket);
   heartbeatTimer = setInterval(() => sendHeartbeat(socket), connectionState.heartbeatMs);
+  transportHeartbeatTimer = setInterval(() => sendTransportPing(socket), TRANSPORT_PING_MS);
 }
 
 function sendSocketResponse(socket, requestId, payload, meta) {
@@ -296,8 +351,12 @@ function sendSocketResponse(socket, requestId, payload, meta) {
 
 function scheduleReconnect(code, reason) {
   if (stopping || reauthorizationRequired) return;
+  const stableConnectionMs = connectionState.connectedAt
+    ? Math.max(0, Date.now() - Date.parse(connectionState.connectedAt))
+    : 0;
   connectionState.markDisconnected(code, reason);
-  const delay = connectionState.nextDelay();
+  const isTransientAbnormalClose = Number(code) === 1006 && stableConnectionMs >= FAST_RECONNECT_STABLE_MS;
+  const delay = isTransientAbnormalClose ? FAST_RECONNECT_MS : connectionState.nextDelay();
   connectionState.scheduleReconnect(delay);
   clearReconnectTimer();
   console.log(`Reconnect scheduled in ${delay}ms`);
@@ -363,6 +422,14 @@ function connect() {
     console.log("Agent connected");
   });
 
+  socket.on("pong", () => {
+    if (socket !== activeSocket) return;
+    if (transportPongDeadlineTimer) {
+      clearTimeout(transportPongDeadlineTimer);
+      transportPongDeadlineTimer = null;
+    }
+  });
+
   socket.on("message", async (raw) => {
     if (socket !== activeSocket) return;
     let message;
@@ -372,6 +439,10 @@ function connect() {
       return;
     }
 
+    if (message?.control === "agent_heartbeat_ack") {
+      heartbeatAckWatchdog.acknowledge();
+      return;
+    }
     if (message?.control === "credential_revoked") {
       requireReauthorization("credential_revoked");
       return;
@@ -437,10 +508,18 @@ function connect() {
   });
 
   socket.on("unexpected-response", (_request, response) => {
-    if (response.statusCode === 401 || response.statusCode === 403) {
-      response.resume();
+    response.resume();
+    if (socket !== activeSocket || stopping || reauthorizationRequired) return;
+    const statusCode = Number(response.statusCode) || 0;
+    if (statusCode === 401 || statusCode === 403) {
       requireReauthorization("credential_rejected");
+      return;
     }
+    activeSocket = null;
+    stopHeartbeat();
+    const reason = statusCode > 0 ? `unexpected_response_${statusCode}` : "unexpected_response";
+    connectionState.markSocketError(reason);
+    scheduleReconnect(null, reason);
   });
 
   socket.on("close", (code, reason) => {

package/agent/terminal-continuity.mjs

@@ -0,0 +1,49 @@
+const SESSION_PREFIX = "terminal";
+
+export function createTerminalSessionId(processEpoch, sessionUuid) {
+  if (typeof processEpoch !== "string" || !processEpoch) throw new Error("invalid_process_epoch");
+  if (typeof sessionUuid !== "string" || !sessionUuid) throw new Error("invalid_session_uuid");
+  return `${SESSION_PREFIX}:${processEpoch}:${sessionUuid}`;
+}
+
+export function parseTerminalSessionId(sessionId) {
+  if (typeof sessionId !== "string" || !sessionId) return null;
+  const match = /^terminal:([^:]+):([^:]+)$/.exec(sessionId);
+  if (!match) return null;
+  return { processEpoch: match[1], sessionUuid: match[2] };
+}
+
+export function terminalSessionMiss(sessionId, processEpoch) {
+  const identity = parseTerminalSessionId(sessionId);
+  if (identity && identity.processEpoch !== processEpoch) {
+    return {
+      ok: false,
+      error: "terminal_session_epoch_mismatch",
+      reason: "agent_process_restarted",
+      sessionId,
+      sessionProcessEpoch: identity.processEpoch,
+      currentProcessEpoch: processEpoch,
+      resumable: false,
+      recovery: "start_new_session",
+    };
+  }
+  return {
+    ok: false,
+    error: "session_not_found",
+    sessionId,
+    currentProcessEpoch: processEpoch,
+    resumable: false,
+  };
+}
+
+export function terminalContinuityConfig(processEpoch, activeSessions) {
+  return {
+    processEpoch,
+    activeSessions,
+    scope: "same_process",
+    preservesSessionsAcrossSocketReconnect: true,
+    preservesSessionsAcrossProcessRestart: false,
+    resumableAfterProcessRestart: false,
+    sessionIdFormat: "terminal:<processEpoch>:<sessionUuid>",
+  };
+}

package/agent/terminal-manager.mjs

@@ -2,6 +2,11 @@ import { execFile, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
+import {
+  createTerminalSessionId,
+  terminalContinuityConfig,
+  terminalSessionMiss,
+} from "./terminal-continuity.mjs";
 
 const MAX_EXEC_BUFFER = 48 * 1024;
 const MAX_SESSION_BUFFER = 256 * 1024;
@@ -524,6 +529,7 @@ export class TerminalManager {
     this.platform = options.platform ?? process.platform;
     this.shell = shellForPlatform(this.platform, options.shell);
     this.sessions = new Map();
+    this.processEpoch = options.processEpoch ?? randomUUID();
     this.batches = new Map();
     this.batchQueue = [];
     this.activeBatchJobs = 0;
@@ -646,12 +652,19 @@ export class TerminalManager {
     return [...this.sessions.values()].map((session) => this.#summary(session));
   }
 
+  getContinuityConfig() {
+    const activeSessions = [...this.sessions.values()]
+      .filter((session) => session.status === "running").length;
+    return terminalContinuityConfig(this.processEpoch, activeSessions);
+  }
+
   observability() {
     this.#cleanup();
     return {
       ok: true,
       sessions: [...this.sessions.values()].map((session) => ({
         sessionId: session.id,
+        processEpoch: session.processEpoch,
         type: session.type,
         status: session.status,
         exitCode: session.exitCode,
@@ -688,6 +701,7 @@ export class TerminalManager {
   read(sessionId, afterSeq = 0, maxChars = MAX_READ_CHARS) {
     this.#cleanup();
     const session = this.#get(sessionId);
+    if (!session) return terminalSessionMiss(sessionId, this.processEpoch);
     const limit = Math.min(Math.max(Number(maxChars) || MAX_READ_CHARS, 1024), MAX_READ_CHARS);
     const oldestSeq = session.chunks[0]?.seq ?? session.nextSeq;
     const chunks = [];
@@ -711,6 +725,7 @@ export class TerminalManager {
 
   write(sessionId, input, appendNewline = true) {
     const session = this.#get(sessionId);
+    if (!session) return terminalSessionMiss(sessionId, this.processEpoch);
     if (session.status !== "running") throw new Error("session_not_running");
     if (typeof input !== "string" || input.length === 0 || input.length > MAX_INPUT_CHARS) {
       throw new Error("invalid_input");
@@ -721,6 +736,7 @@ export class TerminalManager {
 
   async kill(sessionId) {
     const session = this.#get(sessionId);
+    if (!session) return terminalSessionMiss(sessionId, this.processEpoch);
     if (session.status !== "running") return this.#summary(session);
 
     await terminateProcessTree(this.platform, session.pid);
@@ -863,7 +879,8 @@ export class TerminalManager {
     });
 
     const session = {
-      id: randomUUID(),
+      id: createTerminalSessionId(this.processEpoch, randomUUID()),
+      processEpoch: this.processEpoch,
       type,
       command,
       cwd,
@@ -1001,6 +1018,7 @@ export class TerminalManager {
   #summary(session) {
     return {
       sessionId: session.id,
+      processEpoch: session.processEpoch,
       type: session.type,
       command: session.command,
       cwd: session.cwd,
@@ -1016,9 +1034,7 @@ export class TerminalManager {
 
   #get(sessionId) {
     if (typeof sessionId !== "string") throw new Error("invalid_session_id");
-    const session = this.sessions.get(sessionId);
-    if (!session) throw new Error("session_not_found");
-    return session;
+    return this.sessions.get(sessionId) ?? null;
   }
 
   #getBatch(batchId) {

package/cli/index.mjs

@@ -231,8 +231,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   if (command === "resume") return lifecycleAction("resume");
   if (command === "restart") return lifecycleAction("restart");
   if (command === "remote") {
-    await remote(options);
-    return 0;
+    return (await remote(options)) || 0;
   }
 
   console.error(`Unknown command: ${command}`);

package/cli/remote.mjs

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { loadConfig, saveConfig } from "./config.mjs";
 import { login, requestJson } from "./device-login.mjs";
+import { acquireRunnerOwnership, RunnerAlreadyActiveError } from "./runner-ownership.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 let stopping = false;
@@ -82,57 +83,69 @@ export async function remote(options = {}) {
     config = await login(options);
   }
 
-  if (options.allowedRoot && options.allowedRoot !== config.allowedRoots) {
-    config = { ...config, allowedRoots: options.allowedRoot };
-    saveConfig(config);
+  let ownership;
+  try {
+    ownership = await acquireRunnerOwnership({ relayUrl: config.relayUrl, agentId: config.agentId });
+  } catch (error) {
+    if (!(error instanceof RunnerAlreadyActiveError)) throw error;
+    console.error(error.message);
+    return 1;
   }
-  if (options.desktopEnabled !== undefined && Boolean(options.desktopEnabled) !== Boolean(config.desktopEnabled)) {
-    config = { ...config, desktopEnabled: Boolean(options.desktopEnabled) };
-    saveConfig(config);
-  }
-
-  printSummary(config);
-
-  while (!stopping) {
-    const child = spawnAgent(config);
-
-    const stop = () => {
-      stopping = true;
-      terminateChildTree(child);
-    };
-    process.once("SIGINT", stop);
-    process.once("SIGTERM", stop);
-
-    const result = await new Promise((resolve) => {
-      child.once("exit", (code, signal) => resolve({ code, signal }));
-    });
-
-    process.removeListener("SIGINT", stop);
-    process.removeListener("SIGTERM", stop);
-    if (stopping) break;
-
-    if (result.code === 2) {
-      stopping = true;
-      console.error("Agent authorization is no longer valid. Run chat-relay login --force, then chat-relay remote.");
-      break;
+  try {
+    if (options.allowedRoot && options.allowedRoot !== config.allowedRoots) {
+      config = { ...config, allowedRoots: options.allowedRoot };
+      saveConfig(config);
     }
-    if (result.code === 3) {
-      stopping = true;
-      console.error("Agent protocol is incompatible with the relay. Update Chat Relay, then run chat-relay remote again.");
-      break;
-    }
-
-    if (result.code === 4) {
-      console.log("Agent restart requested. Restarting local agent...");
-      continue;
+    if (options.desktopEnabled !== undefined && Boolean(options.desktopEnabled) !== Boolean(config.desktopEnabled)) {
+      config = { ...config, desktopEnabled: Boolean(options.desktopEnabled) };
+      saveConfig(config);
     }
 
-    if (shouldRestartAgent(result, stopping)) {
-      console.error(
-        `Agent stopped (code=${result.code ?? "null"}, signal=${result.signal ?? "none"}). Restarting in 2s...`,
-      );
-      await new Promise((resolve) => setTimeout(resolve, 2000));
+    printSummary(config);
+
+    while (!stopping) {
+      const child = spawnAgent(config);
+
+      const stop = () => {
+        stopping = true;
+        terminateChildTree(child);
+      };
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+
+      const result = await new Promise((resolve) => {
+        child.once("exit", (code, signal) => resolve({ code, signal }));
+      });
+
+      process.removeListener("SIGINT", stop);
+      process.removeListener("SIGTERM", stop);
+      if (stopping) break;
+
+      if (result.code === 2) {
+        stopping = true;
+        console.error("Agent authorization is no longer valid. Run chat-relay login --force, then chat-relay remote.");
+        break;
+      }
+      if (result.code === 3) {
+        stopping = true;
+        console.error("Agent protocol is incompatible with the relay. Update Chat Relay, then run chat-relay remote again.");
+        break;
+      }
+
+      if (result.code === 4) {
+        console.log("Agent restart requested. Restarting local agent...");
+        continue;
+      }
+
+      if (shouldRestartAgent(result, stopping)) {
+        console.error(
+          `Agent stopped (code=${result.code ?? "null"}, signal=${result.signal ?? "none"}). Restarting in 2s...`,
+        );
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+      }
     }
+  } finally {
+    await ownership.release();
   }
 }
 

package/cli/runner-ownership.mjs

@@ -0,0 +1,209 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+import { configDir } from "./config.mjs";
+
+const DEFAULT_STARTUP_GRACE_MS = 1_500;
+const DEFAULT_PROBE_TIMEOUT_MS = 400;
+
+export class RunnerAlreadyActiveError extends Error {
+  constructor({ agentId, relayUrl, pid }) {
+    const owner = Number.isInteger(pid) ? ` (PID ${pid})` : "";
+    super(
+      `Chat Relay agent "${agentId}" is already running for ${relayUrl}${owner}. ` +
+      "Stop the existing runner before starting another one.",
+    );
+    this.name = "RunnerAlreadyActiveError";
+    this.code = "CHAT_RELAY_RUNNER_ACTIVE";
+  }
+}
+
+function normalizeRelayUrl(relayUrl) {
+  try {
+    const url = new URL(String(relayUrl));
+    url.hash = "";
+    url.pathname = url.pathname.replace(/\/+$/, "") || "/";
+    return url.toString();
+  } catch {
+    return String(relayUrl).replace(/\/+$/, "");
+  }
+}
+
+function ownershipKey(relayUrl, agentId) {
+  return createHash("sha256")
+    .update(normalizeRelayUrl(relayUrl))
+    .update("\0")
+    .update(String(agentId))
+    .digest("hex");
+}
+
+function socketEndpoint(key, token) {
+  const name = `chat-relay-${createHash("sha256").update(key).update(token).digest("hex").slice(0, 32)}`;
+  if (process.platform === "win32") return `\\\\.\\pipe\\${name}`;
+  const base = Buffer.byteLength(path.join(os.tmpdir(), `${name}.sock`)) < 100 ? os.tmpdir() : "/tmp";
+  return path.join(base, `${name}.sock`);
+}
+
+function readMetadata(lockDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(lockDir, "owner.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+function probeOwner(metadata, timeoutMs) {
+  if (!metadata?.endpoint || !metadata?.token) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    let settled = false;
+    let response = "";
+    const socket = net.createConnection(metadata.endpoint);
+    const finish = (active) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(active);
+    };
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    socket.setEncoding("utf8");
+    socket.once("connect", () => socket.write("PING\n"));
+    socket.on("data", (chunk) => {
+      response += chunk;
+      if (response.includes("\n")) finish(response.trim() === `OWNER ${metadata.token}`);
+    });
+    socket.once("error", () => finish(false));
+    socket.once("end", () => finish(response.trim() === `OWNER ${metadata.token}`));
+  });
+}
+
+function listen(server, endpoint) {
+  return new Promise((resolve, reject) => {
+    const onError = (error) => reject(error);
+    server.once("error", onError);
+    server.listen(endpoint, () => {
+      server.removeListener("error", onError);
+      resolve();
+    });
+  });
+}
+
+function close(server) {
+  return new Promise((resolve) => server.close(() => resolve()));
+}
+
+function removeSocket(endpoint) {
+  if (process.platform !== "win32") fs.rmSync(endpoint, { force: true });
+}
+
+function removeStaleSocket(endpoint) {
+  if (process.platform === "win32" || typeof endpoint !== "string") return;
+  const allowedDirectories = new Set([path.resolve(os.tmpdir()), path.resolve("/tmp")]);
+  if (!allowedDirectories.has(path.resolve(path.dirname(endpoint)))) return;
+  if (!/^chat-relay-[a-f0-9]{32}\.sock$/.test(path.basename(endpoint))) return;
+  fs.rmSync(endpoint, { force: true });
+}
+
+function reclaim(lockDir) {
+  const staleDir = `${lockDir}.stale-${randomUUID()}`;
+  try {
+    fs.renameSync(lockDir, staleDir);
+  } catch (error) {
+    if (["ENOENT", "EACCES", "EPERM"].includes(error.code)) return false;
+    throw error;
+  }
+  fs.rmSync(staleDir, { recursive: true, force: true });
+  return true;
+}
+
+export async function acquireRunnerOwnership({
+  relayUrl,
+  agentId,
+  directory = configDir(),
+  startupGraceMs = DEFAULT_STARTUP_GRACE_MS,
+  probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS,
+} = {}) {
+  if (!relayUrl || !agentId) throw new Error("Runner ownership requires relayUrl and agentId");
+
+  const key = ownershipKey(relayUrl, agentId);
+  const locksDir = path.join(directory, "runner-locks");
+  const lockDir = path.join(locksDir, key);
+  fs.mkdirSync(locksDir, { recursive: true, mode: 0o700 });
+
+  while (true) {
+    try {
+      fs.mkdirSync(lockDir, { mode: 0o700 });
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+
+      const metadata = readMetadata(lockDir);
+      if (await probeOwner(metadata, probeTimeoutMs)) {
+        throw new RunnerAlreadyActiveError({ agentId, relayUrl, pid: metadata.pid });
+      }
+
+      let ageMs = Number.POSITIVE_INFINITY;
+      try { ageMs = Date.now() - fs.statSync(lockDir).mtimeMs; } catch {}
+      if (ageMs < startupGraceMs) {
+        await delay(Math.min(50, Math.max(1, startupGraceMs - ageMs)));
+        continue;
+      }
+      if (reclaim(lockDir)) removeStaleSocket(metadata?.endpoint);
+      else await delay(50);
+      continue;
+    }
+
+    const token = randomUUID();
+    const endpoint = socketEndpoint(key, token);
+    const metadata = {
+      version: 1,
+      pid: process.pid,
+      token,
+      endpoint,
+      relayUrl: normalizeRelayUrl(relayUrl),
+      agentId: String(agentId),
+      createdAt: new Date().toISOString(),
+    };
+    const server = net.createServer((socket) => {
+      socket.setEncoding("utf8");
+      socket.once("data", () => socket.end(`OWNER ${token}\n`));
+    });
+
+    try {
+      fs.writeFileSync(path.join(lockDir, "owner.json"), JSON.stringify(metadata), { mode: 0o600 });
+      removeSocket(endpoint);
+      await listen(server, endpoint);
+      server.unref();
+      if (process.platform !== "win32") {
+        try { fs.chmodSync(endpoint, 0o600); } catch {}
+      }
+      if (readMetadata(lockDir)?.token !== token) {
+        await close(server);
+        removeSocket(endpoint);
+        continue;
+      }
+    } catch (error) {
+      try { await close(server); } catch {}
+      removeSocket(endpoint);
+      if (readMetadata(lockDir)?.token === token) fs.rmSync(lockDir, { recursive: true, force: true });
+      throw error;
+    }
+
+    let released = false;
+    return {
+      async release() {
+        if (released) return;
+        released = true;
+        await close(server);
+        removeSocket(endpoint);
+        if (readMetadata(lockDir)?.token === token) fs.rmSync(lockDir, { recursive: true, force: true });
+      },
+    };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@anusornneal/chat-relay",
-    "version": "0.9.1",
+    "version": "0.10.0",
     "description": "Zero-checkout remote MCP agent for ChatGPT with terminal, filesystem, process, multi-user, and multi-agent support.",
     "type": "module",
     "bin": {
@@ -30,6 +30,7 @@
         "agent": "node --env-file-if-exists=.dev.vars agent/local-agent.mjs",
         "admin": "node scripts/admin.mjs",
         "test:terminal": "node test/mcp-terminal-smoke.mjs",
+        "test:stability": "node --experimental-strip-types test/relay-stability-smoke.mjs",
         "test:platform": "node test/platform-smoke.mjs",
         "test:full": "node test/multiuser-smoke.mjs",
         "test:device-auth": "node test/device-auth-smoke.mjs",
@@ -46,6 +47,7 @@
         "test:desktop": "node test/mcp-desktop-smoke.mjs",
         "test:device-management": "node test/device-management-smoke.mjs",
         "test:submission": "node test/submission-smoke.mjs",
+        "test:agent-state": "node --experimental-strip-types --test test/agent-state.test.mjs",
         "verify:review": "node scripts/verify-review-artifacts.mjs"
     },
     "dependencies": {