fix: close 18 defects found by a full review of the repo

[btravers]

A full review of packages/start, examples/ and the docs turned up 18
defects. All are fixed here, test-first: every code change was driven by a test
watched failing for the defect itself, and the RED output is quoted in the
review notes below.

Kernel (7)

Five change observable behaviour, so this is a minor changeset.

Defect	Effect
drain.ts sampled awaitIdle() alongside Serving.drain instead of behind it	a unit opening while drain resolved was abandoned with the whole budget unspent
stop() / uncaught never aborted in-flight units	work ran on unsignalled against the state the skip exists to avoid
runMain ignored teardownErrors	a shutdown whose finalisers all failed exited 0
the pre-drain delay ignored time already elapsed	a signal mid-build paid the delay twice, risking SIGKILL
a bad probe port escaped as a Defect	exit 70 where a modeled startup failure exits 1
stderrSink dropped every Error cause	{"type":"uncaught","cause":{}}, and nothing at all when circular
the probe server kept no 'error' listener after binding	a transient accept fault tore down the process

Two are worth reading the diff for. The drain one is invisible to
testRuntime, whose drain resolves synchronously — it only bites a runtime
whose drain is a real wait, which is why the matching order-api defect below
compounds it. The probe listener one had an existing test asserting
listenerCount === 0, itself a deliberate fix for the opposite bug (a stale
onBindError resolving a settled deferred); neither zero listeners nor a stale
one is right, so the bind listener is now swapped rather than removed, and
that test was rewritten to pin both halves.

Examples (5)

• orpc-runtime: drain now marks open responses Connection: close.
  closeIdleConnections() reaches only connections idle at that instant, so a
  busy keep-alive connection survived and node kept serving requests down it —
  measured on Node 22.19: handler invoked twice, socket never destroyed. The
  load-bearing half is marking responses already in flight; their request
  callback ran before the drain existed.
• orpc-runtime: permanent 'error' listener, same shape as the kernel.
• orpc-runtime: an empty x-request-id no longer becomes the trace id.
  traceId falls back to meta.id only when nullish, so "" won.
• queue.ts: a reused message id no longer strands the first publisher
  forever. The example's headline scenario is the duplicate order; only distinct
  ids in the specs hid this.
• temporal-runtime: forceAfter defaults to 15 seconds, below the
  kernel's drainTimeoutMs, as its own TSDoc already advised.

Docs (6)

#10 moved two sections into packages/start/CLAUDE.md but left the root README
pointing where they used to be, and dropped two facts the repo cannot tell a
session itself — the .js import rule (the options live in an external
tsconfig) and the deliberate >=20 vs >=22.19engines divergence. Also
fixed: six→eight example packages, which CLAUDE.md the sync rule means, and
three→four needs-gate.test-d.ts files (the fourth pins di's gate, not
start's). Every behaviour change above is documented in the same commit as its
code.

Gate

format, lint, typecheck, knip, build green. 101 kernel tests (+8)
and 85 example tests (+3). Coverage holds at 100% lines/functions/statements;
branch coverage improved 96.55% → 97.7%.

One caveat: invariants.spec.ts → "binds 9000 when no probe port is given"
could not be run locally — a proxy holds 127.0.0.1:9000 on this machine. It is
unmodified and should pass in CI. Coverage was verified by skipping it
temporarily and restoring it.

Two deliberate omissions

• orpc-runtime's error-listener fix ships without its own test. Reaching
  the raw http.Server needs vi.mock("node:http") atop the spec (vi.spyOn
  fails with Cannot redefine property), which breaks the examples' test
  convention feat: the application kernel #1 in the workspace whose spec shape is the teaching material. The
  identical mechanism is guarded in packages/start/src/probes.spec.ts.
• The port-9000 test is untouched. Every alternative weakens it: mocking the
  bind proves the default is passed but not that it works, and a conditional
  skip is exactly the assertion-that-declines-to-run the test conventions
  forbid. Its comment shows this was already weighed once.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR addresses a set of shutdown/drain correctness defects across the @btravstack/start kernel and its example runtimes, with accompanying test coverage and documentation updates to keep runtime invariants and operator-facing semantics aligned.

Changes:

• Kernel: fixes drain sequencing, shutdown timing (pre-drain delay accounting), unit abort behavior on drain-skipping exits, probe server error handling, and stderr event rendering; updates exit-code semantics to treat teardown failures as unclean exits.
• Examples: fixes HTTP drain behavior for keep-alive connections, trace ID handling for empty headers, queue settlement behavior for reused message IDs, and aligns Temporal force-shutdown defaults with kernel drain timing.
• Docs/changeset: updates READMEs / CLAUDE guidance and adds a minor changeset for the kernel behavior changes.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
README.md	Updates root documentation for exit codes and corrects doc pointers and example counts.
packages/start/src/start.ts	Tracks shutdown-request time, adjusts pre-drain delay, and aborts in-flight units on drain-skipping exits.
packages/start/src/start.spec.ts	Adds coverage for pre-drain delay accounting and abort-on-stop behavior.
packages/start/src/run-main.ts	Treats teardown errors as “unclean” and maps them to exit code 2.
packages/start/src/run-main.spec.ts	Adds test ensuring teardown errors produce exit code 2.
packages/start/src/probes.ts	Prevents synchronous listen() throws from escaping as defects; keeps a permanent post-bind error listener.
packages/start/src/probes.spec.ts	Adds tests for modeled bad-port failures and post-bind error absorption.
packages/start/src/events.ts	Improves stderr event rendering for Error causes and adds a safe fallback when JSON serialization fails.
packages/start/src/events.spec.ts	Adds tests ensuring Error causes are rendered and circular causes don’t drop the event.
packages/start/src/drain.ts	Sequences awaitIdle() after runtime drain completion to avoid abandoning units that open while drain is still resolving.
packages/start/src/drain.spec.ts	Adds coverage for units opening while runtime drain is still pending.
packages/start/README.md	Updates package README exit-code semantics to match runMain.
packages/start/CLAUDE.md	Updates kernel-internals guidance to reflect the fixed invariants and sequencing rationale.
examples/order-worker/src/queue.ts	Changes settlement tracking to handle multiple concurrent waiters per message id.
examples/order-worker/src/queue-runtime.spec.ts	Adds test ensuring both publishes settle when IDs are reused concurrently.
examples/order-temporal/src/temporal-runtime.ts	Adjusts forceAfter default to 15s and documents the rationale vs drain timeout/k8s grace period.
examples/order-api/src/test-fixtures.ts	Adds raw keep-alive socket fixture helpers to test drain behavior and empty header cases.
examples/order-api/src/orpc-runtime.ts	Marks in-flight responses Connection: close during drain and adds a permanent server error listener; treats blank x-request-id as absent.
examples/order-api/src/orpc-runtime.spec.ts	Adds tests for empty x-request-id and for draining a busy keep-alive connection.
examples/order-api/README.md	Documents the Connection: close requirement during drain for busy keep-alive connections.
CLAUDE.md	Updates root spec (stderr cause rendering, exit-code semantics, example counts, and doc-drift sync rules).
.changeset/drain-and-shutdown-fixes.md	Adds a minor changeset describing the kernel shutdown/drain fixes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.