fix(bridge): add 20s timeout guard to core.shutdown() to prevent orphaned processes

[chiefmojo]

Problem

When the Hermes gateway dies abnormally (SIGKILL, OOM, crash), the --no-viewer bridge process calls core.shutdown() which chains through flush() → L2/L3 LLM calls that can block indefinitely. With the parent gone, nobody remains to send SIGKILL. Over 36 hours, 19 orphaned bridges accumulated consuming 299% CPU and writing duplicate traces (6,572 copies of a single turn).

Fixes #1798.

Changes

Adds a withShutdownTimeout() helper that races core.shutdown() against a 20-second deadline. Wraps all six core.shutdown() call sites:

1. Daemon SIGTERM handler (bridge.cts)
2. Non-daemon SIGTERM handler (bridge/stdio.ts)
3. Headless stdin-EOF exit (bridge/stdio.ts)
4. EADDRINUSE exit (×2) — daemon cannot bind viewer port
5. Viewer-running keepalive path — stdin closes while viewer is still serving

Also adds bridge-shutdown-audit.md documenting the full call chain through flush() → L2/L3/skill, confirming all async operations yield the event loop and the 20s timeout is effective on every path.

const SHUTDOWN_TIMEOUT_MS = 20_000;
function withShutdownTimeout(p: Promise<void>): Promise<void> {
  return Promise.race([p, new Promise<void>((r) => setTimeout(r, SHUTDOWN_TIMEOUT_MS))]);
}

Verification

• Code audit — traced every shutdown path, confirmed no sync blocking ops prevent the timeout from firing
• Stress test — kill gateway with SIGKILL, verify bridges exit within 20s, zero orphans
• Watchdog — cron job monitors bridge count across companions, alerts on accumulation

Related

This PR addresses the bridge-side half of the shutdown problem. The adapter-side complement — moving the synchronous session.close HTTP call off the asyncio event loop thread to prevent Discord heartbeat stalls when the bridge is unresponsive — is in #1953 (fix(adapter): fire session.close in daemon thread to unblock event loop).

[Memtensor-AI]

Automated Test Results: PASSED

Cloud test-engine rerun against dev-v2.0.22 completed successfully.

• Run: tr-0c78cd87-439 on cloud test-engine 10011
• memos_local_plugin/unit: 33 passed, 0 failed, 0 skipped

Manual code review is still required before merge.

[shinetata]

Review: Request Changes

Thanks for tackling this — the root cause in #1798 is real and the approach (a bounded Promise.race timeout followed by process.exit) is the correct shape for preventing orphaned bridges. I verified the six hunks apply cleanly onto current main's bridge.cts with no conflicts. Two blockers plus a few smaller items before this can merge.

Blockers

1. bridge.mts is untouched — the fix doesn't cover the preferred entry.

bridge.cts is the legacy CommonJS entry. bridge.mts is its pure-ESM successor and carries the same six core.shutdown() call sites (currently lines 395 / 401 / 410 / 481 / 502 / 511). The Python launcher resolves entries in this order:

dist/bridge.mjs  →  dist/bridge.cjs  →  bridge.mts  →  bridge.cts

(see adapters/hermes/memos_provider/bridge_client.py and daemon_manager.py, pinned by tests/python/test_bridge_script_resolution.py). Any normally-built deployment runs dist/bridge.mjs (compiled from bridge.mts) and never touches the patched .cts / .cjs. As written, the orphaned-bridge fix does not apply to the default production path. Please mirror the guard into bridge.mts, or factor withShutdownTimeout into a shared module both entries import.

2. bridge-shutdown-audit.md is added at the repository root.

This is a Python monorepo; a plugin-specific investigation doc shouldn't live in the repo root. Please move it under apps/memos-local-plugin/docs/ (where RFC-002 already lives) or drop it from the PR. Its line references (bridge.cts:373–381, 479–494, 517–520, 500–515, 358–370) are from the internal companion-stable branch and don't match main (actual sites: 471 / 546 / 574 / 563 / 456) — please correct or remove them if the doc stays.

Should fix

• No test for the new logic. withShutdownTimeout is an easily testable pure function and the repo follows TDD. Please add a unit test (fake timers) asserting the helper resolves after 20s when core.shutdown() never settles — see tests/unit/bridge/stdio.test.ts for a pattern. (The automated "33 passed" comment ran against dev-v2.0.22 and does not exercise this code path.)
• PR description doesn't match the diff. It states sites #2/#3 live in bridge/stdio.ts, but there is no bridge/stdio.ts change — all six sites are in bridge.cts (the non-daemon path merely calls waitForShutdown, which is defined in stdio.ts).

Nit

• withShutdownTimeout's setTimeout is neither unref()'d nor cleared. Harmless today because every call site is immediately followed by process.exit(), but it will keep the loop alive for 20s if the helper is ever reused without an immediate exit — consider .unref().
• The branch merged dev-20260604-v2.0.19 / main and the commit list includes unrelated fixes; please squash on merge so only the 2-file change lands.

[Memtensor-AI]

🤖 Open Code Review

Target: PR #1799
Task: c92f89ebf770abfc
Base: main
Head: fix/bridge-shutdown-timeout

✅ OpenCodeReview: No supported files changed.

Generated by cloud-assistant via Open Code Review.

[Memtensor-AI]

✅ Automated Test Results: PASSED

All tests passed (33/33 executed). memos_local_plugin/unit: 33/33. Duration: 5s [advisory, non-gating] AI-generated tests on branch test/auto-gen-eeab53129f00e68c-20260718033510: 66/70 passed, 4 failed — these do NOT affect the PR verdict; review the branch manually.

Branch: fix/bridge-shutdown-timeout

[Memtensor-AI]

✅ Automated Test Results: PASSED

All tests passed (33/33 executed). memos_local_plugin/unit: 33/33. Duration: 5s [advisory, non-gating] AI-generated tests on branch test/auto-gen-c92f89ebf770abfc-20260718215045: 18/18 passed — these do NOT affect the PR verdict; review the branch manually.

Branch: fix/bridge-shutdown-timeout