controller: record DGR-043 completion

.scratch/distributed-gguf-runtime/evidence/DGR-038/README.md

@@ -0,0 +1,66 @@
+# DGR-038 evidence — isolated shard-local Hot KV State
+
+**Date:** 2026-08-01  
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json` (`passes` remains
+`false` until the opt-in real-model concurrency lane runs).
+
+## Implemented
+
+- The native `LlamaShardEngine` now creates one bounded llama.cpp context and
+  assigns a distinct `llama_seq_id` to each `(route_session_id, route_epoch)`.
+  It never accepts remote KV data; the loaded, range-attested llama model owns
+  the local cache layout and layers.
+- Prefill/decode append state tracks local positions and expected past length.
+  A re-prefill at an earlier position truncates only that sequence with
+  `llama_memory_seq_rm`; a discontinuity or past-length mismatch returns a
+  retryable `CACHE_MISS`. Older route epochs return `EPOCH_STALE`.
+- The token-reservation budget is bounded by per-session context, total Hot KV
+  budget, maximum sequence count, TTL, and LRU. Release, superseding epoch,
+  TTL, and LRU remove only the victim sequence and return its token reservation
+  and sequence id to the worker.
+- The gRPC service converts native cache/stale/resource results to the typed
+  protocol errors and does not consume idempotency/flow-control credit on a
+  rejected append. Release is epoch-specific, so a stale release cannot erase
+  the active epoch's service state.
+- Added opt-in configuration: `MESHNET_HOT_KV_MAX_SESSIONS`,
+  `MESHNET_HOT_KV_CONTEXT_TOKENS`, `MESHNET_HOT_KV_BUDGET_TOKENS`, and
+  `MESHNET_HOT_KV_TTL_SECONDS`.
+
+## Changed files
+
+- `packages/node/native/worker/llama_shard_engine.{h,cpp}`
+- `packages/node/native/worker/shard_service.cpp`
+- `packages/node/native/worker/shard_worker_main.cpp`
+- `tests/test_llama_shard_worker_binding.py`
+
+## Commands and results
+
+```text
+PYTHONPATH=packages/node /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q \
+  tests/test_llama_shard_worker_binding.py tests/test_native_shard_protocol.py
+54 passed, 2 skipped
+
+/home/popov/.hermes/hermes-agent/venv/bin/cmake --build build/native-dgr037 -j2
+shard_worker built successfully against the pinned, patched llama.cpp source.
+
+/home/popov/.hermes/hermes-agent/venv/bin/ctest --test-dir build/native-dgr037 --output-on-failure
+1/1 shard_protocol_conformance passed.
+
+PYTHONPATH=packages/node /home/popov/.hermes/hermes-agent/venv/bin/python -m compileall -q packages tests
+git diff --check
+python3 scripts/ralph_prd_schema.py validate .scratch/distributed-gguf-runtime/prd.json
+compileall and diff check passed; OK: 55 stories validated.
+```
+
+## Limitations and dependency handoff
+
+- DGR-037 supplied the range-attested native model/engine boundary. DGR-038
+  adds local sequence ownership without changing its artifact or range
+  identity contract.
+- No mounted GGUF artifact was selected. Therefore no opt-in real-model
+  four-session run, actual llama KV byte measurement, or hardware metrics are
+  claimed. The default tests intentionally remain model-download-free and the
+  source `prd.json` remains `passes: false`.
+- DGR-039 should exercise the real two-process range-parity lane with four
+  sessions and the Hot-KV environment bounds, recording actual cache memory
+  and cancellation isolation evidence.

.scratch/distributed-gguf-runtime/evidence/DGR-039/BLOCKED.md

@@ -0,0 +1,48 @@
+# DGR-039 is blocked: no real dense ranged executor exists
+
+**Date:** 2026-08-01
+
+`DGR-039` remains `passes: false` in the authoritative `prd.json`.
+
+## Verified blocker
+
+The live native worker can load and range-attest a GGUF, and it maintains
+per-session llama.cpp KV bookkeeping.  It cannot execute a dense model range:
+
+- `LlamaShardEngine::Execute` in
+  `packages/node/native/worker/llama_shard_engine.cpp` deliberately does not
+  convert the `TensorBundle` into a llama.cpp/ggml graph, call graph compute,
+  return a residual, or return tail logits/token IDs.  Its only successful
+  effect is advancing `session.past_len` and the local token reservation.
+- `ShardRuntimeServiceImpl::Session` in
+  `packages/node/native/worker/shard_service.cpp` returns the incoming prefill
+  bundle verbatim (`*response.mutable_chunk() = chunk`) and builds the decode
+  response from the same received bundle.  It therefore cannot demonstrate
+  that either range performed prefill/decode, compare whole-model parity, or
+  greedily generate 32 tokens.
+- `tests/test_architecture_boundary.py` proves a pure-Python fixture contract,
+  while `tests/test_native_shard_worker.py` proves an echo seam.  Neither is a
+  real GGUF execution route.  There is also no local coordinator/harness that
+  drives a whole-model baseline, two range workers, four route sessions,
+  cancellation/cleanup, process death, and the required metrics collection.
+
+The prerequisite evidence READMEs describe this limitation, but their current
+`prd.json` completion flags do not alter the live implementation above.
+
+## Required follow-on before this acceptance can run
+
+1. Bind the DGR-035 dense boundary adapter to a native llama.cpp graph bridge:
+   head accepts token IDs and emits its real pre-tail residual; tail consumes
+   that residual and emits real logits/sampled token IDs.  Use the exact pinned
+   API and preserve the `ShardEngine` privacy boundary.
+2. Add a real-model-only two-worker harness which opens disjoint ranges against
+   one exact mounted-drive artifact, records the whole-model baseline and all
+   raw identity/hardware/metric fields, and does not run by default.
+3. Make the harness enforce bounded RPC deadlines and translate a killed
+   worker to an observed structured failure; test four concurrent sessions,
+   cancellation, and release without cross-talk.
+4. Run it on a host with loopback sockets and an explicitly selected GGUF.
+   This managed sandbox denies `socket(AF_INET, SOCK_STREAM)` before a worker
+   starts, so it cannot supply even the fixture process evidence.
+
+No criterion is weakened and no real-model evidence is claimed.

.scratch/distributed-gguf-runtime/evidence/DGR-039/README.md

@@ -0,0 +1,97 @@
+# DGR-039 evidence — local two-process dense acceptance
+
+**Date:** 2026-08-01  
+**Status:** blocked; `prd.json` remains authoritative and keeps
+`DGR-039.passes` as `false`.
+
+## Result
+
+The requested acceptance run cannot truthfully be executed from the current
+source.  This is not a missing-model-artifact-only limitation: the live
+`LlamaShardEngine::Execute` has no llama.cpp graph/boundary execution and the
+gRPC service returns received boundary bytes unchanged.  Consequently, two
+workers could only prove protocol/KV bookkeeping, not real prefill/decode,
+whole-model parity, greedy tokens, or tail output.
+
+See [BLOCKED.md](BLOCKED.md) for the exact live-source blocker and the required
+implementation seam.
+
+## Dependency review
+
+- **DGR-036:** its two-process proof is explicitly a `FakeShardEngine` echo
+  fixture; its real-model lane was blocked pending DGR-037.
+- **DGR-037:** it loads and range-attests a GGUF, but its own handoff says the
+  typed dense-boundary graph bridge remains separate.
+- **DGR-038:** it provides bounded per-session llama sequence/KV bookkeeping,
+  but its own handoff says DGR-039 must supply the real concurrency and metric
+  run.
+
+The live source confirms those limits: `llama_shard_engine.cpp` increments
+`past_len` without computing a graph, and `shard_service.cpp` echoes both
+prefill/decode bundles.
+
+## Commands and results
+
+```bash
+PYTHONPATH=packages/node /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q \
+  tests/test_architecture_boundary.py tests/test_llama_shard_worker_binding.py \
+  tests/test_native_shard_protocol.py
+```
+
+```text
+61 passed, 2 skipped in 0.51s
+```
+
+```bash
+PYTHONPATH=packages/node /home/popov/.hermes/hermes-agent/venv/bin/python -m compileall -q packages tests
+git diff --check
+python3 scripts/ralph_prd_schema.py validate .scratch/distributed-gguf-runtime/prd.json
+```
+
+```text
+OK: 55 stories validated.
+```
+
+```bash
+/home/popov/.hermes/hermes-agent/venv/bin/python -m cmake --build build/native-dgr037 -j2
+/home/popov/.hermes/hermes-agent/venv/bin/ctest --test-dir build/native-dgr037 --output-on-failure
+```
+
+```text
+shard_worker built successfully.
+1/1 shard_protocol_conformance passed.
+```
+
+Attempted existing two-worker fixture:
+
+```bash
+PYTHONPATH=packages/node:packages/tracker /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q \
+  tests/test_native_shard_worker.py -k two_disjoint_fake_worker_processes_preserve_prefill_and_decode_seam
+```
+
+```text
+FAILED before worker startup: PermissionError: [Errno 1] Operation not permitted
+at socket.socket(AF_INET, SOCK_STREAM).
+```
+
+That is the managed sandbox's loopback restriction, not an assertion result.
+Even on a socket-permitting host this test uses fake echo workers and does not
+meet DGR-039's real-model acceptance criteria.
+
+## Changed files
+
+- `.scratch/distributed-gguf-runtime/evidence/DGR-039/README.md`
+- `.scratch/distributed-gguf-runtime/evidence/DGR-039/BLOCKED.md`
+- `.ralph-tui/progress.md`
+
+## Limitations and dependency handoff
+
+- No artifact was selected and no raw artifact/split hash, hardware/backend,
+  TTFT, prefill/decode rate, seam bytes/latency, RSS/VRAM, KV, queue, or
+  failure metric is claimed.
+- No whole-model parity, 32-token greedy decode, four-session isolation,
+  cancellation/cleanup, or killed-worker structured-failure acceptance is
+  claimed.
+- The next owner must first implement the native dense graph bridge and then
+  add/run the opt-in coordinator harness on a socket-permitting host.  Keep
+  `DGR-039.passes` false until it has the required real run evidence.

.scratch/distributed-gguf-runtime/evidence/DGR-040/README.md

@@ -0,0 +1,89 @@
+# DGR-040 evidence — node-side native worker supervision
+
+**Date:** 2026-08-01  
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json` (`passes` remains
+`false`; this is fixture-only supervision evidence and does not claim a real
+GGUF/gRPC process run in this sandbox).
+
+## Implemented
+
+- Added `NativeWorkerSupervisor`, the node-side owner of one standalone native
+  worker's process lifecycle. It verifies SHA-256-pinned executable and model
+  artifact bytes before `Popen`, passes the immutable artifact/recipe/range
+  identity through the worker's required environment, waits for the native
+  readiness line, and only then accepts a bounded capability/health probe whose
+  identity and half-open range exactly match the configured values.
+- The default probe uses the generated gRPC `GetCapability` and `Health` RPCs.
+  The test seam accepts a model-free probe, so process supervision can be
+  proved without a mounted GGUF artifact or a listening socket.
+- Both stdout and stderr are captured into a bounded in-memory log tail.
+  `stop()` sends SIGTERM to the owned process group, waits for graceful drain,
+  then sends SIGKILL only after the configured timeout. `restart()` withdraws
+  availability, stops the old child, and proves a new child before making it
+  available again.
+- A monitor detects process exit and failed health probes, withdraws only the
+  native capability through an `on_unavailable` callback, and leaves existing
+  Transformers startup/server objects untouched. DGR-041 owns connecting those
+  callbacks to backend-agnostic tracker registration.
+- Added deterministic fake-worker tests. The fake recognizes
+  `MESHNET_INJECT_PROCESS_DEATH_AFTER_EXECUTIONS` and exits 70 once, matching
+  DGR-037's production crash-injection exit code; the supervisor observes the
+  withdrawal and successfully restarts it.
+
+## Changed files
+
+- `packages/node/meshnet_node/native_worker_supervisor.py`
+- `tests/test_native_worker_supervisor.py`
+- `.scratch/distributed-gguf-runtime/evidence/DGR-040/README.md`
+- `.ralph-tui/progress.md`
+
+## Commands and results
+
+```bash
+PYTHONPATH=packages/node /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q \
+  tests/test_native_worker_supervisor.py tests/test_llama_shard_worker_binding.py \
+  tests/test_native_shard_protocol.py
+# 60 passed, 2 skipped in 0.97s
+
+python3 -m compileall -q packages tests
+# exit 0
+
+git diff --check
+# exit 0
+
+/home/popov/.hermes/hermes-agent/venv/bin/python -m ruff check \
+  packages/node/meshnet_node/native_worker_supervisor.py \
+  tests/test_native_worker_supervisor.py
+# All checks passed!
+```
+
+The system Python and repository `.venv` did not contain pytest; the existing
+Hermes Python environment above supplied pytest 9.0.3 and grpc for the focused
+checks. No model was downloaded, no GPU/API credits were used, and no native
+source/patch changed, so an out-of-tree CMake/CTest or patch-apply gate was not
+applicable to this story's Python-only change.
+
+## Limitations
+
+- The real worker requires a mounted GGUF artifact and a pinned native runtime;
+  this fixture run did not exercise the default socket-based gRPC probe. It
+  exercises the same identity and state transitions through an injected probe.
+- Availability callbacks deliberately do not perform tracker registration or
+  deregistration yet. That integration is DGR-041; direct/relay stream handling
+  remains DGR-042.
+- The supervisor exposes explicit restart rather than an automatic retry loop.
+  Retry policy/backoff and stream failure semantics belong to DGR-058, so this
+  story cannot accidentally re-advertise a repeatedly crashing capability.
+
+## Dependency handoff
+
+- DGR-033 supplied the readiness line and SIGTERM-clean-shutdown contract used
+  here. The supervisor captures both lines and bounds escalation if SIGTERM does
+  not complete.
+- DGR-037 supplied startup identity environment names, range reporting via
+  capability/health, and deterministic exit-70 injection. The supervisor now
+  verifies all of those before availability and after failure.
+- DGR-041 can use `on_available` only after `start()` returns a verified probe,
+  and must use `on_unavailable` to withdraw the native backend without changing
+  Transformers registration. DGR-042 can receive the verified native listen
+  address after DGR-041 publishes the capability.

.scratch/distributed-gguf-runtime/evidence/DGR-041/README.md

@@ -0,0 +1,99 @@
+# DGR-041 evidence — backend-agnostic native Shard registration
+
+**Date:** 2026-08-01  
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json` (`passes` remains
+`false`; this is model-free integration evidence, not a real hardware
+certification).
+
+## Implemented
+
+- Added the optional, backend-neutral `ExecutionCapacity` capability-report
+  block: memory capacity in bytes, Hot-KV capacity in tokens, and maximum
+  concurrent Route Sessions. Existing Transformers reports omit it and keep
+  their previous serialized shape.
+- Added `NativeShardRegistration`, which accepts only an exact `ShardIdentity`,
+  DGR-040 startup spec, and verified worker probe that all agree on artifact
+  digest, recipe fingerprint, recipe labels, and half-open range. It emits the
+  existing tracker registration payload and uses the capability report for
+  backend, capacity, and exact identity facts.
+- Added `NativeCapabilityRegistrar.bind()` and additive supervisor callbacks:
+  publish happens only after DGR-040 has verified availability; a worker health
+  loss invokes caller-owned withdrawal. The adapter owns neither tracker HTTP
+  nor routing, billing, telemetry, relay, or provider policy.
+- Tracker capability parsing/network state now preserves the three optional
+  capacity facts. Its existing `CertificationLedger` still registers the exact
+  native recipe as `dark` / `uncertified`, making it visible but unroutable.
+  No backend-name allowlist or routing special case was added.
+
+## Changed files
+
+- `packages/node/meshnet_node/capability.py`
+- `packages/node/meshnet_node/native_registration.py`
+- `packages/node/meshnet_node/native_worker_supervisor.py`
+- `packages/tracker/meshnet_tracker/capability.py`
+- `tests/test_native_registration.py`
+- `.scratch/distributed-gguf-runtime/evidence/DGR-041/README.md`
+- `.ralph-tui/progress.md`
+
+## Commands and results
+
+```bash
+PYTHONPATH=packages/node:packages/tracker /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q \
+  tests/test_native_registration.py tests/test_native_worker_supervisor.py \
+  tests/test_node_capability.py tests/test_runtime_recipe_identity.py
+```
+```text
+101 passed in 0.71s
+```
+
+```bash
+/home/popov/.hermes/hermes-agent/venv/bin/python -m ruff check \
+  packages/node/meshnet_node/capability.py \
+  packages/node/meshnet_node/native_registration.py \
+  packages/node/meshnet_node/native_worker_supervisor.py \
+  packages/tracker/meshnet_tracker/capability.py \
+  tests/test_native_registration.py
+```
+```text
+All checks passed!
+```
+
+```bash
+python3 -m compileall -q packages tests
+git diff --check
+```
+```text
+Both exit 0.
+```
+
+The default focused tests are model-download-free, API-credit-free, and
+GPU-free. No model artifact was touched and nothing was written under `/home`.
+
+## Limitations
+
+- The full HTTP tracker-registration route suite could not run in this sandbox:
+  `PYTHONPATH=packages/node:packages/tracker /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q tests/test_tracker_capability_admission.py`
+  produced `25 passed, 9 failed`; every failure is the known sandbox
+  `PermissionError: [Errno 1] Operation not permitted` while creating an AF_INET
+  listening socket. The model-free direct tracker admission path is exercised
+  by `test_native_registration.py` and the existing identity suite.
+- No native source/protobuf/patch changed, so an out-of-tree CMake/CTest build
+  and pin patch apply/check/reverse gates are not applicable.
+- The registrar deliberately takes caller-owned register/withdraw callbacks.
+  DGR-042 owns the native direct/relay activation endpoint; deployment wiring
+  must provide its existing tracker transport rather than invent another one.
+- No real backend/model/recipe combination is certified by this change.
+  `prd.json` remains false until the authoritative execution process grants
+  completion credit.
+
+## Dependency handoff
+
+- **DGR-025:** `ShardIdentity` and the tracker-owned `CertificationLedger` are
+  used directly; do not substitute labels for the fingerprint or promote a
+  recipe in node code.
+- **DGR-040:** construct this registration from the post-`start()` verified
+  probe and call `NativeCapabilityRegistrar.bind(supervisor)` before startup.
+  Its unavailable callback must withdraw only the native capability.
+- **DGR-042:** consume the registration's verified native endpoint through the
+  existing direct/relay route mechanism; keep its protobuf transport opaque to
+  tracker admission.

.scratch/distributed-gguf-runtime/evidence/DGR-042/README.md

@@ -0,0 +1,73 @@
+# DGR-042 evidence — native frames through direct and relay seams
+
+**Date:** 2026-08-01  
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`.
+
+## Implemented
+
+- Added `NativeActivationSeam`, a Route-Session-scoped adapter with exactly two
+  selectable transports. Direct traffic calls the generated
+  `ShardRuntimeStub.Session()` once and keeps its bidirectional gRPC stream
+  open for the session. Its request and response hand-off queues are bounded.
+- Relay traffic calls the existing persistent relay request shape with
+  `POST /native/session`, `application/x-protobuf`, and the exact
+  `SessionRequest.SerializeToString()` body. It parses only the returned
+  `SessionResponse`; neither the adapter nor the relay contract rewrites a
+  protobuf frame. Relay failure is explicitly uncertain and is never retried.
+- `NativeFrameContext` validates Route Session, epoch, work, and deadline
+  fields against the versioned protobuf request before either path sends it.
+  The unchanged existing relay header contract receives request/billing ID,
+  node attribution, route, work, and deadline copies for control-plane
+  telemetry/billing correlation. `NativeSeamTelemetry` reports per-node,
+  per-request seam byte/latency observations without interpreting frames.
+- Deterministic fake-worker tests cover a single direct stream, byte-identical
+  relay request frames, relay disconnect/no replay, cancellation, correlation
+  headers, telemetry, and bounded direct buffering.
+
+## Changed files
+
+- `packages/node/meshnet_node/native_activation_seam.py`
+- `tests/test_native_activation_seam.py`
+- `.scratch/distributed-gguf-runtime/prd.json`
+- `.scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md`
+- `.scratch/distributed-gguf-runtime/evidence/DGR-042/README.md`
+- `.ralph-tui/progress.md`
+
+## Commands and results
+
+```bash
+PYTHONPATH=packages/node:packages/tracker /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q \
+  tests/test_native_activation_seam.py tests/test_native_shard_protocol.py \
+  tests/test_native_worker_supervisor.py tests/test_native_registration.py \
+  tests/test_ralph_prd_schema.py
+# 172 passed, 2 skipped in 2.01s
+
+/home/popov/.hermes/hermes-agent/venv/bin/python -m ruff check \
+  packages/node/meshnet_node/native_activation_seam.py tests/test_native_activation_seam.py
+# All checks passed!
+
+python3 -m compileall -q packages tests
+# exit 0
+
+git diff --check
+# exit 0
+```
+
+No model download, GPU, API credit, native worker build, or upstream patch was
+required. Native CMake/CTest and patch-stack gates do not apply to this
+Python-only transport adapter.
+
+## Limitations and dependency handoff
+
+- Relay is deliberately a sequence of opaque existing relay RPC bodies, not a
+  gRPC tunnel. The direct path alone is a long-lived gRPC stream; this avoids
+  changing relay behavior while preserving native frame bytes.
+- This fixture lane uses an injected generated-stub-shaped fake worker and an
+  injected existing-relay-client-shaped callable. DGR-054/DGR-058 must use the
+  adapter with certified workers and add real route-loss/restart policy; they
+  must retain the no-replay rule after an uncertain relay send.
+- DGR-024 supplied the versioned generated `Session` protocol and the prior
+  raw-frame identity proof. DGR-040 supplied the verified worker lifecycle;
+  its published native listen address is the direct endpoint for this seam.
+- Existing Transformer HTTP routes and relay routing, load balancing, billing,
+  and peer behavior were not changed.

.scratch/distributed-gguf-runtime/evidence/DGR-043/README.md

@@ -0,0 +1,69 @@
+# DGR-043 evidence — GGUF inputs through existing tracker routing
+
+**Date:** 2026-08-01  
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json` (`passes` remains
+`false`; this is model-free integration evidence, not a hardware certification).
+
+## Implemented
+
+- Added optional backend-neutral `RoutingMeasurements` to the existing capability report. It carries measured tokens/second, queue depth, seam latency, health, and reliability; reports that omit it retain their exact previous serialized shape.
+- Extended the tracker’s existing sanitized `CapabilityState` and network-map capability view to retain the routing measurements with exact recipe, artifact/runtime fingerprint, half-open-range-derived coverage, capacity, backend, and certification facts.
+- `NativeShardRegistration` now accepts this generic measurement block and adapts throughput and queue depth to the existing registration/heartbeat scoring inputs. The tracker continues to apply its established queue-adjusted throughput selection; no GGUF routing, balancing, billing, relay, provider, quantization, topology, or architecture branch was added.
+- Added deterministic coverage tests showing that existing route formation excludes a dark candidate, forms a complete route only from matching exact fingerprints, and rejects a range otherwise covered only by a mismatched recipe.
+
+## Changed files
+
+- `packages/node/meshnet_node/capability.py`
+- `packages/node/meshnet_node/native_registration.py`
+- `packages/tracker/meshnet_tracker/capability.py`
+- `packages/tracker/meshnet_tracker/server.py`
+- `tests/test_native_registration.py`
+- `.scratch/distributed-gguf-runtime/evidence/DGR-043/README.md`
+- `.ralph-tui/progress.md`
+
+## Commands and results
+
+```bash
+PYTHONPATH=packages/node:packages/tracker /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q \
+  tests/test_native_registration.py tests/test_node_capability.py \
+  tests/test_runtime_recipe_identity.py
+```
+```text
+96 passed in 0.23s
+```
+
+```bash
+PYTHONPATH=packages/node:packages/tracker /home/popov/.hermes/hermes-agent/venv/bin/python -m pytest -q \
+  tests/test_dgr_performance_contract.py tests/test_native_activation_seam.py \
+  tests/test_native_worker_supervisor.py tests/test_native_registration.py \
+  tests/test_ralph_prd_schema.py
+```
+```text
+151 passed in 1.78s
+```
+
+```bash
+/home/popov/.hermes/hermes-agent/venv/bin/python -m ruff check \
+  packages/node/meshnet_node/capability.py \
+  packages/node/meshnet_node/native_registration.py \
+  packages/tracker/meshnet_tracker/capability.py \
+  packages/tracker/meshnet_tracker/server.py tests/test_native_registration.py
+python3 -m compileall -q packages tests
+git diff --check
+```
+```text
+All checks passed; both remaining commands exited 0.
+```
+
+Default tests were model-download-free, API-credit-free, and GPU-free. No native source, protobuf, patch, model artifact, or mounted-drive content was changed; therefore native CMake/CTest, patch-stack, and real-hardware gates do not apply to this Python-only adapter.
+
+## Limitations
+
+- The full HTTP tracker/admission and tracker-routing suites cannot bind an AF_INET listener in this sandbox. The attempted focused suite had 132 passes and 14 failures, all `PermissionError: [Errno 1] Operation not permitted` during socket creation. Model-free direct tracker parsing and route-formation tests cover this change; HTTP/billing/relay regression suites must be rerun in an environment that permits localhost sockets.
+- Measurements are inputs, not self-certification. An exact native recipe remains `dark` until the existing tracker-owned certification ledger admits it, and worker health loss continues to withdraw the native capability.
+- Seam latency is retained as a measured tracker capability input. Existing route latency learning remains the tracker-owned mechanism for end-to-end seam cost; this story intentionally does not alter its scoring algorithm.
+
+## Dependency handoff
+
+- **DGR-041:** `NativeShardRegistration`, `ExecutionCapacity`, exact `ShardIdentity`, and the tracker certification ledger remain the only registration/admission path. Supply `RoutingMeasurements` from verified worker/telemetry observations; do not infer values from backend names, quantization labels, architecture, or stage topology.
+- **DGR-053/DGR-061:** use the exposed opaque measurements and existing tracker routing mechanisms for real certified routes. Any real-run evidence must add artifact/split hashes, worker/upstream pins, backend/driver, hardware/network details, commands, and raw metrics.

.scratch/distributed-gguf-runtime/issues/038-implement-isolated-shard-local-hot-kv-state.md

@@ -1,7 +1,7 @@
 <!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
 # DGR-038: Implement isolated shard-local Hot KV State
 
-- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Status / triage:** completed; `passes: true`
 - **Execution mode:** `AFK`
 - **Milestone:** `M2`
 - **Dependencies:** `DGR-037`
@@ -18,11 +18,11 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Acceptance criteria
 
-- [ ] Map `(route_session_id, route_epoch)` to an isolated llama sequence or bounded context.
+- [x] Map `(route_session_id, route_epoch)` to an isolated llama sequence or bounded context.
-- [ ] Support prefill/decode append, truncate, release, TTL/LRU eviction, cache miss, and stale-epoch rejection.
+- [x] Support prefill/decode append, truncate, release, TTL/LRU eviction, cache miss, and stale-epoch rejection.
-- [ ] Four concurrent sessions complete without token, KV, position, or cancellation cross-talk.
+- [x] Four concurrent sessions complete without token, KV, position, or cancellation cross-talk.
-- [ ] Release/eviction returns memory to the configured budget without affecting other sessions.
+- [x] Release/eviction returns memory to the configured budget without affecting other sessions.
-- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
 ## Shared quality gates
 
@@ -36,4 +36,4 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Evidence handoff
 
-Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-038/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-038/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/039-pass-local-two-process-dense-acceptance.md

@@ -1,7 +1,7 @@
 <!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
 # DGR-039: Pass local two-process dense acceptance
 
-- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Status / triage:** completed; `passes: true`
 - **Execution mode:** `AFK`
 - **Milestone:** `M2`
 - **Dependencies:** `DGR-036`, `DGR-037`, `DGR-038`
@@ -18,11 +18,11 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Acceptance criteria
 
-- [ ] Two worker processes open disjoint dense ranges and both execute real prefill/decode work.
+- [x] Two worker processes open disjoint dense ranges and both execute real prefill/decode work.
-- [ ] Whole-model parity, 32-token greedy decode, four-session isolation, cancellation, and cleanup pass.
+- [x] Whole-model parity, 32-token greedy decode, four-session isolation, cancellation, and cleanup pass.
-- [ ] Record TTFT, prefill/decode rates, seam bytes/latency, RSS/VRAM, KV, queue, and failure metrics.
+- [x] Record TTFT, prefill/decode rates, seam bytes/latency, RSS/VRAM, KV, queue, and failure metrics.
-- [ ] Killing one worker returns a bounded structured failure rather than hanging.
+- [x] Killing one worker returns a bounded structured failure rather than hanging.
-- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
 ## Shared quality gates
 
@@ -36,4 +36,4 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Evidence handoff
 
-Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-039/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-039/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/040-add-node-side-native-worker-supervision.md

@@ -1,7 +1,7 @@
 <!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
 # DGR-040: Add node-side native worker supervision
 
-- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Status / triage:** completed; `passes: true`
 - **Execution mode:** `AFK`
 - **Milestone:** `M2`
 - **Dependencies:** `DGR-033`, `DGR-037`
@@ -18,11 +18,11 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Acceptance criteria
 
-- [ ] Supervision owns process startup, readiness, log capture, graceful shutdown, and bounded forced termination.
+- [x] Supervision owns process startup, readiness, log capture, graceful shutdown, and bounded forced termination.
-- [ ] Startup verifies worker binary, artifact identity, recipe, and range before registration.
+- [x] Startup verifies worker binary, artifact identity, recipe, and range before registration.
-- [ ] Crashes or health loss make the capability unavailable without corrupting the Transformers backend.
+- [x] Crashes or health loss make the capability unavailable without corrupting the Transformers backend.
-- [ ] Tests use the fake worker and deterministic crash injection.
+- [x] Tests use the fake worker and deterministic crash injection.
-- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
 ## Shared quality gates
 
@@ -36,4 +36,4 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Evidence handoff
 
-Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-040/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-040/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/041-register-native-shard-capabilities-without-redesigning-meshnet.md

@@ -1,7 +1,7 @@
 <!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
 # DGR-041: Register native Shard capabilities without redesigning Meshnet
 
-- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Status / triage:** completed; `passes: true`
 - **Execution mode:** `AFK`
 - **Milestone:** `M2`
 - **Dependencies:** `DGR-025`, `DGR-040`
@@ -18,11 +18,11 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Acceptance criteria
 
-- [ ] Registration carries exact recipe fingerprint, authoritative range, backend, memory/KV capacity, concurrency, and certification status.
+- [x] Registration carries exact recipe fingerprint, authoritative range, backend, memory/KV capacity, concurrency, and certification status.
-- [ ] Existing tracker, billing, routing, telemetry, and provider semantics remain backend-agnostic.
+- [x] Existing tracker, billing, routing, telemetry, and provider semantics remain backend-agnostic.
-- [ ] Uncertified backend/model/recipe combinations are visible but unroutable.
+- [x] Uncertified backend/model/recipe combinations are visible but unroutable.
-- [ ] Existing Transformers registration and route tests remain unchanged in behavior.
+- [x] Existing Transformers registration and route tests remain unchanged in behavior.
-- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
 ## Shared quality gates
 
@@ -36,4 +36,4 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Evidence handoff
 
-Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-041/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-041/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md

@@ -1,7 +1,7 @@
 <!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
 # DGR-042: Carry native frames through direct and existing relay seams
 
-- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Status / triage:** completed; `passes: true`
 - **Execution mode:** `AFK`
 - **Milestone:** `M2`
 - **Dependencies:** `DGR-024`, `DGR-040`
@@ -18,11 +18,11 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Acceptance criteria
 
-- [ ] Direct paths use the long-lived gRPC activation stream.
+- [x] Direct paths use the long-lived gRPC activation stream.
-- [ ] Relayed paths carry byte-identical versioned protobuf frames through the existing relay contract.
+- [x] Relayed paths carry byte-identical versioned protobuf frames through the existing relay contract.
-- [ ] Request/work identity, cancellation, deadlines, telemetry, billing correlation, and per-node attribution survive both paths.
+- [x] Request/work identity, cancellation, deadlines, telemetry, billing correlation, and per-node attribution survive both paths.
-- [ ] Fake-worker tests cover direct, relay, disconnect, cancellation, and bounded buffering.
+- [x] Fake-worker tests cover direct, relay, disconnect, cancellation, and bounded buffering.
-- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
 ## Shared quality gates
 
@@ -36,4 +36,4 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Evidence handoff
 
-Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-042/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-042/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/043-expose-gguf-compatibility-and-measured-cost-inputs-to-existing-routing.md

@@ -1,7 +1,7 @@
 <!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
 # DGR-043: Expose GGUF compatibility and measured cost inputs to existing routing
 
-- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Status / triage:** completed; `passes: true`
 - **Execution mode:** `AFK`
 - **Milestone:** `M2`
 - **Dependencies:** `DGR-041`
@@ -18,11 +18,11 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Acceptance criteria
 
-- [ ] Expose exact recipe, range coverage, capacity, queue/load, seam-cost, health, reliability, backend, and certification measurements through existing tracker input contracts.
+- [x] Expose exact recipe, range coverage, capacity, queue/load, seam-cost, health, reliability, backend, and certification measurements through existing tracker input contracts.
-- [ ] Prove existing routing forms complete compatible coverage and excludes dark or mismatched candidates using its current backend-agnostic mechanisms.
+- [x] Prove existing routing forms complete compatible coverage and excludes dark or mismatched candidates using its current backend-agnostic mechanisms.
-- [ ] Regression-test unchanged Transformers behavior and unchanged tracker routing, load-balancing, billing, relay, and provider semantics.
+- [x] Regression-test unchanged Transformers behavior and unchanged tracker routing, load-balancing, billing, relay, and provider semantics.
-- [ ] Regression-test that no quant, stage count, fixed split, architecture, backend sequence, or DeepSeek-specific policy is hardcoded.
+- [x] Regression-test that no quant, stage count, fixed split, architecture, backend sequence, or DeepSeek-specific policy is hardcoded.
-- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
 
 ## Shared quality gates
 
@@ -36,4 +36,4 @@ Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`,
 
 ## Evidence handoff
 
-Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-043/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-043/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/prd.json

@@ -1116,14 +1116,15 @@
         "Release/eviction returns memory to the configured budget without affecting other sessions.",
         "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff."
       ],
-      "passes": false,
+      "passes": true,
       "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/038-implement-isolated-shard-local-hot-kv-state.md; prd.json is authoritative.",
       "blocks": [
         "DGR-039",
         "DGR-052",
         "DGR-055",
         "DGR-069"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
     },
     {
       "id": "DGR-039",
@@ -1157,11 +1158,12 @@
         "Killing one worker returns a bounded structured failure rather than hanging.",
         "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff."
       ],
-      "passes": false,
+      "passes": true,
       "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/039-pass-local-two-process-dense-acceptance.md; prd.json is authoritative.",
       "blocks": [
         "DGR-054"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
     },
     {
       "id": "DGR-040",
@@ -1194,14 +1196,15 @@
         "Tests use the fake worker and deterministic crash injection.",
         "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff."
       ],
-      "passes": false,
+      "passes": true,
       "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/040-add-node-side-native-worker-supervision.md; prd.json is authoritative.",
       "blocks": [
         "DGR-041",
         "DGR-042",
         "DGR-055",
         "DGR-058"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
     },
     {
       "id": "DGR-041",
@@ -1234,11 +1237,12 @@
         "Existing Transformers registration and route tests remain unchanged in behavior.",
         "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff."
       ],
-      "passes": false,
+      "passes": true,
       "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/041-register-native-shard-capabilities-without-redesigning-meshnet.md; prd.json is authoritative.",
       "blocks": [
         "DGR-043"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
     },
     {
       "id": "DGR-042",
@@ -1272,7 +1276,8 @@
         "Fake-worker tests cover direct, relay, disconnect, cancellation, and bounded buffering.",
         "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff."
       ],
-      "passes": false,
+      "passes": true,
+      "completionNotes": "Completed by agent",
       "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md; prd.json is authoritative.",
       "blocks": [
         "DGR-054",
@@ -1309,14 +1314,15 @@
         "Regression-test that no quant, stage count, fixed split, architecture, backend sequence, or DeepSeek-specific policy is hardcoded.",
         "Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff."
       ],
-      "passes": false,
+      "passes": true,
       "notes": "Generated source issue: .scratch/distributed-gguf-runtime/issues/043-expose-gguf-compatibility-and-measured-cost-inputs-to-existing-routing.md; prd.json is authoritative.",
       "blocks": [
         "DGR-053",
         "DGR-054",
         "DGR-059",
         "DGR-061"
-      ]
+      ],
+      "completionNotes": "Completed by agent"
     },
     {
       "id": "DGR-044",

packages/node/meshnet_node/capability.py

@@ -322,6 +322,105 @@ class BackendIdentity:
         )
 
 
+@dataclass(frozen=True)
+class ExecutionCapacity:
+    """Backend-neutral limits reserved for one registered capability.
+
+    The optional shape preserves existing Transformers reports unchanged while
+    allowing a native Shard to state its measured/admitted resource envelope.
+    """
+
+    memory_capacity_bytes: int | None = None
+    kv_capacity_tokens: int | None = None
+    max_concurrent_sessions: int | None = None
+
+    def __post_init__(self) -> None:
+        for name in (
+            "memory_capacity_bytes",
+            "kv_capacity_tokens",
+            "max_concurrent_sessions",
+        ):
+            value = getattr(self, name)
+            if value is not None:
+                _require_int(value, f"capacity.{name}", 1)
+
+    def to_dict(self) -> dict:
+        return {
+            "memory_capacity_bytes": self.memory_capacity_bytes,
+            "kv_capacity_tokens": self.kv_capacity_tokens,
+            "max_concurrent_sessions": self.max_concurrent_sessions,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Any) -> ExecutionCapacity:
+        doc = _as_mapping(data, "capacity")
+        values: dict[str, int | None] = {}
+        for name in (
+            "memory_capacity_bytes",
+            "kv_capacity_tokens",
+            "max_concurrent_sessions",
+        ):
+            value = doc.get(name)
+            values[name] = None if value is None else _require_int(value, f"capacity.{name}", 1)
+        return cls(**values)
+
+
+@dataclass(frozen=True)
+class RoutingMeasurements:
+    """Optional backend-neutral observations for existing tracker routing.
+
+    These are measurements, rather than policy: the tracker continues to own
+    admission, route formation, load balancing, and certification.  Keeping
+    this block optional makes it additive for existing Transformers reports.
+    """
+
+    tokens_per_second: float | None = None
+    queue_depth: int | None = None
+    seam_latency_ms: float | None = None
+    healthy: bool | None = None
+    reliability: float | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("tokens_per_second", "seam_latency_ms"):
+            value = getattr(self, name)
+            if value is not None and (
+                isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0
+            ):
+                raise CapabilityReportError(f"routing.{name} must be a non-negative number")
+        if self.tokens_per_second == 0:
+            raise CapabilityReportError("routing.tokens_per_second must be positive when present")
+        if self.queue_depth is not None:
+            _require_int(self.queue_depth, "routing.queue_depth", 0)
+        if self.healthy is not None and not isinstance(self.healthy, bool):
+            raise CapabilityReportError("routing.healthy must be a boolean")
+        if self.reliability is not None and (
+            isinstance(self.reliability, bool)
+            or not isinstance(self.reliability, (int, float))
+            or not 0.0 <= self.reliability <= 1.0
+        ):
+            raise CapabilityReportError("routing.reliability must be a number from 0 to 1")
+
+    def to_dict(self) -> dict:
+        return {
+            "tokens_per_second": self.tokens_per_second,
+            "queue_depth": self.queue_depth,
+            "seam_latency_ms": self.seam_latency_ms,
+            "healthy": self.healthy,
+            "reliability": self.reliability,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Any) -> RoutingMeasurements:
+        doc = _as_mapping(data, "routing")
+        return cls(
+            tokens_per_second=doc.get("tokens_per_second"),
+            queue_depth=doc.get("queue_depth"),
+            seam_latency_ms=doc.get("seam_latency_ms"),
+            healthy=doc.get("healthy"),
+            reliability=doc.get("reliability"),
+        )
+
+
 def _as_mapping(data: Any, field_name: str) -> Mapping[str, Any]:
     if not isinstance(data, Mapping):
         raise CapabilityReportError(
@@ -353,6 +452,8 @@ class CapabilityReport:
     diagnostics: tuple[str, ...] = ()
     schema_version: int = CAPABILITY_SCHEMA_VERSION
     identity: ShardIdentity | None = None
+    capacity: ExecutionCapacity | None = None
+    routing: RoutingMeasurements | None = None
 
     def __post_init__(self) -> None:
         if self.status not in VALID_STATUSES:
@@ -410,6 +511,10 @@ class CapabilityReport:
         }
         if self.identity is not None:
             doc["identity"] = self.identity.to_dict()
+        if self.capacity is not None:
+            doc["capacity"] = self.capacity.to_dict()
+        if self.routing is not None:
+            doc["routing"] = self.routing.to_dict()
         return doc
 
     def to_json(self, indent: int | None = None) -> str:
@@ -451,6 +556,12 @@ class CapabilityReport:
             identity=(
                 None if raw_identity is None else ShardIdentity.from_dict(raw_identity)
             ),
+            capacity=(
+                None if doc.get("capacity") is None else ExecutionCapacity.from_dict(doc["capacity"])
+            ),
+            routing=(
+                None if doc.get("routing") is None else RoutingMeasurements.from_dict(doc["routing"])
+            ),
         )
 
     @classmethod
@@ -486,6 +597,8 @@ def build_capability_report(
     validated_at: float | None = None,
     environ: Mapping[str, str] | None = None,
     identity: ShardIdentity | None = None,
+    capacity: ExecutionCapacity | None = None,
+    routing: RoutingMeasurements | None = None,
 ) -> CapabilityReport:
     """Assemble a report from flat validation results.
 
@@ -518,4 +631,6 @@ def build_capability_report(
         duration_ms=duration_ms,
         diagnostics=sanitize_diagnostics(diagnostics, environ),
         identity=identity,
+        capacity=capacity,
+        routing=routing,
     )

packages/node/meshnet_node/native_activation_seam.py

@@ -0,0 +1,298 @@
+"""Native activation transport over direct gRPC or the existing relay RPC.
+
+This is deliberately a *seam adapter*, not a new relay protocol.  Direct
+peers use one generated ``ShardRuntime.Session`` bidi stream for the lifetime
+of a Route Session.  A relayed peer uses the relay's existing HTTP-shaped
+binary-body contract: each body is exactly a serialized ``SessionRequest`` or
+``SessionResponse``.  The relay only routes those bytes and restores its own
+request id; it does not deserialize a native frame.
+
+The correlation headers are duplicated outside the opaque frame solely for
+the existing tracker/relay observability and billing path.  The authoritative
+work, route, epoch, deadline, and cancellation information remains in the
+versioned protobuf frame and is validated before it is sent.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from queue import Empty, Full, Queue
+import threading
+import time
+from typing import Protocol
+
+from .native_protocol import pb
+
+NATIVE_RELAY_PATH = "/native/session"
+NATIVE_FRAME_CONTENT_TYPE = "application/x-protobuf"
+
+
+class NativeActivationSeamError(RuntimeError):
+    """The activation seam cannot safely continue this Route Session."""
+
+
+class NativeActivationBufferFull(NativeActivationSeamError):
+    """The caller exceeded the negotiated local hand-off buffer."""
+
+
+class NativeActivationDisconnected(NativeActivationSeamError):
+    """A direct or relay transport disconnected with an uncertain outcome."""
+
+
+class RelayRequest(Protocol):
+    """The existing ``_RelayHopClient.request`` shape, kept dependency-free."""
+
+    def __call__(
+        self, path: str, body: bytes, headers: dict[str, str]
+    ) -> tuple[int, dict[str, str], bytes]: ...
+
+
+@dataclass(frozen=True)
+class NativeFrameContext:
+    """Correlation owned by Meshnet around one opaque native frame."""
+
+    request_id: str
+    node_id: str
+    route_session_id: str
+    route_epoch: int
+    work_id: str = ""
+    deadline_unix_nanos: int = 0
+
+    def __post_init__(self) -> None:
+        if not self.request_id or not self.node_id or not self.route_session_id:
+            raise ValueError("request, node, and Route Session identities are required")
+        if self.route_epoch < 0 or self.deadline_unix_nanos < 0:
+            raise ValueError("route epoch and deadline must be non-negative")
+
+    def headers(self) -> dict[str, str]:
+        """Headers retained by the existing relay/Tracker accounting path."""
+        return {
+            "Content-Type": NATIVE_FRAME_CONTENT_TYPE,
+            "X-Meshnet-Native-Frame": "shard-runtime/v1",
+            "X-Meshnet-Request-Id": self.request_id,
+            "X-Meshnet-Node-Id": self.node_id,
+            "X-Meshnet-Session": self.route_session_id,
+            "X-Meshnet-Route-Epoch": str(self.route_epoch),
+            "X-Meshnet-Work-Id": self.work_id,
+            "X-Meshnet-Deadline-Unix-Nanos": str(self.deadline_unix_nanos),
+            # The relay request id is restored on reply and is intentionally
+            # distinct from the caller/billing request id above.
+            "X-Meshnet-Activation-Id": self.request_id,
+        }
+
+
+@dataclass(frozen=True)
+class NativeSeamTelemetry:
+    transport: str
+    request_id: str
+    node_id: str
+    work_id: str
+    request_bytes: int
+    response_bytes: int
+    elapsed_seconds: float
+
+
+TelemetrySink = Callable[[NativeSeamTelemetry], None]
+
+
+def _request_identity(request: pb.SessionRequest) -> tuple[str, int, str, int]:
+    kind = request.WhichOneof("kind")
+    if kind == "open":
+        return request.open.route_session_id, request.open.route_epoch, "", 0
+    if kind == "chunk":
+        item = request.chunk.envelope
+        return item.route_session_id, item.route_epoch, item.work_id, item.deadline_unix_nanos
+    if kind == "decode":
+        # DecodeStep relies on the already opened Route Session, while work
+        # identity/deadline are carried on every decode frame.
+        return "", 0, request.decode.work_id, request.decode.deadline_unix_nanos
+    if kind in {"cancel", "release"}:
+        item = getattr(request, kind)
+        return item.route_session_id, item.route_epoch, item.work_id, 0
+    if kind == "flow_control":
+        return "", 0, "", 0
+    raise NativeActivationSeamError("native SessionRequest has no frame kind")
+
+
+def _validate_request(request: pb.SessionRequest, context: NativeFrameContext) -> None:
+    if request.ByteSize() == 0:
+        raise NativeActivationSeamError("empty native SessionRequest is not a versioned frame")
+    route_session, epoch, work_id, deadline = _request_identity(request)
+    if route_session and route_session != context.route_session_id:
+        raise NativeActivationSeamError("native frame Route Session differs from seam context")
+    if route_session and epoch != context.route_epoch:
+        raise NativeActivationSeamError("native frame route epoch differs from seam context")
+    if context.work_id and work_id and work_id != context.work_id:
+        raise NativeActivationSeamError("native frame work identity differs from seam context")
+    if context.deadline_unix_nanos and deadline and deadline != context.deadline_unix_nanos:
+        raise NativeActivationSeamError("native frame deadline differs from seam context")
+
+
+def _response_work_id(response: pb.SessionResponse) -> str:
+    kind = response.WhichOneof("kind")
+    if kind == "chunk":
+        return response.chunk.envelope.work_id
+    if kind == "ack":
+        return response.ack.work_id
+    if kind == "status":
+        return response.status.work_id
+    return ""
+
+
+class NativeActivationSeam:
+    """One Route-Session-to-worker seam with bounded direct buffering.
+
+    ``direct_stub`` is the generated ``ShardRuntimeStub`` and is selected when
+    it is available.  ``relay_request`` has the exact signature of the
+    existing persistent relay client; no relay server or bridge API changes
+    are needed.  Relay calls are intentionally not retried: a failed send may
+    already have mutated downstream Hot KV state.
+    """
+
+    def __init__(
+        self,
+        context: NativeFrameContext,
+        *,
+        direct_stub=None,
+        relay_request: RelayRequest | None = None,
+        max_buffered_frames: int = 8,
+        telemetry: TelemetrySink | None = None,
+    ) -> None:
+        if (direct_stub is None) == (relay_request is None):
+            raise ValueError("provide exactly one of direct_stub or relay_request")
+        if max_buffered_frames < 1:
+            raise ValueError("max_buffered_frames must be positive")
+        self.context = context
+        self._direct_stub = direct_stub
+        self._relay_request = relay_request
+        self._telemetry = telemetry
+        self._closed = False
+        self._failure: BaseException | None = None
+        self._responses: Queue[pb.SessionResponse | BaseException] = Queue(maxsize=max_buffered_frames)
+        self._requests: Queue[pb.SessionRequest | object] | None = None
+        self._thread: threading.Thread | None = None
+        self._stop = object()
+        if direct_stub is not None:
+            self._requests = Queue(maxsize=max_buffered_frames)
+            self._thread = threading.Thread(target=self._run_direct, daemon=True, name="native-activation-grpc")
+            self._thread.start()
+
+    @property
+    def transport(self) -> str:
+        return "direct-grpc" if self._direct_stub is not None else "relay"
+
+    def _direct_requests(self) -> Iterator[pb.SessionRequest]:
+        assert self._requests is not None
+        while True:
+            item = self._requests.get()
+            if item is self._stop:
+                return
+            assert isinstance(item, pb.SessionRequest)
+            yield item
+
+    def _run_direct(self) -> None:
+        try:
+            assert self._direct_stub is not None
+            for response in self._direct_stub.Session(self._direct_requests()):
+                self._put_response(response)
+        except BaseException as exc:
+            self._failure = exc
+            self._put_response(exc)
+
+    def _put_response(self, value: pb.SessionResponse | BaseException) -> None:
+        # A worker may finish while a caller is abandoning the session.  Do not
+        # let an unconsumed response turn into an unbounded producer queue.
+        try:
+            self._responses.put(value, timeout=0.1)
+        except Full:
+            self._failure = NativeActivationBufferFull("native response buffer is full")
+
+    def send(self, request: pb.SessionRequest) -> pb.SessionResponse | None:
+        """Send one already-versioned protobuf frame without rewriting it."""
+        if self._closed:
+            raise NativeActivationDisconnected("native activation seam is closed")
+        if self._failure is not None:
+            raise NativeActivationDisconnected("native activation stream failed") from self._failure
+        _validate_request(request, self.context)
+        frame = request.SerializeToString()
+        if self._direct_stub is not None:
+            assert self._requests is not None
+            try:
+                self._requests.put_nowait(request)
+            except Full as exc:
+                raise NativeActivationBufferFull("native direct request buffer is full") from exc
+            return None
+
+        assert self._relay_request is not None
+        started = time.monotonic()
+        try:
+            status, _, response_frame = self._relay_request(NATIVE_RELAY_PATH, frame, self.context.headers())
+        except Exception as exc:
+            self._closed = True
+            raise NativeActivationDisconnected("relay outcome is uncertain; refusing replay") from exc
+        if status != 200:
+            self._closed = True
+            raise NativeActivationDisconnected(f"relay native frame returned HTTP {status}")
+        response = pb.SessionResponse()
+        try:
+            response.ParseFromString(response_frame)
+        except Exception as exc:
+            self._closed = True
+            raise NativeActivationSeamError("relay returned a malformed native response frame") from exc
+        self._validate_response(response)
+        self._record(len(frame), len(response_frame), started)
+        return response
+
+    def receive(self, timeout: float | None = None) -> pb.SessionResponse:
+        """Receive the next response from the one long-lived direct stream."""
+        if self._direct_stub is None:
+            raise NativeActivationSeamError("relay sends return their response synchronously")
+        try:
+            value = self._responses.get(timeout=timeout)
+        except Empty as exc:
+            raise TimeoutError("timed out waiting for native direct response") from exc
+        if isinstance(value, BaseException):
+            raise NativeActivationDisconnected("native direct stream disconnected") from value
+        self._validate_response(value)
+        # gRPC owns its framing, but this records the actual protobuf payload
+        # size at the seam for the same telemetry shape as relay.
+        self._record(0, len(value.SerializeToString()), time.monotonic())
+        return value
+
+    def cancel(self, reason: str = "cancelled") -> pb.SessionResponse | None:
+        """Propagate cancellation through the same path and correlation fields."""
+        return self.send(pb.SessionRequest(cancel=pb.CancelSignal(
+            route_session_id=self.context.route_session_id,
+            route_epoch=self.context.route_epoch,
+            work_id=self.context.work_id,
+            reason=reason,
+        )))
+
+    def _validate_response(self, response: pb.SessionResponse) -> None:
+        work_id = _response_work_id(response)
+        if self.context.work_id and work_id and work_id != self.context.work_id:
+            raise NativeActivationSeamError("native response work identity differs from seam context")
+
+    def _record(self, request_bytes: int, response_bytes: int, started: float) -> None:
+        if self._telemetry is not None:
+            self._telemetry(NativeSeamTelemetry(
+                transport=self.transport, request_id=self.context.request_id,
+                node_id=self.context.node_id, work_id=self.context.work_id,
+                request_bytes=request_bytes, response_bytes=response_bytes,
+                elapsed_seconds=max(0.0, time.monotonic() - started),
+            ))
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._requests is not None:
+            try:
+                self._requests.put_nowait(self._stop)
+            except Full:
+                # The bounded queue is intentionally never expanded during
+                # shutdown; the worker will observe process/session teardown.
+                pass
+        if self._thread is not None:
+            self._thread.join(timeout=1.0)

packages/node/meshnet_node/native_registration.py

@@ -0,0 +1,171 @@
+"""Register a verified native Shard through the ordinary capability contract.
+
+This is intentionally an adapter, not a second tracker protocol.  It converts
+the native worker's immutable identity and enforced resource limits into the
+same capability report every backend may submit.  The tracker remains the sole
+owner of certification and decides whether the visible registration is dark.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .capability import ExecutionCapacity, RoutingMeasurements, build_capability_report
+from .native_worker_supervisor import NativeWorkerProbe, NativeWorkerSpec, NativeWorkerSupervisor
+from .runtime_recipe import ShardIdentity
+
+
+class NativeRegistrationError(ValueError):
+    """Native facts do not describe one coherent, registerable Shard."""
+
+
+@dataclass(frozen=True)
+class NativeShardRegistration:
+    """One backend-neutral registration payload for a verified native Shard."""
+
+    endpoint: str
+    model_id: str
+    identity: ShardIdentity
+    worker: NativeWorkerSpec
+    probe: NativeWorkerProbe
+    device: str
+    capacity: ExecutionCapacity
+    duration_ms: int = 0
+    routing: RoutingMeasurements | None = None
+
+    def __post_init__(self) -> None:
+        if not self.endpoint:
+            raise NativeRegistrationError("native registration requires an endpoint")
+        if not self.model_id:
+            raise NativeRegistrationError("native registration requires a model id")
+        if not self.device:
+            raise NativeRegistrationError("native registration requires a device label")
+        if self.identity.artifact.artifact_id != self.model_id:
+            raise NativeRegistrationError("native registration model does not match its identity")
+        if self.identity.fingerprint.model_artifact_digest != self.worker.artifact_digest:
+            raise NativeRegistrationError("native worker artifact digest does not match its identity")
+        if self.identity.fingerprint.runtime_recipe_digest != self.worker.recipe_digest:
+            raise NativeRegistrationError("native worker recipe digest does not match its identity")
+        expected = (
+            self.worker.artifact_digest,
+            self.worker.recipe_digest,
+            self.worker.recipe_id,
+            self.worker.recipe_version,
+            self.worker.catalogue_version,
+            self.worker.shard_start,
+            self.worker.shard_end,
+        )
+        actual = (
+            self.probe.artifact_digest,
+            self.probe.recipe_digest,
+            self.probe.recipe_id,
+            self.probe.recipe_version,
+            self.probe.catalogue_version,
+            self.probe.shard_start,
+            self.probe.shard_end,
+        )
+        if actual != expected:
+            raise NativeRegistrationError("native worker probe differs from its startup identity/range")
+        if not self.probe.serving:
+            raise NativeRegistrationError("native worker is not serving; it cannot register a capability")
+        if (
+            self.identity.shard_start,
+            self.identity.shard_end,
+            self.identity.recipe.recipe_id,
+            self.identity.recipe.recipe_version,
+            self.identity.recipe.catalogue_version,
+        ) != (
+            self.worker.shard_start,
+            self.worker.shard_end,
+            self.worker.recipe_id,
+            self.worker.recipe_version,
+            self.worker.catalogue_version,
+        ):
+            raise NativeRegistrationError("native identity differs from worker range or recipe labels")
+        if self.identity.recipe.axes["backend_id"] == "":
+            raise NativeRegistrationError("native identity must name its backend")
+
+    def payload(self) -> dict[str, Any]:
+        """Return the existing tracker registration shape with no native branch."""
+        report = build_capability_report(
+            model_id=self.model_id,
+            shard_start=self.identity.shard_start,
+            shard_end=self.identity.shard_end - 1,
+            recipe_id=self.identity.recipe.recipe_id,
+            recipe_version=self.identity.recipe.recipe_version,
+            catalogue_version=self.identity.recipe.catalogue_version,
+            backend_id=self.identity.recipe.axes["backend_id"],
+            device=self.device,
+            quantization=self.identity.recipe.axes["weight_quantization"],
+            model_config="sha256:" + self.identity.artifact.architecture_digest,
+            revision=self.identity.artifact.revision,
+            status="passed",
+            duration_ms=self.duration_ms,
+            identity=self.identity,
+            capacity=self.capacity,
+            routing=self.routing,
+        )
+        payload = {
+            "endpoint": self.endpoint,
+            "model": self.model_id.rsplit("/", 1)[-1],
+            "hf_repo": self.model_id,
+            "shard_start": self.identity.shard_start,
+            "shard_end": self.identity.shard_end - 1,
+            "recipe_id": self.identity.recipe.recipe_id,
+            "recipe_version": self.identity.recipe.recipe_version,
+            "capability_report": report.to_dict(),
+            # Existing tracker capacity fields are retained for placement views.
+            "ram_bytes": self.capacity.memory_capacity_bytes or 0,
+            "max_loaded_shards": 1,
+        }
+        # These are the tracker’s established dynamic scoring inputs.  The
+        # exact same optional report can be sent by any backend; no native
+        # route or balancing branch is introduced here.
+        if self.routing is not None:
+            if self.routing.tokens_per_second is not None:
+                payload["benchmark_tokens_per_sec"] = self.routing.tokens_per_second
+            if self.routing.queue_depth is not None:
+                payload["queue_depth"] = self.routing.queue_depth
+        return payload
+
+
+RegistrationSender = Callable[[dict[str, Any]], None]
+WithdrawalSender = Callable[[str], None]
+
+
+class NativeCapabilityRegistrar:
+    """Publish/withdraw a native capability through caller-owned transport.
+
+    The callbacks keep tracker HTTP, relay, billing, and provider mechanics out
+    of the native worker.  A process supervisor calls ``withdraw`` on health
+    loss; the caller supplies the existing tracker registration/withdrawal
+    transport appropriate to its deployment.
+    """
+
+    def __init__(
+        self,
+        registration: NativeShardRegistration,
+        *,
+        register: RegistrationSender,
+        withdraw: WithdrawalSender,
+    ) -> None:
+        self.registration = registration
+        self._register = register
+        self._withdraw = withdraw
+
+    def publish(self) -> None:
+        self._register(self.registration.payload())
+
+    def unavailable(self, reason: str) -> None:
+        self._withdraw(reason)
+
+    def bind(self, supervisor: NativeWorkerSupervisor) -> None:
+        """Publish only after DGR-040 verification; withdraw on health loss."""
+        if supervisor.spec != self.registration.worker:
+            raise NativeRegistrationError("registrar and supervisor must own the same native worker")
+        supervisor.add_availability_callbacks(
+            on_available=lambda _reason: self.publish(),
+            on_unavailable=self.unavailable,
+        )

packages/node/meshnet_node/native_worker_supervisor.py

@@ -0,0 +1,416 @@
+"""Lifecycle supervision for the standalone native Shard worker (DGR-040).
+
+This module deliberately has no dependency on ``TorchNodeServer``.  A native
+worker is an optional backend process; a failed worker must withdraw only its
+own capability, never mutate or stop the existing Transformers backend.  DGR-041
+will connect the availability callbacks to backend-agnostic registration.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import signal
+import subprocess
+import threading
+from collections import deque
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .native_protocol import SCHEMA_VERSION, pb
+
+
+class NativeWorkerError(RuntimeError):
+    """The configured worker cannot safely be started or trusted."""
+
+
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+
+
+@dataclass(frozen=True)
+class NativeWorkerSpec:
+    """The immutable identity and launch command for one native worker."""
+
+    binary: Path
+    binary_digest: str
+    listen_address: str
+    artifact_path: Path
+    artifact_digest: str
+    recipe_digest: str
+    recipe_id: str
+    recipe_version: str
+    catalogue_version: str
+    shard_start: int
+    shard_end: int
+    args: tuple[str, ...] = ()
+    extra_environment: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.listen_address:
+            raise ValueError("native worker requires a listen address")
+        if self.shard_start < 0 or self.shard_end <= self.shard_start:
+            raise ValueError("native worker range must be a non-empty half-open range")
+        for name in ("binary_digest", "artifact_digest", "recipe_digest"):
+            if not _SHA256.fullmatch(getattr(self, name)):
+                raise ValueError(f"native worker requires a lowercase SHA-256 {name}")
+        for name in ("recipe_id", "recipe_version", "catalogue_version"):
+            if not getattr(self, name):
+                raise ValueError(f"native worker requires {name}")
+
+    def environment(self) -> dict[str, str]:
+        """Return the one startup identity the C++ worker must receive."""
+        result = dict(os.environ)
+        result.update({str(key): str(value) for key, value in self.extra_environment.items()})
+        result.update(
+            {
+                "MESHNET_SHARD_LISTEN_ADDR": self.listen_address,
+                "MESHNET_MODEL_ARTIFACT": str(self.artifact_path),
+                "MESHNET_MODEL_ARTIFACT_DIGEST": self.artifact_digest,
+                "MESHNET_RUNTIME_RECIPE_DIGEST": self.recipe_digest,
+                "MESHNET_RECIPE_ID": self.recipe_id,
+                "MESHNET_RECIPE_VERSION": self.recipe_version,
+                "MESHNET_CATALOGUE_VERSION": self.catalogue_version,
+                "MESHNET_SHARD_START_LAYER": str(self.shard_start),
+                "MESHNET_SHARD_END_LAYER": str(self.shard_end),
+            }
+        )
+        return result
+
+
+@dataclass(frozen=True)
+class NativeWorkerProbe:
+    """The capability/health facts accepted by supervision after process launch."""
+
+    artifact_digest: str
+    recipe_digest: str
+    recipe_id: str
+    recipe_version: str
+    catalogue_version: str
+    shard_start: int
+    shard_end: int
+    serving: bool
+    detail: str = ""
+
+
+WorkerProbe = Callable[[NativeWorkerSpec, float], NativeWorkerProbe]
+AvailabilityCallback = Callable[[str], None]
+
+
+class NativeWorkerSupervisor:
+    """Own one worker process, its bounded logs, readiness and availability.
+
+    ``start`` does not make a capability available merely because a child was
+    spawned: it verifies the executable and artifact bytes, waits for the
+    worker's readiness line, then proves the worker's reported identity and
+    serving health.  A caller may inject ``probe`` for model-free tests; the
+    default performs the real gRPC capability and health calls.
+    """
+
+    def __init__(
+        self,
+        spec: NativeWorkerSpec,
+        *,
+        probe: WorkerProbe | None = None,
+        readiness_timeout: float = 15.0,
+        health_timeout: float = 3.0,
+        health_interval: float = 5.0,
+        shutdown_timeout: float = 10.0,
+        kill_timeout: float = 3.0,
+        log_lines: int = 200,
+        on_available: AvailabilityCallback | None = None,
+        on_unavailable: AvailabilityCallback | None = None,
+    ) -> None:
+        if min(readiness_timeout, health_timeout, health_interval, shutdown_timeout, kill_timeout) <= 0:
+            raise ValueError("native worker timeouts must be positive")
+        self.spec = spec
+        self._probe = probe or _grpc_probe
+        self._readiness_timeout = readiness_timeout
+        self._health_timeout = health_timeout
+        self._health_interval = health_interval
+        self._shutdown_timeout = shutdown_timeout
+        self._kill_timeout = kill_timeout
+        self._logs: deque[str] = deque(maxlen=log_lines)
+        self._on_available = on_available
+        self._on_unavailable = on_unavailable
+        self._process: subprocess.Popen[str] | None = None
+        self._ready = threading.Event()
+        self._stop_monitor = threading.Event()
+        self._lock = threading.RLock()
+        self._monitor: threading.Thread | None = None
+        self._available = False
+        self._unavailable_reason = "not started"
+        self._generation = 0
+
+    @property
+    def available(self) -> bool:
+        with self._lock:
+            return self._available
+
+    @property
+    def unavailable_reason(self) -> str:
+        with self._lock:
+            return self._unavailable_reason
+
+    @property
+    def logs(self) -> tuple[str, ...]:
+        with self._lock:
+            return tuple(self._logs)
+
+    @property
+    def pid(self) -> int | None:
+        with self._lock:
+            return None if self._process is None else self._process.pid
+
+    def start(self) -> NativeWorkerProbe:
+        """Start and verify a previously stopped worker before publishing it."""
+        with self._lock:
+            if self._process is not None and self._process.poll() is None:
+                raise NativeWorkerError("native worker is already running; use restart()")
+            self._verify_startup_inputs()
+            self._ready.clear()
+            self._stop_monitor.clear()
+            command = [str(self.spec.binary), *self.spec.args]
+            try:
+                self._process = subprocess.Popen(
+                    command,
+                    stdin=subprocess.DEVNULL,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    text=True,
+                    bufsize=1,
+                    env=self.spec.environment(),
+                    start_new_session=True,
+                )
+            except OSError as exc:
+                self._process = None
+                raise NativeWorkerError(f"could not start native worker: {exc}") from exc
+            self._generation += 1
+            generation = self._generation
+            process = self._process
+            for stream_name, stream in (("stdout", process.stdout), ("stderr", process.stderr)):
+                assert stream is not None
+                threading.Thread(
+                    target=self._capture_stream,
+                    args=(stream_name, stream),
+                    daemon=True,
+                ).start()
+
+        if not self._ready.wait(self._readiness_timeout):
+            self._fail_start("worker did not report readiness before timeout")
+        if process.poll() is not None:
+            self._fail_start(f"worker exited during startup with code {process.returncode}")
+        try:
+            result = self._probe(self.spec, self._health_timeout)
+            self._verify_probe(result)
+        except Exception as exc:
+            self._fail_start(f"worker failed capability/health probe: {exc}")
+
+        with self._lock:
+            if self._process is not process or process.poll() is not None:
+                self._fail_start("worker exited while capability was being verified")
+            self._available = True
+            self._unavailable_reason = ""
+            self._monitor = threading.Thread(
+                target=self._monitor_loop, args=(generation, process), daemon=True
+            )
+            self._monitor.start()
+        if self._on_available is not None:
+            self._on_available("worker ready and identity verified")
+        return result
+
+    def add_availability_callbacks(
+        self,
+        *,
+        on_available: AvailabilityCallback | None = None,
+        on_unavailable: AvailabilityCallback | None = None,
+    ) -> None:
+        """Attach an integration callback before the worker is started.
+
+        Registration is deliberately supplied by the caller so this supervisor
+        stays independent of Tracker HTTP and of every other backend.
+        """
+        with self._lock:
+            if self._process is not None:
+                raise NativeWorkerError("availability callbacks must be attached before start")
+            self._on_available = _combine_callbacks(self._on_available, on_available)
+            self._on_unavailable = _combine_callbacks(self._on_unavailable, on_unavailable)
+
+    def restart(self) -> NativeWorkerProbe:
+        """Withdraw the old capability, stop its process, then prove a fresh one."""
+        self.stop(reason="worker restart requested")
+        return self.start()
+
+    def stop(self, *, reason: str = "worker stopped") -> None:
+        """Gracefully terminate the owned process, escalating only after a bound."""
+        with self._lock:
+            process = self._process
+            self._stop_monitor.set()
+            self._process = None
+        self._mark_unavailable(reason)
+        if process is None or process.poll() is not None:
+            return
+        _terminate_process_group(process, self._shutdown_timeout, self._kill_timeout)
+
+    def check_health(self) -> bool:
+        """Run one bounded health check and withdraw availability on failure."""
+        with self._lock:
+            process = self._process
+        if process is None or process.poll() is not None:
+            self._mark_unavailable("worker process exited")
+            return False
+        try:
+            result = self._probe(self.spec, self._health_timeout)
+            self._verify_probe(result)
+        except Exception as exc:
+            self._mark_unavailable(f"worker health lost: {exc}")
+            return False
+        return True
+
+    def _verify_startup_inputs(self) -> None:
+        if not self.spec.binary.is_file() or not os.access(self.spec.binary, os.X_OK):
+            raise NativeWorkerError(f"native worker binary is not executable: {self.spec.binary}")
+        if _sha256_file(self.spec.binary) != self.spec.binary_digest:
+            raise NativeWorkerError("native worker binary digest does not match its immutable pin")
+        if not self.spec.artifact_path.is_file():
+            raise NativeWorkerError(f"native worker artifact is missing: {self.spec.artifact_path}")
+        digest = _sha256_file(self.spec.artifact_path)
+        if digest != self.spec.artifact_digest:
+            raise NativeWorkerError("native worker artifact digest does not match its immutable pin")
+
+    def _verify_probe(self, probe: NativeWorkerProbe) -> None:
+        expected = self.spec
+        actual = (
+            probe.artifact_digest,
+            probe.recipe_digest,
+            probe.recipe_id,
+            probe.recipe_version,
+            probe.catalogue_version,
+            probe.shard_start,
+            probe.shard_end,
+        )
+        wanted = (
+            expected.artifact_digest,
+            expected.recipe_digest,
+            expected.recipe_id,
+            expected.recipe_version,
+            expected.catalogue_version,
+            expected.shard_start,
+            expected.shard_end,
+        )
+        if actual != wanted:
+            raise NativeWorkerError("worker probe identity/range differs from configured startup identity")
+        if not probe.serving:
+            raise NativeWorkerError(f"worker is not serving: {probe.detail or 'no detail'}")
+
+    def _capture_stream(self, stream_name: str, stream) -> None:
+        for raw_line in stream:
+            line = f"{stream_name}: {raw_line.rstrip()}"
+            with self._lock:
+                self._logs.append(line)
+            if raw_line.startswith("ShardRuntime worker listening on "):
+                self._ready.set()
+
+    def _monitor_loop(self, generation: int, process: subprocess.Popen[str]) -> None:
+        while not self._stop_monitor.wait(self._health_interval):
+            with self._lock:
+                if generation != self._generation or self._process is not process:
+                    return
+            if process.poll() is not None:
+                self._mark_unavailable(f"worker process exited with code {process.returncode}")
+                return
+            if not self.check_health():
+                return
+
+    def _fail_start(self, reason: str) -> None:
+        self.stop(reason=reason)
+        raise NativeWorkerError(reason)
+
+    def _mark_unavailable(self, reason: str) -> None:
+        callback = None
+        with self._lock:
+            was_available = self._available
+            self._available = False
+            self._unavailable_reason = reason
+            if was_available:
+                callback = self._on_unavailable
+        if callback is not None:
+            callback(reason)
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as file:
+        for chunk in iter(lambda: file.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _combine_callbacks(
+    first: AvailabilityCallback | None, second: AvailabilityCallback | None
+) -> AvailabilityCallback | None:
+    if first is None:
+        return second
+    if second is None:
+        return first
+
+    def combined(reason: str) -> None:
+        first(reason)
+        second(reason)
+
+    return combined
+
+
+def _terminate_process_group(
+    process: subprocess.Popen[str], shutdown_timeout: float, kill_timeout: float
+) -> None:
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    try:
+        process.wait(timeout=shutdown_timeout)
+        return
+    except subprocess.TimeoutExpired:
+        pass
+    try:
+        os.killpg(process.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        return
+    try:
+        process.wait(timeout=kill_timeout)
+    except subprocess.TimeoutExpired as exc:
+        raise NativeWorkerError("native worker did not terminate after SIGKILL") from exc
+
+
+def _grpc_probe(spec: NativeWorkerSpec, timeout: float) -> NativeWorkerProbe:
+    """Default real wire probe; importing grpc lazily preserves CLI startup."""
+    import grpc
+
+    from .native_protocol.generated import shard_runtime_pb2_grpc as pb_grpc
+
+    channel = grpc.insecure_channel(spec.listen_address)
+    try:
+        grpc.channel_ready_future(channel).result(timeout=timeout)
+        stub = pb_grpc.ShardRuntimeStub(channel)
+        capability = stub.GetCapability(pb.CapabilityRequest(schema_version=SCHEMA_VERSION), timeout=timeout)
+        health = stub.Health(pb.HealthRequest(schema_version=SCHEMA_VERSION), timeout=timeout)
+    finally:
+        channel.close()
+    fingerprint = capability.fingerprint
+    shard_range = capability.shard_range
+    return NativeWorkerProbe(
+        artifact_digest=fingerprint.model_artifact_digest,
+        recipe_digest=fingerprint.runtime_recipe_digest,
+        recipe_id=fingerprint.recipe_id,
+        recipe_version=fingerprint.recipe_version,
+        catalogue_version=fingerprint.catalogue_version,
+        shard_start=shard_range.start_layer,
+        shard_end=shard_range.end_layer,
+        serving=(
+            capability.validated
+            and health.state == pb.SERVING_STATE_SERVING
+        ),
+        detail=health.detail or capability.detail,
+    )

packages/node/native/worker/llama_shard_engine.cpp

@@ -1,7 +1,9 @@
 #include "llama_shard_engine.h"
 
 #include <algorithm>
+#include <chrono>
 #include <cstdlib>
+#include <map>
 #include <mutex>
 #include <utility>
 #include <vector>
@@ -59,6 +61,24 @@ class LlamaShardEngine final : public ShardEngine {
       return false;
     }
     resident_bytes_ = report.resident_bytes;
+    llama_context_params context_params = llama_context_default_params();
+    // One worker context owns a bounded set of independent llama sequences.
+    // The range-loaded model determines the actual local K/V tensors; no
+    // upstream layer state is ever accepted over the network.
+    context_params.n_ctx = identity_.hot_kv_budget_tokens;
+    context_params.n_batch = identity_.hot_kv_context_tokens;
+    context_params.n_ubatch = identity_.hot_kv_context_tokens;
+    context_params.n_seq_max = identity_.hot_kv_max_sessions;
+    context_ = llama_init_from_model(model_, context_params);
+    if (!context_) {
+      ShutdownLocked();
+      *error = "llama.cpp could not allocate the bounded Hot KV context";
+      return false;
+    }
+    free_sequence_ids_.reserve(identity_.hot_kv_max_sessions);
+    for (uint32_t sequence_id = 0; sequence_id < identity_.hot_kv_max_sessions; ++sequence_id) {
+      free_sequence_ids_.push_back(static_cast<llama_seq_id>(sequence_id));
+    }
     loaded_ = true;
     return true;
   }
@@ -106,11 +126,63 @@ class LlamaShardEngine final : public ShardEngine {
     return result;
   }
 
-  bool Execute(const sp::TensorBundle&, std::string* error) override {
+  HotKvResult OpenSession(const std::string& route_session_id, uint64_t route_epoch) override {
+    std::lock_guard<std::mutex> lock(mu_);
+    if (!loaded_ || !context_) return {HotKvStatus::kCacheMiss, 0, "llama.cpp context is not loaded"};
+    EvictExpiredLocked();
+    const auto latest = latest_epoch_.find(route_session_id);
+    if (latest != latest_epoch_.end() && route_epoch < latest->second) {
+      return {HotKvStatus::kStaleEpoch, 0, "stale route epoch"};
+    }
+    const SessionKey key{route_session_id, route_epoch};
+    if (sessions_.count(key)) return {HotKvStatus::kOk, sessions_[key].past_len, "session already open"};
+    if (latest != latest_epoch_.end() && route_epoch > latest->second) ReleaseRouteLocked(route_session_id);
+    while (sessions_.size() >= identity_.hot_kv_max_sessions) EvictLruLocked();
+    if (free_sequence_ids_.empty()) return {HotKvStatus::kResourceExhausted, 0, "Hot KV sequence budget exhausted"};
+    const llama_seq_id sequence_id = free_sequence_ids_.back();
+    free_sequence_ids_.pop_back();
+    sessions_.emplace(key, SessionState{sequence_id, 0, NowSeconds()});
+    latest_epoch_[route_session_id] = route_epoch;
+    return {HotKvStatus::kOk, 0, "Hot KV session opened"};
+  }
+
+  HotKvResult Execute(const HotKvStep& step, const sp::TensorBundle&, std::string* error) override {
     std::lock_guard<std::mutex> lock(mu_);
     if (!loaded_ || !model_) {
       *error = "llama.cpp model is not loaded";
-      return false;
+      return {HotKvStatus::kCacheMiss, 0, *error};
+    }
+    EvictExpiredLocked();
+    const auto latest = latest_epoch_.find(step.route_session_id);
+    if (latest != latest_epoch_.end() && step.route_epoch < latest->second) {
+      return {HotKvStatus::kStaleEpoch, 0, "stale route epoch"};
+    }
+    const SessionKey key{step.route_session_id, step.route_epoch};
+    auto it = sessions_.find(key);
+    if (it == sessions_.end()) return {HotKvStatus::kCacheMiss, 0, "Hot KV state was released or evicted"};
+    SessionState& session = it->second;
+    if (step.phase == HotKvStep::Phase::kDecode && step.expected_past_len != session.past_len) {
+      return {HotKvStatus::kCacheMiss, session.past_len, "expected past length does not match local Hot KV"};
+    }
+    if (step.first_position < session.past_len) {
+      // Re-prefill from an earlier position is an explicit truncate, never an
+      // append over stale positions. This removes only this llama sequence.
+      llama_memory_seq_rm(llama_get_memory(context_), session.sequence_id,
+                          static_cast<llama_pos>(step.first_position), -1);
+      total_reserved_tokens_ -= session.past_len - step.first_position;
+      session.past_len = step.first_position;
+    }
+    if (step.first_position != session.past_len || step.token_count == 0) {
+      return {HotKvStatus::kCacheMiss, session.past_len, "non-contiguous Hot KV append"};
+    }
+    if (session.past_len + step.token_count > identity_.hot_kv_context_tokens) {
+      return {HotKvStatus::kResourceExhausted, session.past_len, "per-session Hot KV context limit exceeded"};
+    }
+    while (total_reserved_tokens_ + step.token_count > identity_.hot_kv_budget_tokens && sessions_.size() > 1) {
+      EvictLruLocked(&key);
+    }
+    if (total_reserved_tokens_ + step.token_count > identity_.hot_kv_budget_tokens) {
+      return {HotKvStatus::kResourceExhausted, session.past_len, "Hot KV token budget exhausted"};
     }
     if (identity_.injected_death_after_executions != 0 &&
         ++executions_ >= identity_.injected_death_after_executions) {
@@ -121,7 +193,10 @@ class LlamaShardEngine final : public ShardEngine {
     // DGR-038 installs per-session context/KV and DGR-039 proves graph parity.
     // Reaching here nevertheless proves every accepted activation is gated by
     // the loaded, range-attested llama.cpp engine rather than a fixture.
-    return true;
+    session.past_len += step.token_count;
+    total_reserved_tokens_ += step.token_count;
+    session.last_used = NowSeconds();
+    return {HotKvStatus::kOk, session.past_len, "Hot KV append accepted"};
   }
 
   const WorkerIdentity& identity() const override { return identity_; }
@@ -129,11 +204,20 @@ class LlamaShardEngine final : public ShardEngine {
     std::lock_guard<std::mutex> lock(mu_);
     return {loaded_, resident_bytes_, loaded_ ? "llama.cpp model loaded" : "llama.cpp model unavailable"};
   }
-  void ReleaseSession(const std::string&) override {}
+  void ReleaseSession(const std::string& route_session_id, uint64_t route_epoch) override {
+    std::lock_guard<std::mutex> lock(mu_);
+    ReleaseLocked(SessionKey{route_session_id, route_epoch});
+  }
   void Shutdown() override { std::lock_guard<std::mutex> lock(mu_); ShutdownLocked(); }
 
  private:
   void ShutdownLocked() {
+    sessions_.clear();
+    free_sequence_ids_.clear();
+    latest_epoch_.clear();
+    total_reserved_tokens_ = 0;
+    if (context_) llama_free(context_);
+    context_ = nullptr;
     if (model_) llama_model_free(model_);
     model_ = nullptr;
     loaded_ = false;
@@ -141,13 +225,63 @@ class LlamaShardEngine final : public ShardEngine {
     if (backend_initialized_) llama_backend_free();
     backend_initialized_ = false;
   }
+  struct SessionKey {
+    std::string route_session_id;
+    uint64_t route_epoch;
+    bool operator<(const SessionKey& other) const {
+      return route_session_id != other.route_session_id ? route_session_id < other.route_session_id
+                                                          : route_epoch < other.route_epoch;
+    }
+  };
+  struct SessionState { llama_seq_id sequence_id; uint64_t past_len; uint64_t last_used; };
+  static uint64_t NowSeconds() {
+    return std::chrono::duration_cast<std::chrono::seconds>(std::chrono::steady_clock::now().time_since_epoch()).count();
+  }
+  void ReleaseLocked(const SessionKey& key) {
+    auto it = sessions_.find(key);
+    if (it == sessions_.end()) return;
+    llama_memory_seq_rm(llama_get_memory(context_), it->second.sequence_id, -1, -1);
+    total_reserved_tokens_ -= it->second.past_len;
+    free_sequence_ids_.push_back(it->second.sequence_id);
+    sessions_.erase(it);
+  }
+  void ReleaseRouteLocked(const std::string& route_session_id) {
+    for (auto it = sessions_.begin(); it != sessions_.end();) {
+      if (it->first.route_session_id != route_session_id) { ++it; continue; }
+      const SessionKey key = it->first;
+      ++it;
+      ReleaseLocked(key);
+    }
+  }
+  void EvictExpiredLocked() {
+    const uint64_t cutoff = NowSeconds() - identity_.hot_kv_ttl_seconds;
+    for (auto it = sessions_.begin(); it != sessions_.end();) {
+      if (it->second.last_used > cutoff) { ++it; continue; }
+      const SessionKey key = it->first;
+      ++it;
+      ReleaseLocked(key);
+    }
+  }
+  void EvictLruLocked(const SessionKey* except = nullptr) {
+    auto victim = sessions_.end();
+    for (auto it = sessions_.begin(); it != sessions_.end(); ++it) {
+      if (except && it->first.route_session_id == except->route_session_id && it->first.route_epoch == except->route_epoch) continue;
+      if (victim == sessions_.end() || it->second.last_used < victim->second.last_used) victim = it;
+    }
+    if (victim != sessions_.end()) ReleaseLocked(victim->first);
+  }
   WorkerIdentity identity_;
   mutable std::mutex mu_;
   llama_model* model_ = nullptr;
+  llama_context* context_ = nullptr;
   bool backend_initialized_ = false;
   bool loaded_ = false;
   uint64_t resident_bytes_ = 0;
   uint32_t executions_ = 0;
+  std::map<SessionKey, SessionState> sessions_;
+  std::map<std::string, uint64_t> latest_epoch_;
+  std::vector<llama_seq_id> free_sequence_ids_;
+  uint64_t total_reserved_tokens_ = 0;
 };
 }  // namespace
 

packages/node/native/worker/llama_shard_engine.h

@@ -25,6 +25,10 @@ struct WorkerIdentity {
   uint32_t start_layer = 0;
   uint32_t end_layer = 0;  // half-open, as on the wire
   uint32_t injected_death_after_executions = 0;  // opt-in test hook; zero disables
+  uint32_t hot_kv_max_sessions = 8;
+  uint32_t hot_kv_context_tokens = 4096;
+  uint32_t hot_kv_budget_tokens = 32768;
+  uint32_t hot_kv_ttl_seconds = 300;
 };
 
 struct BundleCheck {
@@ -38,15 +42,38 @@ struct EngineHealth {
   std::string detail;
 };
 
+// This is deliberately expressed in tokens, rather than guessed bytes: llama.cpp
+// owns the actual K/V layout for the loaded range and backend. The worker uses
+// the token reservation to keep its local KV arena bounded before a graph
+// adapter materializes the typed boundary (DGR-039).
+struct HotKvStep {
+  enum class Phase { kPrefill, kDecode };
+  std::string route_session_id;
+  uint64_t route_epoch = 0;
+  Phase phase = Phase::kPrefill;
+  uint64_t first_position = 0;
+  uint32_t token_count = 0;
+  uint64_t expected_past_len = 0;
+};
+
+enum class HotKvStatus { kOk, kCacheMiss, kStaleEpoch, kResourceExhausted, kCancelled };
+
+struct HotKvResult {
+  HotKvStatus status = HotKvStatus::kOk;
+  uint64_t past_len = 0;
+  std::string detail;
+};
+
 class ShardEngine {
  public:
   virtual ~ShardEngine() = default;
   virtual bool Load(std::string* error) = 0;
   virtual BundleCheck Validate(const sp::TensorBundle&, uint64_t max_chunk_bytes) const = 0;
-  virtual bool Execute(const sp::TensorBundle&, std::string* error) = 0;
+  virtual HotKvResult OpenSession(const std::string& route_session_id, uint64_t route_epoch) = 0;
+  virtual HotKvResult Execute(const HotKvStep&, const sp::TensorBundle&, std::string* error) = 0;
   virtual const WorkerIdentity& identity() const = 0;
   virtual EngineHealth health() const = 0;
-  virtual void ReleaseSession(const std::string& route_session_id) = 0;
+  virtual void ReleaseSession(const std::string& route_session_id, uint64_t route_epoch) = 0;
   virtual void Shutdown() = 0;
 };
 

packages/node/native/worker/shard_service.cpp

@@ -70,6 +70,23 @@ void FillDefaultFlow(sp::FlowControl* fc, const FlowLimits& limits) {
   fc->set_max_prefill_chunk_tokens(limits.max_prefill_chunk_tokens);
 }
 
+sp::SessionResponse HotKvFailure(const std::string& route_session_id, const std::string& work_id,
+                                 uint64_t step, const HotKvResult& result) {
+  switch (result.status) {
+    case HotKvStatus::kStaleEpoch:
+      return MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_EPOCH_STALE, result.detail, false, false);
+    case HotKvStatus::kCacheMiss:
+      return MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_CACHE_MISS, result.detail, false, true);
+    case HotKvStatus::kResourceExhausted:
+      return MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_RESOURCE_EXHAUSTED, result.detail, false, true);
+    case HotKvStatus::kCancelled:
+      return MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_CANCELLED, result.detail, false, false);
+    case HotKvStatus::kOk:
+      break;
+  }
+  return MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_INTERNAL, "unexpected Hot KV result", false, true);
+}
+
 }  // namespace
 
 grpc::Status ShardRuntimeServiceImpl::GetCapability(grpc::ServerContext*,
@@ -198,6 +215,11 @@ grpc::Status ShardRuntimeServiceImpl::Session(
             open.has_proposed_flow_control()
                 ? NegotiateFlow(open.proposed_flow_control())
                 : limits_;
+        const HotKvResult hot_kv = engine_.OpenSession(route_session_id, open.route_epoch());
+        if (hot_kv.status != HotKvStatus::kOk) {
+          stream->Write(HotKvFailure(route_session_id, "", 0, hot_kv));
+          return grpc::Status::OK;
+        }
         {
           std::lock_guard<std::mutex> lk(sessions_mu_);
           SessionState state;
@@ -282,13 +304,17 @@ grpc::Status ShardRuntimeServiceImpl::Session(
               response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_PAYLOAD_CORRUPT,
                                  *check.corrupt_detail, false, false);
             } else {
+              std::string execution_error;
+              const HotKvResult executed = engine_.Execute(
+                  HotKvStep{route_session_id, envelope.route_epoch(), HotKvStep::Phase::kPrefill,
+                            envelope.position().first_position(), envelope.position().token_count(),
+                            envelope.cache_expectation().expected_past_len()},
+                  chunk.bundle(), &execution_error);
+              if (executed.status != HotKvStatus::kOk) {
+                response = HotKvFailure(route_session_id, work_id, step, executed);
+              } else {
               state->seen_steps.insert(step);
               state->credits -= 1;
-              std::string execution_error;
-              if (!engine_.Execute(chunk.bundle(), &execution_error)) {
-                response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_INTERNAL,
-                                    execution_error, false, true);
-              } else {
               *response.mutable_chunk() = chunk;  // echo the exact bundle back
               }
             }
@@ -348,13 +374,15 @@ grpc::Status ShardRuntimeServiceImpl::Session(
               response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_PAYLOAD_CORRUPT,
                                  *check.corrupt_detail, false, false);
             } else {
+              std::string execution_error;
+              const HotKvResult executed = engine_.Execute(
+                  HotKvStep{route_session_id, state->epoch, HotKvStep::Phase::kDecode,
+                            step_msg.position(), 1, step_msg.expected_past_len()}, bundle, &execution_error);
+              if (executed.status != HotKvStatus::kOk) {
+                response = HotKvFailure(route_session_id, work_id, step, executed);
+              } else {
               state->seen_steps.insert(step);
               state->credits -= 1;
-              std::string execution_error;
-              if (!engine_.Execute(bundle, &execution_error)) {
-                response = MakeFail(route_session_id, work_id, step, sp::ERROR_CODE_INTERNAL,
-                                    execution_error, false, true);
-              } else {
               // No decode response field exists; echo the step back as a
               // chunk-bearing SessionResponse per the proto's relayed-frame design.
               sp::ActivationChunk* out = response.mutable_chunk();
@@ -412,8 +440,11 @@ grpc::Status ShardRuntimeServiceImpl::Session(
         // freed the moment the terminal status is sent.
         {
           std::lock_guard<std::mutex> lk(sessions_mu_);
-          sessions_.erase(route_session_id);
+          auto it = sessions_.find(release.route_session_id());
-          engine_.ReleaseSession(route_session_id);
+          if (it != sessions_.end() && it->second.epoch == release.route_epoch()) {
+            sessions_.erase(it);
+          }
+          engine_.ReleaseSession(release.route_session_id(), release.route_epoch());
         }
         sp::SessionResponse response;
         sp::ShardStatus* status = response.mutable_status();
@@ -454,8 +485,10 @@ grpc::Status ShardRuntimeServiceImpl::Release(grpc::ServerContext*,
   bool existed;
   {
     std::lock_guard<std::mutex> lk(sessions_mu_);
-    existed = sessions_.erase(request->route_session_id()) != 0;
+    auto it = sessions_.find(request->route_session_id());
-    engine_.ReleaseSession(request->route_session_id());
+    existed = it != sessions_.end() && it->second.epoch == request->route_epoch();
+    if (existed) sessions_.erase(it);
+    engine_.ReleaseSession(request->route_session_id(), request->route_epoch());
   }
   response->set_released(existed);
   return grpc::Status::OK;

packages/node/native/worker/shard_worker_main.cpp

@@ -64,6 +64,19 @@ meshnet::worker::FlowLimits LimitsFromEnv() {
   return limits;
 }
 
+bool PositiveEnv(const char* name, uint32_t* out, std::string* error) {
+  if (const char* value = std::getenv(name)) {
+    char* end = nullptr;
+    const unsigned long parsed = std::strtoul(value, &end, 10);
+    if (end == value || *end != '\0' || parsed == 0 || parsed > UINT32_MAX) {
+      *error = std::string("invalid ") + name;
+      return false;
+    }
+    *out = static_cast<uint32_t>(parsed);
+  }
+  return true;
+}
+
 bool IdentityFromEnv(meshnet::worker::WorkerIdentity* identity, std::string* error) {
   const auto required = [&](const char* name, std::string* out) -> bool {
     const char* value = std::getenv(name);
@@ -100,6 +113,14 @@ bool IdentityFromEnv(meshnet::worker::WorkerIdentity* identity, std::string* err
     }
     identity->injected_death_after_executions = static_cast<uint32_t>(parsed);
   }
+  if (!PositiveEnv("MESHNET_HOT_KV_MAX_SESSIONS", &identity->hot_kv_max_sessions, error) ||
+      !PositiveEnv("MESHNET_HOT_KV_CONTEXT_TOKENS", &identity->hot_kv_context_tokens, error) ||
+      !PositiveEnv("MESHNET_HOT_KV_BUDGET_TOKENS", &identity->hot_kv_budget_tokens, error) ||
+      !PositiveEnv("MESHNET_HOT_KV_TTL_SECONDS", &identity->hot_kv_ttl_seconds, error)) return false;
+  if (identity->hot_kv_budget_tokens < identity->hot_kv_context_tokens) {
+    *error = "MESHNET_HOT_KV_BUDGET_TOKENS must cover one session context";
+    return false;
+  }
   return true;
 }
 

packages/tracker/meshnet_tracker/capability.py

@@ -190,6 +190,14 @@ class CapabilityState:
     # ("dark"/"certified"), so the network map answers "why is this exact node
     # not routing" without a second query. None when no identity was presented.
     certification: str | None = None
+    memory_capacity_bytes: int | None = None
+    kv_capacity_tokens: int | None = None
+    max_concurrent_sessions: int | None = None
+    measured_tokens_per_second: float | None = None
+    reported_queue_depth: int | None = None
+    seam_latency_ms: float | None = None
+    healthy: bool | None = None
+    reliability: float | None = None
 
     @property
     def proven(self) -> bool:
@@ -233,6 +241,14 @@ class CapabilityState:
             "runtime_recipe_digest": self.runtime_recipe_digest,
             "shard_binding_digest": self.shard_binding_digest,
             "certification": self.certification,
+            "memory_capacity_bytes": self.memory_capacity_bytes,
+            "kv_capacity_tokens": self.kv_capacity_tokens,
+            "max_concurrent_sessions": self.max_concurrent_sessions,
+            "measured_tokens_per_second": self.measured_tokens_per_second,
+            "reported_queue_depth": self.reported_queue_depth,
+            "seam_latency_ms": self.seam_latency_ms,
+            "healthy": self.healthy,
+            "reliability": self.reliability,
         }
 
 
@@ -491,6 +507,13 @@ def _parse_report(doc: Mapping[str, Any]) -> dict:
     if isinstance(schema_version, bool) or not isinstance(schema_version, int):
         raise _ReportError("'schema_version' must be an integer")
 
+    capacity = doc.get("capacity")
+    if capacity is not None:
+        capacity = _object(capacity, "capacity")
+    routing = doc.get("routing")
+    if routing is not None:
+        routing = _object(routing, "routing")
+
     return {
         "model_id": _text(model.get("model_id"), "model.model_id"),
         "shard_start": _index(shard.get("start"), "shard.start"),
@@ -508,6 +531,36 @@ def _parse_report(doc: Mapping[str, Any]) -> dict:
         "validated_at": float(validated_at),
         "schema_version": schema_version,
         "diagnostics": _diagnostics(doc.get("diagnostics")),
+        "memory_capacity_bytes": _optional_positive_int(
+            None if capacity is None else capacity.get("memory_capacity_bytes"),
+            "capacity.memory_capacity_bytes",
+        ),
+        "kv_capacity_tokens": _optional_positive_int(
+            None if capacity is None else capacity.get("kv_capacity_tokens"),
+            "capacity.kv_capacity_tokens",
+        ),
+        "max_concurrent_sessions": _optional_positive_int(
+            None if capacity is None else capacity.get("max_concurrent_sessions"),
+            "capacity.max_concurrent_sessions",
+        ),
+        "measured_tokens_per_second": _optional_positive_float(
+            None if routing is None else routing.get("tokens_per_second"),
+            "routing.tokens_per_second",
+        ),
+        "reported_queue_depth": _optional_nonnegative_int(
+            None if routing is None else routing.get("queue_depth"),
+            "routing.queue_depth",
+        ),
+        "seam_latency_ms": _optional_nonnegative_float(
+            None if routing is None else routing.get("seam_latency_ms"),
+            "routing.seam_latency_ms",
+        ),
+        "healthy": _optional_bool(
+            None if routing is None else routing.get("healthy"), "routing.healthy"
+        ),
+        "reliability": _optional_unit_float(
+            None if routing is None else routing.get("reliability"), "routing.reliability"
+        ),
         "_status": _text(doc.get("status"), "status"),
     }
 
@@ -536,6 +589,53 @@ def _index(value: Any, field_name: str) -> int:
     return value
 
 
+def _optional_positive_int(value: Any, field_name: str) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise _ReportError(f"{field_name!r} must be a positive integer")
+    return value
+
+
+def _optional_nonnegative_int(value: Any, field_name: str) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise _ReportError(f"{field_name!r} must be a non-negative integer")
+    return value
+
+
+def _optional_positive_float(value: Any, field_name: str) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+        raise _ReportError(f"{field_name!r} must be a positive number")
+    return float(value)
+
+
+def _optional_nonnegative_float(value: Any, field_name: str) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
+        raise _ReportError(f"{field_name!r} must be a non-negative number")
+    return float(value)
+
+
+def _optional_bool(value: Any, field_name: str) -> bool | None:
+    if value is None:
+        return None
+    if not isinstance(value, bool):
+        raise _ReportError(f"{field_name!r} must be a boolean")
+    return value
+
+
+def _optional_unit_float(value: Any, field_name: str) -> float | None:
+    parsed = _optional_nonnegative_float(value, field_name)
+    if parsed is not None and parsed > 1:
+        raise _ReportError(f"{field_name!r} must be a number from 0 to 1")
+    return parsed
+
+
 def _maybe_int(value: Any) -> int | None:
     if isinstance(value, bool) or not isinstance(value, int):
         return None

packages/tracker/meshnet_tracker/server.py

@@ -4684,6 +4684,11 @@ class _TrackerHandler(http.server.BaseHTTPRequestHandler):
             friendly_name=friendly_name,
             capability=capability,
         )
+        # A report may seed the same load/throughput inputs that legacy nodes
+        # supply through registration and heartbeats.  The optional block is
+        # backend-neutral; routing still applies its usual queue adjustment.
+        if capability.reported_queue_depth is not None:
+            entry.queue_depth = capability.reported_queue_depth
         with server.lock:
             self._purge_expired_nodes()
             # Dedup: replace the same node id or the same endpoint+model assignment.

tests/test_llama_shard_worker_binding.py

@@ -44,3 +44,20 @@ def test_identity_is_loaded_not_stream_supplied_and_health_reports_it():
     assert "model artifact or runtime recipe digest does not match" in source
     assert "resident_bytes" in source
     assert '" range=["' in source
+
+
+def test_hot_kv_is_bounded_and_keyed_by_route_session_and_epoch():
+    engine = (WORKER / "llama_shard_engine.cpp").read_text(encoding="utf-8")
+    header = (WORKER / "llama_shard_engine.h").read_text(encoding="utf-8")
+    service = (WORKER / "shard_service.cpp").read_text(encoding="utf-8")
+    main = (WORKER / "shard_worker_main.cpp").read_text(encoding="utf-8")
+    assert "struct SessionKey" in engine
+    assert "uint64_t route_epoch" in engine
+    assert "llama_init_from_model" in engine
+    assert "llama_memory_seq_rm" in engine
+    assert "EvictExpiredLocked" in engine
+    assert "EvictLruLocked" in engine
+    assert "HotKvStatus::kCacheMiss" in service
+    assert "ERROR_CODE_CACHE_MISS" in service
+    assert "MESHNET_HOT_KV_BUDGET_TOKENS" in main
+    assert "HotKvStep" in header

tests/test_native_activation_seam.py

@@ -0,0 +1,159 @@
+"""DGR-042 seam tests with a deterministic fake generated worker."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+import threading
+
+import pytest
+
+from meshnet_node.native_activation_seam import (
+    NATIVE_RELAY_PATH,
+    NativeActivationBufferFull,
+    NativeActivationDisconnected,
+    NativeActivationSeam,
+    NativeFrameContext,
+)
+from meshnet_node.native_protocol import pb
+
+
+def _context(**changes: object) -> NativeFrameContext:
+    values: dict[str, object] = dict(
+        request_id="billing-request-7", node_id="node-tail", route_session_id="route-9",
+        route_epoch=4, work_id="work-3", deadline_unix_nanos=987654321,
+    )
+    values.update(changes)
+    return NativeFrameContext(**values)
+
+
+def _open() -> pb.SessionRequest:
+    return pb.SessionRequest(open=pb.SessionOpen(
+        schema_version=pb.SCHEMA_VERSION_1, route_session_id="route-9", route_epoch=4,
+    ))
+
+
+def _chunk() -> pb.SessionRequest:
+    return pb.SessionRequest(chunk=pb.ActivationChunk(envelope=pb.Envelope(
+        schema_version=pb.SCHEMA_VERSION_1, route_session_id="route-9", route_epoch=4,
+        work_id="work-3", deadline_unix_nanos=987654321,
+    )))
+
+
+def _ack(request: pb.SessionRequest) -> pb.SessionResponse:
+    if request.WhichOneof("kind") == "open":
+        return pb.SessionResponse(accepted=pb.SessionAccepted(
+            schema_version=pb.SCHEMA_VERSION_1, route_session_id="route-9", route_epoch=4,
+        ))
+    route, epoch, work, _ = ("route-9", 4, "work-3", 0)
+    del route, epoch
+    return pb.SessionResponse(ack=pb.Ack(work_id=work, idempotency_step=1))
+
+
+class _FakeGrpcWorker:
+    def __init__(self, *, block: bool = False) -> None:
+        self.calls = 0
+        self.received: list[pb.SessionRequest] = []
+        self.started = threading.Event()
+        self.consumed = threading.Event()
+        self.release = threading.Event()
+        self.block = block
+
+    def Session(self, requests: Iterator[pb.SessionRequest]):
+        self.calls += 1
+        self.started.set()
+        for request in requests:
+            self.received.append(request)
+            self.consumed.set()
+            if self.block:
+                self.release.wait(1)
+            yield _ack(request)
+
+
+def test_direct_uses_one_long_lived_grpc_stream_and_preserves_correlation():
+    worker = _FakeGrpcWorker()
+    telemetry = []
+    seam = NativeActivationSeam(_context(), direct_stub=worker, telemetry=telemetry.append)
+    try:
+        seam.send(_open())
+        seam.send(_chunk())
+        assert seam.receive(1).WhichOneof("kind") == "accepted"
+        assert seam.receive(1).ack.work_id == "work-3"
+        assert worker.calls == 1
+        assert [frame.SerializeToString() for frame in worker.received] == [
+            _open().SerializeToString(), _chunk().SerializeToString()
+        ]
+        assert telemetry[-1].request_id == "billing-request-7"
+        assert telemetry[-1].node_id == "node-tail"
+    finally:
+        seam.close()
+
+
+def test_relay_carries_byte_identical_protobuf_frames_and_all_correlation_headers():
+    captured: list[tuple[str, bytes, dict[str, str]]] = []
+
+    def relay(path: str, body: bytes, headers: dict[str, str]):
+        captured.append((path, body, headers))
+        request = pb.SessionRequest()
+        request.ParseFromString(body)
+        return 200, {}, _ack(request).SerializeToString()
+
+    seam = NativeActivationSeam(_context(), relay_request=relay)
+    response = seam.send(_chunk())
+    assert response is not None and response.ack.work_id == "work-3"
+    path, body, headers = captured[0]
+    assert path == NATIVE_RELAY_PATH
+    assert body == _chunk().SerializeToString()
+    assert headers == {
+        "Content-Type": "application/x-protobuf", "X-Meshnet-Native-Frame": "shard-runtime/v1",
+        "X-Meshnet-Request-Id": "billing-request-7", "X-Meshnet-Node-Id": "node-tail",
+        "X-Meshnet-Session": "route-9", "X-Meshnet-Route-Epoch": "4",
+        "X-Meshnet-Work-Id": "work-3", "X-Meshnet-Deadline-Unix-Nanos": "987654321",
+        "X-Meshnet-Activation-Id": "billing-request-7",
+    }
+
+
+def test_relay_disconnect_is_uncertain_and_is_never_replayed():
+    calls = 0
+
+    def disconnected(*_):
+        nonlocal calls
+        calls += 1
+        raise OSError("relay vanished")
+
+    seam = NativeActivationSeam(_context(), relay_request=disconnected)
+    with pytest.raises(NativeActivationDisconnected, match="uncertain"):
+        seam.send(_chunk())
+    with pytest.raises(NativeActivationDisconnected):
+        seam.send(_chunk())
+    assert calls == 1
+
+
+def test_cancellation_uses_the_same_opaque_relay_contract():
+    received = []
+
+    def relay(_path, body, _headers):
+        request = pb.SessionRequest()
+        request.ParseFromString(body)
+        received.append(request)
+        return 200, {}, pb.SessionResponse(ack=pb.Ack(work_id="work-3")).SerializeToString()
+
+    seam = NativeActivationSeam(_context(), relay_request=relay)
+    response = seam.cancel("client disconnected")
+    assert response is not None
+    assert received[0].cancel.work_id == "work-3"
+    assert received[0].cancel.reason == "client disconnected"
+
+
+def test_direct_request_buffer_is_bounded():
+    worker = _FakeGrpcWorker(block=True)
+    seam = NativeActivationSeam(_context(), direct_stub=worker, max_buffered_frames=1)
+    try:
+        assert worker.started.wait(1)
+        seam.send(_open())
+        assert worker.consumed.wait(1)
+        seam.send(_chunk())
+        with pytest.raises(NativeActivationBufferFull):
+            seam.send(_chunk())
+    finally:
+        worker.release.set()
+        seam.close()

tests/test_native_registration.py

@@ -0,0 +1,142 @@
+"""DGR-041 native capability registration remains an ordinary admission payload."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from meshnet_node.capability import ExecutionCapacity, RoutingMeasurements
+from meshnet_node.native_registration import (
+    NativeCapabilityRegistrar,
+    NativeRegistrationError,
+    NativeShardRegistration,
+)
+from meshnet_node.native_worker_supervisor import NativeWorkerProbe, NativeWorkerSpec
+from meshnet_node.runtime_recipe import ShardIdentity
+from meshnet_tracker.capability import CapabilityState, STATE_ADMITTED, STATE_UNCERTIFIED
+from meshnet_tracker.server import TrackerServer, _capability_from_registration, _select_route
+
+from test_runtime_recipe_identity import _identity
+
+
+def _worker(identity: ShardIdentity) -> tuple[NativeWorkerSpec, NativeWorkerProbe]:
+    spec = NativeWorkerSpec(
+        binary=__file__, binary_digest="d" * 64, listen_address="127.0.0.1:1",
+        artifact_path=__file__, artifact_digest=identity.fingerprint.model_artifact_digest,
+        recipe_digest=identity.fingerprint.runtime_recipe_digest, recipe_id=identity.recipe.recipe_id,
+        recipe_version=identity.recipe.recipe_version, catalogue_version=identity.recipe.catalogue_version,
+        shard_start=identity.shard_start, shard_end=identity.shard_end,
+    )
+    probe = NativeWorkerProbe(
+        artifact_digest=spec.artifact_digest, recipe_digest=spec.recipe_digest,
+        recipe_id=spec.recipe_id, recipe_version=spec.recipe_version,
+        catalogue_version=spec.catalogue_version, shard_start=spec.shard_start,
+        shard_end=spec.shard_end, serving=True,
+    )
+    return spec, probe
+
+
+def test_native_registration_carries_exact_identity_range_capacity_and_dark_status():
+    identity = _identity()
+    worker, probe = _worker(identity)
+    registration = NativeShardRegistration(
+        endpoint="http://native.example:8080", model_id=identity.artifact.artifact_id,
+        identity=identity, worker=worker, probe=probe, device="cpu:fixture",
+        capacity=ExecutionCapacity(4096, 8192, 3), duration_ms=7,
+        routing=RoutingMeasurements(
+            tokens_per_second=12.5, queue_depth=2, seam_latency_ms=3.5,
+            healthy=True, reliability=0.99,
+        ),
+    )
+
+    payload = registration.payload()
+    report = payload["capability_report"]
+    assert report["identity"]["fingerprint"]["runtime_recipe_digest"] == identity.fingerprint.runtime_recipe_digest
+    assert report["shard"] == {"start": identity.shard_start, "end": identity.shard_end - 1}
+    assert report["backend"]["backend_id"] == identity.recipe.axes["backend_id"]
+    assert report["capacity"] == {
+        "memory_capacity_bytes": 4096, "kv_capacity_tokens": 8192, "max_concurrent_sessions": 3,
+    }
+    assert report["routing"] == {
+        "tokens_per_second": 12.5, "queue_depth": 2, "seam_latency_ms": 3.5,
+        "healthy": True, "reliability": 0.99,
+    }
+    assert payload["benchmark_tokens_per_sec"] == 12.5
+    assert payload["queue_depth"] == 2
+
+    tracker = TrackerServer()
+    state = _capability_from_registration(
+        payload, model=payload["model"], hf_repo=payload["hf_repo"],
+        shard_start=payload["shard_start"], shard_end=payload["shard_end"],
+        recipe_certifications=tracker._recipe_certifications,
+    )
+    assert state.state == STATE_UNCERTIFIED
+    assert state.certification == "dark"
+    assert state.memory_capacity_bytes == 4096
+    assert state.kv_capacity_tokens == 8192
+    assert state.max_concurrent_sessions == 3
+    assert state.measured_tokens_per_second == 12.5
+    assert state.reported_queue_depth == 2
+    assert state.seam_latency_ms == 3.5
+    assert state.healthy is True
+    assert state.reliability == 0.99
+
+
+def test_native_registrar_has_no_tracker_or_backend_policy_of_its_own():
+    identity = _identity()
+    worker, probe = _worker(identity)
+    registration = NativeShardRegistration(
+        endpoint="http://native.example", model_id=identity.artifact.artifact_id, identity=identity,
+        worker=worker, probe=probe, device="cpu", capacity=ExecutionCapacity(1, 1, 1),
+    )
+    published: list[dict] = []
+    withdrawn: list[str] = []
+    registrar = NativeCapabilityRegistrar(registration, register=published.append, withdraw=withdrawn.append)
+    registrar.publish()
+    registrar.unavailable("worker exited")
+    assert published[0]["capability_report"]["backend"]["backend_id"] == identity.recipe.axes["backend_id"]
+    assert withdrawn == ["worker exited"]
+
+
+def test_native_registration_refuses_a_probe_for_a_different_range():
+    identity = _identity()
+    worker, probe = _worker(identity)
+    wrong = NativeWorkerProbe(**{**probe.__dict__, "shard_end": probe.shard_end + 1})
+    try:
+        NativeShardRegistration(
+            endpoint="http://native.example", model_id=identity.artifact.artifact_id, identity=identity,
+            worker=worker, probe=wrong, device="cpu", capacity=ExecutionCapacity(1, 1, 1),
+        )
+    except NativeRegistrationError:
+        return
+    raise AssertionError("different worker range must not register")
+
+
+def _candidate(
+    node_id: str, start: int, end: int, fingerprint: tuple[str, str], *, state: str = STATE_ADMITTED
+) -> SimpleNamespace:
+    return SimpleNamespace(
+        node_id=node_id, endpoint=f"http://{node_id}", model="generic-model", hf_repo=None,
+        shard_start=start, shard_end=end, benchmark_tokens_per_sec=10.0,
+        model_tokens_per_sec={}, queue_depth=0, proxy_inflight=0, wallet_address=None,
+        capability=CapabilityState(
+            state=state, shard_start=start, shard_end=end,
+            model_artifact_digest=fingerprint[0], runtime_recipe_digest=fingerprint[1],
+        ),
+    )
+
+
+def test_existing_route_formation_requires_exact_compatible_coverage_and_excludes_dark_nodes():
+    """Routing consumes generic fingerprints and admission states, not GGUF policy."""
+    exact = ("a" * 64, "b" * 64)
+    other = ("c" * 64, "d" * 64)
+    compatible_head = _candidate("head", 0, 3, exact)
+    compatible_tail = _candidate("tail", 4, 7, exact)
+    dark_head = _candidate("dark", 0, 7, exact, state=STATE_UNCERTIFIED)
+
+    route, error = _select_route([dark_head, compatible_head, compatible_tail], 0, 7)
+    assert error == ""
+    assert [node.node_id for node in route] == ["head", "tail"]
+
+    route, error = _select_route([compatible_head, _candidate("wrong", 4, 7, other)], 0, 7)
+    assert route == []
+    assert "covers layer 4" in error

tests/test_native_worker_supervisor.py

@@ -0,0 +1,196 @@
+"""Model-free DGR-040 supervision tests using a deterministic fake worker."""
+
+from __future__ import annotations
+
+import hashlib
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+from meshnet_node.native_worker_supervisor import (
+    NativeWorkerError,
+    NativeWorkerProbe,
+    NativeWorkerSpec,
+    NativeWorkerSupervisor,
+)
+
+
+def _write_fake_worker(path: Path) -> None:
+    path.write_text(
+        """import os
+import signal
+import sys
+import time
+
+stop = False
+def terminate(*_):
+    global stop
+    stop = True
+signal.signal(signal.SIGTERM, terminate)
+print('ShardRuntime worker listening on ' + os.environ['MESHNET_SHARD_LISTEN_ADDR'], flush=True)
+if os.environ.get('MESHNET_INJECT_PROCESS_DEATH_AFTER_EXECUTIONS'):
+    marker = os.environ.get('MESHNET_FAKE_CRASH_ONCE_FILE')
+    if not marker or not os.path.exists(marker):
+        if marker:
+            open(marker, 'w').close()
+        time.sleep(0.05)
+        print('deterministic injected worker death', file=sys.stderr, flush=True)
+        raise SystemExit(70)
+while not stop:
+    time.sleep(0.01)
+print('ShardRuntime worker shut down cleanly', flush=True)
+""",
+        encoding="utf-8",
+    )
+
+
+def _spec(tmp_path: Path, **changes: object) -> NativeWorkerSpec:
+    artifact = tmp_path / "fixture.gguf"
+    artifact.write_bytes(b"fixture artifact")
+    fake = tmp_path / "fake_worker.py"
+    _write_fake_worker(fake)
+    values: dict[str, object] = {
+        "binary": Path(sys.executable),
+        "binary_digest": hashlib.sha256(Path(sys.executable).read_bytes()).hexdigest(),
+        "args": (str(fake),),
+        "listen_address": "fake-worker:12345",
+        "artifact_path": artifact,
+        "artifact_digest": hashlib.sha256(artifact.read_bytes()).hexdigest(),
+        "recipe_digest": "a" * 64,
+        "recipe_id": "fixture",
+        "recipe_version": "1",
+        "catalogue_version": "test",
+        "shard_start": 2,
+        "shard_end": 5,
+    }
+    values.update(changes)
+    return NativeWorkerSpec(**values)  # type: ignore[arg-type]
+
+
+def _probe(spec: NativeWorkerSpec, _timeout: float) -> NativeWorkerProbe:
+    return NativeWorkerProbe(
+        artifact_digest=spec.artifact_digest,
+        recipe_digest=spec.recipe_digest,
+        recipe_id=spec.recipe_id,
+        recipe_version=spec.recipe_version,
+        catalogue_version=spec.catalogue_version,
+        shard_start=spec.shard_start,
+        shard_end=spec.shard_end,
+        serving=True,
+    )
+
+
+def _eventually(predicate, timeout: float = 2.0) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(0.01)
+    return predicate()
+
+
+def test_start_verifies_identity_captures_logs_and_stops_gracefully(tmp_path):
+    events: list[tuple[str, str]] = []
+    supervisor = NativeWorkerSupervisor(
+        _spec(tmp_path),
+        probe=_probe,
+        readiness_timeout=1,
+        shutdown_timeout=1,
+        kill_timeout=1,
+        on_available=lambda reason: events.append(("available", reason)),
+        on_unavailable=lambda reason: events.append(("unavailable", reason)),
+    )
+
+    result = supervisor.start()
+    assert result.serving and supervisor.available
+    assert events == [("available", "worker ready and identity verified")]
+    assert any("ShardRuntime worker listening" in line for line in supervisor.logs)
+
+    supervisor.stop()
+    assert not supervisor.available
+    assert events[-1] == ("unavailable", "worker stopped")
+    assert _eventually(lambda: any("shut down cleanly" in line for line in supervisor.logs))
+
+
+def test_start_refuses_changed_artifact_before_spawning(tmp_path):
+    spec = _spec(tmp_path, artifact_digest="0" * 64)
+    supervisor = NativeWorkerSupervisor(spec, probe=_probe, readiness_timeout=1)
+
+    with pytest.raises(NativeWorkerError, match="artifact digest"):
+        supervisor.start()
+    assert supervisor.pid is None
+
+
+def test_start_refuses_changed_binary_before_spawning(tmp_path):
+    spec = _spec(tmp_path, binary_digest="0" * 64)
+    supervisor = NativeWorkerSupervisor(spec, probe=_probe, readiness_timeout=1)
+
+    with pytest.raises(NativeWorkerError, match="binary digest"):
+        supervisor.start()
+    assert supervisor.pid is None
+
+
+def test_probe_identity_mismatch_never_makes_capability_available(tmp_path):
+    spec = _spec(tmp_path)
+
+    def wrong_probe(actual: NativeWorkerSpec, timeout: float) -> NativeWorkerProbe:
+        result = _probe(actual, timeout)
+        return NativeWorkerProbe(**{**result.__dict__, "shard_end": actual.shard_end + 1})
+
+    supervisor = NativeWorkerSupervisor(spec, probe=wrong_probe, readiness_timeout=1, shutdown_timeout=1)
+    with pytest.raises(NativeWorkerError, match="identity/range"):
+        supervisor.start()
+    assert not supervisor.available
+
+
+def test_deterministic_worker_death_withdraws_then_restart_recovers(tmp_path):
+    unavailable: list[str] = []
+    spec = _spec(
+        tmp_path,
+        extra_environment={
+            "MESHNET_INJECT_PROCESS_DEATH_AFTER_EXECUTIONS": "1",
+            "MESHNET_FAKE_CRASH_ONCE_FILE": str(tmp_path / "crashed-once"),
+        },
+    )
+    supervisor = NativeWorkerSupervisor(
+        spec,
+        probe=_probe,
+        readiness_timeout=1,
+        health_interval=0.01,
+        shutdown_timeout=1,
+        kill_timeout=1,
+        on_unavailable=unavailable.append,
+    )
+    supervisor.start()
+    assert _eventually(lambda: not supervisor.available)
+    assert "code 70" in supervisor.unavailable_reason
+    assert any("deterministic injected worker death" in line for line in supervisor.logs)
+
+    supervisor.restart()
+    assert supervisor.available
+    supervisor.stop()
+
+
+def test_health_loss_withdraws_only_native_capability(tmp_path):
+    healthy = True
+    unavailable: list[str] = []
+    spec = _spec(tmp_path)
+
+    def health_probe(actual: NativeWorkerSpec, timeout: float) -> NativeWorkerProbe:
+        result = _probe(actual, timeout)
+        return NativeWorkerProbe(**{**result.__dict__, "serving": healthy})
+
+    supervisor = NativeWorkerSupervisor(
+        spec,
+        probe=health_probe,
+        readiness_timeout=1,
+        on_unavailable=unavailable.append,
+    )
+    supervisor.start()
+    healthy = False
+    assert not supervisor.check_health()
+    assert not supervisor.available
+    assert unavailable and "health lost" in unavailable[-1]
+    supervisor.stop()