fix: stop/cancel/preempt robustness aligned with Python reference + docs

[william0wang]

Summary

Three rounds of fixes to the stop/cancel/preempt path, found by diffing against the Python reference (zcode-open-bridge), plus documentation updates (acknowledgements, related projects, SECURITY.md).

Stop / cancel / preempt fixes

1. Replace 30s lock-probing with fire-and-forget stop

The earlier ensureTurnStopped sent session/stop then probed session/goal show for up to 30s. Logs showed it timed out repeatedly (90s+ stalls) because the probe returns inconsistent values after stop. Replaced with stopBackendTurn — a fire-and-forget stop that mirrors Python's _cancel_backend_turn. The backend's own turn.completed(cancelled) event is the reliable release signal.

All six bare session/stop notify sites plus the session/send error path were rewritten. ensureTurnStopped (dead code) was deleted.

2. Serialize prompt preempt under a per-session lock

Two near-simultaneous prompts could both scan pendingTurns before either registers, miss each other, and run concurrently (listener overwrite, differ corruption). Added withPreemptLock — a per-zcodeSid promise chain that wraps "register self + preempt others" so concurrent prompts execute strictly one after another.

Also fixes close()'s 3s exit-wait timer leak (the timer was never cleared, keeping the event loop alive).

3. Align stop/reply/usage with Python

• session/stop now carries an id via a new send() method (some backends route by id presence); Python's _cancel_backend_turn always carried one.
• sendReply/sendError mark readerDead on broken pipe, matching request() — without this, a half-closed stdin silently dropped replies and zcode reannounces spun the dedup cache forever.
• translateTurnDone's used fallback chain uses || instead of ?? to match Python's or semantics (a falsy totalTokens falls back to tokenCount).

Verification

• Logs confirm the full preempt chain works: cancel detected

[gemini-code-assist]

Code Review

This pull request introduces a per-session preempt lock to serialize prompt registration and cancellation, replaces polling-based turn stopping with a fire-and-forget mechanism, adds a watchdog timer cleanup, and updates documentation including a new security policy. The reviewer feedback highlights two critical issues: first, withPreemptLock's finally chain lacks a .catch() handler, which could trigger an UnhandledPromiseRejection upon rejection; second, the synchronous try/catch blocks around stdin.write are ineffective for catching asynchronous stream errors (like EPIPE) in Node.js, and should be replaced with an 'error' event listener on the stream.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

In withPreemptLock, next.finally(...) is called to clean up the lock map once the promise settles. However, next.finally(...) returns a new promise that propagates the rejection if next is rejected. Since this returned promise is neither returned nor caught, it will trigger an UnhandledPromiseRejection in Node.js if the body of the lock (e.g., preemptInFlightTurn) rejects.

To prevent this, append .catch(() => {}) to the finally call to safely consume any propagated rejection.

Suggested change

	next.finally(() => {
	if (server.preemptLocks.get(zcodeSid) === next) {
	server.preemptLocks.delete(zcodeSid);
	}
	// Grace window expired without ever seeing the lock: turn never started
	// (stop caught it in time) or already ended. Safe to treat as released.
	log(` [stop] no lock observed within grace window, treating as released`);
	return true;
	}
	log(` [stop] lock wait timed out (30s), lock may still be held`);
	return false;
	});
	next.finally(() => {
	if (server.preemptLocks.get(zcodeSid) === next) {
	server.preemptLocks.delete(zcodeSid);
	}
	}).catch(() => {});

[gemini-code-assist]

In Node.js, stream.write() is asynchronous and does not throw synchronous exceptions for write errors like EPIPE (broken pipe). Instead, these errors are emitted as 'error' events on the stream (stdin).

The synchronous try/catch block here will not catch these errors, and if there is no 'error' event listener registered on this.proc.stdin, the entire Node.js process will crash with an unhandled 'error' event.

To fix this robustly:

1. Register an 'error' event listener on this.proc.stdin (e.g., in the constructor of ZcodeBackend or during initialization) to handle write errors and mark the reader dead:

   this.proc.stdin?.on('error', (err) => {
     this.readerDead = true;
     log(`backend: stdin error: ${err.message}`);
   });

2. Remove the redundant and ineffective try/catch blocks around stdin.write calls in sendReply and sendError.

    stdin.write(JSON.stringify({ id, result }) + "\n");

[gemini-code-assist]

In Node.js, stream.write() is asynchronous and does not throw synchronous exceptions for write errors like EPIPE (broken pipe). Instead, these errors are emitted as 'error' events on the stream (stdin).

The synchronous try/catch block here will not catch these errors, and if there is no 'error' event listener registered on this.proc.stdin, the entire Node.js process will crash with an unhandled 'error' event.

To fix this robustly:

1. Register an 'error' event listener on this.proc.stdin (e.g., in the constructor of ZcodeBackend or during initialization) to handle write errors and mark the reader dead:

   this.proc.stdin?.on('error', (err) => {
     this.readerDead = true;
     log(`backend: stdin error: ${err.message}`);
   });

2. Remove the redundant and ineffective try/catch blocks around stdin.write calls in sendReply and sendError.

    stdin.write(JSON.stringify({ id, error: { code, message } }) + "\n");