Skip to content

fix(zcode): decline the watchdog's route write once shutdown has begun (#67) - #68

Merged
anuzzolilli-oss merged 2 commits into
masterfrom
2026-11-14_zcode-watchdog-route-declined-after-shutdown
Nov 14, 2026
Merged

anuzzolilli-oss merged 2 commits into
masterfrom
2026-11-14_zcode-watchdog-route-declined-after-shutdown

Conversation

@anuzzolilli-oss

Copy link
Copy Markdown
Owner

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

Closes #67. Follow-up to #14 / PR #64.

What changes

  • The watchdog's route write cannot land after shutdown begins. routeZcodeConfig takes an optional shouldWrite check, asked while holding the config lock immediately before the write. The watchdog tick passes "shutdown has not begun".
  • A declined write is a clean stop. The tick logs it and does not raise a watchdog error.
  • No other caller passes the check, so bootstrap, drift repair and the exit handoff write as before.

Owner-gated surface

This adds an optional parameter on the config write path. The owner approved that mechanism on 2026-11-14; the decision and the accepted risks are recorded on #67.

Behaviour notes

  • Lock contention is a precondition. With a free lock the write happens without yielding, so the gap only exists when another process holds the lock. Reproduced in a test with a held lock; not observed on a real ZCode install.
  • stdin EOF also takes the decline, because stopping the watchdog sets the same flag. The outcome is the same as before for a tick that had not reached its write: the exit handoff acts from the old origin.
  • The later plugin-mode stamp is not guarded. Measured on a legacy-format scratch store: stamping after the store was reverted leaves it byte-identical. Not checked on the new-format store.
  • The tick's trailing drift repair is not covered. That is Zcode store-drift repair can overwrite a route transferred during its health probes #63.
  • Correction to PR fix: zcode exit handoff covers a route written by an in-flight watchdog replacement #64's body: it said a proxy respawned during shutdown is "left running and unrouted". The tick does not route to it, but the exit handoff routes the store to it if replacement discovery reports it attachable. The new EOF test pins both outcomes through the discovery seam; what real discovery returns for a just-spawned proxy was not tested.

Verification

Windows 11, Node v24.14.0, targeted only. CI on the pushed head is the authority.

  • tests/zcode-mcp-eof.test.ts: 17 of 17 pass. On unchanged master the new signalled=true test fails with the store routed to the new origin at exit.
  • tests/zcode-native.test.ts: 39 of 39. tests/zcode-mcp-entry.test.ts and tests/zcode-mcp-degraded.test.ts: 15 of 15.
  • npx tsc --noEmit --project tsconfig.json: clean.
  • Mutations, each restored afterwards:
    • Tick always throws on a declined write: the signalled=true test fails.
    • Check hoisted out of the lock: the signalled=true test and both shouldWrite tests fail.
    • Tick's shutdown branch removed: both EOF respawn tests and the existing blocked-in-ensure test fail.

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

#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)
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

📦 Built Package Artifact

Branch: 2026-11-14_zcode-watchdog-route-declined-after-shutdown (914c0f3)

Download artifact

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

Install instructions are refreshed on each push.

@anuzzolilli-oss
anuzzolilli-oss marked this pull request as ready for review November 14, 2026 19:24
events: new EventEmitter(),
handoff: (ownOrigin) => handoffZcodeRoutingOnExit({
ownOrigin, dataDir: dir, env: {}, log: () => {},
findReplacement: async () => (attachable ? { origin: NEW } : undefined),

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 handoff's runtime-info request from the fixed port

With attachable=true, this replacement invokes the real activateZcodePluginMode through handoffZcodeRoutingOnExit (src/zcode/native.ts:616-618), which POSTs runtime-info to NEW, http://127.0.0.1:28787. The activate stub above only covers the watchdog, and neither test preload mocks fetch. If another listener accepts the connection without responding, the request's own 5,000 ms timeout (src/agent/shared.ts:24,298-303) starts after the test's 5,000 ms deadline has begun, so this routing test fails despite correct shutdown behavior. Stub the runtime-info fetch with a test-scoped, automatically restored mock so the test does not contact an unowned fixed port.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

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

Valid. Fixed in 914c0f3: the test now answers the runtime-info request with a test-scoped fetch mock, restored automatically, and asserts the request goes to the replacement origin only when one is reported.

@kilo-code-bot

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

Copy link
Copy Markdown

(ai: openai/gpt-6-astra)

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Reviewed the incremental changes from 296eb0c to 914c0f3: the test-scoped fetch mock and assertions for both replacement-discovery outcomes. Light pass used. No current unresolved findings. Static review only; no code or tests executed, and CI results were not independently verified.

Files Reviewed (1 file)
  • tests/zcode-mcp-eof.test.ts
Previous Review Summary (commit 296eb0c)

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

Previous review (commit 296eb0c)

(ai: openai/gpt-6-astra)

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Reviewed all 3 changed files at 296eb0c7bfde88fb2df5f79f285efda4c3f1b1b6, covering shutdown routing, the config-lock write guard, and regression tests. Default-depth review; Light pass not used. Static analysis only; no code or tests executed and CI results were not independently verified.

Overview

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

WARNING

File Line Issue
tests/zcode-mcp-eof.test.ts 281 The attachable EOF case sends a real runtime-info POST to fixed port 28787. An unresponsive listener causes the five-second test deadline to expire; isolate the request with a test-scoped fetch mock.
Files Reviewed (3 files)
  • src/zcode/mcp-entry.ts - 0 issues
  • src/zcode/native.ts - 0 issues
  • tests/zcode-mcp-eof.test.ts - 1 warning

Fix these issues in Kilo Cloud


Reviewed by gpt-6-astra · Input: 33 · Output: 34.7K · Cached: 399.5K

Review guidance: REVIEW.md from base branch master

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)
@anuzzolilli-oss
anuzzolilli-oss merged commit a8747c1 into master Nov 14, 2026
44 checks passed
@anuzzolilli-oss
anuzzolilli-oss deleted the 2026-11-14_zcode-watchdog-route-declined-after-shutdown branch November 14, 2026 23:50
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 watchdog replacement can write its route after a signal exit handoff when it was waiting on the config lock

1 participant