granttap-mcp 0.8.58 → 0.8.60

package/apps/bridge/src/delivery/index.ts

@@ -5,11 +5,13 @@ import { configDir } from "../config";
 
 const LIMIT = 500;
 const MAX_AGE_MS = 7 * 24 * 60 * 60_000;
-const PROCESSING_LEASE_MS = 5 * 60_000;
+// Cover the ten-minute provider call and completion propagation before retry.
+const PROCESSING_LEASE_MS = 11 * 60_000;
 
 type DeliveryRecord = {
   state: "processing" | "completed";
   updatedAt: number;
+  processingAcknowledged?: boolean;
 };
 
 export type DeliveryStart = "started" | "processing" | "completed";
@@ -55,6 +57,19 @@ function save(records: Record<string, DeliveryRecord>, now: number): void {
   chmodSync(deliveryLedgerPath(), 0o600);
 }
 
+/** Only validated provider work may emit a non-terminal processing receipt. */
+export function acknowledgeProcessingDelivery(messageId: string, now = Date.now()): void {
+  const records = load();
+  if (records[messageId]?.state !== "processing") return;
+  records[messageId] = { state: "processing", updatedAt: now, processingAcknowledged: true };
+  save(records, now);
+}
+
+export function processingDeliveryAcknowledged(messageId: string): boolean {
+  const record = load()[messageId];
+  return record?.state === "processing" && record.processingAcknowledged === true;
+}
+
 /** Acquire a durable processing lease before invoking an agent. */
 export function beginDelivery(messageId: string, now = Date.now()): DeliveryStart {
   const records = load();

package/apps/bridge/src/managed-admission/index.ts

@@ -3,10 +3,12 @@ import { loadAccountLink } from "../account-recovery/link";
 
 /** Account computer identity is stable across QR rooms and provider sessions. */
 export function managedAdmissionOptions(config: PeerConfig,
-  request: typeof fetch = fetch): Pick<RelayClientOptions, "upgradeHeaders"> {
+  request: typeof fetch = fetch): Pick<RelayClientOptions, "upgradeHeaders" | "connectionLeaseExpiresAt"> {
   const url = new URL(config.relayUrl);
   if (config.role !== "machine" || url.protocol !== "wss:" || url.hostname !== "relay.granttap.com") return {};
-  return { upgradeHeaders: async (): Promise<Record<string, string>> => {
+  let expiresAt: number | null = null;
+  return { connectionLeaseExpiresAt: () => expiresAt,
+    upgradeHeaders: async (): Promise<Record<string, string>> => {
     const account = loadAccountLink();
     if (!account) return {};
     const response = await request("https://granttap.com/api/account/machine/admission", {
@@ -25,6 +27,7 @@ export function managedAdmissionOptions(config: PeerConfig,
       || body.expiresAt <= Date.now() || body.expiresAt > Date.now() + 360_000) {
       throw new Error("Managed admission returned an invalid lease.");
     }
+    expiresAt = body.expiresAt;
     return { "X-GrantTap-Admission": body.ticket };
   } };
 }

package/apps/bridge/src/monitor/README.md

@@ -11,3 +11,10 @@ Backbone requests responsive.
 
 Integration tests remain in `tests/monitor`; background publication tests live
 beside `mesh-publication`. This module uses the repository MIT License.
+
+`message-delivery/index.ts` reserves the durable delivery lease, then
+emits a non-terminal processing receipt only after workspace, attachment and
+provider validation. Duplicate validated requests replay that receipt without
+starting another provider run. The eleven-minute lease covers the ten-minute
+provider timeout. New-task startup events are status updates; the correlated
+result is terminal. Delivery integration tests live in `tests/delivery`.

package/apps/bridge/src/monitor/handlers/inbound.ts

@@ -32,7 +32,7 @@ import {
   handleSubscription,
 } from "./session-commands";
 import { handleTaskCreate } from "./task-create";
-import { handleUserMessage } from "./user-message";
+import { handleInboundUserMessage } from "../message-delivery";
 import { publishSessionEvents } from "./catalog";
 import { publishSessionImage } from '../../session-images';
 import { publishTaskWorkspace } from '../../task-files/relay';
@@ -201,42 +201,6 @@ function handleInboundPairingJoin(payload: Extract<Payload, { type: "pairing.joi
   return true;
 }
 
-async function handleInboundUserMessage(
-  client: RelayClient, payload: Extract<Payload, { type: "user.message" }>,
-  publish: (forceHistory?: boolean) => Promise<void>,
-): Promise<boolean> {
-  // Correlated replies belong to the MCP `ask` waiter in one process.
-  if (payload.requestId) return false;
-  let deliveryStarted = false;
-  if (payload.messageId) {
-    const state = beginDelivery(payload.messageId);
-    if (state === "completed") {
-      await sendDeliveryReceipt(client, payload.messageId, "accepted", undefined, payload.sessionId);
-      return true;
-    }
-    if (state === "processing") return false;
-    deliveryStarted = true;
-  }
-  try {
-    const outcome = await handleUserMessage(client, payload);
-    if (payload.messageId && deliveryStarted) {
-      if (outcome === "rejected") {
-        // The phone sends the message again with what was missing; the
-        // ledger must let that second copy through.
-        abandonDelivery(payload.messageId);
-      } else {
-        completeDelivery(payload.messageId);
-        await sendDeliveryReceipt(client, payload.messageId, "accepted", undefined, payload.sessionId);
-      }
-    }
-    void publish().catch(() => {});
-    return true;
-  } catch {
-    if (payload.messageId && deliveryStarted) abandonDelivery(payload.messageId);
-    return false;
-  }
-}
-
 async function handleInboundTaskCreate(
   client: RelayClient, payload: Extract<Payload, { type: "project.task.create" }>,
   publish: (forceHistory?: boolean) => Promise<void>,

package/apps/bridge/src/monitor/handlers/user-message.ts

@@ -22,7 +22,8 @@ import { DELIVERY_TIMEOUT_MS } from "./receipts";
 async function startNewAgentTask(input: {
   client: RelayClient;
   message: UserMessage;
-  say: (text: string, sessionId?: string, wake?: boolean) => Promise<unknown>;
+  say: (text: string, sessionId?: string, wake?: boolean, kind?: "status" | "response") => Promise<unknown>;
+  onProcessing?: () => Promise<void>;
 }): Promise<"rejected" | void> {
   const { client, message, say } = input;
   const agent = message.agent ?? "codex";
@@ -57,7 +58,8 @@ async function startNewAgentTask(input: {
     }
     return "rejected";
   }
-  await say(`Creating a new ${displayName} task…`);
+  await input.onProcessing?.();
+  await say(`Creating a new ${displayName} task…`, undefined, false, "status");
   const create = {
     claude: createClaudeSession,
     codex: createCodexSession,
@@ -77,16 +79,17 @@ async function startNewAgentTask(input: {
 export async function handleUserMessage(
   client: RelayClient,
   message: UserMessage,
+  onProcessing?: () => Promise<void>,
 ): Promise<"accepted" | "rejected" | void> {
-  const say = (text: string, sessionId?: string, wake = false) => {
-    const payload = agentEventForUserMessage(message, text, sessionId);
+  const say = (text: string, sessionId?: string, wake = false, kind: "status" | "response" = "response") => {
+    const payload = agentEventForUserMessage(message, text, sessionId, kind);
     const options = { ttlMs: 15 * 60_000, wake: wake || undefined };
     return (sessionId
       ? sendSessionPayload(client, payload, sessionId, "phone", options)
       : client.send(payload, "phone", options)).catch(() => {});
   };
   if (!message.sessionId) {
-    return startNewAgentTask({ client, message, say });
+    return startNewAgentTask({ client, message, say, onProcessing });
   }
   const resolved = resolveMessageAttachments(message, (attachmentId) => takeAttachment(attachmentId, client.room));
   if (!resolved.ok) {
@@ -135,6 +138,7 @@ export async function handleUserMessage(
 
   // No "sent, waiting" line from a middleman: the delivery receipt already
   // marks the person's bubble, and the next words in the chat are the answer.
+  await onProcessing?.();
   const startedAt = Date.now();
   const result = await deliverToSession(target, message.text, DELIVERY_TIMEOUT_MS, attachments, {
     preferredMcp: message.preferredMcp,

package/apps/bridge/src/monitor/message-delivery/README.md

@@ -0,0 +1,11 @@
+# Phone message delivery
+
+Public entry: `index.ts`. The handler owns the durable delivery lease and receipt
+sequence for non-correlated phone messages. Validation happens before the first
+processing receipt, and duplicate validated messages never start another run.
+Terminal responses remain correlated to the original message id.
+
+Integration tests: `tests/delivery/processing-receipt.test.ts`; attachment rejection
+coverage: `tests/attachment/attachment-uploads.test.ts`. See the monitor README.
+
+This module uses the repository MIT License.

package/apps/bridge/src/monitor/message-delivery/index.ts

@@ -0,0 +1,44 @@
+import type { Payload } from "../../../../../packages/protocol/schema";
+import type { RelayClient } from "../../../../../packages/core/relay-client";
+import { abandonDelivery, beginDelivery, completeDelivery,
+  acknowledgeProcessingDelivery, processingDeliveryAcknowledged } from "../../delivery";
+import { sendDeliveryReceipt } from "../handlers/receipts";
+import { handleUserMessage } from "../handlers/user-message";
+
+/** Receipts acknowledge durable receipt, while the correlated response is terminal. */
+export async function handleInboundUserMessage(
+  client: RelayClient, payload: Extract<Payload, { type: "user.message" }>,
+  publish: (forceHistory?: boolean) => Promise<void>,
+): Promise<boolean> {
+  if (payload.requestId) return false;
+  let deliveryStarted = false;
+  if (payload.messageId) {
+    const state = beginDelivery(payload.messageId);
+    if (state !== "started") {
+      if (state === "completed" || processingDeliveryAcknowledged(payload.messageId)) {
+        await sendDeliveryReceipt(client, payload.messageId, "accepted", undefined, payload.sessionId);
+      }
+      return true;
+    }
+    deliveryStarted = true;
+  }
+  try {
+    const outcome = await handleUserMessage(client, payload, async () => {
+      if (!payload.messageId) return;
+      acknowledgeProcessingDelivery(payload.messageId);
+      await sendDeliveryReceipt(client, payload.messageId, "accepted", undefined, payload.sessionId);
+    });
+    if (payload.messageId && deliveryStarted) {
+      if (outcome === "rejected") abandonDelivery(payload.messageId);
+      else {
+        completeDelivery(payload.messageId);
+        await sendDeliveryReceipt(client, payload.messageId, "accepted", undefined, payload.sessionId);
+      }
+    }
+    void publish().catch(() => {});
+    return true;
+  } catch {
+    if (payload.messageId && deliveryStarted) abandonDelivery(payload.messageId);
+    return false;
+  }
+}

package/cursor-plugin/README.md

@@ -10,7 +10,7 @@ keeps each phone response tied to the exact originating chat and prompt.
 Install the supported CLI on this computer, then run:
 
 ```bash
-npm install -g granttap-mcp@0.8.58
+npm install -g granttap-mcp@0.8.60
 granttap setup
 granttap status
 ```

package/cursor-plugin/mcp.json

@@ -4,7 +4,7 @@
       "command": "node",
       "args": [
         "-e",
-        "\"use strict\";\n\n// Cursor may start this MCP from any cwd. Execute JavaScript entry points with\n// Node itself: Windows batch shims require shell quoting that differs by host.\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { delimiter, dirname, join } = require(\"node:path\");\n\nconst PACKAGE = \"granttap-mcp@0.8.58\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 20+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
+        "\"use strict\";\n\n// Cursor may start this MCP from any cwd. Execute JavaScript entry points with\n// Node itself: Windows batch shims require shell quoting that differs by host.\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { delimiter, dirname, join } = require(\"node:path\");\n\nconst PACKAGE = \"granttap-mcp@0.8.60\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 20+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
       ]
     }
   }

package/cursor-plugin/stdio-bootstrap.cjs

@@ -7,7 +7,7 @@ const { spawn } = require("node:child_process");
 const { existsSync } = require("node:fs");
 const { delimiter, dirname, join } = require("node:path");
 
-const PACKAGE = "granttap-mcp@0.8.58";
+const PACKAGE = "granttap-mcp@0.8.60";
 const dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === "1";
 const platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM
   ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granttap-mcp",
-  "version": "0.8.58",
+  "version": "0.8.60",
   "description": "Personal live control center runtime for local coding agents on iPhone and Apple Watch.",
   "type": "module",
   "bin": {

package/packages/core/relay-client-types.ts

@@ -22,6 +22,8 @@ export type PeerConfig = {
 export type RelayClientOptions = {
   /** Fresh managed admission at each socket upgrade; own relays need no ticket. */
   upgradeHeaders?: () => Promise<Record<string, string>>;
+  /** Verified server lease deadline, refreshed without reconnecting the socket. */
+  connectionLeaseExpiresAt?: () => number | null;
   autoReconnect?: boolean;
   minReconnectMs?: number;
   maxReconnectMs?: number;

package/packages/core/relay-client.ts

@@ -10,6 +10,7 @@
  * the Cloudflare Durable Object deployment.
  */
 import WebSocket from "ws";
+import { ManagedRelayLease, RelaySocketHealth } from "./socket-lifecycle";
 import { OutboundFrameQueue, sendEncryptedPayload } from "./outbound-scheduler";
 import { createHash } from "node:crypto";
 import { Envelope, Payload, type Role } from "../protocol/schema";
@@ -31,8 +32,8 @@ export class RelayClient {
   private connectPromise?: Promise<void>;
   private reconnectTimer?: NodeJS.Timeout;
   private reconnectDelay: number;
-  private livenessTimer?: NodeJS.Timeout;
-  private awaitingPong = false;
+  private readonly socketHealth = new RelaySocketHealth();
+  private readonly admissionLease = new ManagedRelayLease();
   private readonly sessionKeys = new Map<string, string>();
   /**
    * Delivery ids are relay-controlled metadata, so replay protection is bound
@@ -96,14 +97,12 @@ export class RelayClient {
         reject(new Error(`relay connect timeout (${this.cfg.relayUrl})`));
       }, timeoutMs);
 
-      ws.on("pong", () => {
-        if (this.ws === ws) this.awaitingPong = false;
-      });
       ws.on("open", () => {
         opened = true;
         clearTimeout(timer);
         this.reconnectDelay = this.opts.minReconnectMs ?? 1_000;
-        this.startLivenessChecks(ws);
+        this.socketHealth.start(ws, this.opts.pingIntervalMs ?? 20_000);
+        this.admissionLease.start(ws, this.opts);
         // Announce ourselves. The envelope's cleartext (room, from) is what the
         // relay uses to register this socket; the Hello body stays encrypted.
         void this
@@ -122,7 +121,8 @@ export class RelayClient {
       ws.on("close", () => {
         frames.cancel();
         clearTimeout(timer);
-        this.stopLivenessChecks();
+        this.socketHealth.stop(ws);
+        this.admissionLease.stop(ws);
         if (this.ws === ws) this.ws = undefined;
         if (!opened) reject(new Error(`relay connection closed (${this.cfg.relayUrl})`));
         this.scheduleReconnect();
@@ -317,7 +317,8 @@ export class RelayClient {
 
   close(): void {
     this.frames?.cancel();
-    this.stopLivenessChecks();
+    this.socketHealth.stop();
+    this.admissionLease.stop();
     this.intentionalClose = true;
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     this.reconnectTimer = undefined;
@@ -329,48 +330,6 @@ export class RelayClient {
     return this.ws?.readyState === WebSocket.OPEN;
   }
 
-  /**
-   * Prove the socket is still there, rather than trusting `readyState`.
-   *
-   * A machine that changes network — joining a hotspot, waking on another
-   * Wi-Fi — leaves its relay socket half-open. No close event arrives, so
-   * nothing reconnects, and the computer keeps reporting itself as connected
-   * while everything it sends goes nowhere. A ping with a deadline is the only
-   * thing that tells the two apart.
-   */
-  private startLivenessChecks(ws: WebSocket): void {
-    this.stopLivenessChecks();
-    const interval = this.opts.pingIntervalMs ?? 20_000;
-    this.awaitingPong = false;
-    this.livenessTimer = setInterval(() => {
-      if (this.ws !== ws || ws.readyState !== WebSocket.OPEN) {
-        this.stopLivenessChecks();
-        return;
-      }
-      if (this.awaitingPong) {
-        // The previous ping was never answered. Terminating fires `close`,
-        // which is what schedules the reconnect.
-        this.stopLivenessChecks();
-        ws.terminate();
-        return;
-      }
-      this.awaitingPong = true;
-      try {
-        ws.ping();
-      } catch {
-        this.stopLivenessChecks();
-        ws.terminate();
-      }
-    }, interval);
-    this.livenessTimer.unref?.();
-  }
-
-  private stopLivenessChecks(): void {
-    if (this.livenessTimer) clearInterval(this.livenessTimer);
-    this.livenessTimer = undefined;
-    this.awaitingPong = false;
-  }
-
   private scheduleReconnect(): void {
     if (!this.opts.autoReconnect || this.intentionalClose || this.reconnectTimer) return;
     const delay = this.reconnectDelay;

package/packages/core/socket-lifecycle/README.md

@@ -0,0 +1,11 @@
+# Relay socket lifecycle
+
+Public entry point: `index.ts`. `RelayClient` uses this module for network health
+and short managed admission leases. Admission refresh stays on the existing
+socket and does not rotate task keys or reload transcript state. A failed lookup
+cannot extend the server's signed expiry. Closing or replacing a socket cancels
+only its own timers.
+
+The real WebSocket integration is in `tests/core/managed-relay-renewal.test.ts`.
+
+Licensed under the MIT License in the repository root.

package/packages/core/socket-lifecycle/index.ts

@@ -0,0 +1,2 @@
+export { ManagedRelayLease } from "./managed-relay-lease";
+export { RelaySocketHealth } from "./relay-socket-health";

package/packages/core/socket-lifecycle/managed-relay-lease.ts

@@ -0,0 +1,49 @@
+import WebSocket from "ws";
+import type { RelayClientOptions } from "../relay-client-types";
+
+/** Renew a computer's signed admission on its existing socket; no chat keys change. */
+export class ManagedRelayLease {
+  private socket?: WebSocket;
+  private timer?: NodeJS.Timeout;
+
+  start(socket: WebSocket, options: RelayClientOptions): void {
+    this.stop();
+    this.socket = socket;
+    socket.once("close", () => this.stop(socket));
+    this.schedule(socket, options);
+  }
+
+  stop(socket?: WebSocket): void {
+    if (socket && this.socket !== socket) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    this.socket = undefined;
+  }
+
+  private schedule(socket: WebSocket, options: RelayClientOptions, retry = false): void {
+    const expiry = options.connectionLeaseExpiresAt?.();
+    if (!expiry || !Number.isFinite(expiry) || !options.upgradeHeaders) return;
+    const remaining = expiry - Date.now();
+    const margin = Math.min(30_000, Math.max(10, remaining * 0.15));
+    const delay = retry ? 10_000 : Math.max(10, remaining - margin);
+    this.timer = setTimeout(() => void this.renew(socket, options), delay);
+    this.timer.unref();
+  }
+
+  private async renew(socket: WebSocket, options: RelayClientOptions): Promise<void> {
+    this.timer = undefined;
+    if (this.socket !== socket || socket.readyState !== WebSocket.OPEN) return;
+    try {
+      const headers = await options.upgradeHeaders!();
+      if (this.socket !== socket || socket.readyState !== WebSocket.OPEN) return;
+      const ticket = headers["X-GrantTap-Admission"];
+      if (!ticket) throw new Error("No refreshed relay admission");
+      await new Promise<void>((resolve, reject) => socket.send(
+        JSON.stringify({ type: "relay.admission", ticket }), error => error ? reject(error) : resolve()));
+      this.schedule(socket, options);
+    } catch {
+      // The relay's signed expiry remains authoritative; a failed lookup cannot extend it.
+      if (this.socket === socket && socket.readyState === WebSocket.OPEN) this.schedule(socket, options, true);
+    }
+  }
+}

package/packages/core/socket-lifecycle/relay-socket-health.ts

@@ -0,0 +1,31 @@
+import WebSocket from "ws";
+
+/** Detect half-open network sockets independently of managed authorization. */
+export class RelaySocketHealth {
+  private socket?: WebSocket;
+  private timer?: NodeJS.Timeout;
+  private awaitingPong = false;
+
+  start(socket: WebSocket, interval: number): void {
+    this.stop();
+    this.socket = socket;
+    socket.on("pong", () => { if (this.socket === socket) this.awaitingPong = false; });
+    this.timer = setInterval(() => {
+      if (this.socket !== socket || socket.readyState !== WebSocket.OPEN) { this.stop(socket); return; }
+      if (this.awaitingPong) { this.stop(socket); socket.terminate(); return; }
+      this.awaitingPong = true;
+      try { socket.ping(); }
+      catch { this.stop(socket); socket.terminate(); }
+    }, interval);
+    this.timer.unref();
+    socket.once("close", () => this.stop(socket));
+  }
+
+  stop(socket?: WebSocket): void {
+    if (socket && this.socket !== socket) return;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    this.socket = undefined;
+    this.awaitingPong = false;
+  }
+}