From d4060c6dccbc507cfc73d50696e11505fb26fc40 Mon Sep 17 00:00:00 2001 From: paisley <8197966+su8su@users.noreply.github.com> Date: Wed, 12 Aug 2026 15:06:34 +0800 Subject: [PATCH] docs: align Gateway heartbeat recovery threshold to four misses (#1238) --- README.ja-JP.md | 2 +- README.md | 2 +- README.zh-CN.md | 2 +- docs/en-US/architecture.md | 2 +- docs/ja-JP/architecture.md | 2 +- docs/ru-RU/architecture.md | 2 +- docs/zh-CN/architecture.md | 2 +- .../specs/rules/gateway-heartbeat-safety.md | 4 +-- .../gateway-backend-communication.md | 2 +- .../scenarios/gateway-startup-diagnostics.md | 4 +-- ...ke-gateway-heartbeat-observability-only.md | 2 +- ...y-heartbeat-recovery-after-four-misses.md} | 28 +++++++++---------- 12 files changed, 27 insertions(+), 27 deletions(-) rename harness/specs/tasks/{restore-gateway-heartbeat-recovery-after-ten-misses.md => restore-gateway-heartbeat-recovery-after-four-misses.md} (54%) diff --git a/README.ja-JP.md b/README.ja-JP.md index 62a9500a..b59dcef8 100644 --- a/README.ja-JP.md +++ b/README.ja-JP.md @@ -151,7 +151,7 @@ ClawXには、Electron、OpenClaw Gateway、Telegramなどのチャネルがロ ClawXは **Host API統一レイヤーを備えたデュアルプロセスアーキテクチャ**を採用しています。React Rendererは単一のクライアント抽象を呼び出し、Electron Mainがプロトコル選択、Gatewayのライフサイクル、ACP Chatのstdio bridgeを管理します。 - **プロセスモデル**：Electron Mainがウィンドウ、Gateway監視、システム統合、更新を管理します。OpenClaw GatewayはAIオーケストレーション、チャネル、スキル機能を提供し、Rendererはローカルエンドポイントへ直接アクセスしません。 -- **設定の配信**：Gateway実行中は `config.get` / `config.set` を使い、停止中または起動中は解決済みJSON5設定を更新します。通常のプロバイダー、Agent、スキル、モデル変更ではプロセスを置き換えず、認証情報は `secrets.reload` でホットリロードされます。ハートビートが10回連続で失敗した場合は、ライフサイクルで保護された復旧を要求します。 +- **設定の配信**：Gateway実行中は `config.get` / `config.set` を使い、停止中または起動中は解決済みJSON5設定を更新します。通常のプロバイダー、Agent、スキル、モデル変更ではプロセスを置き換えず、認証情報は `secrets.reload` でホットリロードされます。ハートビートが4回連続で失敗した場合は、ライフサイクルで保護された復旧を要求します。 - **ACP Chat**：Chatは [ACP（Agent Client Protocol）](https://agentclientprotocol.com) をMainが所有するstdio bridge経由で使用し、設定リロード後の認証済み履歴リプレイ、ページ移動中のストリーミング、Mainが検証したメディア・添付ファイル・ファイルアクティビティに対応します。 - **設計原則**：フロントエンドの単一入口、Mainによるトランスポート管理、再接続・タイムアウト・バックオフによるグレースフルリカバリ、安全なストレージ、CORSセーフな境界を採用しています。 diff --git a/README.md b/README.md index 853e078d..6d1846a6 100644 --- a/README.md +++ b/README.md @@ -151,7 +151,7 @@ Open **Settings -> Gateway -> Proxy** to configure the default proxy, bypass rul ClawX uses a **dual-process architecture with a unified Host API layer**: the React renderer calls one client abstraction, while Electron Main owns protocol selection, Gateway lifecycle, and the ACP Chat stdio bridge. - **Process model**: Electron Main owns the window, Gateway supervision, system integration, and updates; the OpenClaw Gateway provides AI orchestration, channel, and skill capabilities; the renderer does not access local endpoints directly. -- **Configuration delivery**: Main uses `config.get`/`config.set` while the Gateway is running and updates the resolved JSON5 config while it is stopped or starting; ordinary provider, agent, skill, and model changes do not replace the process, credentials are hot-reloaded through `secrets.reload`, and guarded recovery starts after ten consecutive heartbeat misses. +- **Configuration delivery**: Main uses `config.get`/`config.set` while the Gateway is running and updates the resolved JSON5 config while it is stopped or starting; ordinary provider, agent, skill, and model changes do not replace the process, credentials are hot-reloaded through `secrets.reload`, and guarded recovery starts after four consecutive heartbeat misses. - **ACP Chat**: Chat uses [ACP (Agent Client Protocol)](https://agentclientprotocol.com) through a Main-owned stdio bridge, supporting authenticated history replay after config reloads, streaming across navigation, and Main-validated media, attachments, and file activity. - **Design principles**: One frontend entry point, Main-owned transport, graceful recovery with reconnect/timeout/backoff, secure storage, and CORS-safe boundaries. diff --git a/README.zh-CN.md b/README.zh-CN.md index c89c77d8..28369c6f 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -152,7 +152,7 @@ ClawX 内置了代理设置，适用于需要通过本地代理客户端访问 ClawX 采用 **双进程 + Host API 统一接入架构**：React 渲染进程只通过统一的 host-api/api-client 抽象与后端交互，协议选择、Gateway 生命周期与 ACP Chat stdio bridge 全部由 Electron 主进程统一管理。 - **进程模型**：Electron 主进程负责窗口、网关进程监控、系统集成与自动更新；OpenClaw Gateway 作为独立运行时进程提供 AI 编排、频道和技能能力；渲染层不直接访问本地端点。 -- **配置交付**：Gateway 运行时由 Main 使用 `config.get` / `config.set`，停止或启动中则更新解析后的 JSON5 配置；普通 Provider/Agent/Skill/模型修改不会替换进程，凭据通过 `secrets.reload` 热更新；连续 10 次心跳无响应后才会请求受生命周期保护的自动恢复。 +- **配置交付**：Gateway 运行时由 Main 使用 `config.get` / `config.set`，停止或启动中则更新解析后的 JSON5 配置；普通 Provider/Agent/Skill/模型修改不会替换进程，凭据通过 `secrets.reload` 热更新；连续 4 次心跳无响应后才会请求受生命周期保护的自动恢复。 - **ACP Chat**：Chat UI 基于 ACP ([Agent Client Protocol](https://agentclientprotocol.com)) 与 OpenClaw 交互，从而在高速迭代的 OpenClaw 前找到相对稳定的聊天协议面。ACP 走 Main 持有的 stdio bridge，支持配置热重载后的历史回放认证、跨页面持续流式输出，以及由 Main 验证和加载的媒体/附件/文件活动（Changes）展示。 - **设计原则**：前端调用单一入口、Main 掌控传输策略、优雅恢复（重连/超时/退避）、安全存储与 CORS 安全。 diff --git a/docs/en-US/architecture.md b/docs/en-US/architecture.md index 51ff0766..532f9bc1 100644 --- a/docs/en-US/architecture.md +++ b/docs/en-US/architecture.md @@ -4,7 +4,7 @@ This document provides the detailed version of the Architecture section in the R ClawX uses a **dual-process architecture with a unified Host API layer**. The renderer calls one client abstraction, while protocol selection and process lifecycle are managed by Electron Main: -OpenClaw configuration delivery is also managed by Electron Main. While the Gateway is running, ClawX uses the authoritative snapshot returned by `config.get` as its baseline and commits changes with `config.set`. While the Gateway is stopped or starting, the same coordinator updates the resolved JSON5 configuration file without starting the Gateway. Ordinary provider, agent, channel, binding, skill, and model changes therefore do not replace the Gateway process. Full restarts are reserved for process-launch environment changes such as proxy settings and explicit user actions. Confirmed process exits and WebSocket closes retain their existing automatic reconnect paths. The first nine consecutive WebSocket heartbeat misses remain diagnostic-only so brief pong delays do not interrupt long-running work; a pong or any incoming message resets the count, while a tenth consecutive miss requests guarded automatic Gateway recovery when the lifecycle is in an auto-recoverable running state. After authentication configuration is written to SQLite, ClawX calls OpenClaw's `secrets.reload` so running agents can read new credentials without a process restart. +OpenClaw configuration delivery is also managed by Electron Main. While the Gateway is running, ClawX uses the authoritative snapshot returned by `config.get` as its baseline and commits changes with `config.set`. While the Gateway is stopped or starting, the same coordinator updates the resolved JSON5 configuration file without starting the Gateway. Ordinary provider, agent, channel, binding, skill, and model changes therefore do not replace the Gateway process. Full restarts are reserved for process-launch environment changes such as proxy settings and explicit user actions. Confirmed process exits and WebSocket closes retain their existing automatic reconnect paths. The first three consecutive WebSocket heartbeat misses remain diagnostic-only so brief pong delays do not interrupt long-running work; a pong or any incoming message resets the count, while a fourth consecutive miss requests guarded automatic Gateway recovery when the lifecycle is in an auto-recoverable running state. After authentication configuration is written to SQLite, ClawX calls OpenClaw's `secrets.reload` so running agents can read new credentials without a process restart. Chat uses an ACP stdio bridge owned by Electron Main. Main passes the same app-managed Gateway token to this local child through its private process environment, so ACP history replay remains authenticated when the runtime configuration reloads. The renderer receives typed host events and renders an in-memory ACP timeline. The Gateway remains responsible for non-Chat capabilities such as providers, models, skills, workspace, settings, diagnostics, and media configuration. diff --git a/docs/ja-JP/architecture.md b/docs/ja-JP/architecture.md index 4013c5de..41377dd7 100644 --- a/docs/ja-JP/architecture.md +++ b/docs/ja-JP/architecture.md @@ -4,7 +4,7 @@ ClawXは **統合Host APIレイヤーを備えたデュアルプロセスアーキテクチャ**を採用しています。Rendererは単一のクライアント抽象を呼び出し、プロトコル選択とプロセスライフサイクルはElectron Mainが管理します。 -OpenClawの設定配信もElectron Mainが管理します。Gateway実行中は`config.get`が返す権威あるスナップショットを基準にし、変更を`config.set`でコミットします。Gatewayが停止中または起動中の場合は、同じコーディネーターが解決済みJSON5設定ファイルを更新しますが、これを理由にGatewayを起動することはありません。そのため、通常のプロバイダー、Agent、チャネル、バインディング、スキル、モデルの変更ではGatewayプロセスを置き換えません。完全な再起動は、プロキシなどのプロセス起動環境の変更と、ユーザーによる明示的な操作に限られます。確認済みのプロセス終了とWebSocket切断では、既存の自動再接続経路が引き続き使用されます。WebSocketハートビートの連続9回までの欠落は診断のみとし、短いpong遅延で長時間実行中の処理を中断しません。pongまたは任意の受信メッセージでカウントをリセットし、10回連続で欠落した場合に、ライフサイクルが自動復旧可能なrunning状態であれば、保護されたGateway自動復旧を要求します。認証設定をSQLiteへ書き込んだ後はOpenClawの`secrets.reload`を呼び出し、実行中のAgentがプロセス再起動なしで新しい認証情報を読み取れるようにします。 +OpenClawの設定配信もElectron Mainが管理します。Gateway実行中は`config.get`が返す権威あるスナップショットを基準にし、変更を`config.set`でコミットします。Gatewayが停止中または起動中の場合は、同じコーディネーターが解決済みJSON5設定ファイルを更新しますが、これを理由にGatewayを起動することはありません。そのため、通常のプロバイダー、Agent、チャネル、バインディング、スキル、モデルの変更ではGatewayプロセスを置き換えません。完全な再起動は、プロキシなどのプロセス起動環境の変更と、ユーザーによる明示的な操作に限られます。確認済みのプロセス終了とWebSocket切断では、既存の自動再接続経路が引き続き使用されます。WebSocketハートビートの連続3回までの欠落は診断のみとし、短いpong遅延で長時間実行中の処理を中断しません。pongまたは任意の受信メッセージでカウントをリセットし、4回連続で欠落した場合に、ライフサイクルが自動復旧可能なrunning状態であれば、保護されたGateway自動復旧を要求します。認証設定をSQLiteへ書き込んだ後はOpenClawの`secrets.reload`を呼び出し、実行中のAgentがプロセス再起動なしで新しい認証情報を読み取れるようにします。 ChatはElectron Mainが所有するACP stdio bridgeを使用します。Mainはアプリが管理するGateway tokenをプライベートなプロセス環境経由でローカルの子プロセスへ渡すため、ランタイム設定の再読み込み後もACP履歴リプレイの認証が維持されます。Rendererは型付きhost eventを受け取り、メモリ上のACP timelineを描画します。Gatewayはproviders、models、skills、workspace、settings、diagnostics、media configurationなどの非Chat機能を引き続き担当します。 diff --git a/docs/ru-RU/architecture.md b/docs/ru-RU/architecture.md index ce8bba28..1056fb24 100644 --- a/docs/ru-RU/architecture.md +++ b/docs/ru-RU/architecture.md @@ -4,7 +4,7 @@ ClawX использует **двухпроцессную архитектуру с унифицированным уровнем Host API**. Renderer обращается к единой абстракции клиента, а Electron Main управляет выбором протокола и жизненным циклом процессов. -Доставка конфигурации OpenClaw также управляется Electron Main. Когда Gateway запущен, ClawX использует авторитетный снимок из `config.get` как основу и применяет изменения через `config.set`. Когда Gateway остановлен или запускается, тот же координатор обновляет разрешённый JSON5-файл конфигурации, не запуская Gateway из-за этого обновления. Поэтому обычные изменения провайдера, агента, канала, привязки, навыка и модели не заменяют процесс Gateway. Полные перезапуски остаются только для изменений среды запуска процесса, например прокси, и явных действий пользователя. Подтверждённые завершения процесса и закрытия WebSocket используют существующие пути автоматического переподключения. Первые девять последовательных пропусков WebSocket heartbeat являются только диагностикой, поэтому краткая задержка pong не прерывает долгую операцию; pong или любое входящее сообщение сбрасывает счётчик, а при десятом последовательном пропуске запрашивается защищённое автоматическое восстановление Gateway, если его жизненный цикл находится в состоянии running с разрешённым автовосстановлением. После записи конфигурации аутентификации в SQLite ClawX вызывает `secrets.reload` OpenClaw, чтобы работающие агенты получили новые учётные данные без перезапуска процесса. +Доставка конфигурации OpenClaw также управляется Electron Main. Когда Gateway запущен, ClawX использует авторитетный снимок из `config.get` как основу и применяет изменения через `config.set`. Когда Gateway остановлен или запускается, тот же координатор обновляет разрешённый JSON5-файл конфигурации, не запуская Gateway из-за этого обновления. Поэтому обычные изменения провайдера, агента, канала, привязки, навыка и модели не заменяют процесс Gateway. Полные перезапуски остаются только для изменений среды запуска процесса, например прокси, и явных действий пользователя. Подтверждённые завершения процесса и закрытия WebSocket используют существующие пути автоматического переподключения. Первые три последовательных пропуска WebSocket heartbeat являются только диагностикой, поэтому краткая задержка pong не прерывает долгую операцию; pong или любое входящее сообщение сбрасывает счётчик, а при четвёртом последовательном пропуске запрашивается защищённое автоматическое восстановление Gateway, если его жизненный цикл находится в состоянии running с разрешённым автовосстановлением. После записи конфигурации аутентификации в SQLite ClawX вызывает `secrets.reload` OpenClaw, чтобы работающие агенты получили новые учётные данные без перезапуска процесса. Chat использует ACP stdio bridge, принадлежащий Electron Main. Main передаёт тому же локальному дочернему процессу управляемый приложением Gateway token через приватное окружение процесса, поэтому после перезагрузки конфигурации среды выполнения воспроизведение истории ACP остаётся аутентифицированным. Renderer получает типизированные host events и отображает находящуюся в памяти ACP timeline. Gateway продолжает отвечать за возможности вне Chat: providers, models, skills, workspace, settings, diagnostics и media configuration. diff --git a/docs/zh-CN/architecture.md b/docs/zh-CN/architecture.md index 78c771bb..dd93e5e2 100644 --- a/docs/zh-CN/architecture.md +++ b/docs/zh-CN/architecture.md @@ -4,7 +4,7 @@ ClawX 采用 **双进程 + Host API 统一接入架构**。渲染进程只调用统一客户端抽象，协议选择与进程生命周期由 Electron 主进程统一管理： -OpenClaw 配置交付也统一由 Electron Main 管理。Gateway 运行时，ClawX 以 `config.get` 返回的权威快照为基线，并通过 `config.set` 提交修改；Gateway 停止或启动中时，同一个协调器只更新解析后的 JSON5 配置文件，不会因此启动 Gateway。因此，普通的 Provider、Agent、Channel、绑定、Skill 和模型修改不会替换 Gateway 进程。完整重启仅保留给代理等进程启动环境变化和用户显式操作。已确认的进程退出与 WebSocket 关闭继续使用现有的自动重连路径。连续前 9 次 WebSocket 心跳无响应只更新诊断，不会因短暂的 pong 延迟中断长时间运行的任务；收到 pong 或任意消息会重置计数，连续第 10 次无响应时，只有在生命周期处于可自动恢复的 running 状态时，才会请求受保护的 Gateway 自动恢复。认证配置写入 SQLite 后，ClawX 会调用 OpenClaw 的 `secrets.reload`，让运行中的 Agent 无需重启即可读取新凭据。 +OpenClaw 配置交付也统一由 Electron Main 管理。Gateway 运行时，ClawX 以 `config.get` 返回的权威快照为基线，并通过 `config.set` 提交修改；Gateway 停止或启动中时，同一个协调器只更新解析后的 JSON5 配置文件，不会因此启动 Gateway。因此，普通的 Provider、Agent、Channel、绑定、Skill 和模型修改不会替换 Gateway 进程。完整重启仅保留给代理等进程启动环境变化和用户显式操作。已确认的进程退出与 WebSocket 关闭继续使用现有的自动重连路径。连续前 3 次 WebSocket 心跳无响应只更新诊断，不会因短暂的 pong 延迟中断长时间运行的任务；收到 pong 或任意消息会重置计数，连续第 4 次无响应时，只有在生命周期处于可自动恢复的 running 状态时，才会请求受保护的 Gateway 自动恢复。认证配置写入 SQLite 后，ClawX 会调用 OpenClaw 的 `secrets.reload`，让运行中的 Agent 无需重启即可读取新凭据。 Chat 使用由 Electron Main 持有的 ACP stdio bridge。Main 通过私有进程环境把同一份应用管理的 Gateway token 传给本地子进程，因此运行时配置重载后 ACP 历史回放仍能完成认证。Renderer 接收类型化 host events，并渲染内存中的 ACP timeline。Gateway 仍负责 providers、models、skills、workspace、settings、diagnostics 和 media configuration 等非 Chat 能力。 diff --git a/harness/specs/rules/gateway-heartbeat-safety.md b/harness/specs/rules/gateway-heartbeat-safety.md index 9c351329..beb02525 100644 --- a/harness/specs/rules/gateway-heartbeat-safety.md +++ b/harness/specs/rules/gateway-heartbeat-safety.md @@ -11,8 +11,8 @@ requiredTests: WebSocket heartbeat misses are availability evidence. A short sequence is not proof that the local Gateway process is dead because long-running model, tool, compaction, and scheduled work may temporarily delay Gateway control-plane responses. -Misses one through nine must remain diagnostic-only: they must not terminate the socket, kill the owned Gateway process, or request `GatewayManager.restart`. A pong or any incoming Gateway message resets the sequence. +Misses one through three must remain diagnostic-only: they must not terminate the socket, kill the owned Gateway process, or request `GatewayManager.restart`. A pong or any incoming Gateway message resets the sequence. -After ten consecutive missed responses, ClawX may treat the Gateway as persistently unresponsive and request the guarded `GatewayManager.restart` path only when auto-recovery is enabled and lifecycle state is still `running`. The heartbeat callback must not directly terminate the socket or process, and it must request recovery at most once per uninterrupted miss sequence. +After four consecutive missed responses, ClawX may treat the Gateway as persistently unresponsive and request the guarded `GatewayManager.restart` path only when auto-recovery is enabled and lifecycle state is still `running`. The heartbeat callback must not directly terminate the socket or process, and it must request recovery at most once per uninterrupted miss sequence. Authoritative child-process exit, WebSocket close, and Gateway restart close code 1012 signals retain their existing automatic lifecycle paths. Explicit user restart remains available. diff --git a/harness/specs/scenarios/gateway-backend-communication.md b/harness/specs/scenarios/gateway-backend-communication.md index 45d67e95..5fc2a641 100644 --- a/harness/specs/scenarios/gateway-backend-communication.md +++ b/harness/specs/scenarios/gateway-backend-communication.md @@ -99,4 +99,4 @@ The local HTML Preview privileged bridge is also Main-owned: Renderer may load a Gateway session-catalog subscription, normalization, ordered list/event replay, attention transitions, and reconnect recovery are documented in `harness/reference/sidebar-session-attention.md`. Electron test-process isolation and global-resource scheduling are documented in `harness/reference/e2e-parallelism.md`. -Gateway WebSocket heartbeat misses are diagnostic availability signals for the first nine consecutive misses and must not interrupt long-running work during that window. A pong or any incoming Gateway message resets the sequence. On the tenth consecutive miss, Main may request the guarded Gateway restart path when auto-recovery is enabled and lifecycle state is still running; the heartbeat callback must not directly terminate the socket or process. Authoritative process-exit and socket-close signals retain their existing automatic lifecycle paths. +Gateway WebSocket heartbeat misses are diagnostic availability signals for the first three consecutive misses and must not interrupt long-running work during that window. A pong or any incoming Gateway message resets the sequence. On the fourth consecutive miss, Main may request the guarded Gateway restart path when auto-recovery is enabled and lifecycle state is still running; the heartbeat callback must not directly terminate the socket or process. Authoritative process-exit and socket-close signals retain their existing automatic lifecycle paths. diff --git a/harness/specs/scenarios/gateway-startup-diagnostics.md b/harness/specs/scenarios/gateway-startup-diagnostics.md index 5d5fc27d..45c5290e 100644 --- a/harness/specs/scenarios/gateway-startup-diagnostics.md +++ b/harness/specs/scenarios/gateway-startup-diagnostics.md @@ -33,7 +33,7 @@ ClawX should prefer OpenClaw-native signals over stderr string matching: stderr is supporting evidence only. It should not be the primary source for deciding whether the Gateway is ready, blocked, or should be restarted. -WebSocket heartbeat misses show that the Gateway control plane did not answer within the observation window. The first nine consecutive misses remain diagnostic-only so transient pong delays do not interrupt long-running work. A pong or any incoming message resets the sequence. A tenth consecutive miss marks persistent unresponsiveness and may request the guarded Gateway restart path when auto-recovery is enabled and lifecycle state is still running. Process exit and socket close retain their existing automatic recovery paths. +WebSocket heartbeat misses show that the Gateway control plane did not answer within the observation window. The first three consecutive misses remain diagnostic-only so transient pong delays do not interrupt long-running work. A pong or any incoming message resets the sequence. A fourth consecutive miss marks persistent unresponsiveness and may request the guarded Gateway restart path when auto-recovery is enabled and lifecycle state is still running. Process exit and socket close retain their existing automatic recovery paths. ## Failure Shape @@ -278,7 +278,7 @@ pnpm exec openclaw gateway call status >/tmp/clawx-status.json - `health` and `status` are captured in Gateway diagnostics when available. - Memory doctor calls return when the memory capability is available. - `doctor.memory.*` and `channels.status` failures degrade their capability only and do not trigger Gateway restart. -- The first nine consecutive heartbeat misses do not replace the Gateway process; the tenth records unresponsive diagnostics and requests one guarded restart when lifecycle auto-recovery is allowed. +- The first three consecutive heartbeat misses do not replace the Gateway process; the fourth records unresponsive diagnostics and requests one guarded restart when lifecycle auto-recovery is allowed. - Logs no longer repeat stale runtime cache or escaped managed-skill symlink warnings for entries ClawX can safely clean. ## Required Regression Coverage diff --git a/harness/specs/tasks/make-gateway-heartbeat-observability-only.md b/harness/specs/tasks/make-gateway-heartbeat-observability-only.md index 86db73bc..3ff317b0 100644 --- a/harness/specs/tasks/make-gateway-heartbeat-observability-only.md +++ b/harness/specs/tasks/make-gateway-heartbeat-observability-only.md @@ -44,4 +44,4 @@ docs: required: true --- -Historical first-stage heartbeat safety task. Its observability-only recovery policy is superseded by `restore-gateway-heartbeat-recovery-after-ten-misses`, which keeps the first nine misses diagnostic-only and permits guarded recovery on the tenth consecutive miss. +Historical first-stage heartbeat safety task. Its observability-only recovery policy is superseded by `restore-gateway-heartbeat-recovery-after-four-misses`, which keeps the first three misses diagnostic-only and permits guarded recovery on the fourth consecutive miss. diff --git a/harness/specs/tasks/restore-gateway-heartbeat-recovery-after-ten-misses.md b/harness/specs/tasks/restore-gateway-heartbeat-recovery-after-four-misses.md similarity index 54% rename from harness/specs/tasks/restore-gateway-heartbeat-recovery-after-ten-misses.md rename to harness/specs/tasks/restore-gateway-heartbeat-recovery-after-four-misses.md index c0bc14d6..7fa42d49 100644 --- a/harness/specs/tasks/restore-gateway-heartbeat-recovery-after-ten-misses.md +++ b/harness/specs/tasks/restore-gateway-heartbeat-recovery-after-four-misses.md @@ -1,11 +1,11 @@ --- -id: restore-gateway-heartbeat-recovery-after-ten-misses -title: Restore Gateway heartbeat recovery after ten misses +id: restore-gateway-heartbeat-recovery-after-four-misses +title: Restore Gateway heartbeat recovery after four misses scenario: gateway-backend-communication taskType: runtime-bridge -intent: Recover a persistently unresponsive local Gateway automatically while giving long-running work a longer heartbeat window before process replacement. +intent: Recover a persistently unresponsive local Gateway automatically while giving long-running work a bounded heartbeat window before process replacement. touchedAreas: - - harness/specs/tasks/restore-gateway-heartbeat-recovery-after-ten-misses.md + - harness/specs/tasks/restore-gateway-heartbeat-recovery-after-four-misses.md - harness/specs/tasks/make-gateway-heartbeat-observability-only.md - harness/specs/rules/gateway-heartbeat-safety.md - harness/specs/scenarios/gateway-backend-communication.md @@ -19,9 +19,9 @@ touchedAreas: - README.zh-CN.md - README.ja-JP.md expectedUserBehavior: - - One to nine consecutive missed Gateway heartbeat responses remain diagnostic-only and do not interrupt long-running work. - - Ten consecutive missed heartbeat responses mark the Gateway unresponsive and request an automatic restart when lifecycle auto-recovery is enabled and the Gateway is still running. - - A pong or any incoming Gateway message before the tenth miss resets the consecutive-miss counter. + - One to three consecutive missed Gateway heartbeat responses remain diagnostic-only and do not interrupt long-running work. + - Four consecutive missed heartbeat responses mark the Gateway unresponsive and request an automatic restart when lifecycle auto-recovery is enabled and the Gateway is still running. + - A pong or any incoming Gateway message before the fourth miss resets the consecutive-miss counter. - Process exit, WebSocket close, explicit restart, and code-1012 reconnect behavior remain unchanged. requiredProfiles: - fast @@ -37,15 +37,15 @@ requiredTests: - tests/unit/gateway-manager-diagnostics.test.ts - tests/unit/gateway-connection-monitor.test.ts acceptance: - - The Gateway heartbeat threshold is ten consecutive misses. - - Misses one through nine update monitor state without calling GatewayManager.restart or terminating the socket. - - The tenth consecutive miss records timeout diagnostics and calls GatewayManager.restart exactly once when auto-recovery is allowed. - - The tenth miss does not restart when auto-reconnect is disabled or the Gateway is not running. - - Recovery through a pong or any incoming Gateway message resets the sequence, so only ten new consecutive misses can trigger recovery. + - The Gateway heartbeat threshold is four consecutive misses. + - Misses one through three update monitor state without calling GatewayManager.restart or terminating the socket. + - The fourth consecutive miss records timeout diagnostics and calls GatewayManager.restart exactly once when auto-recovery is allowed. + - The fourth miss does not restart when auto-reconnect is disabled or the Gateway is not running. + - Recovery through a pong or any incoming Gateway message resets the sequence, so only four new consecutive misses can trigger recovery. - Automatic heartbeat recovery behaves consistently on Windows, macOS, and Linux. - - Documentation in all maintained README translations describes the ten-miss automatic recovery policy. + - Documentation in all maintained README translations describes the four-miss automatic recovery policy. docs: required: true --- -This task supersedes the recovery policy from `make-gateway-heartbeat-observability-only`: heartbeat misses remain non-authoritative during the first nine misses, while a tenth consecutive miss is treated as persistent unresponsiveness and may request guarded lifecycle recovery. +This task supersedes the recovery policy from `make-gateway-heartbeat-observability-only`: heartbeat misses remain non-authoritative during the first three misses, while a fourth consecutive miss is treated as persistent unresponsiveness and may request guarded lifecycle recovery.