Skip to content

fix: zcode exit handoff covers a route written by an in-flight watchdog replacement - #64

Merged
anuzzolilli-oss merged 2 commits into
masterfrom
2026-11-14_zcode-signal-handoff-watchdog-race
Nov 14, 2026
Merged

anuzzolilli-oss merged 2 commits into
masterfrom
2026-11-14_zcode-signal-handoff-watchdog-race

Conversation

@anuzzolilli-oss

@anuzzolilli-oss anuzzolilli-oss commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

(ai: anthropic/claude-fable-5-2)

Closes #14

Decisions for the owner

This PR makes three behaviour choices. They are the conservative options as I read #14, but they are yours to confirm:

  1. The signal path still does not wait for the in-flight watchdog tick. Waiting would let a tick blocked in proxy start-up or activation spend the whole 5000 ms deadline, and the process would then exit with no handoff at all. Instead the handoff runs at once and is told which route the tick may have written.
  2. A replacement proxy started by a tick during shutdown is left running and unrouted. The tick no longer routes to it once shutdown has begun; nothing stops that proxy.
  3. This also applies on stdin EOF. A tick that returns from proxy start-up after the watchdog was stopped no longer re-routes before the handoff runs. Before, it re-routed and the handoff then moved the route again.

What this changes

src/zcode/mcp-entry.ts only.

  • A replacement tick records the origin it is about to route to (state.routing) before it writes, and clears it once that origin is adopted as state.origin.
  • The exit handoff tries state.origin first; if the store is not owned by it, it tries state.routing. Each origin is tried once.
  • Starting the handoff sets state.stopped. A tick that finds itself stopped after proxy start-up logs that and skips the re-route.
  • The handoff test seam now receives the origin it is asked to hand off.

Exit codes 130 and 143, the 5000 ms deadline, and the single-handoff guarantee are unchanged.

Evidence

Two new tests in tests/zcode-mcp-eof.test.ts run the real routeZcodeConfig and handoffZcodeRoutingOnExit against a scratch store, with the watchdog tick suspended by a controlled promise and SIGTERM delivered through the injected event source:

Tick suspended in Before (master 9d4bda8e5) After
activation, after the route write store left pointing at the replacement; process exits 143 store reverted to direct; exits 143
proxy start-up, before the route write handoff reverts, then the resumed tick re-routes to the replacement store stays reverted; the tick makes 0 route calls
  • Added after review: the real-store tests pass an isolated environment to every routing, handoff and read call, and two cases pin the fallback (it runs when the adopted origin is not the owner; it does not run after a successful handoff). With the short-circuit deleted, the second case fails.
  • tests/zcode-mcp-eof.test.ts 11 of 11, tests/zcode-mcp-entry.test.ts 9 of 9, tests/zcode-mcp-degraded.test.ts 6 of 6, tests/zcode-native.test.ts 35 of 35 (Windows 11, Node v24.14.0). tsc --noEmit clean.
  • Other direction: third consecutive failure respawns a dead lane proxy (#1821) and its neighbours in tests/zcode-mcp-entry.test.ts still show a normal replacement re-routing when no shutdown is in progress.

Limits

Assisted-by: Cindy (https://cindy.app)

…og replacement

A watchdog replacement tick writes the new route, awaits plugin activation,
and only then updates state.origin. A signal in that interval ran the exit
handoff with the old origin, got "not-ours", and exited leaving the store
pointed at the replacement. A tick still blocked in ensure could also write
its route after the handoff had finished.

The tick now records the origin it is routing to before it writes, and the
exit handoff tries that origin when the adopted one is not the store's
owner. Starting the handoff marks the watchdog stopped, and a tick that
finds itself stopped after ensure no longer re-routes.

The signal path still does not wait for the tick; exit codes 130/143 and
the 5000 ms deadline are unchanged.

Refs #14

Assisted-by: Cindy (https://cindy.app)
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

📦 Built Package Artifact

Branch: 2026-11-14_zcode-signal-handoff-watchdog-race (250dc9e)

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr64.tgz
npm install -g package

Install instructions are refreshed on each push.

Comment thread tests/zcode-mcp-eof.test.ts Outdated
const exits: number[] = [];
let routes = 0;
const state = { origin: OLD, failures: 2, policy: defaultZcodeRoutePolicy() };
await routeZcodeConfig({ origin: OLD, dataDir: dir, log: () => {} });

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(ai: openai/gpt-6-astra)

WARNING: Isolate the real store helpers from ambient path overrides

If the test process inherits ZCODE_PERSONAL_PROVIDER_CONFIG_FILE pointing to a valid personal store with a routable custom provider, this call rewrites that real store rather than the scratch fixture. routeZcodeConfig defaults to process.env, and zcodeStoreCandidates explicitly places that override ahead of dataDir (src/zcode/json-edit.ts:64-78); neither test preload clears it. The calls at lines 145 and 153 inherit the same override, so the test can subsequently unroute the real store and remove its routing snapshots while still passing. Pass an isolated env: {} consistently to both routing calls and the handoff, and pass the same environment to every detectCurrentZcodeOrigin assertion, so all reads and writes stay inside the fixture.

Comment thread src/zcode/mcp-entry.ts
if (ownOrigin === undefined) break;
tried.add(ownOrigin);
const outcome = await (deps.handoff ? deps.handoff(ownOrigin) : handoffZcodeRoutingOnExit({ ownOrigin, log }));
if (outcome !== "not-ours") break;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(ai: openai/gpt-6-astra)

WARNING: Add the required negative assertion for the fallback gate

There is no test with both state.origin and a distinct state.routing populated where the first handoff succeeds and the fallback must not run. The new activation case exercises only not-ours followed by fallback; the ensure case and existing single-handoff tests have no pending routing origin. Consequently, removing this success short-circuit would still satisfy their assertions even though it permits a second handoff after a successful transfer. AGENTS.md:53 and the development contract's gate-test discipline require both directions. Add a case with both origins present, return handed-off or reverted-direct for the first origin, and assert that the handoff receives only that origin.

@kilo-code-bot

kilo-code-bot Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Reviewed the incremental test changes from e98be94a72089c5991645bb49908bc6fecd374ca to 250dc9e43ff6a9e0d72ea572ff20f5e59fd6443c, with targeted current-code verification of previous findings. Standard depth, not a Light pass. Static review only; tests were not executed.

Files Reviewed (2 files)
  • tests/zcode-mcp-eof.test.ts
  • src/zcode/mcp-entry.ts (targeted verification)
Previous Review Summary (commit e98be94)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit e98be94)

Status: 2 Issues Found | Recommendation: Address before merge

Reviewed both changed files at e98be94a72089c5991645bb49908bc6fecd374ca using standard depth, not a Light pass. Static review only; tests were inspected but not executed under the read-only restrictions.

Overview

Severity Count
CRITICAL 0
WARNING 2
SUGGESTION 0
Issue Details (click to expand)

WARNING

File Line Issue
tests/zcode-mcp-eof.test.ts 137 Inherited provider-file overrides let the scratch-store tests rewrite and unroute a real ZCode store. Pass an isolated environment to all store helpers.
src/zcode/mcp-entry.ts 155 The new fallback gate lacks the required negative assertion that a successful first handoff prevents a second call when both origins are present.
Files Reviewed (2 files)
  • src/zcode/mcp-entry.ts - 1 warning
  • tests/zcode-mcp-eof.test.ts - 1 warning

Fix these issues in Kilo Cloud

(ai: openai/gpt-6-astra)


Reviewed by gpt-6-astra · Input: 33 · Output: 3.1K · Cached: 421.2K

Review guidance: REVIEW.md from base branch master

…llback

Review of #64: the real-store tests now pass an isolated env to every
routing, handoff and read call, so an ambient personal-store override
cannot redirect them. Two new cases pin the fallback to the in-flight
routing origin: it runs when the adopted origin is not the owner, and
does not run after a successful handoff.

Refs #14

Assisted-by: Cindy (https://cindy.app)
@anuzzolilli-oss

Copy link
Copy Markdown
Owner Author

(ai: anthropic/claude-fable-5-2)

Correction to this PR's body, after review with the owner on 2026-11-14.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Zcode signal handoff can race an active watchdog replacement

1 participant