From 296eb0c7bfde88fb2df5f79f285efda4c3f1b1b6 Mon Sep 17 00:00:00 2001 From: anuzzolilli-oss Date: Sat, 14 Nov 2026 14:15:56 -0500 Subject: [PATCH 1/2] fix(zcode): decline the watchdog's route write once shutdown has begun (#67) A watchdog replacement waiting for the config lock could write its route after a signal exit handoff had already reverted the store. routeZcodeConfig now takes an optional shouldWrite check, asked under the lock immediately before the write; the watchdog tick passes "shutdown has not begun" and treats a declined write as a clean stop. Tests: reproduction with a held lock (both directions), the check itself (both directions, asserted to run under the lock), and the EOF respawn outcome for an attachable and a non-attachable respawned proxy. Assisted-by: Cindy (https://cindy.app) --- src/zcode/mcp-entry.ts | 22 ++++-- src/zcode/native.ts | 13 +++- tests/zcode-mcp-eof.test.ts | 130 +++++++++++++++++++++++++++++++++++- 3 files changed, 156 insertions(+), 9 deletions(-) diff --git a/src/zcode/mcp-entry.ts b/src/zcode/mcp-entry.ts index 742965f9fd..23663aaf89 100644 --- a/src/zcode/mcp-entry.ts +++ b/src/zcode/mcp-entry.ts @@ -105,13 +105,21 @@ export async function zcodeWatchdogTick(state: MutableZcodeWatchdogState, extern state.routing = origin; process.env.BILI_MCP_PROXY = origin; const route = deps.route ?? routeZcodeConfig; - const routed = await route({ origin, log, policy: state.policy }); - if (!routed) throw new Error("proxy respawned but the zcode config rewrite failed"); - const activate = deps.activate ?? activateZcodePluginMode; - await activate(routed, { log }); - state.origin = origin; - state.routing = undefined; - log(`proxy respawned at ${origin} — config re-routed`); + // The write waits for the config lock; a shutdown that begins + // meanwhile runs the exit handoff, and a route written after + // it would be left pointing at a proxy no session owns. + const routed = await route({ origin, log, policy: state.policy, shouldWrite: () => !state.stopped }); + if (!routed && state.stopped) { + state.routing = undefined; + log(`proxy respawned at ${origin} during shutdown — route not written, routing left to the exit handoff`); + } else { + if (!routed) throw new Error("proxy respawned but the zcode config rewrite failed"); + const activate = deps.activate ?? activateZcodePluginMode; + await activate(routed, { log }); + state.origin = origin; + state.routing = undefined; + log(`proxy respawned at ${origin} — config re-routed`); + } } state.failures = 0; } diff --git a/src/zcode/native.ts b/src/zcode/native.ts index 25d6f71e67..6fd646bf24 100644 --- a/src/zcode/native.ts +++ b/src/zcode/native.ts @@ -133,6 +133,11 @@ interface RouteZcodeOptions { * exemptions — call sites that resolve config themselves (bootstrap, * watchdog, handoff) pass their resolved policy through. */ readonly policy?: ZcodeRoutePolicy; + /** Asked while holding the config lock, immediately before the write. + * Returning false leaves the store untouched and the call returns + * undefined. For callers whose right to write can lapse while they wait + * for the lock (the watchdog once shutdown has begun). */ + readonly shouldWrite?: () => boolean; } // #1002 snapshot discipline: .bili-bak holds the state before bili's LATEST @@ -264,9 +269,15 @@ export async function routeZcodeConfig(opts: RouteZcodeOptions): Promise { + const written = await withConfigLock(dataDir, () => { + if (opts.shouldWrite && !opts.shouldWrite()) return false; snapshotAndWrite(file, applied.text); + return true; }); + if (!written) { + log("route write declined by the caller — leaving the config untouched"); + return undefined; + } // Re-apply against the written text to catch self-apply corruption early // (must be a fixed point: same wrapped set, byte-stable output). const check = applyZcodeRouting(fs.readFileSync(file, "utf8"), kind, opts.origin, policy); diff --git a/tests/zcode-mcp-eof.test.ts b/tests/zcode-mcp-eof.test.ts index e18bcebf2c..8520726649 100644 --- a/tests/zcode-mcp-eof.test.ts +++ b/tests/zcode-mcp-eof.test.ts @@ -2,7 +2,7 @@ import assert from "node:assert/strict"; import { test } from "node:test"; import { EventEmitter } from "node:events"; import * as entry from "../src/zcode/mcp-entry.ts"; -import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import path from "node:path"; import { defaultZcodeRoutePolicy, detectCurrentZcodeOrigin, zcodeStoreCandidates } from "../src/zcode/json-edit.ts"; @@ -169,6 +169,134 @@ for (const blockedAt of ["activate", "ensure"] as const) { }); } +for (const signalled of [true, false]) { + test(`watchdog replacement waiting on the config lock writes its route only if shutdown has not begun (signalled=${signalled})`, { timeout: 8000 }, async () => { + const dir = routedStore(); + const lockDir = path.join(dir, "v2", ".bili-config.lock"); + const entered = deferred(); + const exited = deferred(); + const emitter = new EventEmitter(); + const exits: number[] = []; + const logs: string[] = []; + let storeAtExit: string | undefined = "unset"; + const state = { origin: OLD, failures: 2, policy: defaultZcodeRoutePolicy() }; + await routeZcodeConfig({ origin: OLD, dataDir: dir, env: {}, log: () => {} }); + // Another live process holds the config lock, so the replacement's + // write waits inside routeZcodeConfig. + const holdLock = () => { mkdirSync(lockDir); writeFileSync(path.join(lockDir, "pid"), String(process.pid)); }; + const releaseLock = () => rmSync(lockDir, { recursive: true, force: true }); + holdLock(); + const stop = entry.startWatchdog(state, false, (msg) => logs.push(msg), { + intervalMs: 1, + probe: async () => false, + ensure: async () => ({ origin: NEW }), + route: (opts) => { entered.resolve(); return routeZcodeConfig({ ...opts, dataDir: dir, env: {}, log: () => {} }); }, + activate: async () => {}, + repair: async () => {}, + }); + entry.installExitHandoff(state, () => {}, { + events: emitter, + handoff: async (ownOrigin) => { + const outcome = await handoffZcodeRoutingOnExit({ ownOrigin, dataDir: dir, env: {}, log: () => {}, findReplacement: async () => undefined }); + // The lock frees after the handoff finished but before the + // process exits; the waiting replacement gets its turn. + releaseLock(); + await delay(300); + return outcome; + }, + exit: (code) => { exits.push(code); storeAtExit = detectCurrentZcodeOrigin(dir, {}); exited.resolve(); }, + }); + const hold = setTimeout(() => {}, 8000); + try { + await entered.promise; + assert.equal(detectCurrentZcodeOrigin(dir, {}), OLD); + if (signalled) { + emitter.emit("SIGTERM"); + await exited.promise; + assert.deepEqual(exits, [143]); + assert.equal(storeAtExit, undefined, "no route may be written after the exit handoff reverted the store"); + await stop(); + assert.equal(detectCurrentZcodeOrigin(dir, {}), undefined); + assert.equal(state.origin, OLD); + assert.doesNotMatch(logs.join("\n"), /watchdog error/); + } else { + releaseLock(); + for (let i = 0; i < 50 && state.origin !== NEW; i++) await delay(20); + assert.equal(state.origin, NEW); + assert.equal(detectCurrentZcodeOrigin(dir, {}), NEW); + await stop(); + } + } finally { clearTimeout(hold); releaseLock(); await stop(); rmrf(dir); } + }); +} + +for (const allow of [true, false]) { + test(`routeZcodeConfig asks shouldWrite under the config lock and writes only on true (allow=${allow})`, async () => { + const dir = routedStore(); + const file = zcodeStoreCandidates(dir, "legacy", {})[0]; + const lockDir = path.join(dir, "v2", ".bili-config.lock"); + const logs: string[] = []; + const lockHeld: boolean[] = []; + try { + const before = readFileSync(file, "utf8"); + const routed = await routeZcodeConfig({ + origin: NEW, dataDir: dir, env: {}, log: (msg) => logs.push(msg), + shouldWrite: () => { lockHeld.push(existsSync(lockDir)); return allow; }, + }); + assert.deepEqual(lockHeld, [true]); + assert.equal(existsSync(lockDir), false); + if (allow) { + assert.equal(routed?.origin, NEW); + assert.equal(detectCurrentZcodeOrigin(dir, {}), NEW); + assert.doesNotMatch(logs.join("\n"), /declined/); + } else { + assert.equal(routed, undefined); + assert.equal(readFileSync(file, "utf8"), before); + assert.match(logs.join("\n"), /route write declined/); + } + } finally { rmrf(dir); } + }); +} + +for (const attachable of [true, false]) { + test(`EOF during a watchdog respawn leaves routing to the exit handoff (respawned proxy attachable=${attachable})`, { timeout: 5000 }, async () => { + const dir = routedStore(); + const blocked = deferred(); + const entered = deferred(); + let routes = 0; + const state = { origin: OLD, failures: 2, policy: defaultZcodeRoutePolicy() }; + await routeZcodeConfig({ origin: OLD, dataDir: dir, env: {}, log: () => {} }); + const stop = entry.startWatchdog(state, false, () => {}, { + intervalMs: 1, + probe: async () => false, + ensure: async () => { entered.resolve(); await blocked.promise; return { origin: NEW }; }, + route: async (opts) => { routes++; return routeZcodeConfig({ ...opts, dataDir: dir, env: {}, log: () => {} }); }, + activate: async () => {}, + repair: async () => {}, + }); + const handoff = entry.installExitHandoff(state, () => {}, { + events: new EventEmitter(), + handoff: (ownOrigin) => handoffZcodeRoutingOnExit({ + ownOrigin, dataDir: dir, env: {}, log: () => {}, + findReplacement: async () => (attachable ? { origin: NEW } : undefined), + }), + exit: () => { assert.fail("EOF must not force exit"); }, + }); + const hold = setTimeout(() => {}, 5000); + try { + await entered.promise; + const drained = stop().then(handoff); + blocked.resolve(); + await drained; + // The tick never routes to the proxy it spawned during shutdown; + // the handoff routes to it only when discovery reports it live. + assert.equal(routes, 0); + assert.equal(state.origin, OLD); + assert.equal(detectCurrentZcodeOrigin(dir, {}), attachable ? NEW : undefined); + } finally { clearTimeout(hold); blocked.resolve(); await stop(); rmrf(dir); } + }); +} + for (const first of ["reverted-direct", "not-ours"] as const) { test(`exit handoff tries the in-flight routing origin only when the adopted origin is not the owner (first=${first})`, async () => { const asked: string[] = []; From 914c0f3a6debc8abaaa165d306831e773412a527 Mon Sep 17 00:00:00 2001 From: anuzzolilli-oss Date: Sat, 14 Nov 2026 14:32:30 -0500 Subject: [PATCH 2/2] test: stub the runtime-info request in the EOF respawn test (#67) The attachable case let the exit handoff POST runtime-info to a fixed port the test does not own. Answer it with a test-scoped fetch mock and assert the request goes to the replacement origin only. Assisted-by: Cindy (https://cindy.app) --- tests/zcode-mcp-eof.test.ts | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/tests/zcode-mcp-eof.test.ts b/tests/zcode-mcp-eof.test.ts index 8520726649..c309d23a68 100644 --- a/tests/zcode-mcp-eof.test.ts +++ b/tests/zcode-mcp-eof.test.ts @@ -259,7 +259,14 @@ for (const allow of [true, false]) { } for (const attachable of [true, false]) { - test(`EOF during a watchdog respawn leaves routing to the exit handoff (respawned proxy attachable=${attachable})`, { timeout: 5000 }, async () => { + test(`EOF during a watchdog respawn leaves routing to the exit handoff (respawned proxy attachable=${attachable})`, { timeout: 5000 }, async (t) => { + // The handoff reports runtime-info to the replacement it routes to; + // answer it here so the test never contacts a port it does not own. + const posted: string[] = []; + t.mock.method(globalThis, "fetch", async (input: Parameters[0]) => { + posted.push(String(input)); + return new Response("{}", { status: 200, headers: { "content-type": "application/json" } }); + }); const dir = routedStore(); const blocked = deferred(); const entered = deferred(); @@ -293,6 +300,7 @@ for (const attachable of [true, false]) { assert.equal(routes, 0); assert.equal(state.origin, OLD); assert.equal(detectCurrentZcodeOrigin(dir, {}), attachable ? NEW : undefined); + assert.deepEqual(posted, attachable ? [`${NEW}/__bili/plugin/runtime-info`] : []); } finally { clearTimeout(hold); blocked.resolve(); await stop(); rmrf(dir); } }); }