From 109730082b9540f8ef4bff0e669f2322c589a1a5 Mon Sep 17 00:00:00 2001 From: Erick Date: Sun, 23 Aug 2026 06:31:34 -0700 Subject: [PATCH] fix(bridge): start status heartbeat in --daemon mode PR #1998 made the Python launcher prefer the pure-ESM dist/bridge.mjs entry over dist/bridge.cjs, but bridge.mts only calls markConnected()/ startHeartbeat() in its stdio branch. Daemon spawns therefore never refresh bridge-status.json; every reader applies the 20s staleness rule to the fossilized snapshot and reports 'Hermes bridge heartbeat is stale' indefinitely while RPC traffic keeps working. Mirror the legacy bridge.cts daemon path, which always had both calls. Pinned by a source-level regression guard alongside the existing bridge-startup-ordering.test.ts. --- apps/memos-local-plugin/bridge.mts | 8 ++ .../bridge/bridge-daemon-heartbeat.test.ts | 75 +++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 apps/memos-local-plugin/tests/unit/bridge/bridge-daemon-heartbeat.test.ts diff --git a/apps/memos-local-plugin/bridge.mts b/apps/memos-local-plugin/bridge.mts index 718172af2..bb65a9ede 100644 --- a/apps/memos-local-plugin/bridge.mts +++ b/apps/memos-local-plugin/bridge.mts @@ -410,6 +410,14 @@ async function main(): Promise { } } + // Port bound successfully — start reporting. Mirrors the legacy + // bridge.cts daemon path: without these calls the daemon never + // refreshes bridge-status.json and every reader applies the 20s + // staleness rule to a fossilized snapshot ("Hermes bridge heartbeat + // is stale") while RPC traffic keeps working. + bridgeStatus?.markConnected(); + bridgeHeartbeat = bridgeStatus?.startHeartbeat(); + const shutdownDaemon = async (sig: string) => { process.stderr.write(`bridge: daemon received ${sig}, shutting down\n`); removeOwnedPidFile(); diff --git a/apps/memos-local-plugin/tests/unit/bridge/bridge-daemon-heartbeat.test.ts b/apps/memos-local-plugin/tests/unit/bridge/bridge-daemon-heartbeat.test.ts new file mode 100644 index 000000000..01d55a72c --- /dev/null +++ b/apps/memos-local-plugin/tests/unit/bridge/bridge-daemon-heartbeat.test.ts @@ -0,0 +1,75 @@ +/** + * bridge.mts daemon-mode heartbeat regression guard. + * + * Symptom observed 2026-08-22 after deploying memos-local-plugin v2.0.16 + * on a Hermes host: `POST /api/v1/rpc` served traffic normally, but + * `bridge-status.json` froze at its pre-upgrade timestamp and every health + * report said `disconnected` / "Hermes bridge heartbeat is stale". + * + * Root cause: PR #1998 made the Python launcher prefer the pure-ESM + * `dist/bridge.mjs` entry (fixing #1736). `bridge.mts` only called + * `markConnected()` / `startHeartbeat()` in its stdio (`!args.daemon`) + * branch — the `--daemon` branch never started the status heartbeat, so + * no daemon ever refreshed `bridge-status.json` and the 20s staleness rule + * permanently reported a dead bridge. The legacy `bridge.cts` daemon path + * always had both calls; the ESM successor lost them in translation. + * + * Why source-level (rather than runtime): `bridge.mts` is a top-level + * executable script — same rationale as `bridge-startup-ordering.test.ts`. + * Refactoring it into an injectable function just to runtime-test two call + * sites would be a much larger change than this invariant deserves. A + * source-level assertion catches the regression the moment someone edits + * the daemon startup path. + */ +import { describe, expect, it } from "vitest"; +import { readFileSync } from "node:fs"; +import { resolve, dirname } from "node:path"; +import { fileURLToPath } from "node:url"; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const BRIDGE_MTS_PATH = resolve(HERE, "..", "..", "..", "bridge.mts"); + +describe("bridge.mts daemon-mode heartbeat (stale bridge-status.json regression)", () => { + const src = readFileSync(BRIDGE_MTS_PATH, "utf8"); + + // Scope to the daemon branch of main(): from its `if (args.daemon)` + // guard to the start of the trailing "Normal (stdio) mode" section + // comment. Scoping matters — markConnected()/startHeartbeat() legitimately + // appear in the stdio branch and inside the tracker factory, and those + // must NOT satisfy this guard. + const daemonGuard = src.indexOf("if (args.daemon)"); + const stdioSection = src.indexOf("Normal (stdio) mode"); + + it("has a daemon branch", () => { + expect(daemonGuard).toBeGreaterThanOrEqual(0); + expect(stdioSection).toBeGreaterThan(daemonGuard); + }); + + it("marks connected and starts the status heartbeat after binding the viewer port", () => { + const daemonBranch = src.slice(daemonGuard, stdioSection); + + const connectedIdx = daemonBranch.indexOf("bridgeStatus?.markConnected()"); + expect( + connectedIdx, + "bridge.mts: --daemon branch never calls bridgeStatus?.markConnected() — " + + "the daemon writes no heartbeat and every reader applies the 20s " + + "staleness rule to a fossilized bridge-status.json, reporting " + + "'Hermes bridge heartbeat is stale' forever while RPC keeps working.", + ).toBeGreaterThanOrEqual(0); + + const heartbeatIdx = daemonBranch.indexOf("bridgeHeartbeat = bridgeStatus?.startHeartbeat()"); + expect( + heartbeatIdx, + "bridge.mts: --daemon branch never starts the periodic status heartbeat — " + + "bridge-status.json goes stale immediately after the initial write.", + ).toBeGreaterThanOrEqual(0); + + // Both calls must sit after the bind-retry loop's `break` (i.e. on the + // success path); writing "connected" before we know the port bound + // would lie on the failure paths that exit below. + const breakIdx = daemonBranch.indexOf("break;"); + expect(breakIdx).toBeGreaterThanOrEqual(0); + expect(connectedIdx, "markConnected must follow successful viewer bind").toBeGreaterThan(breakIdx); + expect(heartbeatIdx, "startHeartbeat must follow successful viewer bind").toBeGreaterThan(breakIdx); + }); +});